内置函数签名

ContextGetBoundingBoxWidth

ContextGetBoundingBoxWidth() → Integer

返回包围整个所绘手势的矩形的宽度，以像素为单位。在手势之外返回 0。

参数

无参数。

返回值

以像素为单位的宽度；在手势之外为 0。

ContextGetBoundingBoxX

ContextGetBoundingBoxX() → Integer

返回包围整个所绘手势的矩形的左边缘，以虚拟屏幕像素为单位。在手势之外返回 0。

参数

无参数。

返回值

以虚拟屏幕像素为单位的左边缘；在手势之外为 0。

ContextGetBoundingBoxY

ContextGetBoundingBoxY() → Integer

返回包围整个所绘手势的矩形的上边缘，以虚拟屏幕像素为单位。在手势之外返回 0。

参数

无参数。

返回值

以虚拟屏幕像素为单位的上边缘；在手势之外为 0。

16 个示例: 一个手势，多个选项, 切换手势所在窗口的最大化状态, 将窗口置顶, 循环切换窗口透明度, 将窗口贴靠到光标下方的 3×2 网格单元格中, 将窗口移到下一个显示器, 记住并还原窗口位置, 检查窗口的子控件, 将窗口隐藏到托盘, 触发上下文知道的一切, 按笔画按钮分支, 将光标限制在窗口内 5 秒, 按住 Ctrl 时改变行为, 保存在 Storage 中的列表, 将窗口发送到指定的显示器, 将代码片段用作可重用函数

ContextGetButtonState

ContextGetButtonState() → Text

返回全局鼠标按钮事件是在按下按钮时还是在释放按钮时触发的。只有全局鼠标按钮事件的脚本才会获得值。

参数

无参数。

返回值

按下时为 'down'，释放时为 'up'；对于任何其他触发方式（包括手势），返回空文本。

ContextGetControl

ContextGetControl() → Window

返回触发器所针对的确切控件，例如手势或鼠标下方的编辑框，或者热键或文本扩展触发时具有焦点的窗口。若要获取其应用程序窗口，请使用 ContextGetWindow。

参数

无参数。

返回值

以 Window 形式返回的控件；当触发器没有窗口时（例如在计时器、文件夹监视、串口监视器或 Load 脚本中），返回空窗口。

ContextGetGestureName

ContextGetGestureName() → Text

返回为运行此操作而绘制的手势的名称。这是手势本身的名称，而不是操作的名称；请参阅 ContextGetActionName。

参数

无参数。

返回值

手势的名称；在手势之外返回空文本。

2 个示例: 触发上下文知道的一切, 追加到日志文件

ContextGetPointCount

ContextGetPointCount() → Integer

返回沿所绘手势记录的光标位置数。使用 ContextGetPointX 和 ContextGetPointY 逐个读取。

参数

无参数。

返回值

点的数量；在手势之外为 0。

3 个示例: 手势笔画的长度, 触发上下文知道的一切, 笔画朝哪个方向？

ContextGetPointX

ContextGetPointX(index: Integer) → Integer

返回所绘手势中一个已记录点的水平屏幕位置，以虚拟屏幕像素为单位。

参数

index: Integer — 从 0 开始的点编号，范围为 0 到 ContextGetPointCount() 减 1。点 0 是手势的起点。

返回值

x 坐标；如果 index 超出范围或该操作不是由手势触发的，则为 0。

2 个示例: 手势笔画的长度, 笔画朝哪个方向？

ContextGetPointY

ContextGetPointY(index: Integer) → Integer

返回所绘手势中一个已记录点的垂直屏幕位置，以虚拟屏幕像素为单位。

参数

index: Integer — 从 0 开始的点编号，范围为 0 到 ContextGetPointCount() 减 1。点 0 是手势的起点。

返回值

y 坐标；如果 index 超出范围或该操作不是由手势触发的，则为 0。

2 个示例: 手势笔画的长度, 笔画朝哪个方向？

ContextGetSerialMonitorName

ContextGetSerialMonitorName() → Text

返回其接收到的行启动了此脚本的串口监视器的名称，即传给 SerialMonitorCreate 的名称。只有串口监视器的脚本才会获得值。

参数

无参数。

返回值

监视器的名称；对于任何其他触发方式，返回空文本。

ContextGetSerialPortName

ContextGetSerialPortName() → Text

返回接收到该行的 COM 端口，例如 COM3。只有串口监视器的脚本才会获得值。

参数

无参数。

返回值

端口名称；对于任何其他触发方式，返回空文本。

ContextGetSerialTextLine

ContextGetSerialTextLine() → Text

返回到达串口并启动此脚本的文本行，例如 Arduino 用 Serial.println 发送的传感器读数。行尾符已被移除。

参数

无参数。

返回值

不含终止符的接收行；对于任何其他触发方式，返回空文本。

2 个示例: 将串口设备的按钮映射到媒体键, 将 Arduino 旋钮变成音量控制

ContextGetStrokeButton

ContextGetStrokeButton() → Integer

以 MouseButton 常量的形式返回绘制手势或触发全局鼠标按钮事件的鼠标按钮：对于 Windows 视为左键单击和右键单击的按钮（经过任何主/次按钮交换之后），为 MouseButton.Primary 或 MouseButton.Secondary，否则为 MouseButton.Middle、MouseButton.X1 或 MouseButton.X2。将其传给 MouseClick 或 MouseButtonDown 即可按下同一个按钮。

参数

无参数。

返回值

一个 MouseButton 值，例如 MouseButton.Secondary；对于任何其他触发方式，为 -1。

2 个示例: 触发上下文知道的一切, 按笔画按钮分支

ContextGetWatchAction

ContextGetWatchAction() → Text

返回被监视的文件夹中发生了什么而启动了此脚本：'created'、'deleted'、'modified'、'renamed-old-name'、'renamed-new-name' 或 'overflow'。

参数

无参数。

返回值

更改的类型；对于任何其他触发方式，返回空文本。'overflow' 表示一次到达的更改过多，必须重新检查该文件夹。

1 个示例: 监视文件夹

ContextGetWatchName

ContextGetWatchName() → Text

返回启动此脚本的文件夹监视的名称，即传给 FolderWatchCreate 的名称。只有文件夹监视的脚本才会获得值。

参数

无参数。

返回值

监视的名称；对于任何其他触发方式，返回空文本。

ContextGetWatchPath

ContextGetWatchPath() → Text

返回发生更改并启动此文件夹监视脚本的文件或文件夹的路径，相对于被监视的文件夹。

参数

无参数。

返回值

已更改项相对于被监视文件夹的路径；对于 'overflow' 更改或任何其他触发方式，返回空文本。

1 个示例: 监视文件夹

ContextGetWindow

ContextGetWindow() → Window

返回触发器所针对的应用程序窗口：手势或鼠标下方控件所在的顶级窗口，或者热键或文本扩展触发时具有焦点的控件所在的顶级窗口。

参数

无参数。

返回值

该窗口；当触发器没有窗口时（例如在计时器、文件夹监视、串口监视器或 Load 脚本中），返回空窗口。

ContextRelayGesture

ContextRelayGesture() → Bool

使用同一按钮沿同一路径，将所绘手势作为真实的鼠标拖动重放，使下方的应用程序接收到它，例如用于选择文本。拖动期间会暂缓真实输入。

参数

无参数。

返回值

如果已发送整个拖动，则为 true；如果在手势之外或 Windows 拒绝了部分输入，则为 false。

1 个示例: 放行未识别的绘制

DateTime

DateTimeFormat

DateTimeFormat(iso: Text, style: Integer) → Text · 简单

将日期和时间格式化为采用用户区域格式的可读文本，或格式化为可排序的 FileStamp。带有 Z 或 UTC 偏移量的时间会先转换为本地时间。

参数

iso: Text — ISO 8601 格式的日期和时间，与 DateTimeGetNow 返回的形式相同（2026-10-05T14:05:09-04:00）。仅有日期表示午夜；没有 Z 或偏移量时视为本地时间。年份为 1601 到 9999。
style: Integer — 一个 DateTimeStyle 常量，例如 DateTimeStyle.ShortDate、DateTimeStyle.LongDateTime 或 DateTimeStyle.FileStamp。任何其他值都会使操作因错误而停止。

返回值

格式化后的文本，例如 DateTimeStyle.FileStamp 对应 20261005-140509；如果 iso 为空，则返回空文本。不是 ISO 8601 格式的文本会使操作因错误而停止。

1 个示例: 今天的日期，以及带时间戳的文件名

DateTimeGetNow

DateTimeGetNow() → Text · 简单

以 ISO 8601 文本形式返回当前的本地日期和时间，精确到秒，并带有 UTC 偏移量。可将其传给 DateTimeFormat 或 DateTimeGetPart。

参数

无参数。

返回值

例如 2026-10-05T14:05:09-04:00 这样的文本；如果 Windows 无法报告时区，则返回空文本。

1 个示例: 今天的日期，以及带时间戳的文件名

DateTimeGetPart

DateTimeGetPart(iso: Text, part: Integer) → Integer

以数字形式返回日期和时间的一个部分：年、月、日、时、分、秒或星期几，采用本地时间。

参数

iso: Text — ISO 8601 格式的日期和时间，与 DateTimeGetNow 返回的形式相同。带有 Z 或 UTC 偏移量的时间会转换为本地时间；没有时则视为本地时间。
part: Integer — 一个 DateTimePart 常量，例如 DateTimePart.Hour 或 DateTimePart.Weekday。任何其他值都会使操作因错误而停止。

返回值

