文件对象

以平台无关的方式表示本地文件系统中的文件。除非另有说明，所有属性和方法都会自动解析文件系统别名，并对原始文件进行操作。

文件对象构造函数

File ( [ path ] ); // 可能返回一个文件夹对象
new File ([ path ] ); // 始终返回一个文件对象

要创建一个文件对象，请使用 File 函数或 new 操作符。构造函数接受完整或部分路径名，并返回新对象。

文件的 CRLF 序列预设为系统默认值，编码预设为默认系统编码。

参数	类型	描述
`path`	String	可选。与此对象关联的文件的绝对或相对路径，以平台特定或 URI 格式指定；请参阅指定路径。对象中存储的值是绝对路径。
		路径不必引用现有文件。如果未提供路径，则生成一个临时名称。
		如果路径引用现有文件夹：
		- `File` 函数返回一个文件夹对象而不是文件对象。
		- `new` 操作符返回一个具有相同名称的不存在文件的文件对象。
		!!! 警告
		在 MacOS 上的 After Effects 中，如果 `path.length` 超过 1002，After Effects 会崩溃。
		此问题已在 MacOS 10.11.6 和 After Effects 13.8 及 14.0 上报告。

文件类属性

此属性作为文件类的静态属性可用。无需创建实例即可访问它。

File.fs

File.fs

描述

文件系统的名称。

可能的值：

Windows
Macintosh
Unix

类型

字符串。只读。

文件类方法

这些函数作为文件类的静态方法可用。无需创建实例即可调用它们。

File.decode()

File.decode(uri)

描述

按照 RFC 2396 的要求解码指定的字符串。

所有特殊字符必须以 UTF-8 编码，并存储为以百分号开头后跟两个十六进制数字的转义字符。特殊字符是数值大于 127 的字符，除了以下字符：

/ - _ . ! ~ * ' ( )

例如，字符串 "my%20file" 被解码为 "my<br/>file"。

参数

参数	类型	描述
`uri`	String	要解码的编码字符串。

字符串

File.encode()

File.encode(name)

描述

按照 RFC 2396 的要求编码指定的字符串。

所有特殊字符都以 UTF-8 编码，并存储为以百分号开头后跟两个十六进制数字的转义字符。例如，字符串 "my file" 被编码为 "my%20file"。特殊字符是数值大于 127 的字符，除了以下字符：

/ - _ . ! ~ * ' ( )

参数

参数	类型	描述
`name`	String	要编码的字符串。

字符串

File.isEncodingAvailable()

File.isEncodingAvailable( name)

描述

检查给定的编码是否可用。

参数

参数	类型	描述
`name`	String	编码名称。典型值为 `"ASCII"`、`"binary"` 或 `"UTF-8"`。请参阅文件和文件夹支持的编码名称。

布尔值。如果系统支持指定的编码，则为 true，否则为 false。

File.openDialog()

File.openDialog([prompt="", filter="", multiSelect=false])

描述

打开内置的平台特定文件浏览对话框，用户可以在其中选择现有文件或多个文件，并创建新的文件对象来表示所选文件。

参数

参数	类型	描述
`prompt`	String	可选。提示文本，如果对话框允许提示。
`filter`	String or Function	可选。限制对话框中显示的文件类型的过滤器。
		在 Windows 中，过滤器表达式，例如 `"JavaScript:.jsx;All files:.*"`
		!!! 提示
		- 用分号 (`;`) 分隔表达式以同时过滤这些类型；（显示 `jsx` 和 `all`）
		- 用逗号 (`,`) 分隔以填充过滤器下拉列表，以便一次选择一种类型（显示 `jsx` 或 `all`）
		在 Mac OS 中，过滤器函数接受文件实例并返回 `true` 如果文件应包含在显示中，否则返回 `false`。
`multiSelect`	Boolean	可选。当为 `true` 时，用户可以选择多个文件，返回值为数组。默认为 `false`。

所选文件的文件对象，如果选择了多个文件，则返回文件对象数组。

如果用户取消，返回 null。

File.saveDialog()

File.saveDialog(prompt[, preset=""])

描述

打开内置的平台特定文件浏览对话框，用户可以在其中选择现有文件位置以保存信息，并创建新的文件对象来表示所选文件位置。

参数

参数	类型	描述
`prompt`	String	包含提示文本的字符串，如果对话框允许提示。
`filter`	String or Function	可选。仅限 Windows。限制对话框中显示的文件类型的过滤器。
		过滤器表达式，例如 `"JavaScript:.jsx;All files:.*"`
		!!! 提示
		- 用分号 (`;`) 分隔表达式以同时过滤这些类型；（显示 `jsx` 和 `all`）
		- 用逗号 (`,`) 分隔以填充过滤器下拉列表，以便一次选择一种类型（显示 `jsx` 或 `all`）

