网络对象API

Squish提供了一个用于Web对象的完整API，如下说明。

Squish的全局Web功能按字母顺序列于下文，其后是按字母顺序排列的预定义对象和类，以及它们包含的功能、方法和属性，也按字母顺序排列。

Web对象API函数参数

在下文中列出的一切函数，凡带有objectOrName参数的，参数可以是对象或对象名称的引用。

Web对象API的一些函数可以接受一个modifierState参数，用于指示鼠标点击时按下哪些特殊键，以及是否点击了右键。默认为左键。

modifierState可以是以下之一：HTML_Event.AltKey、HTML_Event.ControlKey、HTML_Event.ShiftKey、HTML_Event.RightButton。在此处所示的形式适用于Python和JavaScript。对于Perl和Ruby，将点替换为两个冒号，例如HTML_Event::ControlKey，对于Tcl，则使用枚举函数，例如enum HTML_Event Control。

可以通过位运算或（逻辑或）组合modifierState值，例如（JavaScript、Perl、JavaScript、Ruby）mouseClick(..., HTML_Event.ShiftKey | HTML_Event.RightButton)。

与多个标签或浏览器窗口交互

Squish目前支持与Firefox、Microsoft Edge、Mac上的Safari、Google Chrome和基于Chromium的应用程序的多重浏览器窗口或标签进行交互。它使用活动浏览器标签的概念来执行点击操作或在对象中查询信息。因此，当通过打开新标签或窗口或使用Squish提供的专门标签函数更改活动标签时，交互和对象查找将在新激活的标签中发生。

单个标签由BrowserTab类表示，可以通过activeBrowserTab()、browserTabs()或使用多属性名称来访问，如BrowserTab类所述。

对基于Chromium的应用程序的支持有限，因为Squish只能访问此类应用程序内多个Web视图的内容。如果应用程序允许更改哪些Web视图可见哪些不可见，例如因为它使用选项卡小部件来显示它们，则Squish无法记录或重播此类更改。

Web函数的本地变体

许多交互函数（如mouseClick、setText、clickItem或selectOption）如果不提及其他native则生成JavaScript级别的网页事件。而对于提及native的则会生成操作系统事件。

本地变体需要正确确定对象在屏幕上的位置，这取决于浏览器和网站内容，可能会有些挑战。它们还要求系统上没有人与此交互或干扰它们。使用JavaScript事件的功能通常会在使用鼠标或键盘进行其他操作时仍然工作。

然而，由于安全原因，某些交互操作受到浏览器的限制，因此它们不能由网站上的JavaScript触发。此外，基于JavaScript的功能可能无法正确复制原始意图。例如，setText无法在JavaScript中正确生成键盘事件，所以它设置字段的值并触发一个change事件，这不足以让某些网站意识到新的值。

Web对象中的合成属性

在DOM树中表示HTML元素的对象根据HTML标准提供对这些HTML元素的公共属性和属性的访问。除了这些之外，它们还可能提供某些信息的便利属性，称为合成属性。大多数这些合成属性不能用作查找这些对象的单一名称的部分，因为Squish通过一种不可直接用于对象查找的机制提供它们。所以例如，HTML_Object.height属性不能用于单一名称。在各个属性文档中对此规则有一些例外，例如HTML_Object.simplifiedInnerText。

Web对象API对象和类

以下是一些到Web对象API对象和类的快速链接（按其继承层次结构显示）

以下是一些到Web对象API函数的快速链接

activateBrowserTab(tab)

此函数更改浏览器中的活动选项卡，如果需要，还会激活对应的窗口。要激活的 tab 必须是 BrowserTab 类的实例。

在基于 CEF 的 Electron 或其他基于 Chromium 的应用程序中使用时，此功能不受支持。在调用列表中第一个以外的 BrowserTab 对象时将抛出异常。

在此类应用程序中激活不同的 Web 视图应通过与其匹配的桌面应用程序版本 Squish 自动化。

activeBrowserTab()

此函数以 BrowserTab 类的实例的形式检索当前活动选项卡。这将是执行所有其他函数和对象查找的选项卡。

在基于 CEF 的 Electron 或其他基于 Chromium 的应用程序中使用时，此功能尚不完全支持。返回的 BrowserTab 对象总是列表中的第一个，并且不会根据应用程序中被激活的 Web 视图而改变。

automateLogin(username, password)

此函数自动使用原生的浏览器认证对话框，传入指定的 username 和 password。

有关在不同场景中使用此函数的详细信息，请参阅自动化原生登录。

注意：在 macOS 上，您必须通过系统偏好设置中的辅助功能启用“通用访问”才能使用此功能。请参阅 macOS 通用访问。

browserTabs()

此函数检索与浏览器中所有窗口当前打开选项卡相对应的 BrowserTab 类实例的列表。

cancelPrompt()

此函数用于模拟用户取消页面 JavaScript 代码中对 prompt 函数的调用而产生的对话框。

在幕后，当Squish测试一个执行JavaScript prompt函数调用的Web应用程序时，Squish会阻止对话框弹出（如果浏览器允许这样做，否则将自动处理），它会抑制对话框，停止Web应用程序的执行，并在重新播放取消时调用cancelPrompt函数，如果重新播放确认，则调用closePrompt(":dummy", text)函数。然后，Squish继续执行Web应用程序。

另请参阅 closePrompt(":dummy", text)，String lastPromptDefault(browserTab) 和 String lastPromptText(browserTab)。

chooseColor(objectOrName, htmlRGBvalue)

此函数用于模拟用户通过HTML颜色字段元素与用户交互选择颜色。必须将objectOrName识别为HTML_ColorField类，否则将引发可捕获的异常。必须将htmlRGBvalue识别为一个包含HTML颜色值（格式如"#RRGGBB"）的字符串，其中每个组件（RR为红色，GG为绿色，BB为蓝色）是表示组件颜色值的两个十六进制数，范围在00到FF之间。（例如，请参阅W3School的HTML颜色页面。）

有关如何添加自定义颜色选择器的支持，请参阅颜色选择器支持。

chooseDate(objectOrName, date)

此函数用于模拟用户通过与用户交互选择日期的日期选择器元素。必须将objectOrName识别为HTML_DateChooser类，否则将引发可捕获的异常。必须将date识别为DateTime类型。

有关如何添加自定义日期选择器的支持，请参阅日期选择器支持。

chooseFile(filepath)

此函数可以用来自动化浏览器打开的文件对话框的交互。必须将filepath识别为要选择的文件的绝对路径。

在文件对话框不是通过标准HTML文件域打开，而是使用一些定制控件来管理上传的文件的情况下，此函数可能很有用。这些控件的交互通常可以正常录制，然后在脚本中添加一行chooseFile以自动选择文件对话框中的文件。

clearObjectCache()

这是一个高级函数，在测试会自动更新自己，替换一些或所有HTML元素为新元素的网站时可能很有用。在这种情况下，在更新后调用此函数可以帮助Squish通过重新读取网页的DOM树来刷新其内部对象缓存。

此函数清除Squish for Web使用的内部缓存，以便Squish无需在浏览器中重复查找相同的对象。调用此函数后，所有对象引用（例如由Object waitForObject(objectOrName)和Object findObject(objectName)函数返回的引用）都无效，因此必须获取新的对象引用，例如使用Object waitForObject(objectOrName)函数来获取任何在清除缓存之后想要交互的对象的新引用。

另见，rehook(browserTab)函数。

clickButton(objectOrName)

此函数点击指定的objectOrName按钮，它可以是一个button、radio、checkbox、submit或image对象。

clickItem(objectOrName, itemText)

clickItem(objectOrName, itemText, modifierState)

clickItem(objectOrName, row, column)

clickItem(objectOrName, row, column, modifierState)

此函数使用可选的modifierState修饰状态（如果提供）点击具有给定itemText的项或给定objectOrName视图小部件中的row和column的项。

注意，在row和column版本中，objectOrName必须是HTML_CustomItemView类的类型。此外，如果row或column超出范围（小于零或大于行数或列数），则不会引发异常，也不会执行点击。

有关哪些值对modifierState有效，请参阅Web对象API函数参数。

clickLink(objectOrName)

此函数点击由objectOrName对象标识的超链接（锚点）。

clickTab(objectOrName, tabTitle)

此函数在objectOrName选项卡小部件中点击带有选项卡标题文本tabTitle的选项卡。如果存在这样的选项卡，则它现在将是最高级（即可见）的选项卡。如果objectOrName未被识别为HTML_TabWidget类，则会引发可捕获的异常。

有关如何添加对自定义选项卡小部件的支持，请参阅Tab Widget支持。

clickTreeHandle(objectOrName, itemText)

此函数点击具有指定itemText的objectOrName树小部件中项的展开/折叠（树句柄）。

注意：该函数通常不应在手写测试脚本中使用，因为Squish可以处理所有受标准支持的网络工具包使用的所有树小部件的这种交互。此函数存在的主要原因是为了支持与Squish默认不支持的自定义Web树小部件的交互。

有关更详细的信息，包括使用示例，请参阅如何设置对复杂小部件的支持。

closeAlert(":dummy")

此函数用于模拟用户在响应网页JavaScript代码中alert函数调用时弹出的对话框中点击确定。第一个参数必须是假对象名称（例如，":dummy"）；。

在幕后，当Squish测试一个执行JavaScript alert函数调用的Web应用程序时，Squish不等待对话框弹出，而是抑制对话框（如果浏览器允许这样做，否则对话框将是自动化的），停止Web应用程序的执行，并等待closeAlert函数。然后Squish恢复Web应用程序的执行，就像用户已关闭对话框一样。

请参阅String lastAlertText(browserTab)。

closeConfirm(":dummy", confirmed)

此函数用于模拟用户在响应网页JavaScript代码中confirm函数调用时弹出的对话框中点击是或否。第一个参数必须是假对象名称（例如，":dummy"）；confirmed是一个布尔值，若为true则表示用户点击了是，若为false则表示用户点击了否。

在幕后，当Squish测试一个执行JavaScript confirm函数调用的Web应用程序时，Squish不等待对话框弹出，而是抑制对话框（如果浏览器允许这样做，否则对话框将是自动化的），停止Web应用程序的执行，并调用closeConfirm函数，如果记录到测试员点击了是则传递true，如果点击了否则传递false。然后Squish恢复Web应用程序的执行，将true或false的结果作为confirm函数调用的返回值返回给应用程序。

请参阅String lastConfirmText(browserTab)。

closePrompt(":dummy", text)

此函数用于模拟用户在响应网页JavaScript代码中prompt函数调用时弹出的对话框中键入一些文本。第一个参数必须是假对象名称（例如，":dummy"）；text是通常发送到提示对话框文本编辑器的文本。

在幕后，当Squish测试一个执行JavaScript prompt函数调用的Web应用程序时，Squish不等待对话框弹出，而是抑制对话框（如果浏览器允许这样做，否则对话框将是自动化的），停止Web应用程序的执行，并在测试记录时回放取消或调用closePrompt函数以确认，传递测试员输入的文本。然后Squish恢复Web应用程序的执行，将文本作为prompt函数调用的返回值返回给应用程序。

请参阅cancelPrompt()、String lastPromptDefault(browserTab)和String lastPromptText(browserTab)。

closeWindow(":[Window]")

此函数关闭浏览器窗口。参数必须是字符串":[Window]。

attachToBrowser(portOrWindowTitle)

此函数允许将Squish for Web连接到已在服务器配置中选择的浏览器运行的实例。这可以在浏览器不应由Squish本身启动，而是由一些作为测试自动化的一部分运行的其他程序启动的情况下使用。portOrWindowTitle对于大多数支持的浏览器都是必需的，并指定了如何找到Squish应连接的浏览器实例。以下示例代码显示了哪些浏览器使用此参数以及应提供哪种类型的值。当指定数字时，必须与在浏览器扩展安装期间配置的通信端口号相匹配。

当portOrWindowTitle是一个字符串时，它需要与现有浏览器窗口的标题匹配。窗口标题模式可以使用通配符来允许连接到标题的一些部分发生变化的窗口。（*匹配任意数量的字符，?匹配任意单个字符）。然而，必须以这种方式指定通配符，以便仅识别单个浏览器窗口。窗口标题通常是浏览器活动标签的标题，通常可以从任务栏中鼠标悬停在该窗口条目上时出现的工具提示中获取。

有关如何使用此功能的更完整的说明，请参阅将附件附加到运行中的Web浏览器。

javascriptperlpythonrubytcl

function main() {
  // Firefox (for Chrome use 9935)
  attachToBrowser( 9932 );
  // Internet Explorer
  // attachToBrowser( "*Automated Cross-Platform GUI Testing" );
  // Safari
  // attachToBrowser();
}

sub main {
  # Firefox (for Chrome use 9935)
  attachToBrowser( 9932 );
  # Internet Explorer
  # attachToBrowser( "*Automated Cross-Platform GUI Testing" );
  # Safari
  # attachToBrowser();
}

def main():
  # Firefox (for Chrome use 9935)
  attachToBrowser( 9932 )
  # Internet Explorer
  # attachToBrowser( "*Automated Cross-Platform GUI Testing" )
  # Safari
  # attachToBrowser()

def main()
  # Firefox (for Chrome use 9935)
  attachToBrowser( 9932 )
  # Internet Explorer
  # attachToBrowser( "*Automated Cross-Platform GUI Testing" )
  # Safari
  # attachToBrowser()
end

proc main {} {
  # Firefox (for Chrome use 9935)
  invoke attachToBrowser 9932
  # Internet Explorer
  # invoke attachToBrowser "*Automated Cross-Platform GUI Testing"
  # Safari
  # invoke attachToBrowser
}

String contextOf(window)

注意：此函数已过时，除非您禁用了标签支持。考虑使用真实名称来识别浏览器标签页和窗口。

此函数返回给定window的上下文字符串。上下文字符串是页面的“基本位置”——这包括精确标识页面必要的任何父位置（例如，如果页面实际上是一个frame或iframe元素）。（另请参阅，HTML_Array contextList()和Boolean setContext(context)。）

HTML_Array contextList()

注意：此函数已过时，除非您禁用了标签支持。考虑使用browserTabs()函数来访问浏览器标签页和窗口。

此函数返回一个包含Squish已连接的浏览器窗口引用的HTML_Array Class。可以使用String contextOf(window)函数获取特定窗口的上下文。

注意：此列表不包括网页中存在的任何frame或iframe元素。它只包含Squish连接到的窗口。

（另请参阅，Boolean setFrameContext(browserTab, frameName)、String currentContext()、String contextOf(window)、Boolean setContext(context)和waitForContextExists(context)。）

String currentContext()

注意：此函数已过时，除非您禁用了标签支持。考虑使用activeBrowserTab()函数代替。

此函数返回当前活动的浏览器窗口。您可以使用 String contextOf(window) 来获取此窗口的字符串表示形式。如果页面使用框架或iframe，这也可以是此类框架的内容窗口，而不是包含该页面的窗口本身。（另请参阅，String contextOf(window)，Boolean setFrameContext(browserTab, frameName)，Boolean setContext(context)，以及waitForContextExists(context)。）

doubleClick(objectOrName, x, y)

此函数在objectOrName小部件上双击鼠标。点击发生在小部件的左上角或指定位置（x，y）——这相对于小部件自身的左上角——如果指定了。

dragAndDrop(src_objectOrName, sx, sy, target_objectOrName, tx, ty)

此函数执行拖放操作。它首先在 source_objectOrName 小部件上开始拖动，位置为 sx 和 sy（相对于 source_objectOrName 小部件的坐标），然后在小部件 target_objectOrName 上放下，位置为 tx 和 ty（相对于 target_objectOrName 小部件的坐标）。

startDrag(src_objectOrName, sx, sy)

此函数执行开始拖动操作。它从 source_objectOrName 小部件开始的坐标位置 sx 和 sy（在 source_objectOrName 小部件的坐标中）开始拖动。如果拖动开始后目标对象才变得可用，这可能很有用。

dropOn(target_objectOrName, tx, ty)

此函数执行放下操作。它将在 target_objectOrName 小部件上放下拖动的对象，位置为 tx 和 ty（在 target_objectOrName 小部件的坐标中）。此函数应在调用 startDrag 之后调用，即拖动操作正在进行中。

Object evalJS(browserTab, code)

Object evalJS(code)

此函数在浏览器标签中评估 JavaScript code 字符串，该标签由 browserTab 引用。返回 code 中最后一条语句的结果。（另请参阅如何使用 evalJS。）

注意：如果未指定 browserTab，则调用将始终使用最初加载的标签，即使当前活动的是其他标签。如果测试涉及多个浏览器标签或窗口，这可能导致意外的行为，因此我们建议在新脚本中始终指定 browserTab 参数。

Boolean hasContext(context)

注意：除非您已禁用标签支持，否则此函数已弃用。当您想要验证给定框架是否存在时请考虑使用 hasFrameContext，如果您想检查标签是否存在，请使用带有能够识别特定标签的限定名称的 waitForObject。

此函数返回 true，如果包含与 context 匹配 URL 的窗口已打开并且可以通过测试脚本来访问；否则返回 false。上下文字符串是页面的“基本位置”，这包括用于精确识别页面（例如，如果页面实际上是帧或iframe元素）所必需的任何父位置。（另请参阅，Boolean setContext(context) 和 waitForContextExists(context)。）

Boolean hasFrameContext(browserTab, context)

此函数返回 true，如果由 browserTab 引用的标签有一个与 context 匹配的框架，并且可以通过测试脚本来访问；否则返回 false。框架上下文是基于框架在内部框架中的嵌套来标识页面内部框架的字符串。例如，页面的第一个框架有上下文 FRAME1，第二个 FRAME2 等，如果一个框架有另一个内部框架，可以使用 FRAME1.FRAME1 识别。（另请参阅，Boolean setFrameContext(browserTab, frameName)。）

installEventHandler(eventName, handlerFunctionNameOrReference)

此函数安装一个全局事件处理器。当发生 eventName 类型的事件时，将调用 handlerFunctionNameOrReference 中命名的或引用的脚本函数。

下面的 eventName 可以是以下任何事件类型的名称

AlertOpened – 当 JavaScript 的 window.alert 函数显示一个警告框时发生
BodyUnloaded – 当 Squish 浏览器加载新页面或重新加载当前页面时发生。此事件在 Squish 成功 hook 任何框架或 iframe 时也会发出。处理器函数接收两个参数。第一个参数是更改的窗口或框架的 Squish context 名称。第二个参数是浏览器将要卸载的内容的 location URL。
ConfirmOpened – 当 JavaScript 的 window.confirm 函数显示一个确认（确定/取消）框时发生
Crash – 如果 AUT 崩溃则发生
ModalDialogOpened – 当使用 Internet Explorer 特定的 JavaScript showModalDialog 函数打开模态对话框时发生
ModelessDialogOpened – 当使用 Internet Explorer 特定的 JavaScript showModelessDialog 函数打开无模式对话框时发生
PromptOpened – 当 JavaScript 的 window.prompt 函数显示一个提示框时发生
Timeout – 当 Squish 响应超时发生
WindowOpened – 当使用 JavaScript 的 window.open 函数打开新窗口时发生

handlerFunctionName 中的函数在注册的事件之一发生时（不带参数）会被调用。

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

注意： 如果调用 installEventHandler 函数时 AUT 已经启动，则该函数将只起作用。例如，可以使用 ApplicationContext startApplication(autName) 函数。