该部分的值：月为 1 到 12，小时为 0 到 23，星期几为 1（星期一）到 7（星期日）。如果 iso 为空，则为 -1。不是 ISO 8601 格式的文本会使操作因错误而停止。

1 个示例: 今天的日期，以及带时间戳的文件名

Display

DisplayGetMonitorDpiFromPoint

DisplayGetMonitorDpiFromPoint(x: Integer, y: Integer) → Integer

返回 Windows 当前为包含某个屏幕点的显示器所使用的 DPI。不在任何显示器上的点使用最近的显示器。

参数

x: Integer — 水平屏幕位置，以像素为单位。
y: Integer — 垂直屏幕位置，以像素为单位。

返回值

DPI，例如缩放比例为百分之一百时为 96，百分之一百五十时为 144。如果 Windows 无法报告，则为系统 DPI。

DisplayGetPixelColorFromPoint

DisplayGetPixelColorFromPoint(x: Integer, y: Integer) → Integer

返回某个点处屏幕像素的颜色，即该像素当前在显示器上显示的颜色。

参数

x: Integer — 像素的水平屏幕位置，以像素为单位。
y: Integer — 像素的垂直屏幕位置，以像素为单位。

返回值

以 0xRRGGBB 形式打包的 Integer 颜色值（红色位于最高字节，蓝色位于最低字节）；如果该点不在任何显示器上或无法读取屏幕，则为 -1。

1 个示例: 读取光标下的像素颜色

DisplayMonitorEnumeratedAll

DisplayMonitorEnumeratedAll() → Integer

为所有已连接的显示器创建快照，按从左到右、再从上到下的顺序排列，供 DisplayMonitorGetEnumerated 系列内置函数按索引读取。显示器发生变化后请再次调用。

参数

无参数。

返回值

快照中的显示器数量。有效索引的范围为 0 到此数量减 1。

2 个示例: 列出显示器, 将窗口发送到指定的显示器

DisplayMonitorExistsByName

DisplayMonitorExistsByName(name: Text) → Bool

检查按名称保存的显示器当前是否已连接。请在 FromName 系列矩形内置函数之前使用它，因为这些函数对于缺失的显示器和真实的 0 坐标都返回 0。

参数

name: Text — 显示器设备路径（可靠的选择，可从 DisplayMonitorGetDevicePathFromPoint 获取）或型号名称，例如 DELL U2720Q。不区分大小写；设备路径完全匹配优先于型号名称。

返回值

如果有已连接的显示器与该名称匹配，则为 true；如果没有匹配的显示器或 name 为空，则为 false。

DisplayMonitorGetDevicePathFromPoint

DisplayMonitorGetDevicePathFromPoint(x: Integer, y: Integer) → Text

返回包含某个屏幕点的显示器的设备路径：一个可以保存、稍后传给 FromName 系列内置函数的唯一名称。如果将显示器改接到其他视频端口，该路径会改变。

参数

x: Integer — 水平屏幕位置，以像素为单位。
y: Integer — 垂直屏幕位置，以像素为单位。

返回值

设备路径；如果 Windows 无法识别该显示器，则返回空文本。不在任何显示器上的点使用最近的显示器。

DisplayMonitorGetEnumeratedDevicePathAt

DisplayMonitorGetEnumeratedDevicePathAt(index: Integer) → Text

返回最近一次 DisplayMonitorEnumeratedAll 快照中某个显示器的设备路径，即一个可以保存的唯一名称。

参数

index: Integer — 显示器在最近一次 DisplayMonitorEnumeratedAll 快照中从 0 开始的位置（从左到右，再从上到下）。

返回值

设备路径；如果 index 超出范围或自快照以来显示器已发生变化，则返回空文本。

DisplayMonitorGetEnumeratedDpiAt

DisplayMonitorGetEnumeratedDpiAt(index: Integer) → Integer

返回最近一次 DisplayMonitorEnumeratedAll 快照中某个显示器在创建快照时的 DPI。

参数

index: Integer — 显示器在最近一次 DisplayMonitorEnumeratedAll 快照中从 0 开始的位置（从左到右，再从上到下）。

返回值

DPI，例如缩放比例为百分之一百时为 96，百分之一百五十时为 144；如果 index 超出范围，则为 0。

1 个示例: 列出显示器

DisplayMonitorGetEnumeratedFriendlyNameAt

DisplayMonitorGetEnumeratedFriendlyNameAt(index: Integer) → Text

返回最近一次 DisplayMonitorEnumeratedAll 快照中某个显示器报告的型号名称，例如 DELL U2720Q。两台相同的显示器报告相同的名称。

参数

index: Integer — 显示器在最近一次 DisplayMonitorEnumeratedAll 快照中从 0 开始的位置（从左到右，再从上到下）。

返回值

型号名称；如果 index 超出范围、显示器未报告名称（笔记本电脑内置屏幕常见此情况），或自快照以来显示器已发生变化，则返回空文本。

1 个示例: 列出显示器

DisplayMonitorGetEnumeratedHeightAt

DisplayMonitorGetEnumeratedHeightAt(index: Integer, workArea: Bool) → Integer

返回最近一次 DisplayMonitorEnumeratedAll 快照中某个显示器在创建快照时的高度，可以是其完整区域，也可以是其工作区。

参数

index: Integer — 显示器在最近一次 DisplayMonitorEnumeratedAll 快照中从 0 开始的位置（从左到右，再从上到下）。
workArea: Bool — true 表示工作区，即不包括任务栏和停靠工具栏的区域；false 表示整个显示器。

返回值

以像素为单位的高度；如果 index 超出范围，则为 0。

1 个示例: 列出显示器

DisplayMonitorGetEnumeratedWidthAt

DisplayMonitorGetEnumeratedWidthAt(index: Integer, workArea: Bool) → Integer

返回最近一次 DisplayMonitorEnumeratedAll 快照中某个显示器在创建快照时的宽度，可以是其完整区域，也可以是其工作区。

参数

index: Integer — 显示器在最近一次 DisplayMonitorEnumeratedAll 快照中从 0 开始的位置（从左到右，再从上到下）。
workArea: Bool — true 表示工作区，即不包括任务栏和停靠工具栏的区域；false 表示整个显示器。

返回值

以像素为单位的宽度；如果 index 超出范围，则为 0。

1 个示例: 列出显示器

DisplayMonitorGetEnumeratedXAt

DisplayMonitorGetEnumeratedXAt(index: Integer, workArea: Bool) → Integer

返回最近一次 DisplayMonitorEnumeratedAll 快照中某个显示器在创建快照时的左边缘，可以是其完整区域的，也可以是其工作区的。

参数

index: Integer — 显示器在最近一次 DisplayMonitorEnumeratedAll 快照中从 0 开始的位置（从左到右，再从上到下）。
workArea: Bool — true 表示工作区，即不包括任务栏和停靠工具栏的区域；false 表示整个显示器。

返回值

以屏幕像素为单位的左边缘（位于主显示器左侧的显示器为负数）；如果 index 超出范围，则为 0。0 也可能是真实的边缘，因此请将 index 与显示器数量进行比较。

DisplayMonitorGetEnumeratedYAt

DisplayMonitorGetEnumeratedYAt(index: Integer, workArea: Bool) → Integer

返回最近一次 DisplayMonitorEnumeratedAll 快照中某个显示器在创建快照时的上边缘，可以是其完整区域的，也可以是其工作区的。

参数

index: Integer — 显示器在最近一次 DisplayMonitorEnumeratedAll 快照中从 0 开始的位置（从左到右，再从上到下）。
workArea: Bool — true 表示工作区，即不包括任务栏和停靠工具栏的区域；false 表示整个显示器。

返回值

以屏幕像素为单位的上边缘（位于主显示器上方的显示器为负数）；如果 index 超出范围，则为 0。0 也可能是真实的边缘，因此请将 index 与显示器数量进行比较。

DisplayMonitorGetFriendlyNameFromPoint

DisplayMonitorGetFriendlyNameFromPoint(x: Integer, y: Integer) → Text

返回包含某个屏幕点的显示器的型号名称，例如 DELL U2720Q。该名称易读但不唯一：两台相同的显示器报告相同的名称。

参数

x: Integer — 水平屏幕位置，以像素为单位。
y: Integer — 垂直屏幕位置，以像素为单位。

返回值

型号名称；如果显示器未报告名称（笔记本电脑内置屏幕常见此情况），则返回空文本。不在任何显示器上的点使用最近的显示器。

DisplayMonitorGetRectHeightFromName

DisplayMonitorGetRectHeightFromName(name: Text, workArea: Bool) → Integer

返回按已保存的设备路径或型号名称找到的已连接显示器的高度，可以是其完整区域，也可以是其工作区。

参数

name: Text — 显示器设备路径（可靠的选择）或型号名称，例如 DELL U2720Q。不区分大小写；设备路径完全匹配优先于型号名称。
workArea: Bool — true 表示工作区，即不包括任务栏和停靠工具栏的区域；false 表示整个显示器。

返回值

以像素为单位的高度；如果没有已连接的显示器与该名称匹配，则为 0。

DisplayMonitorGetRectHeightFromPoint

DisplayMonitorGetRectHeightFromPoint(x: Integer, y: Integer, workArea: Bool) → Integer

返回包含某个屏幕点的显示器的高度，可以是其完整区域，也可以是其工作区。不在任何显示器上的点使用最近的显示器。

参数

x: Integer — 水平屏幕位置，以像素为单位。
y: Integer — 垂直屏幕位置，以像素为单位。
workArea: Bool — true 表示工作区，即不包括任务栏和停靠工具栏的区域；false 表示整个显示器。

返回值

以像素为单位的高度。