所选文件位置的文件对象。

如果用户取消，返回 null。

文件对象属性

这些属性可用于 File 对象。

File.absoluteURI

fileObj.absoluteURI

描述

引用文件的完整路径名，以 URI 表示法表示。

类型

字符串。只读。

File.alias

fileObj.alias

描述

当为 true 时，对象引用文件系统别名或快捷方式。

类型

布尔值。只读。

File.created

fileObj.created

描述

引用文件的创建日期，如果对象未引用磁盘上的文件，则为 null。

类型

日期。只读。

File.creator

fileObj.creator

描述

在 Mac OS 中，文件创建者为一个四字符字符串。在 Windows 或 UNIX 中，值为 "????"。

类型

字符串。只读。

File.displayName

fileObj.displayName

描述

引用文件的本地化名称，不带路径。

类型

字符串。只读。

File.encoding

fileObj.encoding

描述

获取或设置后续读/写操作的编码。编码常量之一，列在文件和文件夹支持的编码名称中。

如果值未被识别，则使用系统默认编码。

特殊编码器 "BINARY" 用于读取二进制文件。它将文件的每个字节存储为一个 Unicode 字符，无论任何编码。写入时，每个 Unicode 字符的低字节被视为要写入的单个字节。

类型

字符串

File.eof

fileObj.eof

描述

当为 true 时，读取尝试导致当前位置位于文件末尾，或文件未打开。

类型

布尔值。只读。

File.error

fileObj.error

描述

描述最后一个文件系统错误的消息；请参阅文件访问错误消息。

通常由文件系统设置，但脚本也可以设置它。设置此值会清除任何错误消息并重置已打开文件的错误位。

如果没有错误，则为空字符串。

类型

字符串

File.exists

fileObj.exists

描述

当为 true 时，此对象引用文件系统中实际存在的文件或文件系统别名。

类型

布尔值。只读。

File.fsName

fileObj.fsName

描述

引用文件的平台特定完整路径名。

类型

字符串。只读。

File.fullName

fileObj.fullName

描述

引用文件的完整路径名，以 URI 表示法表示。

类型

字符串。只读。

File.hidden

fileObj.hidden

描述

当为 true 时，文件不会显示在平台特定的文件浏览器中。可读写。如果对象引用文件系统别名或快捷方式，则标志在别名上更改，而不是在原始文件上更改。

类型

布尔值

File.length

fileObj.length

描述

文件的大小（以字节为单位）。只能为未打开的文件设置，在这种情况下，它会将文件截断或填充 0 字节到新长度。

类型

数字

File.lineFeed

fileObj.lineFeed

描述

文件系统中换行符的写入方式。

可能的值：

Windows - Windows 风格
Macintosh - Mac OS 风格
Unix - UNIX 风格

类型

字符串

File.localizedName

fileObj.localizedName

描述

引用文件的绝对 URI 的文件名部分的本地化版本，不带路径规范。

类型

字符串。只读。

File.modified

fileObj.modified

描述

引用文件的最后修改日期，如果对象未引用磁盘上的文件，则为 null。

类型

日期。只读。

File.name

fileObj.name

描述

引用文件的绝对 URI 的文件名部分，不带路径规范。

类型

字符串。只读。

File.parent

fileObj.parent

描述

包含此文件的文件夹对象。

类型

文件夹。只读。

File.path

fileObj.path

描述

引用文件的绝对 URI 的路径部分，不带文件名。

类型

字符串。只读。

File.readonly

fileObj.readonly

描述

当为 true 时，防止文件被修改或删除。如果引用的文件是文件系统别名或快捷方式，则标志在别名上更改，而不是在原始文件上更改。

类型

布尔值

File.relativeURI

fileObj.relativeURI

描述

引用文件的路径名，以 URI 表示法表示，相对于当前文件夹。

类型

字符串。只读。

File.type

fileObj.type

描述

文件类型为四字符字符串。

在 Mac OS 中，为 Mac OS 文件类型。
- 在 Windows 中，.EXE 文件为 "appl"，.DLL 文件为 "shlb"，其他文件为 "TEXT"。

如果文件不存在，值为 "????"。

类型

字符串。只读。

文件对象方法

这些函数可用于文件对象。

File.changePath()

fileObj.changePath(path)

描述

更改引用文件的路径规范。

参数

