web文件系统

July 24, 2023

本篇的主题为 File System Access API，而不是 File and Directory Entries API

选取器

选取器默认有一个允许所有文件类型的选项，如图所示

如果已经设置了 types 选项，我们可能需要禁止这种行为，可以将 excludeAcceptAllOption 选项设置为 true

showOpenFilePicker()

const btn_showOpenFilePicker = document.createElement("button");
btn_showOpenFilePicker.textContent = "showOpenFilePicker";
document.body.append(btn_showOpenFilePicker);
btn_showOpenFilePicker.addEventListener("click", async () => {
    const fileHandleArray = await window.showOpenFilePicker({
        types: [
            {
                description: "请选择图片",
                accept: {
                    "image/*": [".png", ".gif", ".jpeg", ".jpg", ".webp"],
                },
            },
        ],
        multiple: true,
        excludeAcceptAllOption: true,
    });
    console.log(fileHandleArray);
});

declare interface Window {
    // TODO: 目前 typescript 5.4dev 还没有提供这些 Window 接口方法的定义
    // 布尔值的默认值为 false

    /**
     * MDN 上写的是 AbortError 异常，但实际上是 DOMException
     * 用户取消选择，触发 DOMException: The user aborted a request.
     * 不是用户发起，触发 DOMException: Failed to execute 'showOpenFilePicker' on 'Window': Must be handling a user gesture to show a file picker.
     */
    showOpenFilePicker: (options?: {
        /**
         * 是否选取多个文件
         */
        multiple?: boolean;
        /**
         * 若要开启此选项，需配合 types 选项食用，表示禁用选取框的“所有文件选项”
         */
        excludeAcceptAllOption?: boolean;
        types?: Array<{
            /**
             * 允许的文件类型类别的可选说明
             */
            description?: string;
            /**
             * 键为 MIME 类型，系统会根据 MIME 类型默认生成一些扩展名，值为扩展名（带点号）数组，这个数组只是作为系统生成的扩展名基础上的附加扩展名
             */
            accept?: Record<string, string[]>;
        }>;
    }) => Promise<FileSystemFileHandle[]>; // 返回值总是数组
}

showSaveFilePicker()

const btn_showSaveFilePicker = document.createElement("button");
btn_showSaveFilePicker.textContent = "showSaveFilePicker";
document.body.append(btn_showSaveFilePicker);
btn_showSaveFilePicker.addEventListener("click", async () => {
    const fileHandle = await window.showSaveFilePicker({
        suggestedName: "推荐文件名.txt",
        types: [
            {
                description: "文本文件",
                accept: { "text/plain": [".txt"] },
            },
        ],
    });
    console.log(fileHandle);
});

declare interface Window {
    /**
     * 此方法的选项和 showOpenFilePicker 方法差不多，只返回单个文件接口
     */
    showSaveFilePicker: (options?: {
        excludeAcceptAllOption?: boolean;
        suggestedName?: string;
        types?: Array<{
            description?: string;
            accept?: Record<string, string[]>;
        }>;
    }) => Promise<FileSystemFileHandle>;
}

showDirectoryPicker()

const btn_showDirectoryPicker = document.createElement("button");
btn_showDirectoryPicker.textContent = "showDirectoryPicker";
document.body.append(btn_showDirectoryPicker);
btn_showDirectoryPicker.addEventListener("click", async () => {
    const dirHandle = await window.showDirectoryPicker({
        mode: "readwrite", // 会弹窗窗口提示用户我们的页面能够访问查看或编辑用户的目录
    });
    console.log(dirHandle);
});