2 个示例: 将活动窗口贴靠到其所在显示器的左半边, 将窗口贴靠到光标下方的 3×2 网格单元格中

DisplayMonitorGetRectWidthFromName

DisplayMonitorGetRectWidthFromName(name: Text, workArea: Bool) → Integer

返回按已保存的设备路径或型号名称找到的已连接显示器的宽度，可以是其完整区域，也可以是其工作区。

参数

name: Text — 显示器设备路径（可靠的选择）或型号名称，例如 DELL U2720Q。不区分大小写；设备路径完全匹配优先于型号名称。
workArea: Bool — true 表示工作区，即不包括任务栏和停靠工具栏的区域；false 表示整个显示器。

返回值

以像素为单位的宽度；如果没有已连接的显示器与该名称匹配，则为 0。

DisplayMonitorGetRectWidthFromPoint

DisplayMonitorGetRectWidthFromPoint(x: Integer, y: Integer, workArea: Bool) → Integer

返回包含某个屏幕点的显示器的宽度，可以是其完整区域，也可以是其工作区。不在任何显示器上的点使用最近的显示器。

参数

x: Integer — 水平屏幕位置，以像素为单位。
y: Integer — 垂直屏幕位置，以像素为单位。
workArea: Bool — true 表示工作区，即不包括任务栏和停靠工具栏的区域；false 表示整个显示器。

返回值

以像素为单位的宽度。

3 个示例: else-if 链, 将活动窗口贴靠到其所在显示器的左半边, 将窗口贴靠到光标下方的 3×2 网格单元格中

DisplayMonitorGetRectXFromName

DisplayMonitorGetRectXFromName(name: Text, workArea: Bool) → Integer

返回按已保存的设备路径或型号名称找到的已连接显示器的左边缘，可以是其完整区域的，也可以是其工作区的。

参数

name: Text — 显示器设备路径（可靠的选择）或型号名称，例如 DELL U2720Q。不区分大小写；设备路径完全匹配优先于型号名称。
workArea: Bool — true 表示工作区，即不包括任务栏和停靠工具栏的区域；false 表示整个显示器。

返回值

以屏幕像素为单位的左边缘；如果没有已连接的显示器与该名称匹配，则为 0。0 也可能是真实的边缘，因此请先调用 DisplayMonitorExistsByName 进行检查。

DisplayMonitorGetRectXFromPoint

DisplayMonitorGetRectXFromPoint(x: Integer, y: Integer, workArea: Bool) → Integer

返回包含某个屏幕点的显示器的左边缘，可以是其完整区域的，也可以是其工作区的。不在任何显示器上的点使用最近的显示器。

参数

x: Integer — 水平屏幕位置，以像素为单位。
y: Integer — 垂直屏幕位置，以像素为单位。
workArea: Bool — true 表示工作区，即不包括任务栏和停靠工具栏的区域；false 表示整个显示器。

返回值

以屏幕像素为单位的左边缘；位于主显示器左侧的显示器为负数。

3 个示例: else-if 链, 将活动窗口贴靠到其所在显示器的左半边, 将窗口贴靠到光标下方的 3×2 网格单元格中

DisplayMonitorGetRectYFromName

DisplayMonitorGetRectYFromName(name: Text, workArea: Bool) → Integer

返回按已保存的设备路径或型号名称找到的已连接显示器的上边缘，可以是其完整区域的，也可以是其工作区的。

参数

name: Text — 显示器设备路径（可靠的选择）或型号名称，例如 DELL U2720Q。不区分大小写；设备路径完全匹配优先于型号名称。
workArea: Bool — true 表示工作区，即不包括任务栏和停靠工具栏的区域；false 表示整个显示器。

返回值

以屏幕像素为单位的上边缘；如果没有已连接的显示器与该名称匹配，则为 0。0 也可能是真实的边缘，因此请先调用 DisplayMonitorExistsByName 进行检查。

DisplayMonitorGetRectYFromPoint

DisplayMonitorGetRectYFromPoint(x: Integer, y: Integer, workArea: Bool) → Integer

返回包含某个屏幕点的显示器的上边缘，可以是其完整区域的，也可以是其工作区的。不在任何显示器上的点使用最近的显示器。

参数

x: Integer — 水平屏幕位置，以像素为单位。
y: Integer — 垂直屏幕位置，以像素为单位。
workArea: Bool — true 表示工作区，即不包括任务栏和停靠工具栏的区域；false 表示整个显示器。

返回值

以屏幕像素为单位的上边缘；位于主显示器上方的显示器为负数。

2 个示例: 将活动窗口贴靠到其所在显示器的左半边, 将窗口贴靠到光标下方的 3×2 网格单元格中

Engine

EngineConsumePhysicalInput

EngineConsumePhysicalInput(enable: Bool, timeoutSeconds: Integer) → Bool

阻止用户的真实鼠标和键盘输入到达任何窗口，或结束这种阻止。脚本发送的输入仍然有效，并且阻止会在超时后自行结束。

参数

enable: Bool — true 表示开始或重新开始阻止真实输入；false 表示结束阻止，无论该阻止是由哪个脚本开始的。
timeoutSeconds: Integer — 阻止持续的最长时间，以秒为单位；enable 为 true 时须为 1 或更大。更大的值会被缩短为“脚本”设置页上的最大值（默认为 120 秒）。enable 为 false 时忽略。

返回值

始终为 true。当 enable 设为 true 时，如果 timeoutSeconds 为 0 或更小，脚本将因错误而停止。

EngineDisable

EngineDisable() → Bool · 简单

禁用引擎，与从托盘图标禁用相同，直到 EngineEnable 或托盘将其重新启用。更改在调用返回后立即生效。在安全模式下不执行任何操作。

参数

无参数。

返回值

如果已发送请求，则为 true；如果引擎尚未完成启动，则为 false。

1 个示例: 引擎状态

EngineDisableNextGesture

EngineDisableNextGesture() → Bool · 简单

让下一次按下绘制按钮时直接传递给应用程序，而不是开始手势，仅限一次。引擎处于禁用状态时无效。

参数

无参数。

返回值

始终为 true。

1 个示例: 放行下一次右键拖动

EngineEnable

EngineEnable() → Bool · 简单

在 EngineDisable 或从托盘图标禁用之后重新启用引擎。更改在调用返回后立即生效。在安全模式下不执行任何操作。

参数

无参数。

返回值

如果已发送请求，则为 true；如果引擎尚未完成启动，则为 false。

EngineExit

EngineExit() → Bool · 简单

以正常关闭方式关闭引擎，与托盘菜单上的“退出”相同：隐藏到托盘中的窗口会被还原，配置界面会关闭。关闭在调用返回后立即开始。

参数

无参数。

返回值

如果已发送关闭请求，则为 true；如果引擎尚未完成启动，则为 false。

EngineIsDisabled

EngineIsDisabled() → Bool

返回引擎当前是否处于禁用状态，无论是由 EngineDisable 或托盘图标禁用，还是针对具有焦点的应用程序自动禁用。

参数

无参数。

返回值

如果引擎已禁用，则为 true；如果引擎处于活动状态，则为 false。

1 个示例: 引擎状态

EngineIsSafeMode

EngineIsSafeMode() → Bool

返回引擎是否以安全模式启动。在安全模式下，只有从诊断控制台运行的脚本才能运行。

参数

无参数。

返回值

安全模式下为 true；否则为 false。

1 个示例: 引擎状态

EngineReload

EngineReload() → Bool · 简单

从磁盘重新加载配置而无需重新启动，类似于托盘菜单上的“重新加载配置”。最多等待 3 秒。所有其他正在运行的脚本都会停止；此脚本继续运行。

参数

无参数。

返回值

新配置投入使用后为 true；如果无法加载配置或重新加载耗时超过 3 秒，则为 false。

EngineStopAllActions

EngineStopAllActions() → Bool · 简单

要求所有正在运行的操作和脚本停止，包括调用它的那一个。不会强行终止任何内容：每个脚本在其下一步时停止，因此调用方可能会先多运行一小段。

参数

无参数。

返回值

始终为 true。

File

FileAppendText

FileAppendText(path: Text, text: Text) → Bool

将文本添加到文本文件的末尾，如果文件不存在则创建该文件。适合用于日志。文本以 UTF-8 写入，不会自动添加换行符。

参数

path: Text — 文件的完整路径。其所在文件夹必须已存在。
text: Text — 要添加的文本。以 '\n' 结尾，可使每个条目各占一行。

返回值

如果已写入文本，则为 true；如果文件夹不存在、文件被锁定或现有文件的开头看起来是二进制数据，则为 false。

1 个示例: 追加到日志文件

FileCopy

FileCopy(source: Text, destination: Text, overwrite: Bool) → Bool

将任意类型的文件复制到新路径。目标文件夹必须已存在。

参数

source: Text — 要复制的文件的完整路径。
destination: Text — 新副本的完整路径，包括其文件名。
overwrite: Bool — true 表示替换 destination 处的现有文件；false 表示保留该文件不变并返回 false。

返回值

如果已复制文件，则为 true；如果源文件不存在、目标已存在且 overwrite 为 false，或复制失败，则为 false。

1 个示例: 编辑前备份文件

FileCreate

FileCreate(path: Text, text: Text) → Bool

使用给定内容创建一个新的文本文件，以 UTF-8 写入。如果该路径上已存在任何内容，则拒绝执行；若要替换现有文件的内容，请使用 FileEditText。

参数

path: Text — 新文件的完整路径。其所在文件夹必须已存在。
text: Text — 文件的内容。空文本会创建一个空文件。

返回值

如果已创建文件，则为 true；如果该位置已存在文件或文件夹，或无法写入文件，则为 false。