参数	类型	描述
`path`	String	新路径，绝对路径或相对于当前文件夹的路径。

布尔值。成功时为 true。

File.close()

fileObj.close()

描述

关闭此打开的文件。

布尔值。成功时为 true，如果有 I/O 错误则为 false。

File.copy()

fileObj.copy(target)

描述

将此对象引用的文件复制到指定的目标位置。

解析任何别名以找到源文件。如果目标位置存在文件，则覆盖它。

参数

参数	类型	描述
`target`	String or File object	目标位置的 URI 路径，或引用目标位置的文件对象。

布尔值。如果复制成功则为 true，否则为 false。

File.createAlias()

fileObj.createAlias( [path])

描述

将当前文件创建为指向指定文件的文件系统别名或快捷方式。该文件对象引用的目标文件在磁盘上必须尚未存在。

参数

参数	类型	描述
`path`	String	目标文件的路径。

返回值

布尔值。操作成功返回 true，否则返回 false。

File.execute()

fileObj.execute()

描述

使用适当的应用程序打开此文件，就像在文件浏览器中双击它一样。

你可以使用此方法来运行脚本、启动应用程序等。

返回值

布尔值。如果应用程序启动成功，立即返回 true。

File.getRelativeURI()

fileObj.getRelativeURI([basePath])

描述

获取此文件的相对 URI（以 URI 表示法），相对于指定的基路径。如果未提供基路径，则 URI 相对于当前文件夹的路径。

参数

参数	类型	描述
`basePath`	String	可选。包含相对 URI 基路径的字符串。默认为当前文件夹。

返回值

字符串

File.open()

fileObj.open(mode[, type][, creator])

描述

打开引用的文件以进行后续读写操作。该方法会解析所有别名以找到文件。

该方法尝试检测打开文件的编码。它会读取当前位置的几个字节，并尝试检测字节顺序标记字符 0xFFFE。如果找到，当前位置会移动到检测到的字符之后，并将编码属性设置为以下字符串之一：UCS-2BE、UCS-2LE、UCS4-BE、UCS-4LE 或 UTF-8。如果未找到标记字符，则检查当前位置的零字节，并假设为上述格式之一（UTF-8 除外）。如果所有尝试都失败，则将编码属性设置为系统编码。

小心不要多次打开同一个文件。操作系统通常允许这样做，但如果你使用两个不同的 File 对象开始写入文件，可能会破坏数据。

参数

参数	类型	描述
`mode`	String	表示读写模式的字符串。可选值：
		- `r`：（读取）打开文件用于读取。如果文件不存在或无法找到，调用失败。
		- `w`：（写入）打开文件用于写入。如果文件存在，其内容会被销毁。如果文件不存在，则创建一个新的空文件。
		- `e`：（编辑）打开现有文件用于读写。
		- `a`：（追加）以追加模式打开文件，并将当前位置移动到文件末尾。
`type`	String	可选。在 Mac OS 中，新创建文件的类型，为一个 4 字符的字符串。在 Windows 和 UNIX 中忽略。
`creator`	String	可选。在 Mac OS 中，新创建文件的创建者，为一个 4 字符的字符串。在 Windows 和 UNIX 中忽略。

返回值

布尔值。如果文件成功打开，返回 true，否则返回 false。

File.openDlg()

fileObj.openDlg([prompt=""][, filter=""][, multiSelect=false])

描述

打开内置的平台特定文件浏览对话框，用户可以在其中选择一个或多个现有文件，并创建新的 File 对象来表示所选文件。与类方法 openDialog() 不同，此方法将当前文件夹预设为此 File 对象的父文件夹，并将当前文件预设为此对象关联的文件。

参数

参数	类型	描述
`prompt`	String	可选。对话框的提示文本（如果对话框支持提示）。
`filter`	String 或 Function	可选。限制对话框中显示的文件类型的过滤器。
		在 Windows 中，过滤器表达式，例如 `"JavaScript:.jsx;All files:.*"`
		!!! 提示
		- 用分号 (`;`) 分隔表达式以同时过滤这些类型（显示 `jsx` 和 `all`）
		- 用逗号 (`,`) 分隔以填充过滤器下拉菜单，一次选择一个类型（显示 `jsx` 或 `all`）
		在 Mac OS 中，过滤器函数，接受一个 File 实例并返回 `true` 以包含在显示中，否则返回 `false`。
`multiSelect`	Boolean	可选。当为 `true` 时，用户可以选择多个文件，返回值为数组。默认为 `false`。

返回值

如果用户点击确定，返回所选文件或文件夹的 File 或 Folder 对象，或对象数组。

如果用户取消，返回 null。