Boolean isBrowserDialogOpen()

此函数返回 true，如果当前打开的是原生浏览器对话框（如登录对话框、证书对话框等）；否则返回 false。

注意：在 macOS 上，您必须通过系统偏好设置中的辅助功能启用“通用访问”才能使用此功能。请参阅 macOS 通用访问。

注意：Squish无法检测从网页内容打开的对话框，因此当自动化基于Chromium的应用程序时，此功能始终返回false。

布尔 isBrowserOpen()

此函数返回浏览器是否已运行，返回值为布尔类型， bağlı olarak true或false。

布尔 isPageLoaded(browserTab)

布尔 isPageLoaded()

如果浏览器标签中指定的browserTab的页面已经完全加载，则此函数返回true，否则返回false。完全以及成功的加载意味着页面中的所有对象都可以潜在地被访问。此函数可以与布尔 waitFor(condition)函数一起使用，在测试脚本中访问页面之前等待页面加载。

由于页面加载、HTTP请求等都是异步的，即使调用isPageLoaded函数后返回值为true，仍然需要使用Object waitForObject(objectOrName)函数（或其他等待函数）以确保感兴趣的特定对象已经准备好被访问。此外，可能需要在Object waitForObject(objectOrName)函数中将超时时间设置为比默认的20 000毫秒更长的值。（另请参阅如何在测试中同步网页加载。）

字符串 lastAlertText(browserTab)

字符串 lastAlertText()

此函数返回在指定的browserTab中，网页上最近出现的alert函数调用中出现的文本（如果没有执行任何alert调用，则可能为空）。

如果有多个警报，应使用clearAlertText()在警报之间清除其值。

clearAlertText()

此函数清除字符串 lastAlertText(browserTab)的值。

字符串 lastConfirmText(browserTab)

字符串 lastConfirmText()

此函数返回在指定的browserTab中，网页上最近出现的confirm函数调用中出现的文本（如果没有执行任何confirm调用，则可能为空）。

如果有多个确认，应使用字符串 clearConfirmText()在确认之间清除其值。

另请参阅closeConfirm(":dummy", confirmed)。

字符串 clearConfirmText()

此函数清除字符串 lastConfirmText(browserTab)返回的值。

字符串 lastPromptDefault(browserTab)

字符串 lastPromptDefault()

此函数返回在指定的browserTab中，网页上最近出现的prompt函数调用中出现的文本（如果没有执行任何prompt调用，则可能为空）。

另请参阅字符串 clearPromptDefault(browserTab)、closePrompt(":dummy", text)和字符串 lastPromptText(browserTab)。

String clearPromptDefault(browserTab)

此函数清除了String lastPromptDefault(browserTab)返回的值。

String lastPromptText(browserTab)

String lastPromptText()

此函数返回在指定的browserTab中，网页上最近出现的prompt函数调用中出现的文本（如果没有执行任何prompt调用，则可能为空）。

请参阅String clearPromptText(browserTab)、closePrompt(":dummy", text)和String lastPromptDefault(browserTab)。

String clearPromptText(browserTab)

此函数清除了由String lastPromptText(browserTab)返回的值

loadUrl(url)

注意：此函数已过时。如果可能，请考虑使用startBrowser(url)，或通过JavaScript直接设置窗口的location.href属性来使其立即返回。有关比较这两个示例的说明，请参阅自动化本地登录。

此函数打开一个网络浏览器并加载数据url。

mouseClick(objectOrName)

mouseClick(objectOrName, modifierState)

mouseClick(objectOrName, x, y)

mouseClick(objectOrName, modifierState, x, y)

此函数在指定的objectOrName小部件上点击鼠标。点击发生在小部件的左上角或在指定的情况下，位置为（《translate="no">x，y）——相对小部件自身的左上角——如果指定的话，并且带有给定的modifierState，如果指定的话。

有关哪些值对modifierState有效，请参阅Web对象API函数参数。

nativeMouseClick(objectOrName, button)

nativeMouseClick(objectOrName, x, y, button)

此函数在《translate="no">objectOrName小部件指定的位置x和y（如果指定的话），否则在x=10 / y=10（在《translate="no">objectOrName小部件坐标中）模拟本地鼠标点击。

《translate="no">button参数是要使用的鼠标按钮，并且必须是《translate="no">MouseButton.LeftButton、《translate="no">MouseButton.MiddleButton、《translate="no">MouseButton.RightButton或《translate="no">MouseButton.NoButton（仅执行鼠标移动）之一。

注意：对于支持此功能的浏览器类型，将自动激活包含HTML元素的BrowserTab（或WebView）对象。此规则的例外是所有通过“基于Chromium的应用程序”选项自动化的浏览器。

请使用nativeMouseClick而不是mouseClick时，用于输入字段以确保在点击它们时将输入焦点移入。这样做可以正确复制用户操作。《translate="no">nativeMouseClick函数确保对象的浏览器选项卡具有输入焦点，并且它出现在其他窗口的前面。这是无法通过《translate="no">mouseClick函数完成的，因为《translate="no">mouseClick函数作为网站的一部分运行，无法更改操作系统输入焦点。它只能在不影响操作系统的输入焦点的前提下，在网页内移动焦点。

openNewTab(url)

openNewTab(url, timeout)

此函数在浏览器中打开一个新的标签页，加载指定的 url。该函数返回一个表示新打开标签页的 BrowserTab 类对象。

该函数接收一个可选的以毫秒为单位的 timeout 参数。如果在创建标签页、加载 url 或连接加载的网页时用时超过指定超时，则函数将取消创建标签页。如果发生超时，将生成一个错误，指示超时的原因。

注意：此函数不是所有类型的浏览器都可用。目前支持 Internet Explorer、Firefox、Google Chrome、Safari >=12 和 Microsoft Edge。

raiseWindow()

此函数尝试将浏览器窗口提升到窗口堆栈的最顶层，以便没有任何重叠窗口在其上方。

rehook(browserTab)

rehook?

这是一个高级函数，它重新加载并初始化运行在通过 browserTab 引用的标签内的 Squish for Web 的部分。我们建议尽可能使用 clearObjectCache() 函数，因为它稍微快一些，也更安全。browserTab 参数是可选的，如果没有提供，Squish for Web 将重新连接最初加载的标签。

注意：如果未指定 browserTab，则调用将始终使用最初加载的标签，即使另一个标签当前是活动的也是如此。如果测试使用多个浏览器标签或窗口，这可能导致意外行为，因此我们建议在新的脚本中始终指定 browserTab 参数。

JsObject retrieveJSObject(javascriptcode)

此函数执行一个 JavaScript 片段，并返回该代码片段的结果值。返回值可以是原始值，即字符串或数字，也可以是作为 JsObject 的 JavaScript 对象引用。

scrollTo(objectOrName, top)

此函数滚动浏览器，使 objectOrName 小部件可见。您可以使用可选的布尔参数 top 将对象与屏幕的顶部或底部对齐（即传递 true 将对齐到顶部，传递 false 将对齐到底部）。

selectOption(objectOrName, text)

此函数选择在 objectOrName 选择表单元素（可能是一个选择或单选元素）中具有给定 text 的选项。如果该元素是一个多选框，可以在 text 中通过逗号分隔传递要选择的多个选项。

selectOptions(objectOrName, listOfTexts)

此函数从 objectOrName 选择表单元素（可能是一个选择或单选元素）中选择选项。对于 listOfTexts 中的每个条目，将选择具有相应可见文本的对应选项。如果元素仅允许单选，传递给 listOfTexts 的内容只能有一个条目。

selectOptionByValue(objectOrName, value)

此函数选择在 objectOrName 选择表单元素（可能是一个选择或单选元素）中具有给定 value 属性的选项。

selectOptionsByValue(objectOrName, listOfValues)

此函数从objectOrName选择表单元素（可能是一个选择或单选选择元素）中选择选项。对于listOfValues中的每个条目，都将选择具有该值属性的相应选项。如果元素仅允许单选，传递的listOfValues必须只包含一个条目。

sendEvent(eventName, objectOrName, x, y, modifierState, button)

此函数将类型为eventName的事件发送到objectOrName元素。必须为以下其中一个：

"mouseup"
"mousedown"
"mouseover"
"mouseout"
"mousemove"
"click"
"pointerover"
"pointerenter"
"pointerdown"
"pointermove"
"pointerup"
"pointercancel"
"pointerout"
"pointerleave"

x和y参数是相对objectOrName的事件发生坐标。目前的modifierState参数被忽略，但对于它，应该总是传递一个值为 0 的值。button必须是以下之一：1（左按钮）、2（右按钮）或 4（中按钮）。

Boolean setContext(context)

注意：除非您禁用了标签支持，否则此函数已被弃用。考虑通过一个引用浏览器标签的容器属性扩展现有对象名，以便在您想要查找的对象处发生查找。如果您已使用setContext选择网页中的特定帧进行对象查找，考虑使用接受浏览器标签和上下文名称的重载Boolean setFrameContext(browserTab, frameName)。

此函数使指定的context成为活动窗口。此上下文被用作查找对象名称的首选窗口。这意味着后续的所有对象查找都会在新的活动窗口的上下文中首先执行，并且只有在没有找到对象时才会继续在其他已知的上下文中查找。上下文字符串是页面的“基本位置”——这包括用于精确识别页面（例如，如果页面实际上是框架或iframe元素）的任何父位置。窗口的位置是由在URL中加载的HTML（或php、jsp、asp）文件创建的。因此，例如，“http://yourserver.com/path/to/file.html?parameter=value”，上下文将仅仅是“file.html”。如果窗口的URL没有“file.html”这样的文件名，例如“http://yourserver.com/path/?parameter=value”，则Squish将简单地假设名称为“index.html”。此外，如果有多种上下文具有相同的文件名，则会在上下文中添加一个数字。这是通过在数字周围使用角度括号来完成的，所以如果在上面的例子中您打开了两个“file.html”页面的窗口，则第二个窗口将使用“file.html<2>”作为上下文名称。您可以通过使用HTML_Array contextList()函数在任何时候访问已知的窗口，以及String contextOf(window)检索它们的名称来很容易地看到Squish为给定窗口创建和期望的上下文。（参见，HTML_Array contextList()，String contextOf(window)，String currentContext()，Boolean setFrameContext(browserTab, frameName)，waitForContextExists(context)。）

此函数如果在无法找到上下文名称时将抛出一个可捕获的脚本错误。您可以通过文件 etc/webwrapper.ini 中的 ThrowErrorOnUnknownContextNames 设置来更改此行为。如果该设置设置为 false，此函数将在找到并激活给定的框架上下文名称时简单返回 true，否则返回 false。

setFocus(objectOrName)

此函数将输入焦点设置在 objectOrName 元素上。

Boolean setFrameContext(browserTab, frameName)

Boolean setFrameContext(frameName)

对于使用框架或 iframes 的网页，此函数可以用来指定当在由 browserTab 引用的选项卡内部查找对象时应使用名为 frameName 的框架作为当前上下文。此当前上下文定义了查找对象名称的首选窗口；因此，所有跟随它的对象查找都将首先在指定的框架中搜索对象。如果没有找到对象，则查找将回退到搜索所有其他框架以及顶级页面。`frameName` 使用点分隔的层次结构来标识所需的框架。名称以网页中最顶层的框架开始，使用该框架的 name 属性或 id 属性。接下来的步骤（如果需要）应该是顶层框架内框架的 name 或 id。按照这种方案，可以到达嵌套帧的任何层级。例如，考虑一个包含名为 leftframe 和 rightframe 的两个框架的页面，左侧框架中有一个 id 为 maincontent 的 iframe。为了将查找上下文设置为这个内嵌 iframe，你应该将 "leftframe.maincontent" 作为 frameName 使用。除了这种方案之外，还可以使用 Squish 在多属性和层次化名称中生成的上下文信息。这种上下文信息使用略微不同的格式，其中框架的名称为 "FRAME"，后跟一个数字。该数字表示特定页面中框架列表中的给定框架编号，从 1 开始计数。使用上面的例子再次说明，你可以使用 "FRAME1.FRAME1" 作为左侧框架中 iframe 的名称。如果右侧框架本身有 2 个子框架，你将使用 "FRAME2.FRAME1" 和 "FRAME2.FRAME2" 分别访问此方案中的这两个子框架。（另请参阅，HTML_Array contextList()、String currentContext()、Boolean setContext(context) 和 waitForContextExists(context)。）

setText(objectOrName, text)

此函数将 objectOrName 可编辑表单元素（可以是文本或 textarea 元素）的文本设置为给定的 text。（与此相比，typeText(objectOrName, text) 函数模拟将文本输入到表单元素中。）

此函数的特定用途是自动化上传字段。用于选择文件以上传的表单字段可以通过 setText 自动化。用于上传文件的输入字段名称应作为 objectOrName 使用，而文件的绝对路径应作为 text 传递。setText 调用将透明地处理平台和浏览器之间的文件选择。

记录上传字段上的 setText 调用通常无法获取磁盘上文件的绝对路径，因为浏览器出于安全原因阻止访问此信息。请确保相应地调整绝对路径参数。

startBrowser(url)

startBrowser(url, timeout)

startBrowser()

startBrowser(timeout)

该函数启动浏览器，如果指定 - 则加载由 url 参数指定的网站。如果在启动或加载页面期间出现错误，将引发错误。如果在浏览器正在运行时调用该函数，也会引发错误。可以使用 Boolean isBrowserOpen() 函数查询浏览器是否正在运行。

该函数接受一个可选的 timeout 参数，单位为毫秒。Squish for Web 将等待指定的时间以便浏览器启动并加载给定的 URL。时间结束后，将生成一个错误。如果未指定此参数，将使用最大启动超时值。

toggleExpandable(objectOrName)

此函数点击 objectOrName 可展开的部分标题网页元素（如果 objectOrName 不是类型为 HTML_ExpandableSectionHeader 类，将引发异常）。点击将导致可展开部分的状态变为展开（如果没有展开）或关闭（如果已经展开）。此函数相当于点击鼠标到可展开部分标题上，但不需要（可能不可靠）的坐标。

可展开部分有时被称为“手风琴”或“工具箱”。（另请参阅可展开部分标题支持。）

typeText(objectOrName, text)

此函数将指定的 text（仿佛用户使用了键盘）输入到 objectOrName 可编辑元素中。（比较此与setText(objectOrName, text) 函数，该函数用于程序性地设置文本和 textarea 表单元素的文本。）

waitForContextExists(context)

注意：除非您已禁用选项卡支持，否则该函数已弃用。请考虑使用 Object waitForObject(objectOrName) 与标识特定选项卡的 realname 等待该选项卡，或者使用 Boolean waitFor(condition) 与 Boolean hasFrameContext(browserTab, context) 来等待特定的框架出现

此函数等待直到指定的 context 已被加载并可访问。该 context 是浏览器中显示的特定网页的 URL - 该网页本身可能通过使用框架、iframe 和类似元素包含其自己的页面层级。（另请参阅，HTML_Array contextList()，String currentContext()，Boolean setFrameContext(browserTab, frameName)，Boolean setContext(context)，和 waitForContextExists(context)。）

如果等待指定的时间找不到上下文名称，此函数将抛出一个可捕获的脚本错误。您可以使用文件 etc/webwrapper.ini 中的 ThrowErrorOnUnknownContextNames 设置更改此行为。如果设置设置为 false，则此函数如果给定的框架上下文名称可以找到和激活则返回 true，否则返回 false。

waitForObjectItem(objectOrName, row, column)

waitForObjectItem(objectOrName, row, column, timeoutMSec)

等待 objectOrName 对象可访问（即存在、可见且启用），并包含由 row 和 column 标识的项目。

函数在失败时引发一个（可捕获的）LookupError 异常，即超时时。

函数最多等待 20000 毫秒（默认），或者等待 timeoutMSec 参数中指定的毫秒数。

此函数仅适用于以下类型的对象

支持的（由 HTML_CustomItemView 类处理的）对象示例是 GWT 和 SmartGWT 表。

uninstallEventHandler(eventName, handlerFunctionNameOrReference)

此函数移除先前使用 installEventHandler(eventName, handlerFunctionNameOrReference) 安装的事件处理器。

浏览器对象

该对象的方法提供有关正在使用的浏览器的信息。

注意：当使用针对使用 QtWebKit 模块的 Qt 版本的应用程序时，此对象的名称为 SquishBrowserInfo 以避免与应用程序本身提供的对象发生冲突。因此，在用于 Qt 版本的测试脚本中，应使用 SquishBrowserInfo.name 代替 Browser.name。此规则同样适用于此对象提供的其他函数和属性。

String Browser.name()

此函数以字符串值返回正在用于运行测试的浏览器名称。常见浏览器的值为：

"浏览器在移动设备上" – 移动设备上的浏览器
"Firefox" – Mozilla Firefox
"Google Chrome" – Google Chrome
"基于 Chromium 的应用程序（使用 CEF、Electron、nw.js 等。）" – 基于 Chromium 的应用程序
"Microsoft Internet Explorer" – Microsoft Internet Explorer
"Microsoft Edge" – Microsoft Edge
"Opera" – Opera
"其他浏览器" – 其他浏览器
"Safari" – Safari

String Browser.majorVersion()

此函数以整数值返回正在用于运行测试的浏览器的版本号。

Type Browser.type()

此函数以数字值返回正在用于运行测试的浏览器的类型。返回的类型值应与以下变量之一（每个表示相应的浏览器）进行比较：

Browser.Firefox – Firefox
Browser.InternetExplorer – Internet Explorer（Microsoft）
Browser.Edge – Microsoft Edge
Browser.GoogleChrome – Google Chrome
Browser.ChromiumBased – 基于 Chromium 的应用程序（使用 CEF、Electron、nw.js 等。）
Browser.Mozilla – Mozilla
Browser.Safari – Safari（Apple）
Browser.Proxy – 代理

示例

function main()
{
    // ...

    if (Browser.type() == Browser.InternetExplorer) {
        test.log("Using Internet Explorer!")
    }

    // ...
}

BrowserTab 类

此类提供了浏览器窗口中标签的 API。可以使用具有如下多属性名称的标签标识 {type='BrowserTab' title='AddressBook'}。可以使用严格匹配、通配符匹配或正则表达式匹配在 BrowserTab.title 或 BrowserTab.url 属性上进行匹配。

字符串 BrowserTab.title

此只读属性包含网页浏览器标签的标题。

字符串 BrowserTab.url

此属性包含网页浏览器标签的URL。更改此属性为不同的URL将在该浏览器标签中加载指定的URL，并等待标签被挂载。挂载成功的等待时间受squishserver配置中指定的应用程序启动时间（或AUTTimeout）限制。如果您需要更多的超时控制，请考虑使用BrowserTab.setUrl(url, timeout)。

BrowserTab.close()

此函数关闭浏览器中的标签，如果它是最后一个标签，则还可能关闭窗口。在调用此函数后，访问同一对象的其他属性将引发错误。

BrowserTab.setUrl(url, timeout)

此函数将标签中的URL更改为指定的url，并等待新页面被Squish挂载。等待时间可以使用timeout参数指定，且必须以毫秒为单位。

此函数作为替代BrowserTab.url属性的方案提供，在这种情况下，超时应该被明确指定而不是使用URL属性获取的值。

HTML_Anchor 类

此类提供HTML锚点元素（超链接）的API。此类继承了HTML_Object 类。