declare interface Window {
    /**
     * 目录选择器就比较简单了，只返回一个目录接口
     */
    showDirectoryPicker: (options?: {
        /**
         * By specifying an ID, the browser can remember different directories for different IDs. If the same ID is used for another picker, the picker opens in the same directory.
         * ID 是任意类型，但会被强制转换为字符串，不允许字符会报错
         */
        id?: any;
        /**
         * A string that defaults to "read" for read-only access or "readwrite" for read and write access to the directory.
         * 用户选择完目录后还会弹出提示窗
         */
        mode?: "read" | "readwrite";
        /**
         * A FileSystemHandle or a well known directory ("desktop", "documents", "downloads", "music", "pictures", or "videos") to open the dialog in.
         */
        startIn?: "desktop" | "documents" | "downloads" | "music" | "pictures" | "videos";
    }) => Promise<FileSystemDirectoryHandle>;
}

navigator.storage.getDirectory()

origin private file system : https://developer.mozilla.org/docs/Web/API/File_System_Access_API#origin_private_file_system

window.navigator.storage.getDirectory(); // => Promise<FileSystemDirectoryHandle>

dragEvent.dataTransfer.items[0].getAsFileSystemHandle()

参见 DragEvent.dataTransfer 的有关 API

接口

FileSystemHandle <- FileSystemFileHandle
FileSystemHandle <- FileSystemDirectoryHandle

选取器返回的接口是更具体的接口

FileSystemHandle

interface FileSystemHandle {
    /**
     * 'file'      表示 FileSystemFileHandle
     * 'directory' 表示 FileSystemDirectoryHandle
     */
    readonly kind: FileSystemHandleKind;
    readonly name: string;
    /**
     * 判断当前 handle 和另一个 handle 是不是同一个
     */
    isSameEntry(other: FileSystemHandle): Promise<boolean>;
    /**
     * 查询权限
     */
    queryPermission(fileSystemHandlePermissionDescriptor?: { mode: "read" | "readwrite" }): Promise<PermissionState>;
    /**
     * 请求权限
     */
    requestPermission(fileSystemHandlePermissionDescriptor?: { mode: "read" | "readwrite" }): Promise<PermissionState>;
    remove(options?: {
        /**
         * 递归删除，只对目录有效
         */
        recursive?: boolean;
    }): Promise<void>;
}

FileSystemFileHandle

interface FileSystemFileHandle extends FileSystemHandle {
    readonly kind: "file";
    /**
     * 最主要的方法还是 getFile() 方法
     */
    getFile(): Promise<File>;
    /**
     * 创建一个可写文件流。实际情况是先创建临时文件，写入临时文件，直到句柄结束后再将实际文件替换为临时文件
     */
    createWritable(options?: {
        /**
         * A Boolean. Default false. When set to true if the file exists, the existing file is first copied to the temporary file. Otherwise the temporary file starts out empty.
         */
        keepExistingData?: boolean;
    }): Promise<FileSystemWritableFileStream>;
    /**
     * 只能在 origin private file system 上调用！这里不拓展
     */
    createSyncAccessHandle(): Promise<FileSystemSyncAccessHandle>;
}

FileSystemDirectoryHandle

interface FileSystemDirectoryHandle extends FileSystemHandle {
    readonly kind: "directory";
    /**
     * 遍历目录
     */
    entries(): Array<[key: string, value: FileSystemHandle]>;
    keys(): Array<string>;
    values(): Array<FileSystemHandle>;
    // 指定文件名获取文件
    getFileHandle(
        name: string,
        options?: {
            create?: boolean;
        },
    ): Promise<FileSystemFileHandle>;
    // 指定目录名获取目录
    getDirectoryHandle(
        name: string,
        options?: {
            create?: boolean;
        },
    ): Promise<FileSystemDirectoryHandle>;
    // 移除
    removeEntry(
        name: string,
        options?: {
            recursive?: boolean;
        },
    ): Promise<void>;
    /**
     * 传入一个当前 FileSystemDirectoryHandle 的后代 FileSystemHandle （否则直接返回 null）
     * 返回一个字符串数组，第一个是当前目录名，依次是子目录名，最后是 要解析的文件或目录 的名称
     */
    resolve(possibleDescendant: FileSystemHandle): Promise<string[] | null>;
}