diff --git a/files/zh-cn/web/api/filesystemdirectoryhandle/entries/index.md b/files/zh-cn/web/api/filesystemdirectoryhandle/entries/index.md new file mode 100644 index 00000000000000..f5ece7a7b7b554 --- /dev/null +++ b/files/zh-cn/web/api/filesystemdirectoryhandle/entries/index.md @@ -0,0 +1,47 @@ +--- +title: FileSystemDirectoryHandle:entries() 方法 +slug: Web/API/FileSystemDirectoryHandle/entries +--- + +{{securecontext_header}}{{APIRef("File System API")}} + +{{domxref("FileSystemDirectoryHandle")}} 接口的 **`entries()`** 方法返回一个异步迭代器,用于迭代调用此方法的 `FileSystemDirectoryHandle` 中的条目的键值对。键值对是一个 `[键, 值]` 形式的数组。 + +## 语法 + +```js-nolint +entries() +``` + +### 参数 + +无。 + +### 返回值 + +一个新的包含 `FileSystemDirectoryHandle` 中每个条目的键值对的异步迭代器。 + +## 示例 + +使用 `for await...of` 循环能够简化迭代过程。 + +```js +const dirHandle = await window.showDirectoryPicker(); + +for await (const [key, value] of dirHandle.entries()) { + console.log({ key, value }); +} +``` + +## 规范 + +{{Specifications}} + +## 浏览器兼容性 + +{{Compat}} + +## 参见 + +- [文件系统 API](/zh-CN/docs/Web/API/File_System_API) +- [文件系统访问 API:简化本地文件访问](https://developer.chrome.com/articles/file-system-access/) diff --git a/files/zh-cn/web/api/filesystemdirectoryhandle/getdirectoryhandle/index.md b/files/zh-cn/web/api/filesystemdirectoryhandle/getdirectoryhandle/index.md new file mode 100644 index 00000000000000..bf34c75dec664f --- /dev/null +++ b/files/zh-cn/web/api/filesystemdirectoryhandle/getdirectoryhandle/index.md @@ -0,0 +1,63 @@ +--- +title: FileSystemDirectoryHandle:getDirectoryHandle() 方法 +slug: Web/API/FileSystemDirectoryHandle/getDirectoryHandle +--- + +{{securecontext_header}}{{APIRef("File System API")}} + +{{domxref("FileSystemDirectoryHandle")}} 接口的 **`getDirectoryHandle()`** 方法返回一个位于调用此方法的目录句柄内带有指定名称的子目录的 {{domxref('FileSystemDirectoryHandle')}}。 + +## 语法 + +```js-nolint +getDirectoryHandle(name) +getDirectoryHandle(name, options) +``` + +### 参数 + +- `name` + - : 一个字符串,表示你想要获得的子目录的 {{domxref('FileSystemHandle.name')}}。 +- `options` {{optional_inline}} + + - : 包含要获得的子目录的选项的可选对象,选项如下: + + - `create` + - : 布尔值,默认为 `false`。当设为 `true` 时,如果没有找到对应的目录,将会创建一个指定名称的目录并将其返回。 + +### 返回值 + +一个 {{jsxref('Promise')}} 对象,会兑现一个 {{domxref('FileSystemDirectoryHandle')}}。 + +### 异常 + +- `NotAllowedError` {{domxref("DOMException")}} + - : 如果 {{domxref('PermissionStatus')}} 不为“granted”则抛出此异常。 +- `TypeMismatchError` {{domxref("DOMException")}} + - : 如果将返回的条目是个文件而不是目录时会抛出此异常。 +- `NotFoundError` {{domxref("DOMException")}} + - : 如果目录不存在,并且 `create` 选项被设为 `false` 时会抛出此异常。 + +## 示例 + +下面的示例能够取得指定名称的目录句柄,如果目录不存在,则创建。 + +```js +const dirName = "directoryToGetName"; + +// 假设我们有一个目录句柄:'currentDirHandle' +const subDir = currentDirHandle.getDirectoryHandle(dirName, { create: true }); +``` + +## 规范 + +{{Specifications}} + +## 浏览器兼容性 + +{{Compat}} + +## 参见 + +- [文件系统 API](/zh-CN/docs/Web/API/File_System_API) +- [文件系统访问 API:简化本地文件访问](https://developer.chrome.com/articles/file-system-access/) diff --git a/files/zh-cn/web/api/filesystemdirectoryhandle/getfilehandle/index.md b/files/zh-cn/web/api/filesystemdirectoryhandle/getfilehandle/index.md new file mode 100644 index 00000000000000..13d3378d575c25 --- /dev/null +++ b/files/zh-cn/web/api/filesystemdirectoryhandle/getfilehandle/index.md @@ -0,0 +1,65 @@ +--- +title: FileSystemDirectoryHandle:getFileHandle() 方法 +slug: Web/API/FileSystemDirectoryHandle/getFileHandle +--- + +{{securecontext_header}}{{APIRef("File System API")}} + +{{domxref("FileSystemDirectoryHandle")}} 接口的 **`getFileHandle()`** 方法返回一个位于调用此方法的目录句柄内带有指定名称的文件的 {{domxref('FileSystemFileHandle')}}。 + +## 语法 + +```js-nolint +getFileHandle(name) +getFileHandle(name, options) +``` + +### 参数 + +- `name` + - : 一个字符串,表示你想要获得的文件的 {{domxref('FileSystemHandle.name')}}。 +- `options` {{optional_inline}} + + - : 包含以下属性的对象: + + - `create` + - : 布尔值,默认为 `false`。当设为 `true` 时,如果没有找到对应的文件,将会创建一个指定名称的文件并将其返回。 + +### 返回值 + +一个 {{jsxref('Promise')}} 对象,会兑现一个 {{domxref('FileSystemFileHandle')}}。 + +### 异常 + +- `NotAllowedError` {{domxref("DOMException")}} + - : 如果 {{domxref('PermissionStatus')}} 不为“granted”则抛出此异常。 +- {{jsxref("TypeError")}} + - : 如果指定的名称不是一个合法的字符串或者包含会干扰本地文件系统的字符则抛出此异常。 +- `TypeMismatchError` {{domxref("DOMException")}} + - : 如果指定名称的条目是个目录而不是文件,则抛出此异常。 +- `NotFoundError` {{domxref("DOMException")}} + - : 如果文件不存在,并且 `create` 选项被设为 `false` 时会抛出此异常。 + +## 示例 + +下面的示例能够取得指定名称的文件句柄,如果文件不存在,则创建。 + +```js +const fileName = "fileToGetName"; + +// 假设我们有一个目录句柄:'currentDirHandle' +const fileHandle = currentDirHandle.getFileHandle(fileName, { create: true }); +``` + +## 规范 + +{{Specifications}} + +## 浏览器兼容性 + +{{Compat}} + +## 参见 + +- [文件系统 API](/zh-CN/docs/Web/API/File_System_API) +- [文件系统访问 API:简化本地文件访问](https://developer.chrome.com/articles/file-system-access/) diff --git a/files/zh-cn/web/api/filesystemdirectoryhandle/index.md b/files/zh-cn/web/api/filesystemdirectoryhandle/index.md new file mode 100644 index 00000000000000..a6f96bb2107c68 --- /dev/null +++ b/files/zh-cn/web/api/filesystemdirectoryhandle/index.md @@ -0,0 +1,120 @@ +--- +title: FileSystemDirectoryHandle +slug: Web/API/FileSystemDirectoryHandle +--- + +{{securecontext_header}}{{APIRef("File System API")}} + +{{domxref("File System API", "File System API", "", "nocode")}} 的 **`FileSystemDirectoryHandle`** 接口提供指向一个文件系统目录的句柄。 + +这个接口可以通过 {{domxref('window.showDirectoryPicker()')}}、{{domxref('StorageManager.getDirectory()')}}、{{domxref('DataTransferItem.getAsFileSystemHandle()')}} 和 {{domxref('FileSystemDirectoryHandle.getDirectoryHandle()')}} 这些方法访问。 + +{{InheritanceDiagram}} + +## 实例属性 + +_从父接口 {{DOMxRef("FileSystemHandle")}} 继承属性。_ + +## 实例方法 + +_从父接口 {{DOMxRef("FileSystemHandle")}} 继承方法。_ + +常规方法: + +- {{domxref('FileSystemDirectoryHandle.getDirectoryHandle()')}} + - : 返回一个 {{jsxref('Promise')}},会兑现一个调用此方法的目录句柄内指定名称的子目录的 {{domxref('FileSystemDirectoryHandle')}}。 +- {{domxref('FileSystemDirectoryHandle.getFileHandle()')}} + - : 返回一个 {{jsxref('Promise')}},会兑现一个调用此方法的目录句柄内指定名称的文件的 `FileSystemFileHandle`。 +- {{domxref('FileSystemDirectoryHandle.removeEntry()')}} + - : 如果目录句柄包含一个名为指定名称的文件或目录,则尝试异步将其移除。 +- {{domxref('FileSystemDirectoryHandle.resolve()')}} + - : 返回一个 {{jsxref('Promise')}} 对象,会兑现一个包含从父目录前往指定子条目中间的目录的名称的{{jsxref('Array', '数组', '', 'nocode')}}。数组的最后一项是子条目的名称。 + +[异步迭代器](/zh-CN/docs/Web/JavaScript/Reference/Iteration_protocols#异步迭代器和异步可迭代协议)方法: + +- {{domxref('FileSystemDirectoryHandle.entries()')}} + - : 返回一个新的迭代 `FileSystemDirectoryHandle` 对象内每个条目的键值对的异步迭代器。 +- {{domxref('FileSystemDirectoryHandle.keys()')}} + - : 返回一个新的迭代 `FileSystemDirectoryHandle` 对象内每个条目的键的异步迭代器。 +- {{domxref('FileSystemDirectoryHandle.values()')}} + - : 返回一个新的迭代 `FileSystemDirectoryHandle` 对象内每个条目的句柄的异步迭代器。 +- [`FileSystemDirectoryHandle[@@asyncIterator]()`](/zh-CN/docs/Web/API/FileSystemDirectoryHandle/entries) + - : 默认情况下返回 `entries` 函数。 + +## 示例 + +### 返回目录句柄 + +下面的示例返回一个指定名称的目录句柄,如果对应的目录不存在则创建。 + +```js +const dirName = "directoryToGetName"; + +// 假设我们有一个目录句柄:'currentDirHandle' +const subDir = currentDirHandle.getDirectoryHandle(dirName, { create: true }); +``` + +### 返回文件路径 + +下面的异步函数使用 `resolve()` 来查找被选择文件相对于指定目录句柄的路径。 + +```js +async function returnPathDirectories(directoryHandle) { + // 通过显示文件选择器来获得一个文件句柄 + const [handle] = await self.showOpenFilePicker(); + if (!handle) { + // 如果用户取消了选择或者打开文件失败 + return; + } + + // 检查文件句柄是否存在于目录句柄的目录中 + const relativePaths = await directoryHandle.resolve(handle); + + if (relativePaths === null) { + // 不在目录句柄中 + } else { + // relativePaths 是一个包含名称的数组,指示相对路径 + + for (const name of relativePaths) { + // 打印数组的每个元素 + console.log(name); + } + } +} +``` + +### 返回目录中所有文件的句柄 + +下面的示例会递归地扫描一个目录,以返回目录中每个文件的 {{domxref('FileSystemFileHandle')}} 对象: + +```js +async function* getFilesRecursively(entry) { + if (entry.kind === "file") { + const file = await entry.getFile(); + if (file !== null) { + file.relativePath = getRelativePath(entry); + yield file; + } + } else if (entry.kind === "directory") { + for await (const handle of entry.values()) { + yield* getFilesRecursively(handle); + } + } +} +for await (const fileHandle of getFilesRecursively(directoryHandle)) { + console.log(fileHandle); +} +``` + +## 规范 + +{{Specifications}} + +## 浏览器兼容性 + +{{Compat}} + +## 参见 + +- [文件系统 API](/zh-CN/docs/Web/API/File_System_API) +- [文件系统访问 API:简化本地文件访问](https://developer.chrome.com/articles/file-system-access/) diff --git a/files/zh-cn/web/api/filesystemdirectoryhandle/keys/index.md b/files/zh-cn/web/api/filesystemdirectoryhandle/keys/index.md new file mode 100644 index 00000000000000..17795f0a203b82 --- /dev/null +++ b/files/zh-cn/web/api/filesystemdirectoryhandle/keys/index.md @@ -0,0 +1,47 @@ +--- +title: FileSystemDirectoryHandle:keys() 方法 +slug: Web/API/FileSystemDirectoryHandle/keys +--- + +{{securecontext_header}}{{APIRef("File System API")}} + +{{domxref("FileSystemDirectoryHandle")}} 接口的 **`keys()`** 方法返回一个异步迭代器,用于迭代调用此方法的 `FileSystemDirectoryHandle` 中的条目的键。 + +## 语法 + +```js-nolint +FileSystemDirectoryHandle.keys() +``` + +### 参数 + +无。 + +### 返回值 + +一个新的包含 `FileSystemDirectoryHandle` 中每个条目的键的异步迭代器。 + +## 示例 + +使用 `for await...of` 循环能够简化迭代过程。 + +```js +const dirHandle = await window.showDirectoryPicker(); + +for await (const key of dirHandle.keys()) { + console.log(key); +} +``` + +## 规范 + +{{Specifications}} + +## 浏览器兼容性 + +{{Compat}} + +## 参见 + +- [文件系统 API](/zh-CN/docs/Web/API/File_System_API) +- [文件系统访问 API:简化本地文件访问](https://developer.chrome.com/articles/file-system-access/) diff --git a/files/zh-cn/web/api/filesystemdirectoryhandle/removeentry/index.md b/files/zh-cn/web/api/filesystemdirectoryhandle/removeentry/index.md new file mode 100644 index 00000000000000..b8107bfc5d946f --- /dev/null +++ b/files/zh-cn/web/api/filesystemdirectoryhandle/removeentry/index.md @@ -0,0 +1,67 @@ +--- +title: FileSystemDirectoryHandle:removeEntry() 方法 +slug: Web/API/FileSystemDirectoryHandle/removeEntry +--- + +{{securecontext_header}}{{APIRef("File System API")}} + +{{domxref("FileSystemDirectoryHandle")}} 接口的 **`removeEntry()`** 方法用于尝试将目录句柄内名为指定名称的文件或目录移除。 + +## 语法 + +```js-nolint +removeEntry(name) +removeEntry(name, options) +``` + +### 参数 + +- `name` + - : 一个字符串,表示你想要移除的条目的 {{domxref('FileSystemHandle.name')}}。 +- `options` {{optional_inline}} + + - : 一个包含以下选项的可选对象: + + - `recursive` + - : 布尔值,默认为 `false`。当设为 `true` 时,条目将会被递归移除。 + +### 返回值 + +一个 {{jsxref('Promise')}} 对象,兑现 `undefined`。 + +### 异常 + +- {{jsxref("TypeError")}} + - : 如果 `name` 不是一个合法的字符串或者包含不允许出现在文件系统中的字符时,抛出此异常。 +- `NotAllowedError` {{domxref("DOMException")}} + - : 如果 {{domxref('PermissionStatus')}} 不为“granted”则抛出此异常。 +- `InvalidModificationError` {{domxref("DOMException")}} + - : 如果 `recursive` 被设为 `false`,而对应的条目又有子条目时,抛出此异常。 +- `NotFoundError` {{domxref("DOMException")}} + - : 如果没有找到指定名称的条目,抛出此异常。 + +## 示例 + +下面的示例演示移除目录句柄内的一个条目。 + +```js +const entryName = "entryToRemove"; + +// 假设我们有一个目录句柄:'currentDirHandle' +currentDirHandle.removeEntry(entryName).then(() => { + // 成功移除后要运行的代码 +}); +``` + +## 规范 + +{{Specifications}} + +## 浏览器兼容性 + +{{Compat}} + +## 参见 + +- [文件系统 API](/zh-CN/docs/Web/API/File_System_API) +- [文件系统访问 API:简化本地文件访问](https://developer.chrome.com/articles/file-system-access/) diff --git a/files/zh-cn/web/api/filesystemdirectoryhandle/resolve/index.md b/files/zh-cn/web/api/filesystemdirectoryhandle/resolve/index.md new file mode 100644 index 00000000000000..69995f24549467 --- /dev/null +++ b/files/zh-cn/web/api/filesystemdirectoryhandle/resolve/index.md @@ -0,0 +1,68 @@ +--- +title: FileSystemDirectoryHandle:resolve() 方法 +slug: Web/API/FileSystemDirectoryHandle/resolve +--- + +{{securecontext_header}}{{APIRef("File System API")}} + +{{domxref("FileSystemDirectoryHandle")}} 接口的 **`resolve()`** 方法返回一个 {{jsxref('Promise')}} 对象,会兑现一个包含从父目录前往指定子条目中间的目录的名称的{{jsxref('Array', '数组', '', 'nocode')}}。数组的最后一项是子条目的名称。 + +## 语法 + +```js-nolint +resolve(possibleDescendant) +``` + +### 参数 + +- `possibleDescendant` + - : 要返回其相对路径的 {{domxref('FileSystemHandle')}}。 + +### 返回值 + +一个 {{jsxref('Promise')}} 对象,会兑现一个包含字符串的{{jsxref('Array', '数组', '', 'nocode')}},或者当参数 `possibleDescendant` 不是此 {{domxref('FileSystemDirectoryHandle')}} 的后代时,兑现 `null`。 + +### 异常 + +不抛出异常。 + +## 示例 + +下面的异步函数使用 `resolve()` 来查找被选择文件相对于指定目录句柄的路径。 + +```js +async function returnPathDirectories(directoryHandle) { + // 通过显示文件选择器来获得一个文件句柄 + const [handle] = await self.showOpenFilePicker(); + if (!handle) { + // 如果用户取消了选择或者打开文件失败 + return; + } + + // 检查文件句柄是否存在于目录句柄的目录中 + const relativePaths = await directoryHandle.resolve(handle); + + if (relativePaths === null) { + // 不在目录句柄中 + } else { + // relativePaths 是一个包含名称的数组,指示相对路径 + for (const name of relativePaths) { + // 打印数组的每个元素 + console.log(name); + } + } +} +``` + +## 规范 + +{{Specifications}} + +## 浏览器兼容性 + +{{Compat}} + +## 参见 + +- [文件系统 API](/zh-CN/docs/Web/API/File_System_API) +- [文件系统访问 API:简化本地文件访问](https://developer.chrome.com/articles/file-system-access/) diff --git a/files/zh-cn/web/api/filesystemdirectoryhandle/values/index.md b/files/zh-cn/web/api/filesystemdirectoryhandle/values/index.md new file mode 100644 index 00000000000000..60dde11f4d4186 --- /dev/null +++ b/files/zh-cn/web/api/filesystemdirectoryhandle/values/index.md @@ -0,0 +1,47 @@ +--- +title: FileSystemDirectoryHandle:values() 方法 +slug: Web/API/FileSystemDirectoryHandle/values +--- + +{{securecontext_header}}{{APIRef("File System API")}} + +{{domxref("FileSystemDirectoryHandle")}} 接口的 **`values()`** 方法返回一个异步迭代器,用于迭代调用此方法的 `FileSystemDirectoryHandle` 中的条目的值。 + +## 语法 + +```js-nolint +values() +``` + +### 参数 + +无。 + +### 返回值 + +一个新的包含 `FileSystemDirectoryHandle` 中每个条目的句柄的异步迭代器。 + +## 示例 + +使用 `for await...of` 循环能够简化迭代过程。 + +```js +const dirHandle = await window.showDirectoryPicker(); + +for await (const value of dirHandle.values()) { + console.log(value); +} +``` + +## 规范 + +{{Specifications}} + +## 浏览器兼容性 + +{{Compat}} + +## 参见 + +- [文件系统 API](/zh-CN/docs/Web/API/File_System_API) +- [文件系统访问 API:简化本地文件访问](https://developer.chrome.com/articles/file-system-access/)