2 个示例: 今天的日期，以及带时间戳的文件名, 追加到日志文件

FileDelete

FileDelete(path: Text) → Bool

永久删除文件；文件不会进入回收站。已不存在的文件视为成功。绝不会删除文件夹；删除文件夹请使用 FolderDelete。

参数

path: Text — 要删除的文件的完整路径。

返回值

如果文件已不存在（包括从未存在过的情况），则为 true；如果路径是文件夹，或文件被锁定或访问被拒绝，则为 false。

FileEditText

FileEditText(path: Text, text: Text) → Bool

替换现有文本文件的全部内容，以 UTF-8 写入。拒绝处理看起来是二进制数据的文件。若要创建新文件，请使用 FileCreate。

参数

path: Text — 现有文本文件的完整路径。
text: Text — 新内容，将替换文件中的全部内容。

返回值

如果已重写文件，则为 true；如果文件不存在、其开头看起来是二进制数据或无法写入，则为 false。

1 个示例: 编辑前备份文件

FileExists

FileExists(path: Text) → Bool

检查某个路径上是否存在文件。该路径上的文件夹不算在内；对于文件夹，请使用 FolderExists。

参数

path: Text — 要检查的文件的完整路径。

返回值

如果该位置存在文件，则为 true；如果不存在任何内容或它是一个文件夹，则为 false。

2 个示例: 追加到日志文件, 编辑前备份文件

FileGetCreationDate

FileGetCreationDate(path: Text) → Text

以 UTC 的 ISO 8601 日期和时间返回文件的创建时间，DateTimeFormat 和其他 DateTime 内置函数可以读取该值。

参数

path: Text — 文件的完整路径。

返回值

创建时间，例如 2026-10-01T18:05:09Z；如果文件不存在或该路径是文件夹，则返回空文本。

FileGetModifiedDate

FileGetModifiedDate(path: Text) → Text

以 UTC 的 ISO 8601 日期和时间返回文件内容的上次更改时间，DateTimeFormat 和其他 DateTime 内置函数可以读取该值。

参数

path: Text — 文件的完整路径。

返回值

上次修改时间，例如 2026-10-01T18:05:09Z；如果文件不存在或该路径是文件夹，则返回空文本。

1 个示例: 读取文件并统计行数

FileGetProductVersion

FileGetProductVersion(path: Text) → Text

返回程序或库文件（例如 .exe 或 .dll）中存储的产品版本。这是随该文件一起发布的产品的版本，可能与 FileGetVersion 不同。

参数

path: Text — .exe、.dll 或其他带有版本信息的文件的完整路径。

返回值

由四个数字组成的版本，例如 10.0.22621.1；如果文件没有版本信息或不存在，则返回空文本。

FileGetSize

FileGetSize(path: Text) → Integer

返回文件的大小（以字节为单位），无需打开或读取文件。

参数

path: Text — 文件的完整路径。

返回值

以字节为单位的大小；如果文件不存在或该路径是文件夹，则为 -1。

1 个示例: 读取文件并统计行数

FileGetVersion

FileGetVersion(path: Text) → Text

返回程序或库文件（例如 .exe 或 .dll）中存储的文件版本，即其“属性”中“详细信息”选项卡上显示的版本。

参数

path: Text — .exe、.dll 或其他带有版本信息的文件的完整路径。

返回值

由四个数字组成的版本，例如 10.0.22621.1；如果文件没有版本信息或不存在，则返回空文本。

FileMove

FileMove(source: Text, destination: Text, overwrite: Bool) → Bool

将任意类型的文件移动到新路径，同时也可以为其指定新名称，包括仅更改字母大小写。目标文件夹必须已存在。

参数

source: Text — 要移动的文件的完整路径。
destination: Text — 文件新位置的完整路径，包括其文件名。
overwrite: Bool — true 表示一步替换 destination 处的现有文件；false 表示保留该文件不变并返回 false。与源路径仅字母大小写不同的目标不算现有文件。

返回值

如果已移动文件，则为 true；如果源文件不存在、目标已存在且 overwrite 为 false，或移动失败，则为 false。

FileReadText

FileReadText(path: Text) → Text

读取整个文本文件并返回其内容。支持 UTF-8、带字节顺序标记的 UTF-16 以及采用系统旧版代码页的文件。拒绝处理二进制文件。

参数

path: Text — 文本文件的完整路径。

返回值

文件的内容；如果文件不存在、无法读取或看起来是二进制数据，则返回空文本。

2 个示例: 读取文件并统计行数, 编辑前备份文件

FileRename

FileRename(path: Text, newName: Text) → Bool

重命名文件，并将其保留在当前文件夹中。也可以仅更改字母大小写，例如将 report.txt 改为 Report.txt。若要将文件移动到其他文件夹，请使用 FileMove。

参数

path: Text — 要重命名的文件的完整路径。
newName: Text — 仅新文件名，例如 report-old.txt。包含正斜杠或反斜杠的名称会使脚本因错误而停止。

返回值

如果已重命名文件，则为 true；如果文件不存在、已存在使用新名称的其他文件或文件夹，或重命名失败，则为 false。

Folder

FolderCreate

FolderCreate(path: Text) → Bool

创建文件夹，包括任何缺失的父文件夹。已存在的文件夹视为成功。

参数

path: Text — 要创建的文件夹的完整路径。

返回值

如果之后该文件夹存在，则为 true；如果有文件挡在路径上或无法创建文件夹，则为 false。

FolderDelete

FolderDelete(path: Text, recursive: Bool) → Bool

永久删除文件夹；文件夹不会进入回收站。当 recursive 设为 true 时，其中的所有内容也会被删除。已不存在的文件夹视为成功。绝不会删除文件；删除文件请使用 FileDelete。

参数

path: Text — 要删除的文件夹的完整路径。
recursive: Bool — true 表示删除该文件夹及其中的所有内容；false 表示仅在文件夹为空时才删除。

返回值

如果文件夹已不存在，则为 true；如果路径是文件、文件夹不为空且 recursive 为 false，或其中的某些内容被锁定或受保护，则为 false。

FolderEnumerateAll

FolderEnumerateAll(path: Text, recursive: Bool) → Integer

列出文件夹中的文件和子文件夹，并返回其数量。使用 FolderGetEnumeratedPathAt 读取每个完整路径。无法访问的子文件夹将被跳过。

参数

path: Text — 要列出的文件夹的完整路径。
recursive: Bool — true 表示同时列出所有子文件夹中的全部内容；false 表示仅列出该文件夹的直接内容。

返回值

找到的条目数；如果文件夹不存在或无法读取，则为 -1。

1 个示例: 统计文件夹中的文件类型

FolderExists

FolderExists(path: Text) → Bool

检查某个路径上是否存在文件夹。该路径上的文件不算在内；对于文件，请使用 FileExists。

参数

path: Text — 要检查的文件夹的完整路径。

返回值

如果该位置存在文件夹，则为 true；如果不存在任何内容或它是一个文件，则为 false。

FolderGetEnumeratedPathAt

FolderGetEnumeratedPathAt(index: Integer) → Text

从本次脚本运行中最近一次 FolderEnumerateAll 调用生成的列表中返回一个完整路径。

参数

index: Integer — 在列表中的位置，范围为 0 到 FolderEnumerateAll 返回的数量减 1。

返回值

文件或文件夹的完整路径；如果 index 超出范围或尚未调用 FolderEnumerateAll，则返回空文本。

1 个示例: 统计文件夹中的文件类型

FolderRename

FolderRename(path: Text, newName: Text) → Bool

重命名文件夹，并将其连同内容保留在当前的父文件夹中。也可以仅更改字母大小写。

参数

path: Text — 要重命名的文件夹的完整路径。
newName: Text — 仅新文件夹名称。包含正斜杠或反斜杠的名称会使脚本因错误而停止。

返回值

如果已重命名文件夹，则为 true；如果文件夹不存在、已存在使用新名称的其他文件或文件夹，或重命名失败（例如因为其中的某个文件处于打开状态），则为 false。

FolderWatchCreate

FolderWatchCreate(name: Text, path: Text, recursive: Bool, filterMask: Integer, script: Text) → Bool

开始监视文件夹，并针对 Windows 报告的每个更改（例如文件的创建、更改、重命名或删除）运行一个脚本。此脚本结束后，监视仍会继续运行。

参数

name: Text — 监视的名称。使用已在使用的名称创建监视会替换该监视。名称区分大小写。
path: Text — 要监视的文件夹的完整路径。
recursive: Bool — true 表示同时监视所有子文件夹；false 表示仅监视该文件夹本身。
filterMask: Integer — 要报告的更改类型：用 | 组合的 FileNotify 常量，例如 FileNotify.FileName | FileNotify.LastWrite。
script: Text — 针对每个更改运行的脚本，类型为 Text。它通过 ContextGetWatchAction（created、deleted、modified、renamed-old-name、renamed-new-name 或 overflow）和 ContextGetWatchPath 读取更改。

返回值

如果监视正在运行，则为 true；如果文件夹不存在、无法打开或 filterMask 为 0，则为 false。

1 个示例: 监视文件夹

FolderWatchDelete

FolderWatchDelete(name: Text) → Bool

停止用 FolderWatchCreate 创建的文件夹监视，使其脚本不再运行。

参数

name: Text — 传给 FolderWatchCreate 的名称。名称区分大小写。

返回值

如果找到并停止了具有该名称的监视，则为 true；如果没有这样的监视，则为 false。

1 个示例: 监视文件夹

FolderWatchDeleteAll

FolderWatchDeleteAll() → Bool