File.read()

fileObj.read([chars])

描述

从当前位置开始读取文件内容。

返回一个包含最多指定数量字符的字符串。

参数

参数	类型	描述
`chars`	Number	可选。指定要读取的字符数的整数。默认从当前位置读取到文件末尾。如果文件已编码，可能会读取多个字节以创建单个 Unicode 字符。

返回值

字符串

File.readch()

fileObj.readch()

描述

从文件的当前位置读取单个文本字符。换行符被识别为 CR、LF、CRLF 或 LFCR 对。如果文件已编码，可能会读取多个字节以创建单个 Unicode 字符。

返回包含该字符的字符串。

返回值

字符串

File.readln()

fileObj.readln()

描述

从文件的当前位置读取单行文本，并返回字符串。换行符被识别为 CR、LF、CRLF 或 LFCR 对。如果文件已编码，可能会读取多个字节以创建单个 Unicode 字符。

返回包含文本的字符串。

返回值

字符串

File.remove()

fileObj.remove()

描述

从磁盘中立即删除与此对象关联的文件，而不将其移动到系统回收站。

不解析别名；而是删除引用的别名或快捷方式文件本身。

无法撤销。建议在删除之前提示用户确认。

返回值

布尔值。如果文件成功删除，返回 true。

File.rename()

fileObj.rename(newName)

描述

重命名关联的文件。

不解析别名，但重命名引用的别名或快捷方式文件本身。

参数

参数	类型	描述
`newName`	String	新文件名（不带路径）。

返回值

布尔值。成功时返回 true。

File.resolve()

fileObj.resolve()

描述

如果此对象引用别名或快捷方式，则解析该别名并返回一个新的 File 对象，该对象引用别名解析到的文件系统元素。

返回值

新的 File 对象，如果此对象未引用别名或别名无法解析，则返回 null。

File.saveDlg()

fileObj.saveDlg([prompt=""][, preset=""])

描述

打开内置的平台特定文件浏览对话框，用户可以在其中选择现有文件位置以保存信息，并创建一个新的 File 对象来表示所选文件。

与类方法 saveDialog() 不同，此方法将当前文件夹预设为此 File 对象的父文件夹，并将文件预设为此对象关联的文件。

参数

参数	类型	描述
`prompt`	String	可选。对话框的提示文本（如果对话框支持提示）。
`filter`	String 或 Function	可选。限制对话框中显示的文件类型的过滤器。
		在 Windows 中，过滤器表达式，例如 `"JavaScript:.jsx;All files:.*"`
		!!! 提示
		- 用分号 (`;`) 分隔表达式以同时过滤这些类型（显示 `jsx` 和 `all`）
		- 用逗号 (`,`) 分隔以填充过滤器下拉菜单，一次选择一个类型（显示 `jsx` 或 `all`）
		在 MacOS 中未使用。

返回值

所选文件的 File 对象。

如果用户取消，返回 null。

File.seek()

fileObj.seek(pos[, mode=0])

描述

将文件指针移动到指定位置。新位置不能小于 0 或大于当前文件大小。

参数

参数	类型	描述
`pos`	Number	新的当前位置（以字节为单位的偏移量），根据模式从文件开头、当前位置或末尾计算。
`mode`	Number	可选。查找模式，可选值：
		- `0`：查找绝对位置，其中 pos=0 是文件的第一个字节。这是默认值。
		- `1`：相对于当前位置查找。
		- `2`：从文件末尾向后查找。

返回值

布尔值。如果位置已更改，返回 true。

File.tell()

fileObj.tell()

描述

获取当前位置索引（以字节为单位的偏移量，从文件开头计算）。

返回值

数字

File.write()

fileObj.write( text[, text...]...)

描述

将指定的文本写入文件的当前位置。对于编码文件，写入单个 Unicode 字符可能会写入多个字节。

小心不要写入在另一个应用程序或对象中打开的文件，因为这可能会覆盖现有数据。

参数

参数	类型	描述
`text`	String	要写入的一个或多个字符串，会连接成单个字符串。

返回值

布尔值。成功时返回 true。

File.writeln()

fileObj.writeln (text[, text...]...)

描述

将指定的文本写入文件的当前位置，并附加一个由 linefeed 属性指定风格的换行序列。对于编码文件，写入单个 Unicode 字符可能会写入多个字节。

小心不要写入在另一个应用程序或对象中打开的文件，因为这可能会覆盖现有数据。

参数

参数	类型	描述
`text`	String	要写入的一个或多个字符串，会连接成单个字符串。

返回值

布尔值。成功时返回 true。