HTML_Anchor.click()

此函数点击此锚点（超链接），就像用户自己点击了一样。

HTML_Array 类

此类代表JavaScript数组，例如由HTML_Array HTML_Document.getElementsByTagName(tagName)等网页函数返回的数组。此类继承了HTML_Object 类。

对象 HTML_Array.at(index)

此函数返回数组的index位置上的元素。有效的索引位置范围是0到array.length - 1。

int HTML_Array.length

此只读属性包含数组中的元素数量。如果数组为空，则此值为0。

HTML_Button 类

此类提供HTML按钮和提交输入元素的API。此类继承了HTML_ButtonBase 类，该类继承了HTML_FormElement 类，该类又继承了HTML_Object 类。

HTML_Button.submit()

对于普通按钮，这等同于调用HTML_ButtonBase.click()。对于提交按钮，这将调用按钮的表单的提交操作。

HTML_ButtonBase 类

这是所有HTML输入按钮元素（如，按钮、提交、单选按钮、复选框和图像）的基类，并提供了它们共有的API。此类继承了HTML_FormElement 类，该类继承了HTML_Object 类。

HTML_ButtonBase.click()

点击此按钮（或复选框、图像等），就像用户点击它一样。一些子类允许指定键盘修饰符和元素被点击的确切位置。

String HTML_ButtonBase.value

该属性以字符串形式存储此按钮（或复选框、图像等）的值。

HTML_CheckBox 类

此类提供 HTML 复选框输入元素的 API。该类继承自 HTML_ButtonBase 类，HTML_ButtonBase 类继承自 HTML_FormElement 类，HTML_FormElement 类继承自 HTML_Object 类。

Boolean HTML_CheckBox.checked

该属性如果复选框被选中则保存 true，否则保存 false。

HTML_CheckBox.click()

HTML_CheckBox.click(modifierState)

HTML_CheckBox.click(modifierState, x, y)

点击此复选框，就像用户点击它一样。所有参数都是可选的。请参阅 Web 对象 API 函数参数，了解哪些值对于 modifierState 是有效的。其中 x 和 y 是相对复选框的点击坐标。

HTML_CalendarEvent 类

此类提供支持日历事件的 API，它提供了四个有用的属性。该类继承自 HTML_Object 类。

注意，对于类型为 DateTime 类型的属性，时间分辨率为最近的分钟（即，秒数始终为零）。

String HTML_CalendarEvent.description

该读/写属性以字符串形式保存事件描述（可能为空）。

DateTime HTML_CalendarEvent.endDateTime

该读/写属性持有事件何时结束的 DateTime 类型。

DateTime HTML_CalendarEvent.startDateTime

该读/写属性持有事件何时开始的 DateTime 类型。

String HTML_CalendarEvent.title

该读/写属性持有事件标题的字符串。

另请参阅日历事件支持。

HTML_CalendarView 类

此类提供支持 Web 日历小部件的 API，包括一个有用的属性和两个方法。该类继承自 HTML_CustomItemView 类，HTML_CustomItemView 类继承自 HTML_FormElement 类，HTML_FormElement 类继承自 HTML_Object 类。

DateTime HTML_CalendarView.date

该读/写属性以 DateTime 类型存储日历的当前日期。注意，时间分辨率为最近的分钟（即，秒数始终为零）。

int HTML_CalendarView.numVisibleEvents()

返回在视图中可见的 HTML_CalendarEvent 类的数量。

HTML_CalendarEvent HTML_CalendarView.visibleEventAt(index)

返回视图中可见的HTML_CalendarEvent 类的索引为 index 的对象。

另请参阅，日历视图支持。

HTML_ColorField 类

该类提供了用于 HTML 颜色选择器的 API。此类继承自 HTML_Object 类。

String HTML_ColorField.fieldName

此只读属性包含该字段的标签文本，如果有的话。

Boolean HTML_ColorField.isEnabled

此读写属性包含颜色选择器是否启用的状态。

String HTML_ColorField.rgbColor