停止用 FolderWatchCreate 创建的所有文件夹监视，使它们的脚本都不再运行。

参数

无参数。

返回值

始终为 true。

FolderWatchGetCount

FolderWatchGetCount() → Integer

返回正在运行的文件夹监视的数量，并为 FolderWatchGetEnumeratedNameAt 创建其名称的快照。

参数

无参数。

返回值

正在运行的文件夹监视的数量；如果没有，则为 0。

FolderWatchGetEnumeratedNameAt

FolderWatchGetEnumeratedNameAt(index: Integer) → Text

从本次脚本运行中最近一次 FolderWatchGetCount 调用创建的快照中返回一个监视名称。

参数

index: Integer — 在快照中的位置，范围为 0 到数量减 1。顺序没有意义。

返回值

监视名称；如果 index 超出范围或尚未调用 FolderWatchGetCount，则返回空文本。

GestureProfile

GestureProfileEnumerateAll

GestureProfileEnumerateAll() → Integer

获取配置中所有手势配置方案的列表，并返回其数量。使用 GestureProfileGetEnumeratedIdAt 和 GestureProfileGetEnumeratedNameAt 逐个读取。

参数

无参数。

返回值

手势配置方案的数量；如果没有，则为 0。

GestureProfileGetActiveId

GestureProfileGetActiveId() → Text

返回当前处于活动状态的手势配置方案的 ID。

参数

无参数。

返回值

活动配置方案的 ID；如果没有活动的配置方案，则返回空文本。

2 个示例: Windows 通知, 切换到下一个手势配置方案

GestureProfileGetEnumeratedIdAt

GestureProfileGetEnumeratedIdAt(index: Integer) → Text

从本脚本中 GestureProfileEnumerateAll 最近一次获取的列表中返回一个配置方案的 ID。可将该 ID 传给 GestureProfileSwitch。

参数

index: Integer — 在列表中从 0 开始的位置，范围为 0 到数量减 1。

返回值

配置方案的 ID；如果 index 超出范围或尚未调用 GestureProfileEnumerateAll，则返回空文本。

GestureProfileGetEnumeratedNameAt

GestureProfileGetEnumeratedNameAt(index: Integer) → Text

从本脚本中 GestureProfileEnumerateAll 最近一次获取的列表中返回一个配置方案的显示名称。

参数

index: Integer — 在列表中从 0 开始的位置，范围为 0 到数量减 1。

返回值

配置方案的名称；如果 index 超出范围或尚未调用 GestureProfileEnumerateAll，则返回空文本。

GestureProfileSwitch

GestureProfileSwitch(profileId: Text) → Bool · 简单

切换到另一个手势配置方案，与从托盘菜单中选择它相同，并且重新启动后仍会记住该选择。切换在调用返回后立即进行。

参数

profileId: Text — 要切换到的配置方案的 ID，例如从 GestureProfileGetEnumeratedIdAt 获取的 ID；空文本表示不使用配置方案。

返回值

如果已发送请求，则为 true；如果没有配置文件使用该 ID，则为 false，且不会有任何更改。切换在调用返回后立即发生；请使用 GestureProfileGetActiveId 确认切换结果。

Keyboard

KeyboardGetKeyState

KeyboardGetKeyState(key: Integer) → Integer

返回某个键此刻的原始 Windows 状态。当其他桌面（例如 UAC 提示或锁屏界面）位于前台时，所有键都读作未按下。若只需要“是”或“否”，请使用 KeyboardIsKeyDown 或 KeyboardIsKeyToggled。

参数

key: Integer — 一个 VirtualKey 常量，例如 VirtualKey.CapsLock，或 0 到 255 之间的虚拟键码。任何其他值都会使脚本因错误而停止。

返回值

一个原始 Integer：键按下时为负数（最高位已设置）；Caps Lock 等锁定键打开时为奇数（最低位已设置）。

1 个示例: 按键状态位

KeyboardGetKeyStateAsync

KeyboardGetKeyStateAsync(key: Integer) → Integer

返回某个键在此时此刻的原始 Windows 状态，无论哪个窗口具有焦点。

参数

key: Integer — 一个 VirtualKey 常量，例如 VirtualKey.ShiftKey，或 0 到 255 之间的虚拟键码。任何其他值都会使脚本因错误而停止。

返回值

一个原始 Integer：键当前处于按下状态时为负数（最高位已设置）。如果自上次检查以来该键被按下过，则最低位可能被设置，但 Windows 不保证这一点。

KeyboardIsKeyDown

KeyboardIsKeyDown(key: Integer) → Bool

检查某个键此刻是否处于按住状态。当其他桌面（例如 UAC 提示或锁屏界面）位于前台时，所有键都读作未按下。

参数

key: Integer — 一个 VirtualKey 常量，例如 VirtualKey.ControlKey，或 0 到 255 之间的虚拟键码。任何其他值都会使脚本因错误而停止。

返回值

如果键处于按下状态，则为 true；如果处于弹起状态，则为 false。

2 个示例: 按键状态位, 按住 Ctrl 时改变行为

KeyboardIsKeyToggled

KeyboardIsKeyToggled(key: Integer) → Bool

检查某个锁定键是否已打开。仅对 VirtualKey.CapsLock、VirtualKey.NumLock 和 VirtualKey.Scroll 有意义。

参数

key: Integer — 一个 VirtualKey 常量，例如 VirtualKey.CapsLock，或 0 到 255 之间的虚拟键码。任何其他值都会使脚本因错误而停止。

返回值

如果锁定键已打开，则为 true；如果已关闭，则为 false。

1 个示例: 按键状态位

KeyboardKeyDown

KeyboardKeyDown(key: Integer) → Bool

按下一个键并保持按下状态，直到 KeyboardKeyUp 将其释放。当“将媒体键和浏览器键作为命令发送”设置打开时，媒体键、音量键或浏览器键会改为发送其命令。

参数

key: Integer — 一个 VirtualKey 常量，例如 VirtualKey.ShiftKey，或 0 到 255 之间的虚拟键码。任何其他值都会使脚本因错误而停止。

返回值

如果已发送按键，则为 true；如果 Windows 阻止了按键，或者对于作为命令发送的键而言没有窗口具有焦点，则为 false。

1 个示例: Shift+单击

KeyboardKeyUp

KeyboardKeyUp(key: Integer) → Bool

释放用 KeyboardKeyDown 按下的键。对于作为命令发送的媒体键、音量键或浏览器键，它不执行任何操作，因为命令在按下时就已发出。

参数

key: Integer — 一个 VirtualKey 常量，例如 VirtualKey.ShiftKey，或 0 到 255 之间的虚拟键码。任何其他值都会使脚本因错误而停止。

返回值

如果已发送释放键的操作，则为 true，对于作为命令发送的键始终为 true；如果 Windows 阻止了该操作，则为 false。

1 个示例: Shift+单击

KeyboardPressKey

KeyboardPressKey(key: Integer) → Bool · 简单

按下并释放一个键，可以是 Windows 为其定义了键码的任何键，包括媒体键。当“将媒体键和浏览器键作为命令发送”设置打开时，这些键会改为发送其命令。

参数

key: Integer — 一个 VirtualKey 常量，例如 VirtualKey.MediaPlayPause，或 0 到 255 之间的虚拟键码。任何其他值都会使脚本因错误而停止。

返回值

如果已发送按键，则为 true；如果 Windows 阻止了按键，或者对于作为命令发送的键而言没有窗口具有焦点，则为 false。

3 个示例: 命名常量与原始数字, 媒体键, 将串口设备的按钮映射到媒体键

KeyboardPressKeyCombo

KeyboardPressKeyCombo(combo: Text) → Bool · 简单

按下一个组合键，例如 Ctrl+C：按住修饰键，按下并释放该键，然后释放修饰键。每次调用发送一个组合键。

参数

combo: Text — 可选的修饰符号（^ 表示 Ctrl，+ 表示 Shift，@ 表示 Windows，百分号表示 Alt），后跟一个字母或数字，或者后跟用大括号括起的键名，例如 {ENTER}、{F5} 或 {LEFT}，字母大小写不限。示例：'^c' 即 Ctrl+C。

返回值

如果已发送击键，则为 true；如果 Windows 阻止了击键，则为 false。无法识别的 combo 会使脚本因错误而停止。

4 个示例: 组合键, 键入签名, 将所选文本转为大写, 在网上搜索所选内容

KeyboardTypeText

KeyboardTypeText(text: Text) → Bool · 简单

逐个字符地将文本键入到具有焦点的窗口中，支持任何语言（包括表情符号），与键盘布局无关。在每个字符之前等待“键入延迟”设置所指定的时间。

参数

text: Text — 要键入的文本。每个换行符作为一次 Enter 按键发送。在文本扩展的脚本中，结束触发的那个键会在文本之后键入。

返回值

如果已发送每个字符或文本为空，则为 true；如果 Windows 阻止了其中某些字符，则为 false。

3 个示例: 启动程序、等待其窗口出现并对其操作, 今天的日期，以及带时间戳的文件名, 键入签名

Macro

MacroClearTemporary

MacroClearTemporary() → Bool

丢弃用 MacroRecordTemporary 录制的宏。

参数

无参数。

返回值

如果有已录制的宏可丢弃，则为 true；如果没有，则为 false。

MacroExpectFocusedWindow

MacroExpectFocusedWindow(exeName: Text, windowClass: Text) → Bool

等待前台窗口属于给定的程序和窗口类，最长等待设置中的回放窗口等待时间（默认为 2 秒）。如果始终不匹配，则显示通知并停止脚本。

参数

