FSUtil · Directory Opus

**FSUtil** 对象提供了多个实用程序方法，用于处理文件系统。它使用 **DOpus.FSUtil** 方法获得。 <table> <thead><tr><th> 方法名称</th><th> **参数**</th><th> 返回类型</th><th> 描述 </th></tr></thead><tbody><tr><td> CancelWatchChanges</td><td> \<string:id\></td><td> *无*</td><td> 取消先前的调用**WatchChanges** 方法建立的文件夹或文件更改监视。**id** 参数是你创建监视器时分配给它的 ID。 </td></tr><tr><td> ComparePath</td><td> \<string:path1\> \<string:path2\> \<string:flags\></td><td> *bool*</td><td> 比较两个提供的路径字符串是否相等 - 如果两个路径相等，则返回 **True**，否则返回 **False**。可选的 **flags** 参数允许你修改比较行为。此参数是一个包含以下一个或多个字母（区分大小写）的字符串： | | | |-------|---------------------------------------------------------------------| | **c** | 使路径比较**区分大小写**。 | | **p** | 如果*path2* 等于或为 *path1* 的**父项**，则返回 **True**。 | </td></tr><tr><td> DisplayName</td><td> \<string:path\> \<string:flags\></td><td> *string*</td><td> 检索路径的显示名称。这是供用户查看的路径形式，而不是 Opus 内部使用的路径形式。例如，对于一个库路径，它将剥离 Opus 用于识别库成员文件夹的内部 *?xxxxxxx* 符号。可选的 **flags** 参数允许你修改行为。此参数是一个包含以下一个或多个字母（区分大小写）的字符串： | | | |-------|-----------------------------------------------------------------------------| | **e** | 用于编辑（返回一个设计用于编辑而非显示的字符串） | | **f** | 文件部分（返回显示的文件名而不是整个路径） | | **r** | 解析（将库路径解析为其底层文件系统文件夹） | </td></tr><tr><td> Drives</td><td> *无*</td><td> **Vector:[Drive](drive.zh.md)**</td><td> 返回一个 **[Vector](vector.zh.md)** 的 **[Drive](drive.zh.md)** 对象，每个对象对应系统上的一个驱动器。 </td></tr><tr><td> Exists</td><td> \<string:path\> \<string:flags\></td><td> *bool*</td><td> 如果指定的文件夹、文件或设备存在，则返回 **True**，否则返回 **False**。可选的 *flags* 参数可以设置为 **w** 以在最终路径组件中使用通配符。 </td></tr><tr><td> GetADSNames</td><td> \<string:path\></td><td> *object:***[StringSet](stringset.zh.md)**</td><td> 返回一个 **[StringSet](stringset.zh.md)** ，包含为指定的文件夹或文件找到的任何备用数据流 (ADS) 的名称。 </td></tr><tr><td> GetErrorMsg</td><td> \<int:error\></td><td> *string*</td><td> 返回系统错误代码的本地化文本描述。 </td></tr><tr><td> GetFolderPair</td><td> \<string:path\> \<string:flags\></td><td> *object:***[PairedFolder](pairedfolder.zh.md)**</td><td> 如果存在，则返回指定文件夹的 [对](/Manual/preferences/preferences_categories/frequently_used_paths/paired_folders.zh.md)。将可选标志与这对的配置选项进行比较；它们让你控制在哪些条件下返回该对，以及在配对文件夹不存在时如何处理该对。 | | | |-------|-----------------------------------------------| | **d** | 默认双栏文件夹 | | **v** | 默认导航锁定目标 | | **n** | 自动开启导航锁定 | | **y** | 默认同步目标 | | **l** | 始终在左/上方显示主文件夹 | | **u** | 即使路径不存在也使用路径 | | **i** | 忽略该对 | | **g** | 转到第一个存在的父项 | </td></tr><tr><td> GetItem</td><td> \<string:path\></td><td> *object*:**[Item](item.zh.md)**</td><td> 为指定的文件路径创建一个 **[Item](item.zh.md)** 对象。 </td></tr><tr><td> GetMetadata</td><td> \<string:path\></td><td> *object:***[Metadata](metadata.zh.md)**</td><td> 返回表示指定文件元数据的 **[Metadata](metadata.zh.md)** 对象。 </td></tr><tr><td> GetShellProperty</td><td> \<string:path\> \<string:property\> 或 \<**[Map](map.zh.md)**:properties\> \<string:type\></td><td> *variant*</td><td> 返回指定文件的一个或多个 shell 属性的值。文件路径必须作为第一个参数提供。第二个参数可以是要检索的属性的名称（或 PKEY），在这种情况下将返回属性值。或者，第二个参数可以是 **[Map](map.zh.md)** 对象，它让你一次检索多个属性。你想要检索的每个属性都应添加为 **[Map](map.zh.md)** 的键，值为一个空字符串。**Map** 中的值将替换为属性值。可选的 **type** 参数是一个字符串，它让你控制如何按名称查找属性（不区分大小写）： | | | |-------|-------------------------------------------------------------| | **R** | 将使用原始名称匹配的第一个属性。 | | **D** | 将使用显示名称匹配的第一个属性。 | 如果两个都没有指定，则原始名称和显示名称都可以匹配。请注意，如果 shell 属性由系统作为 SAFEARRAY 类型返回，它将自动转换为 **[Vector](vector.zh.md)** 对象。 </td></tr><tr><td> GetShellPropertyList</td><td> \<string:pattern\> \<string:type\></td><td> *object:***[ShellProperty](shellproperty.zh.md)**</td><td> 返回一个 **[Vector](vector.zh.md)** 的 **[ShellProperty](shellproperty.zh.md)** 对象，它表示系统上可用的所有可能的 shell 属性。你可以选择将通配符 *pattern* 作为第一个参数提供 - 如果这样做，则只返回名称与提供的模式匹配的属性。可选的 **type** 参数是一个字符串，它让你进一步限制属性列表（不区分大小写）： | | | |-------|------------------------------------------------| | **R** | 属性原始名称必须与模式匹配。 | | **D** | 属性显示名称必须与模式匹配。 | 如果两个都没有指定，则原始名称和显示名称都可以匹配。 </td></tr><tr><td> GetTempDirPath</td><td> \<int:lifetime\></td><td> *object:***[Path](path.zh.md)**</td><td> 创建一个临时文件夹（具有唯一名称），并在 **[Path](path.zh.md)** 对象中返回其路径。通过此方法创建的临时文件夹在 Opus 将自动将其删除之后具有有限的生存周期（它还将在关闭和重新启动时对其进行清理）。默认生命周期为 20 分钟；你可以使用可选参数更改此值。 </td></tr><tr><td> GetTempFile</td><td> \<string:suffix\> \<string:prefix\> \<string:flags\> \<object:window\></td><td> *object:***[文件](file.zh.md)**</td><td> 创建一个临时文件，返回可以写入的 **[文件](file.zh.md)** 对象。返回的对象支持读取和写入，无需再次打开文件（尽管如果你觉得更容易，也可以这样做）。你可以使用 **[文件](file.zh.md)**.path 属性获取文件名。可以指定一个可选文件后缀 **suffix**；如果没有提供（或传递了一个空字符串），则默认为“.tmp”。还可以指定一个可选的 **prefix** 前缀；如果没有提供（或者传递了一个空字符串），则默认为“dop”。在后缀和前缀之间，Opus 将在名称中插入额外的字符以确保它是唯一的。例如，**DOpus.FSUtil.GetTempFilePath(".txt","cat-")** 可能会为文件路径生成 *C:\Users\Leo\AppData\Local\Temp\cat-202106230928470962.txt*。可选的 **flags** 参数可以包含以下一个或多个字母（不区分大小写）： | | | |-------|------------------------------------------------------------------| | **d** | close 时删除。在关闭文件时会自动删除文件。 | | **p** | 允许删除。其它的进程可以删除这些文件。 | | **r** | 可共享读取。其它进程可以读取文件。 | | **w** | 可共享写入。其它进程可以写入文件。 | 读取、写入和删除共享模式会影响在文件仍然打开时允许其它进程执行的操作。当文件关闭后（假设它没有被自动删除），其它进程始终可以自由读取、写入或删除文件。当使用 close-on-close 时，其它进程可能无法打开文件，除非在打开文件时明确允许删除该文件。可选的 **window** 参数允许你将 **文件** 对象与 **[标签](tab.zh.md)** 或 **[列表](lister.zh.md)** 关联，如果 Opus 需要显示任何对话框（例如 UAC 提升对话框），将使用该标签或列表。 </td></tr><tr><td> GetTempFilePath</td><td> \<string:suffix\> \<string:prefix\></td><td> *object:***[路径](path.zh.md)**</td><td> 创建一个临时文件（具有唯一名称），并在 **[路径](path.zh.md)** 对象中返回它的路径。可以指定一个可选文件后缀 **suffix**；如果没有提供（或传递了一个空字符串），则默认为“.tmp”。还可以指定一个可选的 **prefix** 前缀；如果没有提供（或者传递了一个空字符串），则默认为“dop”。在后缀和前缀之间，Opus 将在名称中插入额外的字符以确保它是唯一的。例如，**DOpus.FSUtil.GetTempFilePath(".txt","cat-")** 可能会为文件路径生成 *C:\Users\Leo\AppData\Local\Temp\cat-202106230928470962.txt*。 </td></tr><tr><td> GetType</td><td> \<string:path\> \<string:flags\></td><td> *string*</td><td> 返回一个字符串指示指定文件路径的项目类型。如果路径不存在，则字符串将是 **file**、**dir** 或 **invalid**。可选的 **flags** 参数用于控制压缩包的行为。通常，压缩包将被报告为 **dir**，但是，如果你为 flags 参数指定 **“a”**，它将被报告为 **file**。此方法与 **PathType** 不同，**PathType** 告诉你的是底层“命名空间”类型，而不是某项只是文件还是文件夹。 </td></tr><tr><td> Hash</td><td> \<string:path\> 或 \<object:**[二进制](blob.zh.md)**\> \<string:type\></td><td> *string* 或 *object:***[矢量](vector.zh.md)**</td><td> 计算指定文件或 **[二进制](blob.zh.md)** 的校验和。默认情况下，计算 MD5 哈希，但是你可以使用可选的 **type** 参数来更改哈希/校验和算法。有效值（不区分大小写）是 **md5**、**blake3**、**sha1**、**sha256**、**sha512**、**crc32**、**crc32_php** 和 **crc32_php_rev**。你还可以同时指定多种类型（例如 *“md5,sha1,sha256”*），在这种情况下，将同时计算指定的校验和，并将结果作为 *string* 的 **[矢量](vector.zh.md)** 返回（按你请求它们的顺序返回）。与其它算法不同, CRC32 更多地是一个概念, 而不是一个明确定义的标准。我们提供了最常遇到的三个 CRC32 实现： - *CRC32* 在 Windows 界中最常见，与 7-Zip 和 PKZip 等工具称之为“CRC32”以及 PHP 称之为“CRC32b”的相匹配。 - *CRC32_PHP* 不太常见，与 BZIP2 使用的以及 PHP 默认输出的相匹配。 - *CRC32_PHP_REV* 与 *CRC32_PHP* 相同，但是结果的字节顺序与一些工具的输出相反。 *示例（VBScript）：* DOpus.FSUtil.Hash("C:\Windows\Notepad.exe","md5") </td></tr><tr><td> NewFileAttr</td><td> *\<attributes\>*</td><td> *object:***[文件属性](fileattr.zh.md)**</td><td> 创建一个新的 **[文件属性](fileattr.zh.md)** 对象，它表示文件属性。可以通过传递表示要打开的属性（例如 *“hsr”*）或另一个 **[文件属性](fileattr.zh.md)** 对象的字符串来初始化新对象。如果你不传递一个值，新对象将默认关闭所有属性。 </td></tr><tr><td> NewFileSize</td><td> *\<size\>* 或 \<string:"s"\> *\<size\>*</td><td> *object:***[文件大小](filesize.zh.md)**</td><td> 创建新的 **[文件大小](filesize.zh.md)** 对象，使其更容易处理 64 位文件大小。你可以使用多个数据类型初始化它（*int*、*string*、*decimal*、*currency*、另一个 **[文件大小](filesize.zh.md)** 对象或包含恰好 1、2、4 或 8 个字节的 **[二进制](blob.zh.md)**）。你可以通过前面加上 **\$** 或 **0x** 来使用十六进制字符串。 *示例（VBScript）：* DOpus.FSUtil.NewFileSize(1024) 当仅指定一个 size 时，结果将是一个 *无符号* 值，这意味着它可以表示较大的 size 值，但不能表示负值。要创建一个 *有符号* 值，请将 **“s”** 指定为第一个参数，将 size 指定为第二个参数。区分大小写；它必须是小写“s”。 *示例（VBScript）：* DOpus.FSUtil.NewFileSize("s", -1024) </td></tr><tr><td> NewPath</td><td> \<string:path\></td><td> *object:***[路径](path.zh.md)**</td><td> 创建一个新的 **[路径](path.zh.md)** 对象，并将其初始化为提供的路径字符串。 </td></tr><tr><td> NewWild</td><td> \<string:pattern\> \<string:flags\></td><td> *object:***[通配符](wild.zh.md)**</td><td> 创建一个新的 **[通配符](wild.zh.md)** 对象。如果提供了 **pattern** 和 **flags**，则将自动解析该模式；否则，在使用之前，你必须对返回的对象调用 **Parse** 方法。有关有效标志的列表，请参见 **[通配符](wild.zh.md).Parse** 方法的说明。 </td></tr><tr><td> OpenFile</td><td> \<string:path\> 或 \<object:**[二进制](blob.zh.md)**\> \<string:mode\> \<object:window\> 或 \<string:elevation\></td><td> *object:***[文件](file.zh.md)**</td><td> 打开或创建一个文件，并返回一个 **[文件](file.zh.md)** 对象，让你可以以二进制数据形式访问其内容。即使无法打开文件，也始终返回一个 **File** 对象。在创建对象后，立即检查返回对象上的 **File.error** 以查看是否成功打开了文件。即使没有打开文件，返回的对象的某些方法仍可能起作用。例如，如果文件存在但权限阻止您打开它，您仍然可以更改其属性，反之亦然。第一个参数可以是： - 指定要打开的文件的字符串或 **[Path](path.zh.md)** 对象。 - 一个现有的 **[Blob](blob.zh.md)** 对象，用于创建一个 **[File](file.zh.md)** 对象，该对象可让您对一段内存进行读/写流访问。在打开 **[Blob](blob.zh.md)** 时，创建的对象将始终处于 *读写模式*，而其余参数（**mode** 和 **window**/**elevation**) 不使用，也不需要指定。在打开文件时，可选的 **mode** 参数指定如何打开它（区分大小写）： | | | |--------|---------------------------------------------------------------------------| | **r** | *读取模式*。该文件可以读取，但不能写入。（这是默认设置。） | | **w** | *写入模式*。该文件可以写入，但不能读取。 | | **rw** | *读写模式*。可以从同一个对象读取和写入文件。 | 在以 *写入模式* 或 *读写模式* 打开时，您可以指定控制如何创建或打开文件的其它 **mode** 标志（区分大小写）： | | | |-------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **c** | 仅当文件不存在时才创建一个新文件。如果文件已存在，则该调用将失败。 | | **a** | 始终创建新文件。如果文件已存在，它将被覆盖，即截断为零长度。（如果单独使用 **w** 或 **rw**，这是默认设置。） | | **e** | 打开现有文件。如果文件不存在，该调用将失败。 | | **o** | 打开现有文件。如果文件不存在，则创建该文件。 | | **t** | 截断现有文件。如果文件存在，它将被截断为零长度。如果文件不存在，则该调用将失败。 | **mode** 标志还可以包括以下字母（区分大小写）： | | | |-------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **d** | 关闭时删除。关闭时文件将自动删除。（如果其它文件也处于打开状态，则直到所有内容都关闭之前，文件将不会被删除。） | | **f** | 强制。如果写保护属性阻止打开文件以进行写入，Opus 将清除该文件的文件的只读属性；否则，尝试打开只读文件以进行写入将失败。例如，“**wof**”类似于“**wo**”模式，但也会清除只读属性。 | | **m** | 修改模式。如果您希望使用 **File** 对象来读取或修改文件属性，或者获取文件大小而无需读取或写入实际文件内容，请使用此功能。 | | **p** | 允许删除。其它进程可以在文件关闭之前删除文件，尽管任何删除操作都不会在文件关闭之前发生。通过此方法打开的文件始终允许其它读写器和编写器。您的脚本不应假设对文件或其内容拥有独占锁。 | 在打开已被其它内容标记为删除的现有文件（包括已在 *关闭时删除* 模式下打开的文件）时，必须指定 **p**（允许删除）标志。非 Windows 文件系统可能具有不同的锁定和共享规则。Opus 将向它们传递请求的标志，但它们的最终行为取决于它们。可选的第三个参数接受 **window** 对象或指示 **elevation** 模式的字符串。此参数会影响打开文件时可能触发的 UAC 提升提示（以及其它可能的 UI 元素）。它可以是以下之一： - 当需要提升且尚未获取提升时，UAC 提示将出现在其上的 Opus **[Tab](tab.zh.md)** 或 **[文件窗口](lister.zh.md)** 对象。 - 字符串“**NoElevate**”，用于在打开此文件时完全阻止 UAC 提升。 - 字符串“**ElevateNoAsk**”，用于在其它内容已经获取了提升的情况下（例如，之前的 **OpenFile** 调用），防止 UAC 提示，但仍提升权限。 *示例（VBScript）：* Set F = DOpus.FSUtil.OpenFile("C:\Test.txt","wrcf","NoElevate") </td></tr><tr><td> PathType</td><td> \<string:path\></td><td> *string*</td><td> 返回一个字符串，指示指定文件路径的底层“命名空间”类型。可能的值为： | | | |-------------|---------------------------------------------------------------------------------| | **shell** | 路径指向 Windows shell - 例如，如“此电脑”的虚拟文件夹 | | **filesys** | 路径是真实的文件系统路径 - 例如，C:\Windows | | **ftp** | 路径是 FTP 路径 | | **zip** | 路径是 zip 文件 | | **mtp** | 路径是 MTP 路径（即手机或平板电脑等便携式设备） | | **lib** | 路径是库 | | **coll** | 路径是集合 | | **plugin** | 路径是由插件提供的命名空间，很可能是压缩包（但不是 Zip） | 此方法不同于 **GetType**，**GetType** 会告诉您某是否是文件或目录。 </td></tr><tr><td> ReadDir</td><td> \<string:path\> \<string:flags\></td><td> *object:***[FolderEnum](folderenum.zh.md)**</td><td> 返回一个 **[FolderEnum](folderenum.zh.md)** 对象，这个对象允许您枚举指定文件夹的内容。可选的 **flags** 字符串可包括零个或多个标志字符（不区分大小写）： | | | |-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **r** | 递归地枚举文件夹，列出文件夹、其子文件夹、子文件夹的子文件夹等的内容。 | | **l** | 跳过链接。在递归枚举文件夹时，阻止遍历符号链接和连接。 | | **s** | Shell 枚举。询问 Windows Shell 来枚举非文件系统文件夹。例如，可以使用 **ReadDir("/quickaccess","s")** 来枚举 Windows 10 上的 *快速访问* 文件夹；它不使用“**s**”无法工作，因为快速访问不是真正的文件系统目录。 | 如果您不需要任何标志，则完全跳过第二个参数。您可能会看到较旧的脚本将 **True** 和 **False** 作为第二个参数传递，以打开和关闭递归；这已弃用，但仍受支持以保持兼容性。 </td></tr><tr><td> Resolve</td><td> \<string:path\> \<string:flags\></td><td> *object:***[Path](path.zh.md)**</td><td> 将指定的文件路径字符串解析为其真实的文件系统路径，支持转换： - **[文件夹别名](/Manual/basic_concepts/the_lister/navigation/aliases.zh.md)** 为它们指向的真实路径。 - **库** 和 **文件集合** 项为其真实的文件系统路径。 - **{apppath\|*appname*}** 形式的应用程序路径。 - 环境变量。 - 可选择将 **连接** 和 **符号链接** 解析为其目标。传递不需要解析的路径是安全的；路径将按原样返回，因此您可以在不需要首先检查的情况下对此进行调用。通常将当前目录传递到外部软件的脚本应该首先对路径调用 Resolve，否则它们有可能将诸如 */desktop* 这样的别名传递给无法理解它们的对象。可选的 **flags** 字符串可以包括以下字母（不区分大小写）： | | | |-------|-------------------------------------------------------------| | **j** | 将连接和符号链接解析为其目标文件夹 | 请注意，**[Path](path.zh.md)** 对象还有一个类似的 **Resolve** 方法，它可以就地修改它们。 </td></tr><tr><td> SameDrive</td><td> \<string:path1\> \<string:path2\> \<string:flags\></td><td> *bool*</td><td> 如果两个指定路径都指向相同的驱动器或分区，则返回 **True**。可选的 **flags** 字符串可以包含以下一个或多个字母（区分大小写）： | | | |-------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **c** | 将 **CD 刻录暂存区** 视为 CD（或其它可刻录的光学媒体）本身。 | | **m** | 处理 **NTFS 挂载点**。（如果任一路径可能位于实际上指向不同驱动器的挂载点下方，则速度较慢但更准确）。 | | **r** | 仅真实路径。（跳过仅对 FTP 站点和 MTP 设备等内容有用的额外的处理）。 | | **s** | 测试路径是否通过 Windows **subst** 命令创建的驱动器号指向同一驱动器。 | | **u** | 比较 **FTP 用户**。（默认情况下，如果 FTP 路径指向相同的 FTP 站点，则认为其为“同一驱动器”。**u** 标志增加了两个路径都具有相同用户名这一要求）。 | | **z** | 如果 **path1** 位于 Zip 文件或其它压缩包文件中，只有当 **path2** 是压缩包文件本身或位于同一压缩包文件中时，才认为其位于“同一驱动器”上。 | | **Z** | 如果 **path1** 位于 Zip 文件或其它压缩包文件中，只有当 **path2** 位于同一压缩包文件中时，才认为其位于“同一驱动器”上。 | 当同时未指定 **z** 和 **Z** 时，本质上将压缩包文件视为普通目录并将其视为位于压缩包文件所在的同一驱动器上的任何路径的“同一驱动器”上，包括该驱动器上的其它压缩包文件路径。 </td></tr><tr><td> WatchChanges</td><td> \<string:id\> \<string:path\> \<string:flags\></td><td> *int*</td><td> 建立监视文件夹或文件是否发生变化。成功时返回 **0**，失败时返回错误代码。当监视的文件或文件夹发生更改时，将触发脚本的 [OnFilesystemChange](/Manual/reference/scripting_reference/scripting_events/onfilesystemchange.zh.md) 事件。 **id** 参数允许您为此观察者提供一个 ID，此 ID 用于在发生更改时识别它。**dir** 是一个文件系统文件夹的完整路径，如果设置了 **i** 标志，则为一个文件。可选标志为： | | | |-------|-----------------------------------------------------------------| | **f** | 监视文件夹中的文件更改（例如，创建文件） | | **d** | 监视文件夹中的目录更改（例如，创建目录） | | **r** | 递归 - 监视子文件夹 | | **a** | 监视文件属性更改 | | **s** | 监视文件大小更改 | | **w** | 监视上次写入时间更改 | | **i** | 监视单个文件，而不是文件夹 | 使用 **CancelWatchChanges** 方法取消监视。将下列英文文本翻译成中文：