此读写属性包含颜色选择器的颜色，以 HTML 格式化字符串 (#RRGGBB) 的形式表示；请参阅 chooseColor(objectOrName, htmlRGBvalue) 函数。

HTML_CustomButton 类

该类提供支持高级定制的按钮（例如，使用 <div> 或 <span> HTML 元素创建的按钮）的 Web 工具包的 API。API 与 HTML_Button 类提供的 API 非常相似。此类继承自 HTML_CustomButtonBase 类（提供该类的大部分属性）和 HTML_Object 类。

另请参阅，按钮支持。

String HTML_CustomButton.value

此读写属性包含按钮的工具包特定数据值。（这与 HTML_CustomButtonBase.text 属性不同。）

HTML_CustomButtonBase 类

该类提供了一个支持使用高级定制的按钮的 Web 工具包的抽象 API（例如，使用 <div> 或 <span> HTML 元素创建的按钮）的抽象 API。API 与 HTML_Button 类提供的 API 非常相似。此类继承自 HTML_Object 类。

另请参阅，按钮支持。

Boolean HTML_CustomButtonBase.disabled

此读写属性表示按钮是否禁用（true）或启用（false）。

Boolean HTML_CustomButtonBase.showText

此读写属性表示按钮显示文本（true）或图像（false）。

String HTML_CustomButtonBase.text

此读写属性包含在 showText 属性为 true 的情况下显示在按钮上的文本；否则它包含一个空字符串。

此读写属性包含按钮的工具提示文本（可能为空）。

Boolean HTML_CustomButtonBase.visible

此只读属性指示按钮是否在网页中可见。

HTML_CustomComboBox 类

这个类旨在支持在扩展中实现高度定制的组合框（例如，使用 <div> 或 <span> 元素而不是标准 <select> 元素）的 Web 工具包。该 API 与 HTML_Select 类类似的 API。这个类继承了 HTML_FormElement 类，而 HTML_FormElement 类又继承了 HTML_Object 类。

有关如何添加对自定义组合框的支持，请参阅组合框支持。

布尔值 HTML_CustomComboBox.hasOption(option)

此函数返回组合框是否包含指定的 option。

字符串 HTML_CustomComboBox.selectedOption

这个读写属性包含当前选中选项的文本。

HTML_CustomCheckbox 类

这个类代表一个定制的复选框—例如，可以使用 <div> 或 <span> 标签创建的复选框，而不是使用 <button> 元素。这个类继承了 HTML_Object 类。（参见复选框支持。）

布尔值 HTML_CustomCheckbox.checked

这个读写属性包含复选框是否被选中。

HTML_CustomItem 类

这个类提供一个抽象的项 API，以便访问自定义项视图中支持的任何项类型（HTML_CustomItemView 类。）此类继承自 HTML_Object 类。（有关如何使用此 API 支持Squish作为标准不支持的定制项视图小部件的信息，请参阅如何设置复杂小部件的支持。）

以下是 HTML_CustomItem 类的方法和属性的快速链接

HTML_CustomItem HTML_CustomItem.childItem()

HTML_CustomItem HTML_CustomItem.childItem(column)

返回一个对为此项的第一个子项（HTML_CustomItem 类）的引用，如果没有，则返回 0。

column 是可选的（并且并非所有项都支持它），但如果指定（且受支持），则在给定的 column 中有此项的第一个子项，则返回此子项；否则返回 0。

整数 HTML_CustomItem.column

这个只读属性包含项的列，或者如果此属性不受相关 HTML 扩展支持，则返回 -1。

HTML_CustomItem HTML_CustomItem.findItem(row, column)

此函数返回对给定 row 和 column 的子项的引用。如果找不到项或扩展不支持此功能，则函数返回 0。

HTML_Object HTML_CustomItem.itemHandle()

此函数返回对当前项句柄的引用（类型为HTML_Object 类），如果此项没有句柄，则返回0。

HTML_CustomItemView HTML_CustomItem.itemView()

此函数返回包含此项的视图（类型为HTML_CustomItemView 类）。

HTML_CustomItem HTML_CustomItem.nextSibling()

HTML_CustomItem HTML_CustomItem.nextSibling(column)

返回当前项的下一个“兄弟”项的引用（类型为HTML_CustomItem 类）；如果没有“兄弟”项，则返回0。

column是可选的（并且并非所有项都支持它），但如果指定（并且受到支持），则函数返回在下一行的给定column中的项；如果没有，则返回0。

int HTML_CustomItem.numRows

此只读属性表示当前项有多少直系子项（适用于树形视图中的项）。如果项没有子项（或项不在树形视图中），则值为0；如果是支持的HTML扩展不支持此属性，则值为-1。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

Boolean HTML_CustomItem.open

此属性表示如果此项是打开的（即展开的——在这种情况下，此项的子项将可见）；否则它包含false。

如果此属性设置为true，则打开（展开）此项，使其所有子项都可见。如果此属性设置为false，则关闭（折叠）此项，使其所有子项都隐藏。

HTML_CustomItem HTML_CustomItem.parentItem()

HTML_CustomItem HTML_CustomItem.parentItem(column)

返回当前项父项的引用（类型为HTML_CustomItem 类）；如果没有父项，返回0，即此项是根项。

column是可选的（并且并非所有项都支持它），但如果指定（并且受到支持），则如果存在给定column的父项，则返回该项的父项；否则返回0。

String HTML_CustomItem.realType

此只读属性表示API包装的实际（即真实）类型名称的字符串。名称可能是视图的类型名称，而不是项的类型名称，具体取决于实现。（携带Squish的示例返回视图的类型名称。）

返回的类型名称可能是“gwttree”、“itmilltree”、“dojotree”等。

int HTML_CustomItem.row

此只读属性表示项的行。对于树形视图中的项，该行相对于顶级项的视图或相对于项的父项。对于不在树形视图中的项，它是视图中项的行。如果此属性不受相关HTML扩展支持，则值为-1。

Boolean HTML_CustomItem.selected

该属性在选中该项时保持 true；否则保持 false。

如果将此属性设置为 true，则选中该项。如果将此属性设置为 false，则取消选中该项。

String HTML_CustomItem.text

此只读属性以字符串形式持有项目的文本。

如果扩展提供了 itemText 函数，则返回该函数的返回值；否则返回项目的 innerText 属性的值。

HTML_CustomItemView 类

此类提供了一种抽象的项视图 API，以访问任何受支持的项视图，即任何具有专用支持的 DHTML/AJAX/JS 项视图小部件。此类继承自 HTML_FormElement 类，而 HTML_Object 类继承自它。（请参阅如何设置对复杂小部件的支持了解如何使用此 API 支持Squish作为标准不支持的自定义项视图小部件。）

项视图中的项的 API 由 HTML_CustomItem 类提供。

在以下许多方法中使用的 itemText 用来标识相关项。在Squish提供的示例中，itemText 总是项的文本字符串。

以下是一些快速链接到 HTML_CustomItemView 类的方法和属性

HTML_CustomItem HTML_CustomItemView.childItem()

HTML_CustomItem HTML_CustomItemView.childItem(column)

返回视图的第一个项的引用（类型为 HTML_CustomItem 类）；如果视图为空，则返回 0。

column 是可选的（并非所有视图都支持），但如果指定（且受支持），则返回视图在给定的 column 中的第一个子项，如果存在的话；否则返回 0。

HTML_CustomItemView.clickHandle(itemName)

点击名为 itemName 的项的展开/折叠处理。

HTML_CustomItemView.clickItem(itemName)

HTML_CustomItemView.clickItem(row, column)

此函数点击具有给定 itemName 文本或给定 row 和 column 的项。如果找不到项或扩展不支持此函数（某些仅支持 itemName 版本），则此函数不进行任何操作。

String HTML_CustomItemView.columnCaption(column)

返回给定 column 的视图的标题。

HTML_CustomItemView.doubleClickItem(itemName)

HTML_CustomItemView.doubleClickItem(itemName, modifierState)

双击名为 itemName 的项目。请参阅 Web 对象 API 函数参数，了解可选的 modifierState 的有效值。

HTML_CustomItem HTML_CustomItemView.findItem(itemName)

HTML_CustomItem HTML_CustomItemView.findItem(row, column)

此函数返回对给定 itemName 或在给定的 row 和 column 的项目的引用（类型为 HTML_CustomItem 类）。如果找不到项目或扩展不支持此函数（一些只支持 itemName 版本），则函数返回 0。

Boolean HTML_CustomItemView.hasItem(itemName)

如果视图有名为 itemName 的项目，则该函数返回 true；否则返回 false。

Boolean HTML_CustomItemView.isOpen(itemName)

如果视图有名为 itemName 的项目，并且该项目是打开的（即其任何子项都是可见的），则该函数返回 true；否则返回 false。

Boolean HTML_CustomItemView.isSelected(itemName)

如果视图有名为 itemName 的项目，并且该项目被选中，则该函数返回 true；否则返回 false。

int HTML_CustomItemView.numColumns

此只读属性保存视图显示的列数。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

int HTML_CustomItemView.numRows

此只读属性保存视图显示的行数。在树型视图中，这是顶级子项的数量。并非所有扩展都支持此属性，在这种情况下，其值是 -1。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

String HTML_CustomItemView.realType

此只读属性保存此 API 包装的实际（即真实）类型的类型名作为字符串。

类型名可能是“gwttree”、“itmilltree”、“dojotree”等。

HTML_CustomRadioButton Class

此类表示自定义单选按钮——例如，使用 <div> 或 <span> 标签创建的，而不是使用 <button> 元素。此类继承自 HTML_Object 类。（另请参阅单选按钮支持。）

Boolean HTML_CustomRadioButton.selected

此可读写属性保存单选按钮是否选中（勾选）。

HTML_CustomSelectList Class

此类表示自定义多选列表——例如，使用

或标签创建的列表，而不是使用元素。此类继承自HTML_FormElement 类，而HTML_Object 类继承了它。（参见文本域支持和HTML_Text 类。）

HTML_CustomText.focus()

此函数将键盘焦点置于文本域中。

字符串 HTML_CustomText.value

此读写属性包含文本域的文本。

HTML_DateChooser 类

此类代表日期选择器对象并提供了一个有用的属性。此类继承自HTML_Object 类。

DateTime HTML_DateChooser.date

此读写属性包含日期选择器的当前日期/时间，格式为DateTime 类型。

参见chooseDate函数和日期选择器支持。

HTML_Document 类

此类代表网页的HTML文档对象并提供了一些有用的访问方法。此类继承自HTML_Object 类。

注意：要创建一个涵盖整个页面的视觉验证点，请选择文档对象的子对象，例如BODY元素。没有HTML_Document对象的视觉表示。

HTML_Object HTML_Document.getElementById(id)

此函数返回具有给定id的元素。（参见HTML_Object 类。）

HTML_Array HTML_Document.getElementsByTagName(tagName)

此函数返回所有具有给定 tagName 的 DOM 树元素的数组。 (另请参阅，HTML_Array 类。)

HTML_ExpandableSectionHeader 类

此类表示网页的 HTML 可展开部分标题元素。（可展开部分有时被称为“手风琴”或“工具箱”。）该类提供了一些有用的属性，并继承了 HTML_Object 类。另请参阅，toggleExpandable(objectOrName) 函数和可展开部分标题支持。

Boolean HTML_ExpandableSectionHeader.isEnabled

此读写属性表示可展开部分是否启用。

Boolean HTML_ExpandableSectionHeader.isExpanded

此读写属性表示可展开部分是否已展开。

String HTML_ExpandableSectionHeader.title

此读写属性表示可展开部分的标题文本。

HTML_Form 类

此类提供了一个网页的 HTML 表单元素的 API。此类继承了 HTML_Object 类。

HTML_Form.submit()

触发表单的 "submit" 动作。

HTML_FormElement 类

此类是 HTML 表单元素（如按钮、复选框等）的基类，并提供了所有这些元素共享的公共 API。此类继承了 HTML_Object 类。

Boolean HTML_FormElement.disabled

如果此表单元素被禁用，则此属性将保留 true；否则保留 false。

HTML_FormElement.focus()

将键盘焦点给予此表单元素。

String HTML_FormElement.type

此只读属性保留此表单元素的类型名称（如，按钮、选择、文本等）。

HTML_ImageButton 类

此类提供了 HTML 图像输入元素的 API，其方法都是从其基类继承的。此类继承了 HTML_ButtonBase 类，该类继承了 HTML_FormElement 类，该类继承了 HTML_Object 类。

此类提供了一个 HTML 菜单和菜单栏的 API。此类继承了 HTML_Object 类，并且还具有自己的属性和方法。有关如何添加自定义菜单支持，请参阅菜单支持。

此函数将返回第一个具有给定 iconUrl 的 HTML_MenuItem 类，如果没有找到，则返回空值（可以使用布尔 isNull(object) 函数测试空值）。

此函数返回具有给定 text 的第一个 HTML_MenuItem 类，如果没有找到则返回 null 值。（可以通过使用 Boolean isNull(object) 函数来测试 null 值。）

此函数返回指定 index 位置的 HTML_MenuItem 类，如果没有找到则返回 null 值。（可以通过使用 Boolean isNull(object) 函数来测试 null 值。）

此只读属性保存菜单项在菜单（或菜单栏）中的数量。

HTML_MenuButton 类

此类提供了 HTML 菜单按钮的 API。此类继承自 HTML_CustomButtonBase 类（提供大多数属性）和 HTML_Object 类。此外，此类拥有自己的方法。有关如何添加支持自定义菜单按钮的信息，请参阅 Menu Button Support。

此函数返回当点击此按钮时弹出的 HTML_Menu 类，如果没有则返回 null 值。（可以通过使用 Boolean isNull(object) 函数来测试 null 值。）

HTML_MenuItem 类

此类提供了 HTML 菜单项的 API。此类继承自 HTML_Object 类，并添加了额外的属性和方法。有关如何添加支持自定义菜单项的信息，请参阅 Menu Item Support。

String HTML_MenuItem.iconUrl

此读写属性保存菜单项图标的 URL，如果没有图标则为空字符串。

Boolean HTML_MenuItem.isChecked

此读写属性保存菜单项是否被选中。

Boolean HTML_MenuItem.isEnabled

此读写属性保存菜单项是否可用。

Boolean HTML_MenuItem.isSeparator

此读写属性保存菜单项是否仅作为菜单项分隔符。

此函数返回包含此菜单项的 HTML_Menu 类（即菜单或菜单栏）。

此函数返回附加到此菜单项的 HTML_Menu 类，如果没有则返回 null 值。（可以通过使用 Boolean isNull(object) 函数来测试 null 值。）

String HTML_MenuItem.text

此读写属性保存菜单项的文本。

HTML_Object 类

这是用于所有HTML元素的通用基类。在这个类中定义的函数和属性对所有从Object findObject(objectName) 函数返回的对象都是可用的。

以下是一些快速链接到 HTML_Object 类的方法和属性

ScreenRect HTML_Object.boundingClientRect

这个只读属性持有对象的矩形，相对于Web视图区域左上角的位置。返回的对象有4个属性：x 和 width 持有水平位置和大小，y 和 height 持有垂直位置和大小。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

String HTML_Object.className()

此函数返回HTML对象的子类名称；例如，HTML_Button 类。（另请参阅，HTML_Object.domClassName。）

HTML_Object.click()

HTML_Object.click(modifierState)

HTML_Object.click(modifierState, x)

HTML_Object.click(modifierState, x, y)

HTML_Object.click(modifierState, x, y, button)

模拟用户单击此HTML对象。所有参数都是可选的。有关有效值，请参阅 Web Object API 函数参数。 x 和 y 是单击的相对于对象坐标的坐标。 button 必须是 1（左按钮）、2（右按钮）或 4（中按钮）。

HTML_Object.css

这是一个只读属性，提供了对HTML对象可能具有的各种CSS属性的影响。属性作为css对象的子属性建模，可以直接单独访问或通过KeyValueMap object.properties(object) 函数检索所有属性。

一些CSS属性名称在脚本语言中可能有问题，例如 background-color。为了减轻此问题，Squish通过删除破折号并将以下字母转换为大写来公开此类属性。因此，可以使用CSS属性对象的 backgroundColor 名称访问CSS属性 background-color。

单个CSS属性的值被建模为字符串，但对于提供颜色信息的CSS属性（如backgroundColor和color）除外。这些与颜色相关的属性使用CssColor类型进行建模。

以下是验证对象背景颜色的示例

pythonjavascriptperlrubytcl

blue_title = waitForObject(blue_title_H1)
expectedColor = CssColor.fromRgb(20, 20, 200)
test.compare(blue_title.css.backgroundColor, expectedColor)

var blue_title = waitForObject(blue_title_H1)
var expectedColor = CssColor.fromRgb(20, 20, 200)
test.compare(blue_title.css.backgroundColor, expectedColor)

my $blue_title = waitForObject(blue_title_H1)
my $expectedColor = CssColor::fromRgb(20, 20, 200)
test->compare(blue_title->css->backgroundColor, expectedColor)

blue_title = waitForObject(blue_title_H1)
expectedColor = CssColor.fromRgb(20, 20, 200)
Test::compare(blue_title.css.backgroundColor, expectedColor)

set blue_title [waitForObject blue_title_H1]
set expectedColor [invoke CssColor fromRgb 20 20 200]
set css_props [property get blue_title css]
test compare [property get css_props backgroundColor] expectedColor

String HTML_Object.domClassName

此只读属性包含对象在DOM中使用的类名。

这是一个合成属性，但可以在不同的名称下在多属性名称中使用。有关合成属性的更多信息，请参阅Web对象中的合成属性，有关如何在多属性名称中使用它的信息，请参阅String HTML_Object.className()。

String HTML_Object.domPath

此只读属性包含对象在DOM树中的路径。此属性的值可以用作识别对象的层次名称。请注意，domPath在网站结构的更改方面可能不是稳定的。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

HTML_Object.doubleClick()

HTML_Object.doubleClick(modifierState)

HTML_Object.doubleClick(modifierState, x)

HTML_Object.doubleClick(modifierState, x, y)

在此HTML对象上执行双击事件，好像用户双击了它。所有参数都是可选的。有关修改状态的合法值，请参阅Web对象API函数参数。x和y是双击事件的相对坐标。

HTML_XPathResult HTML_Object.evaluateXPath(statement)

评估XPath statement 并返回一个HTML_XPathResult类对象。XPath statement 在此 HTML_Object 的XPath下执行。

此方法使得在Web应用程序的DOM文档上进行高效操作成为可能，例如检索元素和访问它们的属性。

另请参阅如何使用XPath。

HTML_Object HTML_Object.firstChild()

此函数返回对象的第一个子对象（作为HTML_Object），如果没有子对象，则返回无效对象。（另请参阅，HTML_Object HTML_Object.lastChild()，HTML_Object HTML_Object.nextSibling()，HTML_Object.numChildren，HTML_Object HTML_Object.parentElement()，以及HTML_Object HTML_Object.previousSibling()。）

bool HTML_Object.hasFocus

此只读属性指示给定对象是否在文档中有键盘焦点。这对于文本字段通常才有意义。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

int HTML_Object.height

此只读属性包含对象的高度。（另请参阅，HTML_Object.width。）

注意：此属性已弃用，因为对于所有浏览器，该值可能无法正确计算。建议改用由HTML_Object.boundingClientRect提供的矩形高度。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

String HTML_Object.hierarchicalQualifiedName()

此函数返回该对象的层次结构化和限定名称。

Object HTML_Object.id

此只读属性保存对象的ID。

String HTML_Object.innerHTML

此只读属性保存对象的内部文本—这可能包含HTML标记。（另见，HTML_Object.innerText 和 HTML_Object.simplifiedInnerText。）

String HTML_Object.innerText

此只读属性保存对象的内部文本（纯文本），因此返回的字符串不包含任何HTML标记。（另见，HTML_Object.innerHTML 和 HTML_Object.simplifiedInnerText。）

HTML_Object HTML_Object.shadowRoot

此只读属性提供对给定对象的shadow root节点的访问（如果有）。该属性返回一个HTML_Object实例，可用于访问Shadow DOM内部的子节点。

如果元素具有一个已连接的shadow root节点并且该shadow root以开放模式创建，则该属性将仅返回shadow root对象。有关Shadow DOM的更多信息，请参阅Mozilla Shadow DOM文档。

要从shadow root导航回包含元素，请使用HTML_Object.parentElement()。

String HTML_Object.simplifiedInnerText

此只读属性保存对象的内部文本（纯文本），因此返回的字符串不包含任何HTML标记。此外，空白将被简化，所以任何数量的空白仅保留一个空格。在此上下文中，换行符、制表符和行分隔符也被视为空白，因此它们也将被替换为一个空格。（另见，HTML_Object.innerHTML 和 HTML_Object.innerText。）

这是一个合成属性，但在多属性名称中使用是可以的。有关合成属性的信息，请参阅Web对象中的合成属性。

HTML_Object.invoke(methodName)

HTML_Object.invoke(methodName, argument1)

HTML_Object.invoke(methodName, argument1, argument2)

调用名为methodName的HTML_Object方法，并以字符串的形式返回方法调用的返回值。argument1和argument2参数都是可选的。如果提供任何或全部参数，则它们作为参数传递给方法调用。

HTML_Object HTML_Object.lastChild()

此函数返回对象的最后一个子对象（作为HTML_Object），如果没有子对象，则返回一个无效对象。（另请参阅，HTML_Object HTML_Object.firstChild()`，HTML_Object HTML_Object.nextSibling()，HTML_Object.numChildren，HTML_Object HTML_Object.parentElement()，以及HTML_Object HTML_Object.previousSibling()。）

String HTML_Object.name?

此函数返回此对象的内部JavaScript引用名称。

HTML_Object HTML_Object.nextSibling?

此函数返回对象的下一个兄弟（作为HTML_Object），如果没有后续兄弟，则返回一个无效对象。（另请参阅，HTML_Object HTML_Object.firstChild()，HTML_Object HTML_Object.lastChild()，HTML_Object.numChildren，HTML_Object HTML_Object.parentElement()，以及HTML_Object HTML_Object.previousSibling()。）

int HTML_Object.numChildren

此只读属性保留此对象有多少个子对象—这可能是0。（另请参阅，HTML_Object HTML_Object.firstChild()，HTML_Object HTML_Object.lastChild()，HTML_Object HTML_Object.nextSibling()，HTML_Object HTML_Object.parentElement()，以及HTML_Object HTML_Object.previousSibling()。）

HTML_Object.openContextMenu?

以用户打开该对象上下文菜单的方式点击HTML对象。

HTML_Object HTML_Object.parentElement?

此函数返回对象的父对象（作为HTML_Object），如果没有父对象，则返回一个无效对象。注意，只有网站文档节点没有父节点；所有其他节点都是文档或其他文档节点中的孩子。（另请参阅，HTML_Object HTML_Object.firstChild()，HTML_Object HTML_Object.lastChild()，HTML_Object HTML_Object.nextSibling()，HTML_Object.numChildren，以及HTML_Object HTML_Object.previousSibling()。）

HTML_Object HTML_Object.previousSibling?

此函数返回对象的上一个兄弟（作为HTML_Object），如果没有前导兄弟，则返回一个无效对象。（另请参阅，HTML_Object HTML_Object.firstChild()，HTML_Object HTML_Object.lastChild()，HTML_Object HTML_Object.nextSibling()，HTML_Object.numChildren，以及HTML_Object HTML_Object.parentElement()。）

String HTML_Object.property(name)

此函数返回名为name的属性值（作为字符串）。（返回的值始终为字符串，即使属性设置为整数或布尔值。）（另请参阅，HTML_Object.setProperty(name, value)。）

ScreenRect HTML_Object.screenRect

这个只读属性包含对象的长方形，其位置相对于桌面的左上角。返回的对象有 4 个属性：x 和 width 保存横向位置和大小，而 y 和 height 保存纵向位置和大小。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

HTML_Object.scrollTo(top)

该函数将网页内容滚动，使得调用它的对象可见。可选的 top 可以用来指示对象应在网页内容的顶部还是底部出现。传递 true（无参数时的默认值）将其定位到顶部，传递 false 则定位到底部。（此函数由全局 scrollTo(objectOrName, top) 函数内部调用。）

HTML_Object.setProperty(name, value)

将名为 name 的属性的值设为 value。值可以是字符串、整数或布尔值。（也参见，String HTML_Object.property(name)。）

HTML_Style HTML_Object.style()

此函数返回一个 HTML_Style 类对象，可用于查询此对象的 CSS（层叠样式表）属性。

String HTML_Object.styleDisplay

这个只读属性包含对象的 style.display 值。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

String HTML_Object.styleVisibility

此函数返回对象的 style.visibility 值。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

String HTML_Object.tagName

这个只读属性包含对象的 HTML 标签名，例如，DIV 或 INPUT。

String HTML_Object.title

这个只读属性包含对象的标题。

Boolean HTML_Object.visible

这个只读属性当对象根据应用的 CSS 规则可见时包含 true。如果对象的 'visibility' CSS 属性设置为隐藏，或者如果对象或任何父级的 'display' CSS 属性设置为 none，此属性包含 false。

这是一个合成属性，但在多属性名称中使用是可以的。有关合成属性的信息，请参阅Web对象中的合成属性。

注意：在较旧版本的 Squish 中，此属性有不同的含义，反映了对象的 visible 属性值而非根据 CSS 的对象可见性。通过在文件 etc/webwrapper.ini 中将 BackwardsCompatibleVisiblePropertyForHTML_Object 设置设为 true 可以恢复此行为。

int HTML_Object.width

这个只读属性包含对象的大小。也参见，HTML_Object.height。

注意：此属性已被弃用，因为其值可能无法在所有浏览器中正确计算。考虑使用由 HTML_Object.boundingClientRect 提供的矩形宽度。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

int HTML_Object.x

这个只读属性包含对象的 x-坐标。

注意：此属性已被弃用，因为其值可能无法在所有浏览器中正确计算。考虑使用由 HTML_Object.boundingClientRect 或 HTML_Object.screenRect 提供的矩形的 y 属性。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

int HTML_Object.y

这个只读属性包含对象的 y-坐标。

注意：该属性已弃用，因为对于所有浏览器来说，其值可能计算不正确。请考虑使用由HTML_Object.boundingClientRect提供的矩形属性的x属性或HTML_Object.screenRect属性。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

HTML_Option类

此类提供对HTML选项元素的API，这些选项元素提供了选择元素的正文内容。此类继承自HTML_Object类。（也可参见，HTML_Select类。）

布尔值的HTML_Option.defaultSelected

此只读属性保留true，如果此选项默认选中；否则保留false。

整数的HTML_Option.index

此属性保留此选项在选择元素中的0基于索引位置。

布尔值的HTML_Option.selected

此只读属性保留true，如果此选项被选中；否则保留false。

字符串HTML_Option.text

此属性保留此选项的文本作为一个字符串。

字符串HTML_Option.value

此属性保留此选项的值作为一个字符串。

HTML_RadioButton类

此类提供对HTML单选按钮输入元素的API。此类继承自HTML_ButtonBase类，它继承自HTML_FormElement类，它继承自HTML_Object类。

布尔值的HTML_RadioButton.checked

此属性保留true，如果此单选按钮被选中；否则保留false。

HTML_RadioButton.click()

HTML_RadioButton.click(modifierState)

HTML_RadioButton.click(modifierState, x, y)

像用户点击它一样点击此单选按钮。所有参数都是可选的。参见Web Object API函数参数，以了解哪些值对于modifierState有效。其中x和y是点击按钮相关坐标。

HTML_Select类

此类提供对HTML选择输入元素（选择和单一选择）的API。Web浏览器通常将选择元素渲染为列表框，将单一选择元素渲染为组合框。此类继承自HTML_FormElement类，它继承自HTML_Object类。（还可参见HTML_CustomSelectList类。）

布尔值的HTML_Select.isMulti()

此函数返回true，如果此选择元素是多项选择（select类型）；否则返回false（表示此元素是单一选择类型）。

HTML_Option HTML_Select.optionAt(index)

返回此选择元素中位置为 index 的选项（HTML_Option 类）。(索引从0开始。)

这是一个等效于 html_select_object.options().at(index) 的便利函数。

HTML_Array HTML_Select.options()

此函数返回一个数组（HTML_Array 类），其中包含此选择元素中的所有选项（作为 HTML_Option 类对象）。

listOfTexts HTML_Select.selectedTexts

此属性提供选择元素中当前选中所有选项的文本列表。

将新的文本列表分配给此属性会更改选择元素中的选中选项，以便所有其文本与列表中的任何项匹配的选项将被选中，而元素中其他所有选项将不被选中。例如，如果该元素包含具有文本红色、蓝色、绿色和黑色的4个选项，并且当前选中的文本是红色和绿色，则将新的列表蓝色、黑色分配给此属性将取消选中红色和绿色条目，而是选中蓝色和黑色。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

listOfValues HTML_Select.selectedValues

此属性提供选择元素中当前选中所有选项的值属性列表。

将新的值列表分配给此属性会更改选择元素中的选中选项，以便所有其值与列表中任何项匹配的选项将被选中，而元素中其他所有选项将不被选中。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

listOfNumbers HTML_Select.selectedIndexes

此属性提供选择元素中当前选中所有选项的索引列表。

将新的索引列表分配给此属性会更改选择元素中的选中选项，以便所有其索引与列表中任何项匹配的选项将被选中，而元素中其他所有选项将不被选中。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

listOfNumbers HTML_Select.selectedLabels

此属性提供选择元素中当前选中所有选项的标签列表。

此属性不允许赋值，它只能读取。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

HTML_Select.deselectByValues(values)

此函数取消选中选择元素中具有在 values 参数中列出的值的项。

HTML_Select.deselectByTexts(texts)

此函数取消选中选择元素中具有在 texts 参数中列出的文本的项。

HTML_Select.deselectByIndexes(indexes)

此函数取消选中选择元素中具有在 indexes 参数中列出的索引的项。

int HTML_Select.selectedIndex

此属性包含此选择元素的选中索引。（此属性对于单选框特别有用，即类型为 select-one 的那些。）

String HTML_Select.selectedOption

此属性已过时，请考虑使用 HTML_Select.selectedTexts 属性。

此属性包含选中选项的文本，如果这是一个选择（多选）元素，则包含一个包含选中选项文本的逗号分隔的字符串。

如果将此属性分配给它，它将设置与给定text相同的文本选项为选中。

如果这是一个选择（多选）元素，使用逗号分隔的text字符串可以指定选项文本列表。在这种情况下，具有与逗号分隔的列表中任一文本匹配的文本的每个选项都将被选中。

HTML_Select.setSelectedOption(`text`)

此函数已弃用，请考虑使用HTML_Select.selectedTexts属性代替。

此函数选择表单元素（可能是一个选择或单选框元素）中具有给定text的选项。如果元素是复选框，可以用逗号分隔的text传递要选择的多个选项。

HTML_Select.setSelectedOptions(`listOfTexts`)

此函数从表单元素（可能是一个选择或单选框元素）中选择选项。对于listOfTexts中的每个条目，将选择具有相应可见文本的相应选项。如果元素仅允许单选，传递的listOfTexts必须仅包含一个条目。

HTML_Select.setSelectedOptionByValue(`value`)

此函数选择具有给定value属性值的表单元素（可能是一个选择或单选框元素）中的选项。

HTML_Select.setSelectedOptionsByValue(`listOfValues`)

此函数从表单元素选择选项（可能是一个选择或单选框元素）。对于listOfValues中的每个条目，将选择具有相应值属性值的选项。如果元素仅允许单选，传递的listOfValues必须仅包含一个条目。

HTML_ProgressBar类

这个类提供了HTML进度条的API，以便验证它们的状态。此类继承了HTML_Object类。参阅进度条支持。

int HTML_ProgressBar.maximum

这个只读属性包含进度条的最大值。

int HTML_ProgressBar.minimum

这个只读属性包含进度条的最小值。

int HTML_ProgressBar.value

这个读写属性包含进度条值。该值应该在minimum和maximum之间，包括两者。

HTML_Style类

此类提供访问对象的CSS（级联样式表）的API。HTML_Style对象由HTML_Style HTML_Object.style()函数返回。此类继承了HTML_Object类。

String HTML_Style.value(name)

此函数返回给定name的CSS（级联样式表）属性的字符串值，如果没有名为name的元素，则返回空字符串。

对于组合属性（例如 background-color），Squish 引入了广泛使用的 JavaScript 习惯，即在被连字符后的字母大写，并删除连字符。所以，例如，要访问背景颜色，将写入类似的内容：

var style = myobject.style();
var bgColor = style.value("backgroundColor");

HTML_Table 类

此类提供 HTML 表格的 API。此类继承自 HTML_Object 类。

Number HTML_Table.rowCount

此只读属性包含表格中的行数（不包括标题行）。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

Number HTML_Table.columnCount

此只读属性包含表格中的列数。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

HTML_Object HTML_TabWidget.cellAt(row, column)

此函数检索指定 row 和 column 的单元格对象。row 和 column 的索引从 0 开始，其中row 不包括任何标题行，仅包括实际内容行。

HTML_Tab 类

此类提供 HTML 选项卡小部件选项卡的 API。此类继承自 HTML_Object 类。每个选项卡属于类型 HTML_TabWidget 类的选项卡小部件。

Boolean HTML_Tab.enabled

此读写属性包含选项卡是否启用的信息。

String HTML_Tab.icon

此读写属性包含选项卡图标的 URL（如果有），如果有则标记为空字符串。

String HTML_Tab.title

此读写属性包含选项卡的标题文本。

HTML_TabWidget 类

此类提供 HTML 选项卡小程序件的 API。此类继承自 HTML_Object 类。选项卡小程序件中的每个选项卡都是类型 HTML_Tab 类的。

HTML_TabWidget.clickTab(tabTitle)

此函数将点击具有指定选项卡标题文本的选项卡（如果有）。通常这会使被点击的选项卡浮到最前面。

HTML_TabWidget.findTab(tabTitle)

此函数返回指定选项卡标题文本的引用，作为类型 HTML_Tab 类的对象。如果没有此选项卡，则该函数返回空值，对于 Squish 的布尔 isNull(object) 函数返回真值。

HTML_TabWidget.getCurrentTab()

此函数返回当前活动选项卡的引用，作为类型 HTML_Tab 类的对象。

HTML_Text 类

此类提供 HTML 文本输入元素的 API。此类的所有 API 都是从其基类继承而来的。此类继承自 HTML_TextBase 类，该类继承自 HTML_FormElement 类，该类继承自 HTML_Object 类。

HTML_TextArea 类

本类提供了HTML文本输入元素（文本和textarea）的API。这个类的所有API都继承自它的基类。本类继承自HTML_TextBase类，而HTML_TextBase类继承自HTML_FormElement类，HTML_FormElement类继承自HTML_Object类。

HTML_TextBase 类

这是HTML文本输入元素（文本和textarea）的基类，提供了两者共有的方法。本类继承自HTML_FormElement类，而HTML_FormElement类继承自HTML_Object类。

String HTML_TextBase.value

该属性以字符串形式持有该文本或textarea的内容。

HTML_TextBase.selectAll()

选择文本字段中的所有文本，便于后续文本输入将删除或覆盖它。

String HTML_TextBase.selectedText

该属性以字符串形式持有所选择的文本。

这是一个合成属性，有关更多信息，请参阅Web Objects中的合成属性。

HTML_XPathResult 类

这是在评估XPath时返回的结果对象的类型。该类继承自HTML_Object类。

在评估任何HTML_Object类上的XPath语句时（见HTML_XPathResult HTML_Object.evaluateXPath(statement)），将返回HTML_XPathResult类型的对象。此对象包含XPath执行的结果。

另请参阅如何使用XPath。

Boolean HTML_XPathResult.booleanValue

只读属性，持有XPath结果作为布尔值。

Number HTML_XPathResult.numberValue

只读原型，将XPath结果作为数值。

HTML_Object HTML_XPathResult.singleNodeValue()

该函数返回节点列表中第一个节点（类型为HTML_Object类）如果XPath执行的结果是节点列表。

int HTML_XPathResult.snapshotLength

只读属性，持有XPath执行返回的节点数。值为-1表示没有返回节点列表。

String HTML_XPathResult.stringValue

只读属性，持有XPath结果作为字符串。

HTML_Object HTML_XPathResult.snapshotItem(index)

此函数返回节点列表中给定索引位置上的节点（类型为HTML_Object类）。如果XPath执行的结果是节点列表。

JsObject 类

本类提供访问JavaScript对象引用的API。JsObject对象可以通过JsObject retrieveJSObject(javascriptcode)函数以及本类的属性和调用函数返回。

String JsObject.property(name)

此函数返回给定 name 的 JavaScript 属性的值。返回的值可以是原始值，例如字符串或数字，也可以是作为 JsObject 的 JavaScript 对象的引用。

String JsObject.call(methodname, methodarguments)

该函数在给定的 JavaScript 对象上执行名为 name 的方法。methodarguments 可选，如果要执行的方法不需要任何参数。如果 JavaScript 方法确实需要参数，则 methodarguments 应该是一个值列表，这些值将被传递给 JavaScript 方法。参数可以是原始值，如字符串或数字，也可以是脚本中之前获得的 JsObject 的引用。返回的值可以是原始值，如字符串或数字，也可以是作为 JsObject 的 JavaScript 对象的引用。

CssColor 类型

CssColor 类型可以存储颜色和 alpha 值。

CssColor CssColor.fromRgb(red, green, blue)

此构造函数可以从 red、green 和 blue 参数中提供的组件创建新的颜色对象。使用此函数时，对象的 CssColor.alpha 属性将为 1.0。以下是创建有效 Color 对象的方法

pythonjavascriptperlrubytcl

orange = CssColor.fromgRgb(235, 155, 52)

var orange = CssColor.fromRgb(235, 155, 52)

my $orange = CssColor::fromRgb(235, 155, 52)

orange = CssColor.fromRgb(235, 155, 52)

set color [invoke CssColor fromgRgb 235 155 52]

CssColor CssColor.fromRgba(red, green, blue, alpha)

此构造函数可以从 red、green、blue 和 alpha 参数中提供的组件创建新的颜色对象。以下是创建有效的 CssColor 对象的方法

pythonjavascriptperlrubytcl

orange = CssColor.fromgRgba(235, 155, 52, 0.5)

var orange = CssColor.fromRgba(235, 155, 52, 0.5)

my $orange = CssColor::fromRgba(235, 155, 52, 0.5)

orange = CssColor.fromRgba(235, 155, 52, 0.5)

set color [invoke CssColor fromgRgba 235 155 52, 0.5]

CssColor 对象具有以下属性

int CssColor.red

这个可读写属性包含颜色的红色分量值。它将在 0-255 范围内。

int CssColor.green

这个可读写属性包含颜色的绿色分量值。它将在 0-255 范围内。

int CssColor.blue

这个可读写属性包含颜色的蓝色分量值。它将在 0-255 范围内。

double CssColor.alpha

这个可读写属性包含颜色的 alpha 分量值。它将在 0-1.0 范围内。

boolean CssColor.isValid

这个只读属性指示对象的其他属性是否有效。Squish 可能会提供无效的颜色值，当无法获取颜色时。

JavaScript 扩展 API

本部分展示了如何使用 JavaScript 扩展 API 来支持测试自定义 AJAX/DHTML/JavaScript 小部件。

Squish 提供对 Web DOM 元素的访问，使得测试可以具有完整的低级访问和控制能力。然而，在这个级别上进行操作与在测试 GUI 应用程序时使用硬编码的屏幕坐标相似——这是一个相当脆弱的方法。

为了创建健壮的测试脚本，测试框架和自动化测试应该与应用程序和高级小部件的 HTML 进行交互，而不是与低级 DOM 元素交互。这样，测试将在抽象的 GUI 水平上工作，而无需了解应用程序的内部结构（即不需要直接访问应用程序的 DOM）。

使用高级测试，这些测试是针对小部件而不是直接针对DOM工作的，其优势在于测试不会仅仅因为DOM表示或小部件实现的变化而中断。这种变化在应用程序及其使用的框架发展过程中相当常见。

因此，除了提供底层访问外，Squish还提供了一种创建高级测试的方法，这种测试很可能更加可靠。这是可能的，因为Squish内置了对流行的AJAX和DHTML框架的支持，并识别它们的部件。但是，鉴于目前可用的AJAX、DHTML和JavaScript框架以及自定义小部件的数量，以及不断出现的新框架，Squish是不可能全部提供开箱即用的支持的。

幸运的是，即使是目前尚未支持的Web框架，也可以在Squish中添加对它们的框架支持。这是通过使用Squish的JavaScript扩展API实现的，它使得可以扩展Squish的小部件支持以识别自定义AJAX、DHTML和JavaScript小部件，正确识别它们，与它们交互，当然，也使得它们的API对测试脚本可用。

在本节中，我们首先介绍对扩展脚本可用的Squish对象API，然后展示概述和示例，向您展示如何自行实现对自定义小部件的支持。或者，如果您想让我们为您实现自定义小部件或框架的扩展，请使用Qt支持中心。

Squish对象

Squish对象通过提供API来扩展Squish的Web版，使其能够识别自定义AJAX/JavaScript/DHTML小部件。这意味着Squish可以在高级自定义小部件上工作，而不是在低级的DOM对象上工作。（请注意，此API不能用于测试脚本——测试时请使用上面描述的HTML_*类。）

使用这种机制，您可以为Squish不作为标准支持的那些AJAX/JavaScript/DHTML小部件创建强大的高级测试。

有关如何使用Squish对象的详尽示例，请参阅下面的子节，从概念和设置开始。另请参阅编写HTML类特定扩展。

以下是Squish对象的类型的快速链接

对象名称对象

以下是Squish对象的方法的快速链接

Squish.addClickHook(function)

该函数将给定的函数注册为模拟鼠标点击的处理程序。当需要在该元素上执行点击操作时，这个函数会使用HTML元素作为参数来调用。如果元素是处理程序函数希望处理的元素，处理程序函数应该执行点击并返回true；否则，如果它希望Squish尝试其他处理程序（如果没有其他处理程序可用，或者所有处理程序都返回undefined，则默认使用Squish自己的功能），则应返回undefined。

Squish.addEventObjectHook(function)

此函数将给定的函数注册为查找事件所引用的实际对象时的处理程序。当该元素发生事件时，该函数将使用HTML元素作为参数调用，可以返回该元素、另一个元素或undefined。如果它希望Squish尝试其他处理程序（如果没有其他处理程序可用，或者所有处理程序都返回undefined，则默认使用Squish自己的功能），则应返回undefined。

Squish.addEventToStringHook(function)

该函数将给定的函数注册为处理程序。注册的函数将使用三个参数调用：事件应用的对象的类型名称（作为字符串返回，由typeOf函数返回，如下所述的Squish.addTypeOfHook(function)函数），对对象本身的引用以及准备检查的原始事件对象。注册的函数应返回一个包含在HTTP查询格式的自定义记录参数的字符串，例如，"name1=value1&name2=value2"。当然，每个value都应该通过JavaScript escape函数传递。如果注册的函数不想自定义事件字符串，它应返回undefined。如果返回一个字符串，Squish将添加额外的信息，特别是对象的位置坐标、键盘修改状态和鼠标按钮状态，以及对象的名称和类型。

Squish.addEventTypeHook(function)

此函数将给定的函数注册为事件类型处理程序。注册的函数将使用两个参数调用：对HTML元素对象的引用和准备检查的原始事件对象。（事件对象可能不同于event.source属性，因为它来自Squish for Web扩展可以定制的eventObject函数。另请参阅Squish.addEventObjectHook(function)函数。）注册的函数应返回一个包含JavaScript事件名称的字符串，例如"mousedown"、"click"、"change"等。

注册事件类型处理程序在编写自定义HTML元素的扩展时可能会很有用。例如，这样做可以将自定义组合框上的mouseClick(objectOrName)调用转换为selectOption(objectOrName, text)调用。（另请参阅编写HTML类特定扩展。）

Squish.addItemTextForEventObjectHook(function)

此函数将给定的函数注册为处理程序，用于确定点击某个事件对象时项文本。处理程序接收点击的HTML元素或与之交互的元素。应与Squish.addNameOfHook(function)一起使用来实现项支持。钩子函数nameOf应始终返回项视图对象的名称，对于同一HTML元素，钩子函数itemTextForEventObject应返回该元素的项文本（如果适用）。如果无法识别项文本，则函数应返回undefined

Squish.addMatchObjectHook(function)

此函数将给定的函数注册为对象名称匹配函数，它返回一个布尔值以指示是否匹配实际（多属性）名称，即如果对象匹配其属性。此函数将使用一个对象、一个属性名称和一个valueObject调用（有关参数的更多信息，请参阅 Boolean Squish.matchProperty(valueObject, property)函数），如果无法执行匹配则返回布尔值或undefined。匹配名称时，Squish将使用已通过此函数注册的所有名称匹配函数尝试，如果所有这些函数都返回undefined（或如果没有），Squish将回退到使用它自己的内置名称匹配算法。（有关用法示例，请参阅如何实现自定义名称匹配器；另请参阅改进对象识别。）

Squish.addNameOfHook(function)

此函数将给定的函数注册为名称生成函数，返回一个给定对象的唯一真实（多属性）名称。此函数将使用对象调用并必须返回一个唯一标识对象的名称字符串——或者如果无法为对象生成名称，则必须返回undefined。生成对象的真实名称时，Squish将尝试通过此函数注册的所有名称生成函数，如果所有这些函数都返回undefined（或如果没有），Squish将回退到使用它自己的内置名称生成算法。（有关实现自定义名称生成器的示例，请参阅如何实现自定义名称生成器。）

Squish.addTypeOfHook(function)

此函数将给定的函数注册为返回DOM对象高层类型的函数。函数typeOf (function)将单个字符串（元素）作为参数，并返回一个字符串作为其结果。

当Squish遇到已通过Squish.registerWidget(argumentObject)函数注册的HTML元素时，并且每当它需要知道元素的类型时，它将使用在此处注册的钩子函数。因此，例如，如果我们有一个我们想要作为按钮处理的<span>标签，我们可以返回该标签的类型为“button”，而不是默认类型（在这个例子中将是“span”。

下面是一个非常简单的我们可以通过Squish.addTypeOfHook函数注册的typeOf函数。

function typeOf(element)
{
    if (element.className == "span")
    return "button";
    return undefined;
}

此函数将 <span> 标签重新识别为按钮，但保持所有其他标签的类型不变。对于您希望 Squish 作为可交互元素处理的元素，您通常应返回下面类型之一： button、checkbox、image、radio 或 submit。对于我们不处理的情形返回 undefined 是重要的——这表示 Squish 将寻找另一个 typeOf 函数（因为可以注册多个），如果没有其他函数或者所有其他函数都对此元素返回 undefined，则回退到其内部 typeOf 函数。

Squish.addUnmatchedProperty(objectName, propertyName)

此函数可用于匹配对象钩子函数中（请参阅 Squish.addMatchObjectHook(function)）以添加给定的 objectName 的不匹配属性列表。该函数应使用匹配对象钩子函数中提供的对象名称和未由此对象匹配的属性名称来调用。此函数的目的是为了在对象查找失败时提供更好的反馈，因为 Squish 将在错误信息中包含未匹配的属性名称。

背景：从 Squish 3.4 开始，自定义包装程序就可以生成一个未匹配的属性列表，从而提供更具信息的“对象未找到”错误消息。此 Squish.addUnmatchedProperty 函数的目的是让自定义 Squish for Web 扩展利用此功能。这对于自定义（即扩展）Squish 内置的对象匹配算法的扩展特别有用。

例如，假设我们想要实现支持自定义 Web 工具包（如 SmartGWT），其中工具包在生成名称时添加自定义属性（例如 iscLocator）。此类属性必须为 Web 扩展的匹配对象钩子函数所理解。因此，钩子函数需要一种将 iscLocator 属性添加到不匹配属性列表的方法，如果匹配失败。因此，如果使用此工具包的网页中有一个如 <button name="update">Update</button> 的元素，生成的名称可能如下所示：{tagName='BUTTON' iscLocator='//[Button id="1"]/'}。（如果该工具包真的是 SmartGWT，则这两个属性就足以唯一识别元素，因此 name 属性既不需要也不使用。）现在在对象查找过程中，Squish 将从 DOM 中获取所有 <button> 元素，然后尝试将这些其它属性与找到的每个元素上的真实（多属性）名称进行匹配。如果没有任何元素匹配，则匹配对象钩子将调用 addUnmatchedProperty 函数。因此，当用户收到“对象未找到”错误消息时，其中将包括 iscLocator 属性名称。

String Squish.cleanString(s)

此函数返回一个不包含任何前导和尾随空白，并且将内部多空格（或制表符或换行符）出现的次数替换为一个空格的字符串副本。同时，所有出现 Unicode 字符 U+2011（非断开连字符）和 U+2013（破折号）的次数都替换为连字符。

Squish.clickButton(buttonElement)

此函数点击给定的 buttonElement HTML 按钮元素。这用于 Squish for Web 扩展，它们可能需要在一些浏览器中特别处理原生 HTML 按钮。请参阅 HTML_CustomButtonBase 类、HTML_CustomButton 类和按钮支持。

String Squish.createClickItemInformationForMenuItem(menuElement, menuText)

```menuElement```是一个表示菜单的DOM元素。此函数返回一个字符串，用于标识哪个菜单项被点击。这个字符串适合作为事件到字符串钩子的返回值（见Squish.addEventToStringHook(function)）。

Squish for Web扩展应在自定义事件到字符串功能时使用此函数，用于记录对```clickItem(objectOrName, itemText)```函数的调用。

另请参阅，菜单支持和菜单项支持。

String Squish.createClickTabInformation(tabWidgeElement, tabTitle)

```tabWidgetElement```是一个表示标签小部件的DOM元素。此函数返回一个字符串，用于标识标签小部件的哪个标签被点击。此字符串适合用作事件到字符串钩子的返回值（见Squish.addEventToStringHook(function)）。

Squish for Web扩展应在自定义事件到字符串功能时使用此函数，用于记录对```clickTab(objectOrName, tabTitle)```函数的调用。

另请参阅：标签小部件支持。

String Squish.createChooseDateInformation(jsDate)

```jsDate```是JavaScript的```Date```对象。此函数返回一个字符串，适合从事件到字符串钩子返回，并包含给定日期的年、月和日。（见Squish.addEventToStringHook(function)。）

Squish for Web扩展应在自定义事件到字符串功能时使用此函数，用于记录对```chooseDate(objectOrName, date)```函数的调用。

另请参阅：日期选择器支持。

String Squish.createItemName(viewObjectName, itemText)

该函数的支持已被移除。为了支持对项的点击记录，您需要通过Squish.addItemTextForEventObjectHook(function)添加钩子函数。

String Squish.createMultiOptionString(arrayOfSelectedOptions)

此函数返回一个单一字符串，它是所有```arrayOfSelectedOptions```的值的连接，这些值由合适的分隔符分隔。此函数对提供组合框小部件且不使用标准HTML元素类型进行渲染的Web扩展很有用。对于此类小部件扩展，需要为事件到字符串钩子生成合适的参数值（见Squish.addEventToStringHook(function)函数）。对于逆操作请参见ArrayOfStrings Squish.splitMultiOptionString(multiOptionString)函数。

HTMLElement Squish.getElementByClassName(contextNode, className, tagName)

此函数返回相对于指定的```contextNode```的第一个具有给定```className```和```tagName```的元素。（请参阅项目遍历中的示例。）

Array Squish.getElementsByClassName(contextNode, className, tagName)

此函数返回具有给定```className```和```tagName```的元素数组，它们的相对位置是在指定的```contextNode```上。

Squish.getEventSourceElement(event)

此函数返回浏览器提供给事件的源元素。这是真实的源元素，而不是由安装的事件对象钩子函数返回的元素（有关详细信息，请参阅 Squish.addEventObjectHook(function)）。

Array-of-strings Squish.getSelectedOptionTexts(selectElement)

此函数返回 multiselect 或 combobox 元素中选中项的字符串值数组。必须为 selectElement，它应是一个 HTML_Select 类元素（即，HTML <select>）或提供相同属性和方法的对象。

Boolean Squish.hasClassName(objectOrName, className)

如果给定的 DOM 对象/网页元素具有与通过 className 传递的文本匹配的 DOM 类，则此函数返回 true；否则返回 false。

对于只有一个类名名称的 HTML 元素，例如 <span class="warning">dangerous ducks</span>，此函数按预期工作。例如

if (Squish.hasClassName(element, "warning"))
    handleWarningElement(element)

但是，HTML 元素可以自由地具有多个由空格分隔的类名，例如 <span class="heading major">New Section</span>。在这种情况下，Squish 将类名作为列表跟踪，这非常灵活。例如

if ((Squish.hasClassName(element, "heading") and
     Squish.hasClassName(element, "major")):
    # Both class names present
    handleMajorHeadingElement(element)
elif Squish.hasClassName(element, "heading"):
    # Only "heading" class name present
    handleHeadingElement(element)

Boolean Squish.isElementVisible(element)

如果给定 element 根据 CSS display 和 visibility 属性可见，则此函数返回 true；否则返回 false。

element 的 z 值不会被考虑，因此不会考虑元素是否位于另一个元素之下。

Boolean Squish.matchProperty(valueObject, property)

如果给定 valueObject 的值与给定 property 的值匹配，则此函数返回 true；否则返回 false。

valueObject 包含要匹配的字符串值以及一个表示是否基于文本书面比较（0）、通配符匹配（2）或正则表达式匹配（1）的整数标志，格式为 {value: string, modifiers: integer}。

应使用此函数代替直接比较在你的自定义 matchObject 函数中。

使用 Squish.addMatchObjectHook(function) 函数注册自定义匹配属性函数。（有关示例用途，请参阅如何实现自定义名称匹配器；另请参阅改进对象识别。）

Squish.mouseClick(objectOrName)

Squish.mouseClick(objectOrName, ctrl)

Squish.mouseClick(objectOrName, ctrl, shift)

Squish.mouseClick(objectOrName, ctrl, shift, alt)

Squish.mouseClick(objectOrName, ctrl, shift, alt, x, y)

Squish.mouseClick(objectOrName, ctrl, shift, alt, x, y, button)

在指定的相对位置 x，y 上发送给给定 objectOrName 的鼠标点击事件。ctrl 是一个布尔值，如果为 true 则表示按下 Ctrl 键。同样，shift 和 alt 也是布尔值，与 Shift 和 Alt 键的作用方式相同。默认情况下，点击使用左鼠标按钮，但可以通过指定 button 参数为一个数字来重写：1 表示左按钮，2 表示右按钮，4 表示中按钮。除了第一个参数之外的所有参数都是可选的，可以省略。

String Squish.nameOf(objectOrName)

此函数返回给定 objectOrName 的实际（多属性）名称。

此方法可能调用已注册的名称钩子函数，因此在从您的自定义名称钩子处理器调用时应小心。

Squish.ObjectName Squish.ObjectName()

构建一个新实例 ObjectName 对象，允许添加或删除使用普通字符串比较、通配符或正则表达式的属性。

String Squish.propertiesToName(objectOrName, listOfPropertyNames)

给定一个 DOM objectOrName/网页元素，该函数返回一个包含一个或多个用空格分隔的 propertyName='propertyValue' 对的字符串，每个对对应于给定的 listOfPropertyNames 中的每个属性。生成的字符串适用于在名称生成中使用，例如，由 String Squish.uniquifyName(name, objectOrName) 函数。

Squish.RegExPropertyValue Squish.RegExPropertyValue(regexString)

构建一个新的 RegExPropertyValue 实例，可以作为属性值添加到 ObjectName 对象。regexString 指定应匹配的属性的正则表达式。

Squish.registerWidget(argumentObject)

此函数用于在 Squish 中注册自定义网页元素，以便它们可以正确地进行脚本来录播。

Event – 这是一个字符串，指定要记录哪种类型的事件；例如，“mousedown”。
Class – 这是一个字符串，指定 Squish 应识别为部件的 DOM 对象的类名（即 className 属性的值）。

有关示例，请参阅如何设置简单部件支持。

此函数的目的是允许您为 Squish 常忽视的 HTML 元素上的鼠标点击（例如，mouseClick(objectOrName)）添加支持。如果您想记录对 <span> 标签或由您使用的特定网页框架支持的定制标签的点击，这将很有用。

可以通过检查元素的 type 属性或其 tagname 来判断元素类型，但你可以通过注册一个 typeOf 函数来覆盖这种行为（例如，使 <span> 标记被当作按钮处理），利用 Squish.addTypeOfHook(function) 函数。注意，尽管每注册一个自定义元素需要通过单独的 Squish.registerWidget 函数调用，但我们可以一次调用 Squish.addTypeOfHook(function)，因为在 typeOf 函数中，我们可以为所有注册的自定义元素返回适当类型。

ArrayOfStrings Squish.splitMultiOptionString(multiOptionString)

此函数返回通过分割指定的 multiOptionString 所产生的字符串数组。分隔符使用逗号，除非字符串的最后一个字符是 ";|-+*!/" 之一，此时则按照那个字符进行分隔。反向操作请参阅 String Squish.createMultiOptionString(arrayOfSelectedOptions) 函数。

String Squish.uniquifyName(name, objectOrName)

此函数通过将正确的出现次数添加到名称中，为给定的 objectOrName 返回名称的 "唯一化" 版本。

name 必须提供真实名称，即形式为 {propertyName1='propertyValue1' propertyName2='propertyValue2' ... propertyNameN='propertyValueN'} 的字符串。给定一个 name 和一个 objectOrName，如果该名称可以唯一标识应用程序对象，则此函数不改变 name；否则，返回带有额外属性（occurrence）的 name，其值为一个整数，使得名称是唯一的。此函数的目的是创建一个可以唯一标识给定 objectOrName 的名称。

Squish.WildCardPropertyValue Squish.WildCardPropertyValue(wildcardString)

构造一个新的 WildCardPropertyValue 实例，该实例可以添加到 ObjectName 对象中。wildcardString 指示了属性应该与之匹配的通配符表达式。

ObjectName Object

此对象的方法用于访问构成对象的属性。它允许添加属性、更改值、获取属性名称列表以及将名称转换为多属性名称字符串。

ObjectName.addProperty(propertyName, propertyValue)

此函数添加或用 propertyName 和 propertyValue 提供的属性值替换该属性。属性值必须是用于严格匹配的字符串，或是一个 Squish.WildCardPropertyValue Squish.WildCardPropertyValue(wildcardString) 或 Squish.RegExPropertyValue Squish.RegExPropertyValue(regexString)。

PropertyValue ObjectName.getPropertyValue(propertyName)

此函数返回具有 propertyName 属性值的属性，如果对象名没有该属性，则返回 undefined。返回的值可以是 String（用于严格匹配属性），也可以是 Squish.WildCardPropertyValue Squish.WildCardPropertyValue(wildcardString) 或 Squish.RegExPropertyValue Squish.RegExPropertyValue(regexString)。

ObjectName.removeProperty(propertyName)

此函数从此对象名中移除具有 propertyName 属性的属性。

ListOfStrings ObjectName.getPropertyNames()

此函数返回当前属于此对象名的属性名列表。

概念和设置

通过指定实现它的 JavaScript 文件的路径来启用此扩展。当 Squish 钩入 Web 浏览器时，它将在浏览器中评估扩展文件内的 JavaScript。

在 JavaScript 扩展文件中，可以使用 Squish 的编程接口来 hook 到框架提供的对象识别、命名生成和其他功能。此外，通过实现某些 JavaScript 钩子函数，还可以暴露框架自定义小部件的 API，使其对测试脚本可访问。

为了指定 JavaScript 扩展文件（例如，假设文件名为 C:\squishext\myextension.js），请将以下类似行添加到 Squish 安装 etc 子目录中的 squish.ini 文件中

Wrappers/Web/ExtensionScripts="C:\\squishext\\myextension.js"

如果您进行分布式测试，则只需在用于 squishrunner 或 squishide 的机器上执行此操作。

用于实现扩展的 API 在 Squish 对象中进行说明——该对象提供了支持 Squish 的 JavaScript 扩展的方法。以下章节解释了对象的 API，并展示了一些使用示例。

如何设置对简单小部件的支持

为了避免记录多余的鼠标点击，Squish 只会记录已知响应点击的 DOM 元素上的点击。为了判断一个元素是否响应点击，Squish 将检查元素是否有设置的鼠标事件处理器（例如一个 onClick 函数），或者元素是否是已知的可点击小部件——例如表单输入元素、链接等。

如果您的 JavaScript 库带有自定义可点击小部件，例如自定义按钮，您可以使用 Squish.registerWidget(argumentObject) JavaScript 函数来告诉 Squish。此函数预期有一个命名参数列表（即对象），该对象指定了元素的 DOM 类和应记录的事件类型。

例如，假设您有一个特殊按钮实现，该实现以以下方式在 DOM 中表示

<span class='ajaxbutton'>Click Me</span>

要使 Squish 能够记录此类小部件的鼠标点击事件，请在您的扩展 JavaScript 文件中添加以下行

Squish.registerWidget({Class: "ajaxbutton", Event: "click"});

现在，当您录制脚本并点击此按钮时，Squish 将记录 mouseClick(objectOrName) 语句。

在回放测试时识别小部件时，Squish 默认使用自己的内置命名生成算法。在这个特定示例中，将使用 innerText，因为未设置 id 或 name，这对于这个情况来说是足够的。因此，为此对象生成的真实名称将是，{tagName='SPAN' innerText='点击我'}。

您可以为Squish的名字生成器添加自己的名字生成算法——如果您在生成名称时希望使用来自web框架自定义元素的自定义属性，这尤其有用。相关内容在下一节中介绍。

如何扩展名称生成器和识别

为了生成小部件的名称，Squish会生成一个属性对列表来识别该对象。Squish使用一系列预定义的属性，如tagName、id、name、title、innerText等。

如果属性无法唯一识别对象，则在名称中添加一个occurrence属性，该属性指定应该选择与其他属性匹配的对象中哪一个。

tagName除外——这是所有名称都必须具有的一个强制属性——其他属性都是可选的，可以自由选择。

在某些情况下，可能会希望使用某些类型对象的名称中的自定义属性。为此，您可以指定自己的钩子函数，然后将被调用以生成您自己小部件的名称。如果需要，还可以安装执行对象搜索时进行的属性匹配的钩子函数。

如何实现自定义名称生成器

为了展示如何实现自定义名称生成器，我们将从一个示例菜单元素开始

<SPAN class='menu' id='fileMenu'>
    <SPAN class='menuItem' menuID='fileOpen'>Open</SPAN>
    <SPAN class='menuItem' menuID='fileQuit'>Quit</SPAN>
</SPAN class='menu'>

首先，我们必须使用Squish.registerWidget(argumentObject)函数将菜单项注册为可点击的小部件

Squish.registerWidget({Class: "menuItem", Event: "click"});

（我们之前已经看到了这个函数的一个示例：如何设置简单小部件的支持。）

在这个例子中，我们将使用menuID属性和其他DOM类以及父元素的ID来为我们的菜单元素（即每个menuItem <span>标签）提供唯一的标识名称。

var myUiExtension = new Object;

myUiExtension.nameOf = function(obj) {
    if (obj.tagName == "SPAN" &&
        Squish.hasClassName(obj, "menuItem")) {
        var name = '{' +
            Squish.propertiesToName(obj, ["tagName", "menuID"]) +
            " parentID='" + obj.parentNode.id + "'" +
            " className='menuItem'" +
            "}";
        return escape(Squish.uniquifyName(name, obj));
    }
    return undefined;
}

我们将这个函数作为自定义myUiExtension对象的一个属性添加。在实现中，我们检查对象是否是我们想要处理的类型，即menuItem <span>标签。如果类型正确，我们使用自定义代码为其创建一个唯一的名称；否则，我们返回undefined——这不是一个有效的名称值，因此Squish将尝试每个其他已注册的名称生成钩子函数（如果有），如果所有这些函数都返回undefined（或如果没有任何函数），Squish将回退到使用其默认的名称生成器。

为了确定该元素是否是我们要处理的那些元素之一，我们检查其标签名是否为SPAN，其DOM类是否为menuItem。对于第二个检查，我们使用Squish.hasClassName(objectOrName, className)辅助函数，该函数返回一个布尔值，如果DOM对象的一个DOM类具有与给定类名相同的名称，则返回true。

如果元素类型正确，我们将使用自定义的名字生成算法为它创建一个名称。一个真实的（多属性）名称由一个或多个属性名-值对组成，它们都包含在括号内。在这里，我们首先使用String Squish.propertiesToName(objectOrName, listOfPropertyNames)函数来创建包含指定的属性名和值的名称字符串；然后，我们添加两个额外的属性对，一个用于父ID，另一个用于类名。最后，我们使用String Squish.uniquifyName(name, objectOrName)函数来确保生成唯一的名称。此函数接受一个实际的（多属性）名称作为字符串和该名称应识别的对象，如果可能的话，将返回未更改的名称，或者如果需要进一步区分名称以确保其唯一性，则返回带有occurrence属性的名称。

因此，对于上面显示的示例，如果该对象是fileOpen菜单项，String Squish.propertiesToName(objectOrName, listOfPropertyNames)函数将给我们字符串"tagName='SPAN' menuID='fileOpen'"，并且在添加父ID和类名后，我们会得到的最终名称是"{tagName='SPAN' menuID='fileOpen' parentID='fileMenu' className='menuItem'}"。

我们无法使用String Squish.propertiesToName(objectOrName, listOfPropertyNames)函数来指定父ID或类名属性。对于父ID，这是因为在Squish中，它不是一个常规属性，而是一个伪属性，因此我们必须自己处理它。一旦成为真实名称的一部分，Squish将像处理任何其他属性一样处理它。在类名的情况下，我们无法使用String Squish.propertiesToName(objectOrName, listOfPropertyNames)函数的唯一原因是，DOM属性名是class，而Squish使用JavaScript的className名称。此外，DOM类可能包含多个值，而我们需要指定一个menuItem。

最后，我们确保任何特殊字符都已被正确转义——我们为此使用标准的JavaScriptescape函数。然后我们返回结果。

一旦我们的名字生成函数就绪，我们必须通知Squish其存在，以便在需要名称时使用它。这是通过将其注册为钩子函数来完成的

Squish.addNameOfHook(myUiExtension.nameOf);

在这里，我们使用Squish.addNameOfHook(function)函数将myUiExtension.nameOf函数注册为名称生成函数。从现在起，Squish将使用此函数在需要生成真实名称时使用，如果函数返回undefined，则将回退到使用任何其他生成函数（作为最后手段），并使用Squish的内置默认名称生成函数。

如何实现自定义名称匹配器

在按名称搜索对象时，Squish遍历DOM树中的所有对象，并查询指定的对象属性，以查看它们的值是否与名称中的值匹配。

使用自定义名称匹配器钩子可以在搜索匹配的对象时考虑名称的伪属性（例如，我们之前看到的parentID）。由于Squish对我们创建的任何伪属性都没有了解，我们必须实现一个自定义函数来进行查找和名称匹配，考虑到我们的伪属性。

myUiExtension.matchObject = function(obj, property, valueObject) {
    if (property == "parentID")
    return Squish.matchProperty(valueObject, obj.parentNode.id);
    return undefined;
}

同样，我们将此函数作为自定义myUiExtension对象的属性实现。Squish将传递对象、属性名和名称中指定的预期值到这个函数。

如果给定的属性是我们的伪属性，我们使用内置的布尔Squish.matchProperty(valueObject, property)函数来确定是否存在匹配。否则我们返回undefined；在这些情况下，Squish将尝试所有其他已注册的匹配对象（如果有的话），如果没有给出明确的真或假（或者如果没有），则回退到其自身的内部名称匹配函数。请注意，valueObject不仅仅是一个字符串，而是一个包含一个字符串值和一个标志的对象，该标志表示匹配是否应根据字面的字符串比较、通配符匹配或正则表达式匹配进行。参见提高对象识别。）

在本例中，我们选择自行处理parentID伪属性；对任何其他属性返回undefined，以便将匹配工作传递给Squish（对除了我们感兴趣的伪属性外的任何内容）。

通过安装钩子完成自定义名称匹配设置

Squish.addMatchObjectHook(myUiExtension.matchObject);

可以使用的Squish.addMatchObjectHook(function)函数可以注册任意数量的名称匹配函数。

如何设置对复杂小部件的支持

使用扩展机制，还可以添加对复杂小部件的专用支持——即包含项的小部件，如树形小部件、表格、菜单、日历控件和其他基于项的小部件。例如，树包含节点，表格包含单元格，菜单包含项，日历包含日期单元格。我们通常将此类复杂小部件称为“项视图”，并经常将这些节点、单元格和项简单地称为“项”。

为了使与这些小部件的高级交互成为可能，用户操作，如单元格或项上的鼠标点击，以及展开和折叠树节点，必须被识别和回放——并且以一种与底层HTML表示无关的方式进行。此外，某些状态和属性，如当前选择，应允许从测试脚本中查询，以实现健壮和自动验证。

使用项和项视图抽象以及必要的JavaScript钩子和API，Squish支持添加任何自定义项视图DHTML/AJAX/JS小部件，以便测试脚本可以访问小部件及其项的状态、属性和函数。

本节说明如何实现此类专用项视图支持，以便Squish能够正确记录使用自定义项视图的测试脚本，并准确回放此类测试。这是通过使用Squish的JavaScript扩展API来完成的。

我们将通过一个AJAX小部件的例子来说明说明——谷歌Web工具包（GWT）中的树控件。我们将实现所有必要的支持，以正确记录和回放项和项控件的点击，以独立于DOM识别树和项，并允许查询树的选择。

一旦实现必要的钩子，在与支持的小部件交互时会记录对clickItem(objectOrName, itemText)函数和clickTreeHandle(objectOrName, itemText)函数的调用。此外，使用HTML_CustomItemView类和HTML_CustomItem类抽象API，测试脚本将能够访问小部件并与其项、状态和属性一起工作。

在我们开始实现必要的支持之前，我们需要查看小部件的DOM结构，因为我们自己的自定义支持将使用Web应用程序的DOM来提供测试脚本所依赖的抽象和封装。

以下是GWT Tree小部件在浏览器中呈现的截图

GWT Tree小部件

GWT用于表示此树小部件的DOM层次结构具有以下结构（省略了无关细节和大多数数据）

<DIV class="gwt-Tree">
  <TABLE>
    <TR>
      <TD>
      <IMG src="tree_open.gif"/>
      </TD>
      <TD>
      <SPAN class="gwt-TreeItem">Beethoven</SPAN>
      </TD>
    </TR>
  </TABLE>
  <SPAN>
    <DIV>
    <TABLE>
      <TR>
        <TD>
        <IMG src="tree_closed.gif"/>
        </TD>
        <TD>
        <SPAN
class="gwt-TreeItem gwt-TreeItem-selected">Concertos</SPAN>
        </TD>
      </TR>
      </TBODY>
    </TABLE>
    </DIV>
    <DIV>
    <TABLE>
      <TR>
        <TD>
        <IMG src="tree_closed.gif"/>
        </TD>
        <TD>
        <SPAN class="gwt-TreeItem">Quartets</SPAN>
        </TD>
      </TR>
      </TBODY>
    </TABLE>
    </DIV>
  </SPAN>
...
</DIV>

因此，我们可以看到树小部件是用类名为gwt-Tree的DIV元素表示的。树本身位于此DIV元素内部，在一个TABLE中。

每个树项都被一个具有类名gwt-TreeItem的SPAN元素包含。项的文本是元素的内部文本，并且当选中项还会有一个额外的类名gwt-TreeItem-selected。

项处理（通常显示为*或-符号，表示项可展开或已展开），通过位于项上方的TD元素中的一个IMG元素来表示—具体来说，是该项父级的下一个兄弟的第一个子元素。可以通过IMG的src属性来确定项是展开的（src="tree_open.gif"）还是折叠的（src="tree_closed.gif"）。

项之间的关系（即实际的树结构），通过包含其父级相对的一组兄弟元素的嵌套SPAN元素来模拟。

这个信息足够我们检测网页的DOM结构中的GWT Tree元素、树项元素以及项的处理。拥有了这些知识，我们就可以创建一个高级API，我们的测试脚本可以使用这个API与GWT Tree及其项交互，使用Squish统一的“项视图”API。

请注意，以下小节中使用的所有代码均取自文件lib/extensions/web/jshook_gwt.js。

记录高级GUI操作的钩子

要在工具包的扩展对象中实现的功能

第一步是实现记录GWT Tree上高级GUI操作的JavaScript钩子。这意味着，如果用户单击一个项，应记录一个(treeName, itemName)函数调用。同样，如果单击树项的处理，应记录为(treeName, itemName)。

要实现这一点，我们必须实现三个不同的钩子

事件对象钩子：一个返回事件源DOM元素的函数。
对象类型钩子：一个返回DOM对象的顶层类型名称的函数。
对象名称钩子：一个返回DOM对象的Squish对象名称的函数。

一旦这些功能被实现，它们必须注册到Squish中，以便由Squish的事件记录器调用。当Squish调用它们时，它会传递作为参数的DOM事件源对象，根据这个，我们可以决定是否响应。（我们可以安全地忽略我们不希望处理的的事件，让Squish来解决。）

对于GWT Tree，当实现这些函数时，我们必须处理三种不同的高级对象

树对象
树项
树项处理

所以，对于所有三个函数，我们需要一种判断我们处理的是哪种类型对象的手段。为此，我们将首先定义一个gwtExtension对象来包含我们编写的所有与GWT Tree相关的代码。然后，我们将定义一些常量，然后我们将创建一个getType函数。

var gwtExtension = new Object;

gwtExtension.Tree = 0;
gwtExtension.TreeItem = 1;
gwtExtension.TreeItemHandle = 2;

我们将使用这些常量来区分我们感兴趣的处理的对象。现在我们需要一个可以匹配DOM类名到这些常量的函数

gwtExtension.getType = function(obj)
{
    if (Squish.hasClassName(obj, 'gwt-TreeItem'))
    return gwtExtension.TreeItem;
    else if (obj.tagName == 'IMG' &&
        (obj.src.indexOf('tree_open') != -1 ||
     obj.src.indexOf('tree_closed') != -1) &&
        Squish.hasClassName(gwttreeExtension.itemOfHandle(obj),
                'gwt-TreeItem'))
    return gwtExtension.TreeItemHandle;
    else if (Squish.hasClassName(obj, 'gwt-Tree'))
    return gwtExtension.Tree;

    return undefined;
}

自定义的 getType 函数使用 Boolean Squish.hasClassName(objectOrName, className) 函数来判断元素是否为树项，如果是，则返回相应的常量。类似的代码也用于处理树木本身，但对于树句柄，我们必须检查标记是否为 IMG 并且具有适当的图像之一，以及与图像关联的元素是一个具有正确类 (gwt-TreeItem) 的项目。我们很快就会看到 gwttreeExtension 对象和 gwttreeExtension.itemOfHandle 函数的创建。

如果元素不是我们所感兴趣的其中之一，我们返回 undefined，这表示 Sabish 应尝试尚未尝试的类型函数，或者回退到其内置功能。

事件对象

现在我们有了合适的 getType 函数，实现所需的三个钩子函数相当简单

gwtExtension.eventObject = function(obj)
{
    if (!obj)
        return undefined;
    switch (gwtExtension.getType(obj)) {
    case gwtExtension.TreeItem: // fallthrough
    case gwtExtension.TreeItemHandle:
    return obj;
    }
    return undefined;
}

如果高级对象类型是树项或树项句柄，我们返回此对象。这告诉 Squish 该对象是我们希望记录事件的，因此事件记录器不应忽略它。一如既往，如果我们不识别该对象，我们将返回 undefined，这告诉 Squish 为我们处理它。

对象类型

如果 Squish 遇到应该记录事件的对象，它需要知道对象的类型。为此，我们必须实现一个适合的钩子函数

gwtExtension.typeOf = function(obj)
{
    switch (gwtExtension.getType(obj)) {
    case gwtExtension.TreeItem:
    return 'custom_item_gwttree';
    case gwtExtension.TreeItemHandle:
    return 'custom_itemhandle_gwttree';
    case gwtExtension.Tree:
    return 'custom_itemview_gwttree';
    }
    return undefined;
}

此函数返回的类型名称必须遵循 必须遵循的 约定！Squish 提供了一个通用的项目视图抽象，为了正确工作，我们必须返回正确形式的类型名称。

对象名称

用于自定义树的项目视图 API 的三个主要组件，以及对应于 DOM 对象表示的组件，是项目、句柄和视图 - 视图是一个列表、表格或树小部件。我们必须遵循的自定义类型名称的命名约定非常简单：项目类型名称必须以 custom_item_ 开头；项目句柄类型名称必须以 custom_itemhandle_ 开头；视图类型名称必须以 custom_itemview_ 开头。名称的其余部分必须标识我们的自定义视图（因此在此示例中，每个类型名称都以 _gwttree 结尾）。

我们必须实现的第三个钩子函数返回特定高级视图对象的名称

gwtExtension.nameOf = function(obj)
{
    switch (gwtExtension.getType(obj)) {
    case gwtExtension.TreeItem:
        return escape(gwtExtension.nameOfTreeItem(obj)["object"]);
    case gwtExtension.TreeItemHandle:
    return escape(gwtExtension.nameOfTreeItem(
                gwttreeExtension.itemOfHandle(obj))["object"]);
    case gwtExtension.Tree:
    return Squish.uniquifyName(gwtExtension.nameOfTree(obj), obj);
    }

    return undefined;
}

一如既往，我们通过返回 undefined 来告诉 Squish 处理我们不感兴趣的对象。

此函数使用两个其他函数，gwtExtension.nameOfTree 和 gwtExtension.nameOfTreeItem 来为自定义对象创建适当的实际（多属性）名称。以下是它们的实现

gwtExtension.nameOfTree = function(obj)
{
    return '{' + Squish.propertiesToName(obj,
        ["tagName", "id", "name"]) + "className='gwt-Tree'}";
}

此函数为每个 Squish 遇到的 GWT 树对象创建一个唯一名称。（有关创建名称的更多信息，请参阅如何实现自定义名称生成器）

以下是生成树项名称的函数

gwtExtension.nameOfTreeItem = function (obj)
{
    var tree = obj;
    while (tree && (!Squish.hasClassName(tree, 'gwt-Tree')))
    tree = tree.parentNode;
    var treeName = Squish.nameOf(tree);
    var item = obj;
    return {"object": treeName, "itemText": item.innerText};
}

项的名称由包含项视图的项名称（即树小部件）和项的实际名称组成（通常使用项的文本 - 即其 innerText）。这两个部分分别返回，以便在下面的 nameOf 函数和 itemTextForEventObject 函数中重用。

首先，我们要找到该项所属的树小部件。这通过访问该项的父组件来完成，如果不是树，就访问父组件的父组件，依此类推，直到我们找到类 gwt-Tree 的对象。一旦我们找到了树对象，就可以调用 String Squish.nameOf(objectOrName) 函数来获取其实际的（多属性）名称。该项的文本（从该项的 innerText 获取）将单独返回。

要实现第四个函数是一个回调，它将在发现点击事件发生时提供实际的项文本。这允许Squish为项上的点击事件生成漂亮的 clickItem 调用。

gwtExtension.itemTextForEventObject = function( eventObject )
{
    switch (gwtExtension.getType(eventObject)) {
        case gwtExtension.TreeItem:
            return gwtExtension.nameOfTreeItem(eventObject)["itemText"];
        case gwtExtension.TreeItemHandle:
            return gwtExtension.nameOfTreeItem(gwttreeExtension.itemOfHandle(eventObject))["itemText"];
    }

    return undefined;
}

该函数重用了nameOfTreeItem函数，但如果给定的对象是指向树项或树项句柄，则返回由该函数计算出的项文本。

注册钩子函数

现在我们已经实现了所有必要的钩子函数，我们必须注册它们以使它们生效

Squish.addNameOfHook(gwtExtension.nameOf);
Squish.addTypeOfHook(gwtExtension.typeOf);
Squish.addEventObjectHook(gwtExtension.eventObject);
Squish.addItemTextForEventObjectHook(gwtExtension.itemTextForEventObject);

有了这些钩子，如果我们在GWT Tree上记录事件，预期的高级操作将被正确记录。

用于重新播放高级GUI操作的钩子

在视图扩展对象中要实现的功能

一旦实现并记录了记录钩子，并正常工作，下一步是实现钩子，以使Squish能够识别并正确重新播放记录的GUI操作。

查找项

要支持重现项上的点击（clickItem(objectOrName, itemText)），只需实现一个额外的函数。该函数必须在树中按名称搜索项，并返回代表该项的DOM对象的引用。Squish将使用此函数来获取要发送点击事件的项。

该函数的名称必须遵循一定的命名约定。特别是，它必须被称为 findItem，并且它必须作为名为 typenameExtension 的对象的函数属性存在，其中 typename 是与我们在 typeOf 钩子函数中附加到对象类型名称完全相同的名称。

对于GWT Tree示例，我们有类型名称 custom_item_gwttree 等，因此我们必须使用的名称是 gwttree。这意味着我们必须创建一个名为 gwttreeExtension 的对象，并为它提供一个 findItem 函数，正如以下代码所示

var gwttreeExtension = new Object;

gwttreeExtension.findItem = function(tree, name)
{
    var node = tree.firstChild;
    while (node) {
    if (node.firstChild) {
        var node2 = gwttreeExtension.findItem(node, name);
        if (node2) {
        return node2;
        }
    }
    if (node.className &&
        Squish.hasClassName(node, 'gwt-TreeItem') &&
        Squish.cleanString(node.innerText) == name) {
        return node;
    }
    node = node.nextSibling;
    }
    return undefined;
}

tree 是树DOM元素的引用，而 itemText 是项的文本（实际上是其 innerText）。

该函数将遍历树的全部子元素，直到找到类 gwt-TreeItem 的元素，其 innerText 与请求的项文本匹配。

项句柄

对于列表和表小部件，提供 findItem 函数就足够了，但对于树小部件，还需要一个额外函数来处理项句柄。

为此目的，必须在同一对象中实现一个名为 itemHandle 的函数，该函数返回给定项所属的句柄。以下是供GWT Tree项使用的函数实现

gwttreeExtension.itemHandle = function(node)
{
    return node.parentNode.previousSibling.firstChild;
}

此函数返回与项句柄（在项的 TD 元素上方的 IMG 元素）对应的GWT Tree元素（即项的父组件的前一个兄弟的第一个子元素）。

实现这两个函数全部是实现项和项句柄上重现高级操作的必要条件。

公开 Item 视图 API

在视图扩展对象中要实现的功能

itemText
isItemSelected
isItemOpen
setItemSelected（见isItemSelected）
setItemOpen（见isItemOpen）
childItem（见项遍历）
parentItem（见项遍历）
nextSibling（见项遍历）
itemView（见项遍历）
numColumns（见列）
columnCaption（见列）

为了让 Squish 能够检测项视图及其项，并能够记录和回放与它们相关的GUI操作，我们迄今为止所做的工作已经足够。

但 Squish 的项视图抽象也向测试提供了迭代项和查询设置选择和其他属性的API。为了支持这种功能，需要实现各种附加功能——所有这些我们都会在这里介绍，并提供基于 GWT Tree 示例的示例。

项文本

Squish 测试脚本项视图API允许我们检索树项（例如，使用tree.findItem(...)），并查询项的text属性。

默认情况下，Squish 返回项的innerText，但如果这对您正在处理的项不合适，您可以在视图的扩展对象中实现自己的itemText(item)函数，然后将调用该函数而不是Squish的默认函数。

gwttreeExtension.itemText = function(item)
{
    return item.innerText;
}

如果typenameExtension有一个itemText函数属性，Squish将调用此函数并提供相关项的DOM对象的引用。该原则也适用于其他函数：如果提供给我们的函数用于我们的扩展类型，则Squish将使用该函数；否则，Squish将回退为其内置功能。

在这种情况下（即，对于GWT Tree项），不需要实现此函数，因为内置版本本就返回了innerText。

项选择

Squish 测试脚本项视图API允许我们检索树项（例如，使用tree.findItem(...)），并查询项的selected属性。

为了查询项的选择状态，必须在视图的扩展对象中提供isItemSelected函数。这里有一个适用于GWT Trees的示例。

gwttreeExtension.isItemSelected = function(item)
{
    return Squish.hasClassName(item, "gwt-TreeItem-selected");
}

如果typenameExtension有一个isItemSelected函数属性，Squish将调用此函数并提供相关项的DOM对象的引用。

要检查项是否选中，我们只需返回相应的true或false，具体取决于项的类名中是否有gwt-TreeItem-selected。

Squish 的项视图API也支持更改项的选择状态。这可以通过在相同的扩展对象中实现一个setItemSelected(item, selected)函数来实现。这里的item是项的DOM对象的引用，而selected是一个布尔值，其中true表示该项应被选中，false表示该项应取消选中。

项句柄的状态

Squish的测试脚本item-view API允许我们获取树状项的句柄并查询以判断项是否展开（子项可见）或折叠（子项隐藏）。句柄的展开状态由opened属性持有，为了支持这个属性，我们必须在树的扩展对象中实现一个isItemOpened函数。(注意，这个功能对于列表或表格视图来说是没有意义的。

以下是一个GWT Tree的示例实现。

gwttreeExtension.isItemOpen = function(item)
{
    try {
        var obj = item;
        while (obj && obj.tagName != 'TABLE') {
            obj = obj.parentNode;
        }
        if (!obj || !obj.nextSibling) {
            return undefined;
        }
        obj = obj.nextSibling;
        return Squish.isElementVisible(obj);
    }
    catch (_e) {
        return false;
    }
}

如果typenameExtension有一个isItemOpen属性函数，Squish将会调用这个函数并传递一个代表相关项的DOM对象的引用。

在此，我们简单地获取项的句柄并返回一个布尔值，以反映该项是否有展开的图标。

item-view API也支持更改项的展开/折叠状态。这可以通过在同一扩展对象中实现一个setItemOpen(item, expand)函数来实现。参数item是项的DOM对象引用，而参数expand是一个布尔值，其中true代表该项应该展开（打开），而false代表该项应该折叠（关闭）。

项遍历

item-view API还包括在树视图中遍历项的函数。这些遍历函数是：childItem(treeOrItem)、nextSibling(item)和parentItem(item)。还有一个itemView(item)函数；这个函数返回给定项所在的视图。

使用这些API可以遍历树中项，然后使用前面显示的函数检索项的文本、选择或取消选择项、展开或折叠项。

如果我们想让我们的自定义视图提供遍历，则必须在我们的自定义视图的扩展对象中实现这四个函数的版本。同样，正如我们之前讨论过的函数，如果我们创建了这些函数的版本，Squish会调用它们并将代表相关项的DOM对象的引用传递给它们。请注意，对于childItem函数来说，Squish可能会用树或项调用它。

以下是这些函数针对GWT树实现的版本。

gwttreeExtension.childItem = function(parent)
{
    if (Squish.hasClassName(parent, "gwt-Tree")) {
        return gwttreeExtension._findFirstTreeItem(parent);
    } else {
    while (parent && parent.tagName != 'TABLE')
        parent = parent.parentNode;
    if (!parent || !parent.nextSibling)
        return undefined;
    parent = parent.nextSibling;
        return gwttreeExtension._findFirstTreeItem(parent);
    }
}

gwttreeExtension._findFirstTreeItem = function(baseNode)
{
    obj = Squish.getElementByClassName(baseNode,
            'gwt-TreeItem', 'SPAN');
    if(!obj) {
        obj = Squish.getElementByClassName(baseNode,
            'gwt-TreeItem', 'DIV');
    }
    return obj;
}

gwttreeExtension.nextSibling = function(node)
{
    node = node.parentNode;
    while (node && node.tagName != 'DIV')
        node = node.parentNode;
    if (!node || !node.nextSibling)
        return undefined;
    node = node.nextSibling;
    return gwttreeExtension._findFirstTreeItem(node);
}

gwttreeExtension.parentItem = function(node)
{
    node = node.parentNode;
    while (node && node.tagName != 'DIV')
    node = node.parentNode;
    if (!node || !node.parentNode || !node.parentNode.previousSibling)
    return undefined;
    node = node.parentNode.previousSibling;
    return gwttreeExtension._findFirstTreeItem(node);
}

gwttreeExtension.itemView = function(node)
{
    var obj = node;
    while (obj && (!Squish.hasClassName(obj, 'gwt-Tree')))
    obj = obj.parentNode;
    return obj;
}

这些实现相当自解释，尤其是如果你查看GWT Tree使用的DOM结构。(注意，GWT实现已经更改了，所以我们必须考虑到旧的版本和最新版本—这就是为什么我们有gwttreeExtension._findFirstTreeItem函数的原因。）

列

如果项视图支持多列，可以在视图的扩展对象中实现columnCaption(view, column)和numColumns(view)函数，以允许测试脚本使用具有相同名称的API调用来查询列信息。

测试和结论

这完成了对JavaScript扩展API的介绍。可以在examples/web/suite_gwt套件中找到使用本节中开发的GWT Tree API编写的几个测试脚本。

编写HTML类特定的扩展

为了使Squish能够记录和播放自定义HTML小部件类型的特定对象，我们可以为我们感兴趣的特定类型实现扩展（如前面所述的GWT Trees扩展）。每种类型都有它的特定要求。以下是一些到支持类型的快速链接

按钮支持

为了使Squish能够识别自定义按钮控件，必须定义一个合适的自定义typeOf函数并将其注册到一个扩展中，使用Squish.addTypeOfHook(function)函数。注册的函数应该返回形式为"custom_button_name"的字符串（例如，"custom_button_CustomButton"）。

除了注册钩子函数之外，扩展还必须提供一个名为nameExtension的JavaScript对象（例如，CustomButtonExtension）。此类对象必须提供以下方法

click(buttonElement) — 模拟按钮点击；这应使用Squish.mouseClick(objectOrName)函数或适当的Squish.clickButton(buttonElement)函数。
getText(buttonElement) — 返回按钮的文本
getTooltip(buttonElement) — 返回按钮的工具提示文本（可能为空）
getValue(buttonElement) — 返回按钮元素的数据值
isDisabled(buttonElement) — 如果按钮元素已禁用，则返回true；否则（即，如果按钮元素已启用），则返回false
isTextShown(buttonElement) — 如果按钮显示文本，则返回true；如果按钮显示图像，则返回false
setDisabled(buttonElement, disable) — 如果disable为false，则启用按钮元素；否则禁用它
setText(buttonElement, text) — 将按钮的文本设置为给定的text
setTextShown(buttonElement, showText) — 如果showText为true，则将按钮设置为显示文本（取自其text属性）；否则将按钮设置为显示图像
setTooltip(buttonElement, tip) — 将按钮的工具提示设置为给定的tip文本
setValue(buttonElement, value) — 将按钮元素的数据值更改为给定的value

此外，扩展可以实施一个使用Squish.addEventToStringHook(function)函数的事件到字符串钩子。此函数应该确保在返回的字符串中添加value参数并包含文本字段的值。

另请参阅Squish.clickButton(buttonElement)函数、HTML_CustomButtonBase类和HTML_CustomButton类。

组合框支持

为了使Squish能够识别自定义组合框，必须定义一个合适的自定义typeOf函数并将其注册到一个扩展中，使用Squish.addTypeOfHook(function)函数。注册的函数应该返回形式为"custom_combobox_name"的字符串（例如，"custom_combobox_CustomComboBox"）。

除了注册钩子函数之外，扩展还必须提供一个名为nameExtension的JavaScript对象（例如，CustomComboBoxExtension）。此类对象必须提供以下方法

hasOption(comboboxElement, optionValue) — 如果给定的组合框元素具有给定optionValue的条目，则返回true
getSelectedOption(comboboxElement) — 返回组合框元素的当前选中项
setSelectedOption(comboboxElement, optionValue) — 在给定的组合框元素中选中给定的optionValue

除了上述内容外，扩展还应使用 Squish.addEventToStringHook(function) 函数实现一个字符串钩子事件。该函数应确保将选项值参数添加到返回的字符串中，并且它包含组合框当前选中项的值。

此外，如果组合框不生成“change”事件，还应使用 Squish.addEventTypeHook(function) 函数实现一个事件类型钩子。对于此类组合框，扩展可以挂钩到鼠标事件等类似事件，并在钩子函数中返回 "change"。这对于记录很重要，因为当Squish看到一个带有值参数的 change-event 时，它将记录对 selectOption(objectOrName, text) 函数的调用而不是通用的鼠标点击。

另见 HTML_CustomComboBox 类。

日历事件支持

要使Squish能够识别自定义日历事件，必须使用 Squish.addTypeOfHook(function) 函数定义并注册一个适当的自定义 typeOf 函数在扩展中。已注册的函数应返回形如 "calendarevent_name"（例如，"calendarevent_CustomCalendarEvent"）的字符串。

除了注册钩子函数外，扩展还必须提供一个名为 nameExtension 的JavaScript对象（例如，CustomCalendarEventExtension）。此对象必须提供以下方法

getDescription(calendarEventElement) - 返回日历事件的说明文本或 undefined 如果没有则无。
getEndDateTime(calendarEventElement) - 返回一个JavaScript Date 对象，包含日历事件的结束日期/时间。
getStartDateTime(calendarEventElement) - 返回一个JavaScript Date 对象，包含日历事件的开始日期/时间。
getTitle(calendarEventElement) - 返回日历事件的标题文本。
setDescription(calendarEventElement, text) - 将日历事件的说明设置为给定的 text。
setEndDateTime(calendarEventElement, jsDate) - 将日历事件的结束日期/时间设置为给定的 jsDate（必须是JavaScript Date 对象）。
setStartDateTime(calendarEventElement, jsDate) - 将日历事件的开始日期/时间设置为给定的 jsDate（必须是JavaScript Date 对象）。
setTitle(calendarEventElement, text) - 将日历事件的标题设置为给定的 text。

另见，HTML_CalendarEvent 类和 HTML_CalendarView 类。

日历视图支持

要使Squish能够识别自定义日历视图控件，必须定义一个适当的自定义 typeOf 函数，并使用 Squish.addTypeOfHook(function) 函数在扩展中进行注册。注册的函数应返回形如 "calendarview_name"（例如，"calendarview_CustomCalendarView"）的字符串。

除了注册钩子函数外，扩展还必须提供一个名为 nameExtension 的JavaScript对象（例如，CustomCalendarViewExtension）。此对象必须提供以下方法。

getVisibleEventCount(calendarViewElement) — 返回日历视图中可见的 HTML_CalendarEvent 类的数量。
getVisibleEventAt(calendarViewElement, index) — 返回日历视图中索引为 index 的可见 HTML_CalendarEvent 类。
getDate(calendarViewElement) — 返回日历视图中当前选中的日期时间，作为 JavaScript 的 Date 对象。
setDate(calendarViewElement, jsDate) — 设置日历视图的当前日期时间（即显示的日期时间）为给定的 jsDate，它必须是一个 JavaScript Date 对象。

另见，HTML_CalendarEvent 类和 HTML_CalendarView 类。

复选框支持

为了使 Squish 识别自定义复选框，必须在扩展中使用 Squish.addTypeOfHook(function) 函数定义并注册一个合适的自定义 typeOf 函数。注册的函数应返回形式为 "custom_checkbox_name" 的字符串（例如，"custom_checkbox_CustomCheckBox"）。

除了注册钩子函数，扩展还必须提供一个名为 nameExtension 的 JavaScript 对象（例如，CustomCheckBoxExtension）。此对象必须提供以下方法

isChecked(checkboxElement) — 返回元素是否被选中。
setChecked(checkboxElement, checked) — 如果 checked 是 true，则选中该元素；否则取消选中。

另请参阅 HTML_CustomCheckbox 类。

颜色选择器支持

为了使 Squish 识别自定义颜色选择器小部件，必须在扩展中使用 Squish.addTypeOfHook(function) 函数定义并注册一个合适的自定义 typeOf 函数。注册的函数应返回形式为 "colorfield_name" 的字符串（例如，"colorfield_CustomColorPicker"）。

除了注册钩子函数，扩展还必须提供一个名为 nameExtension 的 JavaScript 对象（例如，CustomColorPickerExtension）。此对象必须提供以下方法

getFieldName(colorFieldElement, fieldName) — 返回颜色字段元素的标签，如果没有则返回空字符串
getRgbColor(colorFieldElement) — 返回颜色字段元素的 HTML 格式颜色（即，"#RRGGBB"）
isEnabled(colorFieldElement) — 返回颜色字段元素是否已启用
setEnabled(colorFieldElement, enabled) — 如果 enabled 为 true，则启用颜色字段元素；否则禁用它
setFieldName(colorFieldElement, fieldName) — 将颜色字段的标签设置为给定的 fieldName
setRgbColor(colorFieldElement, htmlRGBvalue) — 将颜色字段的颜色设置为给定的 htmlRGBvalue（它必须是形式为 "#RRGGBB" 的 HTML 颜色字符串）

除了上述内容外，还应使用 Squish.addEventToStringHook(function) 函数实现事件到字符串的钩子。这个函数应该返回记录 chooseColor(objectOrName, htmlRGBvalue) 函数调用的必要信息，至少应提供颜色本身（以HTML形式，即 "#RRGGBB"），以及可选的标签。指定标签对于事件发生对象不是颜色字段（例如，颜色选择器的确定按钮）的情况很有用，这允许忽略与颜色对话框的交互。

此外，还应使用 Squish.addEventTypeHook(function) 函数实现事件类型钩子。这个函数应返回选择颜色的事件类型（例如，如果通过输入或点击颜色或通过点击颜色选择器的确定按钮来选择颜色），或者在应该不记录与颜色选择器交互的情况下返回 chooseColorIncomplete 事件类型。

请参阅 chooseColor(objectOrName, htmlRGBvalue) 函数和 HTML_ColorField 类。

日期选择器支持

为了使 Squish 识别自定义日期选择器小部件，必须使用 Squish.addTypeOfHook(function) 函数定义并注册一个合适的自定义 typeOf 函数。注册的函数应返回形式为 "datechooser_name" 的字符串（例如，"datechooser_CustomDatePicker"）。

除了注册钩子函数外，扩展还必须提供名为 nameExtension 的 JavaScript 对象（例如，CustomDatePickerExtension）。该对象必须为可展开部分标题小部件提供以下方法

getDate(dateChooserElement) — 以 JavaScript Date 对象的形式返回日期选择器元素的当前日期。
setDate(dateChooserElement, jsDate) — 将日期选择器元素的当前日期设置为给定的日期。 jsDate 是一个 JavaScript Date 对象。

除了上述内容外，还应使用 Squish.addEventToStringHook(function) 函数实现事件到字符串的钩子。该函数应返回记录由 String Squish.createChooseDateInformation(jsDate) 函数返回的 chooseDate(objectOrName, date) 函数调用的必要信息。

也可以使用 Squish.addEventTypeHook(function) 函数实现事件类型钩子。当点击日期选择器用于导航（例如，改变年份或月份）而不是实际选择日期时，此钩子应返回特殊的 "ignoreEvent" 类型。

请参阅 chooseDate(objectOrName, date) 函数和 HTML_DateChooser 类。

可展开部分标题支持

可展开部分有时也称为“手风琴”或“工具箱”。

为了使 Squish 识别自定义可展开部分标题小部件，必须定义并使用 Squish.addTypeOfHook(function) 函数在扩展中注册一个合适的自定义 typeOf 函数。注册的函数应返回形式为 "expandablesectionheader_name" 的字符串（例如，"expandablesectionheader_CustomAccordion"）。

除了注册钩子函数外，扩展还必须提供名为 nameExtension 的 JavaScript 对象（例如，CustomAccordionExtension）。该对象必须为可展开部分标题小部件提供以下方法

click(headerElement) — 点击头部元素并切换其状态（即展开未展开的头部，或展开已展开的头部）
getTitle(headerElement) — 返回头部元素的标题文本
isEnabled(headerElement) — 返回头部元素是否启用
isExpanded(headerElement) — 返回头部元素是否展开
setEnabled(headerElement, enable) — 如果 enabled 为 true，则启用头部元素；否则禁用它
setExpanded(headerElement, expand) — 如果 expand 为 true，则展开头部元素；否则取消展开
setTitle(headerElement, title) — 将头部元素的标题文本设置为给定的 title 文本

另请参阅函数 toggleExpandable(objectOrName) 和类 HTML_ExpandableSectionHeader .

为了让 Squish 识别菜单或菜单栏小部件，必须定义一个合适的自定义 typeOf 函数，并使用 Squish.addTypeOfHook(function) 函数在扩展中注册。注册的函数应返回形式为 "menu_name" 的字符串（例如，"menu_CustomMenu"）。

除了注册钩子函数外，扩展还必须提供一个名为 nameExtension 的 JavaScript 对象（例如，CustomMenuExtension）。该对象必须为菜单小部件提供以下方法

findItemByIconUrl(menuElement, iconUrl) — 返回具有给定 iconUrl 的菜单项的 HTML 菜单项元素。
findItemByText(menuElement, text) — 返回具有给定 text 的菜单项的 HTML 菜单项元素。
getMenuItemAt(menuElement, index) — 返回给定 index 位置的 HTML 菜单项元素。
getMenuItemCount(menuElement) — 返回给定 menuElement 中 HTML 菜单项元素的数量。

除了上述功能外，扩展还应该使用 Squish.addEventToStringHook(function) 函数实现事件到字符串钩子。该函数应返回记录 clickItem(objectOrName, itemText) 函数调用所需的信息，该函数调用通过 String Squish.createClickItemInformationForMenuItem(menuElement, menuText) 函数返回。 (如果没有钩子函数，则不会记录对 clickItem(objectOrName, itemText) 函数的调用。)

另请参阅菜单项支持、函数 String Squish.createClickItemInformationForMenuItem(menuElement, menuText) 和类 HTML_Menu。

为了让 Squish 识别菜单按钮小部件，必须定义一个合适的自定义 typeOf 函数，并使用 Squish.addTypeOfHook(function) 函数在扩展中注册。注册的函数应返回形式为 "menubutton_name" 的字符串（例如，"menubutton_CustomMenuButton"）。

除了注册钩子函数外，扩展还必须提供一个名为 nameExtension 的 JavaScript 对象（例如，CustomMenuButtonExtension）。该对象必须为菜单按钮小部件提供以下方法

getMenu(menuButtonElement) —— 返回与给定 menuButtonElement 相关的 HTML 菜单元素，如果没有则返回 undefined。

另请参阅 HTML_MenuButton 类。

为了使 Squish 能够识别菜单项，必须在扩展程序中定义并注册一个合适的自定义 typeOf 函数，使用 Squish.addTypeOfHook(function) 函数。注册的函数应返回形式为 "menuitem_name" 的字符串（例如，"menuitem_CustomMenuItem"）。

除了注册钩子函数外，扩展程序还必须提供一个名为 nameExtension（例如，CustomMenuItemExtension）的 JavaScript 对象。该对象必须为菜单项提供以下方法：

getMenuItemIconUrl(menuItemElement) —— 返回此菜单项元素的图标 URL，如果没有图标则返回 undefined。
getMenuItemText(menuItemElement) —— 返回此菜单项元素的文本。
getParentMenu(menuItemElement) —— 返回此菜单项元素的父菜单。
getSubMenu(menuItemElement) —— 返回此菜单项元素的子菜单，如果没有则返回 undefined。
isMenuItemChecked(menuItemElement) —— 返回此菜单项元素是否被选中。
isMenuItemEnabled(menuItemElement) —— 返回此菜单项元素是否启用。
isMenuItemSeparator(menuItemElement) —— 返回此菜单项元素是否仅为分隔符。
setMenuItemChecked(menuItemElement, check) —— 如果 check 为 true，则选中此菜单项；否则取消选中。
setMenuItemEnabled(menuItemElement, enable) —— 如果 enable 为 true，则启用此菜单项；否则禁用。
setMenuItemIconUrl(menuItemElement, iconUrl) —— 将此菜单项的图标 URL 设置为给定的 iconUrl。
setMenuItemSeparator(menuItemElement, separator) —— 如果 separator 为 true，则将此菜单项设置为分隔符；否则将其设为普通菜单项。
setMenuItemText(menuItemElement, text) —— 将此菜单项的文本设置为给定的 text。

另请参阅菜单支持、Squish.createClickItemInformationForMenuItem(menuElement, menuText) 函数以及 HTML_MenuItem 类。

进度条支持

为了使 Squish 能够识别进度条小部件，必须在扩展程序中定义并注册一个合适的自定义 typeOf 函数，使用 Squish.addTypeOfHook(function) 函数。注册的函数应返回形式为 "progressbar_name" 的字符串（例如，"progressbar_CustomProgressBar"）。

除了注册钩子函数外，扩展程序还必须提供一个名为 nameExtension（例如，CustomProgressBarExtension）的 JavaScript 对象。该对象必须为进度条小部件提供以下方法：

getMaximum(progressBarElement) —— 返回与进度条最大值对应的整数。
getMinimum(progressBarElement) —— 返回与进度条最小值对应的整数。
getValue(progressBarElement) —— 返回与进度条显示进度量对应的整数。
setValue(progressBarElement, value) — 将进度条的值设置为给定的value，该值应在进度条的最小值和最大值之间，包括最小值和最大值

参阅HTML_ProgressBar类。

单选按钮支持

为了使Squish能够识别自定义单选按钮，必须定义并注册一个合适的自定义typeOf函数，并使用Squish.addTypeOfHook(function)函数在扩展中注册。注册的函数应返回形式为"custom_radiobutton_name"的字符串（例如，"custom_radiobutton_CustomRadioButton"）。

除了注册钩子函数之外，扩展还必须提供一个名为nameExtension（例如，CustomRadioButtonExtension）的JavaScript对象。此对象必须提供以下方法

isSelected(radiobuttonElement) — 返回元素是否被选中（勾选）。
setSelected(radiobuttonElement, selected) — 如果selected为true，选中（勾选）元素；否则取消选中（取消勾选）它。

参阅HTML_CustomRadioButton类。

选择列表支持

为了使Squish能够识别自定义选择列表，必须定义并注册一个合适的自定义typeOf函数，并使用Squish.addTypeOfHook(function)函数在扩展中注册。注册的函数应返回形式为"custom_selectlist_name"的字符串（例如，"custom_selectlist_CustomSelectList"）。

除了注册钩子函数之外，扩展还必须提供一个名为nameExtension（例如，CustomSelectListExtension）的JavaScript对象。此对象必须提供以下方法

hasOption(selectlistElement, optionValue) — 如果指定选择列表元素具有给定optionValue的条目，则返回true。
getSelectedOptions(selectlistElement) — 返回使用说明中的格式描述的选择列表元素当前选中的条目HTML_CustomSelectList.selectedOptions属性。
setSelectedOption(selectlistElement, multioptionString) — 将当前选项字符串替换为给定multioptionString，该字符串的格式与HTML_CustomSelectList.selectedOptions属性中描述的格式相同。

除了上述内容外，扩展还应该实现使用Squish.addEventToStringHook(function)函数的事件到字符串钩子。此函数应确保将 "value" 参数添加到返回的字符串中，并包含选择列表中当前选中条目的值或包含所有选中条目的值的字符串。对于后者，可以使用ArrayOfStrings Squish.getSelectedOptionTexts(selectElement)函数。

此外，如果选择列表不生成 "change" 事件，扩展还应实现使用Squish.addEventTypeHook(function)函数的事件类型钩子。对于此类选择列表，扩展可以钩入鼠标事件或类似事件，并通过钩子函数返回"change"。这对于记录非常重要，因为当Squish看到一个带有值参数的change-event时，它将记录一个对selectOption(objectOrName, text)函数的调用，而不是通用鼠标点击。

另请参阅 HTML_CustomSelectList 类。

为了让 Squish 识别自定义标签小部件，必须在扩展中使用 Squish.addTypeOfHook(function) 函数定义并注册一个合适的自定义 typeOf 函数。已注册的函数应返回一个字符串，其形式为 "tabwidget_name"（例如，"tabwidget_CustomWidgets"）表示标签小部件本身，以及表示单独标签的 "tabitem_name"。

除了注册钩子函数外，扩展还必须提供一个名为 nameExtension（例如，CustomWidgetsExtension）的 JavaScript 对象。此对象必须为标签小部件提供以下方法

clickTab(tabWidgetElement, tabTitle) — 如果存在具有指定标题文本的标签，则点击指定的标签小部件的标签。
getCurrentTab(tabWidgetElement) — 返回给定标签小部件当前选中（即最顶层）的标签元素
findTab(tabWidgetElement, tabTitle) — 如果存在，则返回给定标签小部件的标题为指定标签的标签

由 getCurrentTab 和 findTab 方法返回的标签元素必须提供以下方法

getIcon(tabElement) — 返回标签元素的图标 URL 或空字符串（如果没有图标）
getTitle(tabElement) — 返回标签元素的标题文本
isEnabled(tabElement) — 返回标签元素是否启用
setEnabled(tabElement, enabled) — 如果 enabled 为 true，则启用标签元素；否则禁用它
setIcon(tabElement, iconUrl) — 将标签元素的图标 URL 设置为指定的 iconUrl
setTitle(tabElement, tabTitle) — 将标签元素的标题文本设置为指定的 tabTitle 文本

除此之外，扩展还应实现使用 Squish.addEventToStringHook(function) 函数的事件到字符串钩子。此函数应返回记录 clickTab(objectOrName, tabTitle) 函数调用的必要信息，如由 String Squish.createClickTabInformation(tabWidgeElement, tabTitle) 函数返回的信息。（如果没有钩子函数，则不会记录对 clickTab(objectOrName, tabTitle) 函数的调用。）

另请参阅 clickTab(objectOrName, tabTitle) 函数和 String Squish.createClickTabInformation(tabWidgeElement, tabTitle) 函数，以及 HTML_Tab 类和 HTML_TabWidget 类。

文本字段支持

为了让 Squish 识别自定义文本字段，必须使用 Squish.addTypeOfHook(function) 函数在扩展中定义并注册一个合适的自定义 typeOf 函数。注册的函数应返回一个形式为 "customtext_name"（例如，"customtext_CustomTextField"）的字符串。

除了注册钩子函数外，扩展还必须提供一个名为 nameExtension（例如，CustomTextFieldExtension）的 JavaScript 对象。此对象必须提供以下方法

getValue(textFieldElement) — 返回元素的当前文本。
setFocus(textFieldElement) — 将键盘焦点移动到指定的 textFieldElement。
setValue(textFieldElement, text) — 将文本字段元素的当前文本设置为指定的文本。

除了上述内容外，扩展还应实现使用函数的事件到字符串钩子。此函数应确保将“value”参数添加到返回的字符串，并包含文本字段的值。

另请参阅HTML_CustomText类。

Tk Windows

©2024 The Qt Company Ltd. 本文档的文档贡献为其各自所有者的版权。
本提供的文档是根据Free Software Foundation发布的GNU自由文档许可版本1.3许可的。
Qt及其相关标志是芬兰及全球其他地区的The Qt Company Ltd.的商标。所有其他商标均为其各自所有者的财产。