exeName: Text — 程序的文件名，例如 notepad.exe。不区分大小写；空文本匹配任何程序。
windowClass: Text — 顶级窗口的类名，例如 Notepad。不区分大小写；空文本匹配任何类。

返回值

窗口匹配时为 true；如果在等待期间要求脚本停止，则为 false。

MacroExpectWindowAt

MacroExpectWindowAt(x: Integer, y: Integer, exeName: Text, windowClass: Text) → Bool

等待某个屏幕点处的顶级窗口属于给定的程序和窗口类，最长等待设置中的回放窗口等待时间（默认为 2 秒）。如果始终不匹配，则显示通知并停止脚本。

参数

x: Integer — 要检查的水平屏幕位置，以虚拟屏幕像素为单位。
y: Integer — 要检查的垂直屏幕位置，以虚拟屏幕像素为单位。
exeName: Text — 程序的文件名，例如 notepad.exe。不区分大小写；空文本匹配任何程序。
windowClass: Text — 顶级窗口的类名，例如 Notepad。不区分大小写；空文本匹配任何类。

返回值

窗口匹配时为 true；如果在等待期间要求脚本停止，则为 false。

MacroGetTemporaryScript

MacroGetTemporaryScript() → Text

以步骤脚本文本的形式返回用 MacroRecordTemporary 录制的宏，以便脚本可以保存或检查它。

参数

无参数。

返回值

最近一次完成的录制的步骤文本；如果尚未录制任何内容或已将其清除，则返回空文本。在新的录制进行期间，仍返回上一次的录制。

MacroPlayTemporary

MacroPlayTemporary(timeoutSeconds: Integer) → Bool

回放用 MacroRecordTemporary 录制的宏，并等待其完成或超时。回放期间会暂缓用户的真实鼠标和键盘输入。

参数

timeoutSeconds: Integer — 最长等待时间，以秒为单位；必须为 1 或更大，否则脚本将因错误而停止。超过此时间后仍在运行的宏会继续运行，但不再暂缓真实输入。

返回值

如果宏在规定时间内播放完毕，则为 true；如果未录制任何内容、某个步骤或窗口检查失败、回放被停止，或超时时仍在运行，则为 false。

MacroRecordTemporary

MacroRecordTemporary() → Bool

开始将鼠标和键盘输入录制到保存在内存中的临时宏；按 Ctrl+Break 可停止。在录制开始之前即立即返回。可能会先出现一个确认框。

参数

无参数。

返回值

如果已发送录制请求，则为 true；如果已有录制正在运行、正在启动或已被请求，或者引擎尚未完成启动，则为 false。

Math

MathAbs

MathAbs(value: Any) → Any

返回数字的绝对值，即去掉负号后的数字。适用于 Integer 和 Real 值。

参数

value: Any — Integer 或 Real 数字。

返回值

绝对值，类型与 value 相同（Integer 或 Real）；如果 Real 为 NaN 或无穷大，则为 0.0。不是数字的值会使操作因错误而停止。

2 个示例: 将值限制在范围内, 笔画朝哪个方向？

MathAtan2

MathAtan2(y: Any, x: Any) → Real

返回从原点到点 (x, y) 的角度，以弧度为单位。屏幕 y 坐标向下增大，因此若要按通常的数学方向求笔画角度，请传入取反后的垂直变化量。

参数

y: Any — 该点的垂直坐标。Integer 或 Real。注意 y 在前。
x: Any — 该点的水平坐标。Integer 或 Real。

返回值

以弧度为单位的角度，范围为 -pi 到 pi，类型为 Real；如果任一参数为 NaN 或无穷大，则为 0.0。不是数字的参数会使操作因错误而停止。

MathCeil

MathCeil(value: Real) → Integer

将数字向上舍入为最接近的整数。MathCeil(2.1) 为 3；MathCeil(-2.1) 为 -2。

参数

value: Real — 要向上舍入的数字。Integer 按原样接受。

返回值

舍入后的值，类型为 Integer。如果 value 为 NaN 或无穷大，则为 0；超出 Integer 范围的值会得到最大或最小的 Integer。

1 个示例: 舍入和 Real 数学内置函数

MathClamp

MathClamp(value: Any, min: Any, max: Any) → Any

将数字限制在某个范围内：如果 value 小于 min，则返回 min；如果 value 大于 max，则返回 max；否则返回 value。适用于 Integer 和 Real 值。

参数

value: Any — 要限制在范围内的数字。
min: Any — 允许的最小值。不得大于 max。
max: Any — 允许的最大值。

返回值

value、min 或 max 中被选中的那一个，保留其自身类型（Integer 或 Real）；如果任一参数为 NaN 或无穷大，则为 0.0。非数字或 min 大于 max 会使操作因错误而停止。

1 个示例: 将值限制在范围内

MathCos

MathCos(radians: Real) → Real

返回以弧度给出的角度的余弦值。若要转换角度值，请乘以 MathGetPi() 再除以 180。

参数

radians: Real — 以弧度为单位的角度。Integer 按原样接受。

返回值

余弦值，范围为 -1 到 1，类型为 Real；如果 radians 为 NaN 或无穷大，则为 0.0。

1 个示例: 让鼠标沿圆周移动

MathFloor

MathFloor(value: Real) → Integer

将数字向下舍入为最接近的整数。MathFloor(2.9) 为 2；MathFloor(-2.1) 为 -3。

参数

value: Real — 要向下舍入的数字。Integer 按原样接受。

返回值

舍入后的值，类型为 Integer。如果 value 为 NaN 或无穷大，则为 0；超出 Integer 范围的值会得到最大或最小的 Integer。

1 个示例: 舍入和 Real 数学内置函数

MathGetE

MathGetE() → Real

返回数学常数 e（约为 2.71828），即自然对数的底数。

参数

无参数。

返回值

e 的值，类型为 Real。

MathGetPi

MathGetPi() → Real

返回数学常数 pi（约为 3.14159）。可用于在角度和弧度之间进行转换。

参数

无参数。

返回值

pi 的值，类型为 Real。

1 个示例: 让鼠标沿圆周移动

MathLog

MathLog(value: Real) → Real

返回数字的自然对数（以 e 为底）。除以 MathLog(10.0) 可得到以 10 为底的对数。

参数

value: Real — 大于 0 的数字。Integer 按原样接受。

返回值

自然对数，类型为 Real；如果 value 为 0、负数、NaN 或无穷大，则为 0。

MathMax

MathMax(a: Any, b: Any) → Any

返回两个数字中较大的一个。适用于 Integer 和 Real 值。

参数

a: Any — 第一个数字。
b: Any — 第二个数字。

返回值

a 和 b 中较大的一个，保留其自身类型；如果两者相等，则为 a；如果任一参数为 NaN 或无穷大，则为 0.0。不是数字的参数会使操作因错误而停止。

MathMin

MathMin(a: Any, b: Any) → Any

返回两个数字中较小的一个。适用于 Integer 和 Real 值。

参数

a: Any — 第一个数字。
b: Any — 第二个数字。

返回值

a 和 b 中较小的一个，保留其自身类型；如果两者相等，则为 a；如果任一参数为 NaN 或无穷大，则为 0.0。不是数字的参数会使操作因错误而停止。

1 个示例: 调高音量并显示屏幕提示

MathMod

MathMod(value: Any, divisor: Any) → Any

返回 value 除以 divisor 的余数。结果的符号与除数相同，因此 MathMod(-30, 360) 为 330，适合用于角度回绕或循环索引。

参数

value: Any — 被除数。Integer 或 Real。
divisor: Any — 除数。Integer 或 Real。

返回值

余数：两个参数均为 Integer 时为 Integer，否则为 Real。如果 divisor 为 0，或任一参数为 NaN 或无穷大，则为 0。不是数字的参数会使操作因错误而停止。

MathPow

MathPow(base: Real, exponent: Real) → Real

求数字的幂，例如平方或立方。MathPow(2.0, 10.0) 为 1024。

参数

base: Real — 底数。Integer 按原样接受。
exponent: Real — 指数。可以为负数或小数；0.5 表示求平方根。

返回值

结果，类型为 Real；如果某个参数为 NaN 或无穷大，或没有有限的结果（例如 0 的负数次幂，或结果太大而无法容纳），则为 0。

MathRandom

MathRandom(min: Integer, max: Integer) → Integer

返回一个介于 min 和 max 之间（含两端）的随机整数。MathRandom(1, 6) 相当于掷一次骰子。

参数

min: Integer — 可能的最小结果。
max: Integer — 可能的最大结果。不得小于 min。

返回值

一个从 min 到 max 的随机 Integer。min 大于 max 会使操作因错误而停止。

2 个示例: 带退出标志的 while (true), 随机数和抛硬币

MathRound

MathRound(value: Real) → Integer

将数字舍入为最接近的整数。0.5 按远离零的方向舍入：2.5 变为 3，-2.5 变为 -3。

参数

value: Real — 要舍入的数字。若要以整数形式保留两位小数，请对 value 乘以 100 的结果进行舍入。

返回值

舍入后的值，类型为 Integer。如果 value 为 NaN 或无穷大，则为 0；超出 Integer 范围的值会得到最大或最小的 Integer。

5 个示例: 舍入和 Real 数学内置函数, 手势笔画的长度, 让鼠标沿圆周移动, 格式化 Real 而不显示六位小数, 调高音量并显示屏幕提示

MathSin

MathSin(radians: Real) → Real

返回以弧度给出的角度的正弦值。若要转换角度值，请乘以 MathGetPi() 再除以 180。

参数

radians: Real — 以弧度为单位的角度。Integer 按原样接受。

返回值

