macOS便利API

当提及GUI对象时，Squish文档使用“小部件”这个术语。macOS开发者可能更熟悉这个概念下的“视图”一词。

macOS便捷函数参数

一些macOS便捷函数可以接受一个modifierState参数，表示在鼠标点击时按下哪些特殊键。有些函数还可以接受一个button参数，表示按下的是哪个鼠标按钮。

modifierState是一个整数，用作位掩码。其值可以是0（无修饰符）或一个或多个：1（Shift）、2（Control）、4（Command）、8（Option），多个修饰符可以用或操作符组合在一起（例如，1|2表示Shift+Control）。

button是一个整数：0表示“主”鼠标按钮（通常是左键），1表示右键。

macOS便捷函数

以下是一些指向macOS便捷API函数的快速链接

activateItem(objectOrName)

此函数激活了objectOrName菜单项。此菜单项必须是NSMenuItem的引用（或一个标识该NSMenuItem的名称）。菜单项可以是应用程序菜单的一部分或NSPopUpButton中的菜单项。

macOS辅助功能

要重新播放macOS上的菜单激活以及使用nativeType(keys)和nativeMouseClick(x, y, button)函数，您必须在系统偏好设置中为某些进程启用辅助功能支持。系统将在第一次启动squishide时打开一个弹出对话框，允许您直接进入偏好设置对话框以启用squishide的辅助功能支持。

要打开对话框，请选择系统偏好设置并选择安全性与隐私。然后选择左侧的隐私选项卡，并选择左边的辅助功能。

要更改设置，单击左下角的锁定图标并输入管理员的凭据。然后从列表中检查需要权限的Squishide或Terminal应用。

在任何时候，都只有一个拥有对辅助功能API的访问权限的squishide实例可以运行自动菜单、使用nativeType(keys)或nativeMouseClick(x, y, button)函数的程序集。为了使用另一个squishide，例如从同一系统上的另一个Squish安装，您需要从列表中完全删除现有的条目，然后启动另一个squishide实例。然后当对话框弹出时再次启用辅助功能支持。

最后，有时macOS会在启动squishide时总是要求启用辅助功能支持。在这种情况下，完全重置辅助功能启用的数据库并清除整个列表可能会有所帮助。这可以使用macOS中的tccutil来完成

tccutil reset Accessibility

执行命令后，重新启动squishide以再次触发辅助功能启用弹出窗口。

chooseFile([filePath, filePath, ...])

在测试回放过程中自动化操作Cocoa文件选择对话框（NSOpenPanel）。它必须在打开文件选择器的 mouseClick 之后立即调用。作为参数提供的字符串列表将被馈送到AUT作为所选文件。使用它来避免通过原生输入对 NSOpenPanel 进行易于出错的自动化。可以通过传递空数组到该函数取消文件对话框。

测试脚本负责确保给定的路径对AUT来说是合理的，例如，它们可以在文件选择器中被实际选中。

如果在一个 NSOpenPanel 被触发后没有调用 chooseFile，那么 NSOpenPanel 将在延迟后正常打开。延迟可以在 SQUISH_DIR/etc/macwrapper.ini 中配置。

chooseFile(filePath)

为 chooseFile 提供一种便捷的重载形式，它只接受一个 filePath 字符串。

clearWebObjectCache()

此功能用于清除WebView中对象的层次结构名的缓存。在Web应用程序在与网页交互后删除网页的一些元素，然后应该使用之前相同的层次结构名找到不同的对象的情况下，这可能是有用的。如果没有清除此情况下的缓存，则当网站更改其内容后重新搜索层次结构名时，将检索旧对象。然而，缓存对于保持更深层次结构的搜索的高效和可扩展性是必要的。

——过时—— clickButton(objectOrName)

此功能与 mouseClick(objectOrName) 相同。它仅用于与旧脚本兼容。不应在新脚本中使用它，因为它最终可能从Squish中删除。

——过时—— clickTab(objectOrName)

此功能与 mouseClick(objectOrName) 相同。它仅用于与旧脚本兼容。不应在新脚本中使用它，因为它最终可能从Squish中删除。

doubleClick(objectOrName)

doubleClick(objectOrName, x, y)

doubleClick(objectOrName, x, y, modifierState, button)

此功能在指定的 objectOrName 小部件上双击鼠标。

