FileSystemEntry.copyTo() — Methode · JavaScript-Referenz

Signatur

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

Beschreibung

copyTo() gehört zur alten, nie standardisierten File and Directory Entries API (früher „FileSystem API“). Die Methode kopiert den Eintrag – eine Datei (FileSystemFileEntry) oder ein Verzeichnis (FileSystemDirectoryEntry) – in das angegebene Zielverzeichnis newParent. Verzeichnisse werden dabei rekursiv mit ihrem gesamten Inhalt kopiert.

Die Methode arbeitet asynchron und rein callback-basiert: Nach erfolgreicher Kopie wird successCallback mit dem neuen Eintrag aufgerufen, bei einem Fehler errorCallback mit einem DOMException- bzw. FileError-Objekt. Lässt man newName weg, behält die Kopie den ursprünglichen Namen.

Praktisch nutzbar ist copyTo() nur im sandboxed Dateisystem von Chromium, das man über window.webkitRequestFileSystem() erhält. Einträge aus Drag & Drop (DataTransferItem.webkitGetAsEntry()) sind schreibgeschützt und lassen sich damit nicht in das echte Dateisystem des Nutzers kopieren. Für neue Projekte nimmt man das Origin Private File System (OPFS) über navigator.storage.getDirectory() oder die File System Access API.

Parameter

Name	Typ	Default	Beschreibung
$newParent Pflicht	FileSystemDirectoryEntry		Zielverzeichnis, in das der Eintrag kopiert wird. Es muss im selben Dateisystem liegen.
$newName	string	ursprünglicher Name	Neuer Name der Kopie. Weggelassen oder `undefined` bedeutet: der bisherige Name bleibt.
$successCallback	(entry: FileSystemEntry) => void		Wird nach erfolgreicher Kopie mit dem neu angelegten Eintrag aufgerufen.
$errorCallback	(error: DOMException \| FileError) => void		Wird bei einem Fehler aufgerufen, z. B. bei ungültigem Ziel, fehlenden Rechten oder einem Namenskonflikt.

Rückgabewert

Typ

undefined

Beschreibung

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

Beispiele

Datei im Sandbox-Dateisystem sichern (Chromium)

// Temporäres Sandbox-Dateisystem mit 5 MB anfordern
window.webkitRequestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, (fs) => {
  fs.root.getFile('notizen.txt', { create: true }, (fileEntry) => {
    fs.root.getDirectory('backup', { create: true }, (backupDir) => {
      fileEntry.copyTo(
        backupDir,
        'notizen-kopie.txt',
        (copy) => console.log('Kopiert nach:', copy.fullPath),
        (err) => console.error('Kopieren fehlgeschlagen:', err.name)
      );
    });
  });
}, (err) => console.error('Kein Dateisystem:', err));

Kopiert nach: /backup/notizen-kopie.txt

copyTo() als Promise nutzen (async/await)

const copyEntry = (entry, targetDir, newName) =>
  new Promise((resolve, reject) => {
    entry.copyTo(targetDir, newName, resolve, reject);
  });

const getDir = (root, path) =>
  new Promise((resolve, reject) =>
    root.getDirectory(path, { create: true }, resolve, reject));

window.webkitRequestFileSystem(window.TEMPORARY, 1024 * 1024, async (fs) => {
  try {
    const src = await getDir(fs.root, 'projekt');
    const archiv = await getDir(fs.root, 'archiv');
    // Verzeichnis wird rekursiv kopiert
    const kopie = await copyEntry(src, archiv, 'projekt-2024');
    console.log(kopie.isDirectory, kopie.fullPath);
  } catch (err) {
    console.error(err.name, err.message);
  }
});

true /archiv/projekt-2024

Moderne Alternative: Datei im OPFS kopieren

// Origin Private File System – in allen aktuellen Browsern verfügbar
const root = await navigator.storage.getDirectory();

const quelle = await root.getFileHandle('notizen.txt', { create: true });
const ziel = await root.getFileHandle('notizen-kopie.txt', { create: true });

const datei = await quelle.getFile();
const writable = await ziel.createWritable();
await writable.write(datei);
await writable.close();

console.log('Kopie erstellt:', ziel.name);

Kopie erstellt: notizen-kopie.txt

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: copyTo() gibt es nur im Chromium-Sandbox-Dateisystem (webkitRequestFileSystem). Firefox und Safari bieten zwar Teile der Entries API für Drag & Drop an, aber kein copyTo(). Vor dem Aufruf per Feature-Erkennung prüfen: typeof entry.copyTo === 'function'.
Ungültige Ziele: Einen Eintrag unter demselben Namen in sein eigenes Elternverzeichnis zu kopieren oder ein Verzeichnis in eines seiner Unterverzeichnisse zu kopieren, führt zu einem Fehler (InvalidModificationError).
Namenskonflikte: Eine vorhandene Datei mit gleichem Namen kann überschrieben werden. Ein vorhandenes, nicht leeres Verzeichnis dagegen erzeugt einen Fehler. Eine Datei auf ein Verzeichnis zu kopieren (oder umgekehrt) schlägt ebenfalls fehl.
Drag-&-Drop-Einträge aus webkitGetAsEntry() sind schreibgeschützt. copyTo() kopiert nichts in das echte Dateisystem des Nutzers.
Nur Callbacks: Die Methode liefert kein Promise. Für async/await braucht man einen eigenen Wrapper (siehe Beispiel).
Für neue Anwendungen navigator.storage.getDirectory() (OPFS) oder die File System Access API (FileSystemFileHandle) verwenden.

Siehe auch

FileSystemEntry.moveTo() FileSystemEntry.toURL() FileSystemEntry.remove() FileSystemEntry.getParent() FileSystemEntry.getMetadata()