正弦值，范围为 -1 到 1，类型为 Real；如果 radians 为 NaN 或无穷大，则为 0.0。

1 个示例: 让鼠标沿圆周移动

MathSqrt

MathSqrt(value: Real) → Real

返回数字的平方根。MathSqrt(dx * dx + dy * dy) 即两点之间的距离。

参数

value: Real — 大于或等于 0 的数字。Integer 按原样接受。

返回值

平方根，类型为 Real；如果 value 为负数、NaN 或无穷大，则为 0。

2 个示例: 舍入和 Real 数学内置函数, 手势笔画的长度

MathTan

MathTan(radians: Real) → Real

返回以弧度给出的角度的正切值。在接近直角时结果会变得非常大。

参数

radians: Real — 以弧度为单位的角度。Integer 按原样接受。

返回值

正切值，类型为 Real；如果 radians 为 NaN 或无穷大，则为 0.0。

Mouse

MouseButtonDown

MouseButtonDown(button: Integer) → Bool

在当前光标位置按下鼠标按钮并保持按下状态，直到调用 MouseButtonUp。与 MouseMoveTo 结合使用可编写拖动操作的脚本。

参数

button: Integer — 一个 MouseButton 常量，例如 MouseButton.Primary。Primary 和 Secondary 遵循 Windows 中的切换主次按钮设置；Left 和 Right 是物理按钮。

返回值

如果已发送按下按钮的操作，则为 true；如果 Windows 阻止了该操作，则为 false。未知的按钮会使脚本因错误而停止。

1 个示例: 脚本化拖动

MouseButtonUp

MouseButtonUp(button: Integer) → Bool

在当前光标位置释放鼠标按钮，通常是用 MouseButtonDown 按下的按钮。

参数

button: Integer — 一个 MouseButton 常量，例如 MouseButton.Primary。Primary 和 Secondary 遵循 Windows 中的切换主次按钮设置；Left 和 Right 是物理按钮。

返回值

如果已发送释放按钮的操作，则为 true；如果 Windows 阻止了该操作，则为 false。未知的按钮会使脚本因错误而停止。

1 个示例: 脚本化拖动

MouseClick

MouseClick(x: Integer, y: Integer, button: Integer) → Bool · 简单

将光标移动到某个屏幕点并在该处单击鼠标按钮。之后光标停留在该点。

参数

x: Integer — 要单击的水平屏幕位置，以像素为单位。
y: Integer — 要单击的垂直屏幕位置，以像素为单位。
button: Integer — 一个 MouseButton 常量，例如 MouseButton.Primary。Primary 和 Secondary 遵循 Windows 中的切换主次按钮设置；Left 和 Right 是物理按钮。

返回值

如果已发送单击，则为 true；如果无法将光标移动到该点（此时不会单击任何内容），或 Windows 阻止了单击，则为 false。未知的按钮会使脚本因错误而停止。

2 个示例: 点击某处，然后将光标放回原处, Shift+单击

MouseClickAtClientPoint

MouseClickAtClientPoint(window: Window, x: Integer, y: Integer, button: Integer) → Bool

在相对于窗口工作区（即不含标题栏和边框的内部区域）左上角测量的某个点处单击鼠标按钮。光标会移动到该处并停留。

参数

window: Window — 其工作区作为 x 和 y 测量起点的窗口。
x: Integer — 到工作区左边缘的距离，以该窗口自身的像素为单位；对于 Windows 按 DPI 缩放的窗口，这可能与屏幕像素不同。
y: Integer — 到工作区上边缘的距离，以该窗口自身的像素为单位；对于 Windows 按 DPI 缩放的窗口，这可能与屏幕像素不同。
button: Integer — 一个 MouseButton 常量，例如 MouseButton.Primary。Primary 和 Secondary 遵循 Windows 中的切换主次按钮设置；Left 和 Right 是物理按钮。

返回值

如果已发送单击，则为 true；如果窗口无效或已不存在、无法将光标移动到该点（此时不会单击任何内容），或 Windows 阻止了单击，则为 false。未知的按钮会使脚本因错误而停止。

1 个示例: 点击窗口内的某个点

MouseDoubleClick

MouseDoubleClick(x: Integer, y: Integer, button: Integer) → Bool · 简单

将光标移动到某个屏幕点并在该处双击鼠标按钮。之后光标停留在该点。

参数

x: Integer — 要双击的水平屏幕位置，以像素为单位。
y: Integer — 要双击的垂直屏幕位置，以像素为单位。
button: Integer — 一个 MouseButton 常量，例如 MouseButton.Primary。Primary 和 Secondary 遵循 Windows 中的切换主次按钮设置；Left 和 Right 是物理按钮。

返回值

如果两次单击都已发送，则为 true；如果无法将光标移动到该点（此时不会单击任何内容），或 Windows 阻止了单击，则为 false。未知的按钮会使脚本因错误而停止。

MouseGetCursorX

MouseGetCursorX() → Integer

返回鼠标光标的水平屏幕位置。

参数

无参数。

返回值

光标的 x 位置，以屏幕像素为单位；在位于主显示器左侧的显示器上为负数。

8 个示例: else-if 链, 让鼠标沿圆周移动, 读取光标下的像素颜色, 将窗口贴靠到光标下方的 3×2 网格单元格中, 描述光标下方的内容, 点击某处，然后将光标放回原处, 脚本化拖动, Shift+单击

MouseGetCursorY

MouseGetCursorY() → Integer

返回鼠标光标的垂直屏幕位置。

参数

无参数。

返回值

光标的 y 位置，以屏幕像素为单位；在位于主显示器上方的显示器上为负数。

MouseIsButtonDown

MouseIsButtonDown(button: Integer) → Bool

检查此刻某个鼠标按钮是否处于按住状态。

参数

button: Integer — 一个 MouseButton 常量，例如 MouseButton.Primary。Primary 和 Secondary 遵循 Windows 中的切换主次按钮设置；Left 和 Right 是物理按钮。

返回值

如果按钮处于按下状态，则为 true；如果处于弹起状态，则为 false。未知的按钮会使脚本因错误而停止。

MouseLockToRect

MouseLockToRect(x: Integer, y: Integer, width: Integer, height: Integer) → Bool

将鼠标光标限制在一个屏幕矩形内。该锁定在脚本结束后仍然有效，直到调用 MouseUnlock 或其他程序更改它为止，因此完成后务必解除锁定。

参数

x: Integer — 矩形的左边缘，以屏幕像素为单位。
y: Integer — 矩形的上边缘，以屏幕像素为单位。
width: Integer — 矩形的宽度，以像素为单位。必须大于 0。
height: Integer — 矩形的高度，以像素为单位。必须大于 0。

返回值

如果光标现已被限制，则为 true；如果 width 或 height 不是正数或 Windows 拒绝了请求，则为 false。

1 个示例: 将光标限制在窗口内 5 秒

MouseMoveTo

MouseMoveTo(x: Integer, y: Integer) → Bool · 简单

将鼠标光标移动到任意显示器上的某个屏幕点，如同用户移动了鼠标。

参数

x: Integer — 水平屏幕位置，以像素为单位。
y: Integer — 垂直屏幕位置，以像素为单位。

返回值

如果已发送移动，则为 true；如果 Windows 阻止了移动，则为 false。

3 个示例: 让鼠标沿圆周移动, 点击某处，然后将光标放回原处, 脚本化拖动

MouseScrollHorizontal

MouseScrollHorizontal(amount: Integer) → Bool · 简单

在当前光标位置转动水平鼠标滚轮。若要在其他位置滚动，请先使用 MouseMoveTo。

参数

amount: Integer — 滚轮距离，120 为一格：正数向右滚动，负数向左滚动。在支持的应用中，较小的值可实现更精细的滚动。

返回值

如果已发送滚动，则为 true；如果 Windows 阻止了滚动，则为 false。

1 个示例: 按刻度滚动

MouseScrollVertical

MouseScrollVertical(amount: Integer) → Bool · 简单

在当前光标位置转动垂直鼠标滚轮。若要在其他位置滚动，请先使用 MouseMoveTo。

参数

amount: Integer — 滚轮距离，120 为一格：正数向上滚动，负数向下滚动。在支持的应用中，较小的值可实现更精细的滚动。

返回值

如果已发送滚动，则为 true；如果 Windows 阻止了滚动，则为 false。

1 个示例: 按刻度滚动

MouseUnlock

MouseUnlock() → Bool

解除对鼠标光标的任何限制，无论该限制是由 MouseLockToRect 还是由其他程序设置的。

参数

无参数。

返回值

如果光标已不受限制，则为 true；如果 Windows 拒绝了请求，则为 false。

1 个示例: 将光标限制在窗口内 5 秒

Multimedia

MultimediaGetMute

MultimediaGetMute(endpoint: Integer) → Bool

报告由 endpoint 选择的默认播放设备或麦克风在 Windows 中是否已静音。

参数

endpoint: Integer — 要检查的设备：AudioEndpoint.Playback（默认扬声器或耳机）、AudioEndpoint.Capture（默认麦克风）或 AudioEndpoint.Communications（Windows 用于通话的麦克风）。任何其他值都会使操作因错误而停止。

返回值

如果设备已静音，则为 true；如果未静音或设备不存在（例如未连接麦克风），则为 false。

1 个示例: 切换麦克风静音

MultimediaGetVolume

MultimediaGetVolume(endpoint: Integer) → Real

以 0.0 到 1.0 之间的 Real 值返回由 endpoint 选择的默认播放设备或麦克风的主音量。

参数