默认情况下在对象中间点击，但可以通过传递对象相对坐标，即 x 和 y 来改变。默认使用按钮 0（主按钮），但可以通过指定可选的 button 参数来改变。同样，默认修改器状态为 0（无修改器），但也可以通过指定 modifierState 参数来改变。注意，要指定修改器，必须同时指定按钮；要指定修改器，必须指定位置。有关 modifierState 和 button 参数有效值的更多信息，请参阅 macOS Convenience Function Parameters。

installEventHandler(eventName, handlerFunctionName)

此功能安装一个全局事件处理器。当发生指定为 eventName 类型的事件时，将调用名为 handlerFunctionName 的脚本函数（必须以字符串形式传递，而不是以函数引用形式传递，除了Python也支持传递函数引用）。

eventName 可以是以下事件类型中的任何一个的名称：

• "Crash" – 如果AUT崩溃时发生
• "SheetOpened" – 当macOS窗口显示时发生（注意，这仅适用于Cocoa应用程序）
• "WindowOpened" – 发生在 macOS 最高级窗口显示时（注意，这仅适用于 Cocoa 应用程序）
• "Timeout" – 当 Squish 响应超时时发生

当 SheetOpened 事件发生时，会调用 handlerFunctionName 中指定的函数。该函数传入一个参数——打开表单的单窗口对象。如果您想访问表单本身，请调用位于 NSWindow 对象上的 attachedSheet 函数。

当 WindowOpened 事件发生时，会调用 handlerFunctionName 中指定的函数。该函数传入一个参数——打开的窗口对象。此事件仅针对顶级窗口（NSWindow 和 NSPanel 对象），但它不会发生在以表单形式显示的窗口上。如果您对表单感兴趣，请使用 SheetOpened 事件。

有关示例，请参阅 如何使用事件处理程序。

mouseClick(objectOrName)

mouseClick(objectOrName, x, y)

mouseClick(objectOrName, x, y, modifierState, button)

此函数在指定的 objectOrName 小部件上单击鼠标。

默认情况下在对象中间点击，但可以通过传递对象相对坐标，即 x 和 y 来改变。默认使用按钮 0（主按钮），但可以通过指定可选的 button 参数来改变。同样，默认修改器状态为 0（无修改器），但也可以通过指定 modifierState 参数来改变。注意，要指定修改器，必须同时指定按钮；要指定修改器，必须指定位置。有关 modifierState 和 button 参数有效值的更多信息，请参阅 macOS Convenience Function Parameters。

mouseDrag(objectOrName, x, y, dx, dy)

mouseDrag(objectOrName, x, y, dx, dy, modifierState, button)

此函数执行从 objectOrName 小部件到水平偏移 dx 像素和垂直偏移 dy 像素的鼠标拖动，这是在 objectOrName 小部件的坐标中的 x，y 位置。

默认情况下使用按钮 0（主按钮），但可以通过指定可选的 button 参数来更改它。同样，默认修改状态为 0（无修改），但可以通过指定 modifierState 参数来更改它。请注意，要指定修改状态，必须也要指定按钮，并且要指定修改状态，必须也要指定位置。请参阅 macOS 便捷函数参数，了解哪些值适用于 modifierState 和 button 参数。

scrollToObject(objectOrName)

此函数确保通过必要的滚动使指定的 objectOrName 小部件在其包含的滚动小部件中可见。

如果有嵌套的滚动小部件，则包含 objectOrName 小部件的最内层小部件将是滚动的小部件。

目前，此函数仅适用于 NSView 子类以及位于 NSTableView 和 NSOutlineView 中的项目。如果您需要支持其他类，请联系 froglogic 支持。

type(objectOrName, text)

此函数将指定的 文本（就好像用户使用了键盘一样）输入到 objectOrName 可编辑小部件中。如果文本被尖括号（<>）包围，它会被解析为一个键组合，例如 "<Ctrl+Return>"。输入区分大小写，因此 type(object, "R") 与 type(object, "r") 是不同的。

以下非打印键在键组合中受支持： <Ctrl>、<Command>、<Shift>、<Option>、<Up>、<Down>、<Left>、<Right>、<Del>、<Return>、<Tab>、<Backtab>、<Esc> 和 <Backspace>。

uninstallEventHandler(eventName, handlerFunctionName)

此函数卸载之前使用 installEventHandler(eventName, handlerFunctionName) 安装的某个事件处理程序。