FileSystemEntry.moveTo() — Methode · JavaScript-Referenz

Signatur

FileSystemEntry.prototype.moveTo(newParent, newName, successCallback, errorCallback)

Beschreibung

Die Methode moveTo() des Interfaces FileSystemEntry verschiebt den Eintrag – eine Datei (FileSystemFileEntry) oder ein Verzeichnis (FileSystemDirectoryEntry) – in das angegebene Zielverzeichnis newParent. Wird zusätzlich newName übergeben, erhält der Eintrag am Ziel diesen Namen. Ist das Zielverzeichnis dasselbe wie das bisherige Elternverzeichnis, entspricht der Aufruf einem Umbenennen.

Die Methode gehört zum alten, callback-basierten File and Directory Entries API. Sie funktioniert nur in einem sandboxed Dateisystem, das über window.webkitRequestFileSystem() angefordert wurde. Einträge, die per Drag-and-drop (DataTransferItem.webkitGetAsEntry()) oder über <input webkitdirectory> kommen, sind schreibgeschützt und lassen sich nicht verschieben.

Das Ergebnis wird nicht als Promise geliefert. Stattdessen wird bei Erfolg successCallback mit dem neuen FileSystemEntry aufgerufen, bei einem Fehler errorCallback mit einem Fehlerobjekt. Das ursprüngliche Entry-Objekt verweist danach auf einen Pfad, den es nicht mehr gibt. Arbeite deshalb mit dem Eintrag weiter, den du im Callback bekommst.

In neuem Code solltest du stattdessen das File System Access API bzw. das Origin Private File System (OPFS) nutzen, also FileSystemHandle.move(). Dieses API arbeitet mit Promises und ist in allen modernen Browsern verfügbar.

Parameter

Name	Typ	Default	Beschreibung
$newParent Pflicht	FileSystemDirectoryEntry		Das Verzeichnis, in das der Eintrag verschoben wird. Es muss zum selben Dateisystem gehören.
$newName	string	bisheriger Name	Neuer Name am Zielort. Fehlt der Name, bleibt der alte erhalten. Ist `newParent` das bisherige Elternverzeichnis, ist ein anderer Name Pflicht, sonst gibt es einen Fehler.
$successCallback	(entry: FileSystemEntry) => void		Wird nach erfolgreichem Verschieben mit dem neuen Eintrag am Zielort aufgerufen.
$errorCallback	(error: DOMException \| FileError) => void		Wird bei einem Fehler aufgerufen, z. B. bei `InvalidModificationError`, `NotFoundError` oder `SecurityError`.

Rückgabewert

Typ

void

Beschreibung

Kein direkter Rückgabewert. Das Ergebnis kommt über successCallback bzw. errorCallback.

Beispiele

Datei im sandboxed Dateisystem in einen Archivordner verschieben

// Nur in Chromium: temporäres Sandbox-Dateisystem mit 5 MB anfordern
window.webkitRequestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, (fs) => {
  fs.root.getFile('log.txt', { create: true }, (fileEntry) => {
    fs.root.getDirectory('archiv', { create: true }, (dirEntry) => {
      fileEntry.moveTo(
        dirEntry,
        'log-2024.txt',
        (moved) => console.log('Verschoben nach:', moved.fullPath),
        (err) => console.error('Fehler beim Verschieben:', err.name)
      );
    });
  });
}, (err) => console.error('Kein Dateisystem:', err));

Verschoben nach: /archiv/log-2024.txt

Umbenennen im selben Verzeichnis, als Promise verpackt

// moveTo() in ein Promise verpacken, damit async/await funktioniert
const moveEntry = (entry, parent, name) =>
  new Promise((resolve, reject) => entry.moveTo(parent, name, resolve, reject));

const getParent = (entry) =>
  new Promise((resolve, reject) => entry.getParent(resolve, reject));

const renameEntry = async (entry, newName) => {
  const parent = await getParent(entry);
  // Gleiches Verzeichnis + neuer Name = Umbenennen
  return moveEntry(entry, parent, newName);
};

// Verwendung (fileEntry stammt z. B. aus fs.root.getFile())
// const renamed = await renameEntry(fileEntry, 'notizen-final.txt');
// console.log(renamed.name);

notizen-final.txt

Moderne Alternative: FileSystemHandle.move() im OPFS

const root = await navigator.storage.getDirectory();
const file = await root.getFileHandle('entwurf.txt', { create: true });
const archiv = await root.getDirectoryHandle('archiv', { create: true });

// Verschieben und gleichzeitig umbenennen
await file.move(archiv, 'entwurf-alt.txt');
console.log(file.name);

entwurf-alt.txt

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: moveTo() war nur im alten Chromium-File-System-API mit webkitRequestFileSystem() nutzbar. Firefox und Safari kennen zwar FileSystemEntry für Drag-and-drop, unterstützen moveTo() aber nicht. Nutze für neue Projekte FileSystemHandle.move().
Du kannst ein Verzeichnis nicht in sich selbst oder in eines seiner Unterverzeichnisse verschieben. Das löst einen InvalidModificationError aus.
Verschiebst du in dasselbe Elternverzeichnis ohne neuen Namen, gibt es ebenfalls einen Fehler.
Liegt am Ziel schon eine Datei mit dem Namen, wird sie überschrieben. Eine Datei kann aber kein Verzeichnis ersetzen, und ein Verzeichnis ersetzt nur ein leeres Verzeichnis. In den übrigen Fällen schlägt der Aufruf fehl.
Einträge aus Drag-and-drop oder aus <input type=\"file\" webkitdirectory> sind schreibgeschützt. moveTo() scheitert dort.
Das alte Entry-Objekt ist nach dem Verschieben nicht mehr gültig. Arbeite mit dem Eintrag aus successCallback weiter.
Ein Verschieben zwischen verschiedenen Dateisystemen, etwa von TEMPORARY nach PERSISTENT, ist nicht vorgesehen.

Siehe auch

FileSystemDirectoryEntry.removeRecursively() FileSystemEntry.copyTo() FileSystemEntry.remove() FileSystemEntry.toURL() FileSystemEntry.getParent()