endpoint: Integer — 要读取的设备：AudioEndpoint.Playback（默认扬声器或耳机）、AudioEndpoint.Capture（默认麦克风）或 AudioEndpoint.Communications（Windows 用于通话的麦克风）。任何其他值都会使操作因错误而停止。

返回值

音量，范围为 0.0（静音）到 1.0（最大），与 MultimediaSetVolume 的刻度相同；如果设备不存在，则为 0.0。

1 个示例: 调高音量并显示屏幕提示

MultimediaPlayMp3File

MultimediaPlayMp3File(path: Text) → Bool · 简单

开始播放 MP3 文件，并在播放期间立即返回。开始播放另一个 MP3 会停止仍在播放的那一个。

参数

path: Text — .mp3 文件的完整路径，例如 C:/Music/done.mp3。

返回值

如果已开始播放，则为 true；如果文件不存在、Windows 无法在 10 秒内打开或播放它，或“全部停止”结束了等待，则为 false。

MultimediaPlayWavFile

MultimediaPlayWavFile(path: Text) → Bool · 简单

开始播放 .wav 声音文件，并在播放期间立即返回。开始播放另一个 WAV 会停止仍在播放的那一个。仅支持 .wav 文件；对于 MP3，请使用 MultimediaPlayMp3File。

参数

path: Text — .wav 文件的完整路径，例如 C:/Windows/Media/chimes.wav。

返回值

如果文件存在且已开始播放，则为 true；如果该路径上没有文件，则为 false。文件存在但不是可播放的 WAV 时，返回 true 且不播放任何内容。

1 个示例: 播放声音

MultimediaSetMute

MultimediaSetMute(endpoint: Integer, muted: Bool) → Bool · 简单

将由 endpoint 选择的默认播放设备或麦克风静音或取消静音，效果与 Windows 音量静音按钮相同。

参数

endpoint: Integer — 要更改的设备：AudioEndpoint.Playback（默认扬声器或耳机）、AudioEndpoint.Capture（默认麦克风）或 AudioEndpoint.Communications（Windows 用于通话的麦克风）。任何其他值都会使操作因错误而停止。
muted: Bool — true 表示将设备静音；false 表示取消静音。

返回值

如果已设置静音状态，则为 true；如果设备不存在或拒绝了更改，则为 false。

1 个示例: 在多次运行之间保持的开关

MultimediaSetVolume

MultimediaSetVolume(endpoint: Integer, level: Real) → Bool · 简单

将由 endpoint 选择的默认播放设备或麦克风的主音量设置为一个精确的级别。

参数

endpoint: Integer — 要更改的设备：AudioEndpoint.Playback（默认扬声器或耳机）、AudioEndpoint.Capture（默认麦克风）或 AudioEndpoint.Communications（Windows 用于通话的麦克风）。任何其他值都会使操作因错误而停止。
level: Real — 新音量，范围为 0.0（静音）到 1.0（最大）；0.5 相当于 Windows 音量滑块上的 50。超出 0.0 到 1.0 的值会被限制在该范围内。

返回值

如果已设置音量，则为 true；如果设备不存在或拒绝了更改，则为 false。

2 个示例: 调高音量并显示屏幕提示, 将 Arduino 旋钮变成音量控制

MultimediaToggleMute

MultimediaToggleMute(endpoint: Integer) → Bool · 简单

如果由 endpoint 选择的默认播放设备或麦克风未静音，则将其静音；如果已静音，则取消静音。之后可调用 MultimediaGetMute 获取新状态。

参数

endpoint: Integer — 要切换的设备：AudioEndpoint.Playback（默认扬声器或耳机）、AudioEndpoint.Capture（默认麦克风）或 AudioEndpoint.Communications（Windows 用于通话的麦克风）。任何其他值都会使操作因错误而停止。

返回值

如果已切换静音状态，则为 true；如果设备不存在或拒绝了更改，则为 false。这不是新的静音状态。

1 个示例: 切换麦克风静音

Plugin

PluginSendMessage

PluginSendMessage(pluginName: Text, message: Text, timeoutSeconds: Integer) → Text

向一个接受命令的正在运行的插件发送文本消息，并等待其回复。插件一次处理一条消息；在其忙碌时发送的消息会在队列中等待。

参数

pluginName: Text — 插件的显示名称，须完全匹配，包括大小写。
message: Text — 要发送的文本。其含义由插件决定。
timeoutSeconds: Integer — 等待回复的时间，以秒为单位，范围为 0 到 10；任何其他值都会使脚本因错误而停止。为 0 时，调用会立即返回空文本。

返回值

插件的回复；如果插件未及时回复，则返回空文本。没有这样的正在运行的插件、队列已满或消息过长，都会使脚本因错误而停止。

1 个示例: 与插件通信

Region

RegionGetCellIndexAt

RegionGetCellIndexAt(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, pointX: Integer, pointY: Integer) → Integer

将矩形按列和行拆分为网格，并返回包含某个点的单元格。单元格从 0 开始编号，从左到右，再从上到下。

参数

rectX: Integer — 要拆分的矩形的左边缘，以像素为单位。
rectY: Integer — 要拆分的矩形的上边缘，以像素为单位。
rectWidth: Integer — 矩形的宽度，以像素为单位。必须大于 0。
rectHeight: Integer — 矩形的高度，以像素为单位。必须大于 0。
columns: Integer — 网格中的列数。必须大于 0。剩余的像素依次分给前面的列，每列一个。
rows: Integer — 网格中的行数。必须大于 0。剩余的像素依次分给前面的行，每行一个。
pointX: Integer — 要查找的点的水平位置，所用像素单位与 rectX 相同。
pointY: Integer — 要查找的点的垂直位置，所用像素单位与 rectY 相同。

返回值

单元格编号（行号乘以列数，再加上列号）；如果该点位于矩形之外，或 rectWidth、rectHeight、columns 或 rows 不是正数，则为 -1。

RegionGetHeight

RegionGetHeight(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, index: Integer) → Integer

返回将矩形按列和行拆分为网格后某个单元格的高度。剩余的像素依次分给前面的行，每行一个。

参数

rectX: Integer — 要拆分的矩形的左边缘，以像素为单位。
rectY: Integer — 要拆分的矩形的上边缘，以像素为单位。
rectWidth: Integer — 矩形的宽度，以像素为单位。必须大于 0。
rectHeight: Integer — 矩形的高度，以像素为单位。必须大于 0。
columns: Integer — 网格中的列数。必须大于 0。
rows: Integer — 网格中的行数。必须大于 0。
index: Integer — 从 0 开始的单元格编号，从左到右、再从上到下计数，范围为 0 到列数乘以行数减 1。

返回值

单元格的高度，以像素为单位；如果 index 超出范围，或 rectWidth、rectHeight、columns 或 rows 不是正数，则为 -1。

RegionGetWidth

RegionGetWidth(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, index: Integer) → Integer

返回将矩形按列和行拆分为网格后某个单元格的宽度。剩余的像素依次分给前面的列，每列一个。

参数

rectX: Integer — 要拆分的矩形的左边缘，以像素为单位。
rectY: Integer — 要拆分的矩形的上边缘，以像素为单位。
rectWidth: Integer — 矩形的宽度，以像素为单位。必须大于 0。
rectHeight: Integer — 矩形的高度，以像素为单位。必须大于 0。
columns: Integer — 网格中的列数。必须大于 0。
rows: Integer — 网格中的行数。必须大于 0。
index: Integer — 从 0 开始的单元格编号，从左到右、再从上到下计数，范围为 0 到列数乘以行数减 1。

返回值

单元格的宽度，以像素为单位；如果 index 超出范围，或 rectWidth、rectHeight、columns 或 rows 不是正数，则为 -1。

RegionGetX

RegionGetX(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, index: Integer) → Integer

返回将矩形按列和行拆分为网格后某个单元格的左边缘。剩余的像素依次分给前面的列，每列一个。

参数

rectX: Integer — 要拆分的矩形的左边缘，以像素为单位。
rectY: Integer — 要拆分的矩形的上边缘，以像素为单位。
rectWidth: Integer — 矩形的宽度，以像素为单位。必须大于 0。
rectHeight: Integer — 矩形的高度，以像素为单位。必须大于 0。
columns: Integer — 网格中的列数。必须大于 0。
rows: Integer — 网格中的行数。必须大于 0。
index: Integer — 从 0 开始的单元格编号，从左到右、再从上到下计数，范围为 0 到列数乘以行数减 1。

返回值

单元格的左边缘；如果 index 超出范围，或 rectWidth、rectHeight、columns 或 rows 不是正数，则为 -1。真实的单元格也可能从 -1 开始，因此请先检查 index。

RegionGetY

RegionGetY(rectX: Integer, rectY: Integer, rectWidth: Integer, rectHeight: Integer, columns: Integer, rows: Integer, index: Integer) → Integer

返回将矩形按列和行拆分为网格后某个单元格的上边缘。剩余的像素依次分给前面的行，每行一个。

参数

rectX: Integer — 要拆分的矩形的左边缘，以像素为单位。
rectY: Integer — 要拆分的矩形的上边缘，以像素为单位。
rectWidth: Integer — 矩形的宽度，以像素为单位。必须大于 0。
rectHeight: Integer — 矩形的高度，以像素为单位。必须大于 0。
columns: Integer — 网格中的列数。必须大于 0。
rows: Integer — 网格中的行数。必须大于 0。
index: Integer — 从 0 开始的单元格编号，从左到右、再从上到下计数，范围为 0 到列数乘以行数减 1。

返回值

单元格的上边缘；如果 index 超出范围，或 rectWidth、rectHeight、columns 或 rows 不是正数，则为 -1。真实的单元格也可能从 -1 开始，因此请先检查 index。