基本类型对象

在上一篇中我们了解了CukeTest中的容器类和控件基类，接下来就是针对各种不同的控件类的API介绍了。本篇文章中将介绍以下几个基础的控件类：

按钮控件: Button
窗口控件: Window
输入框控件: Edit/Document/Text/Spinner
单选按钮控件: RadioButton
复选框控件: CheckBox
组合框: ComboBox
选值框: Spinner
滚动条控件: ScrollBar
图片: Image
超链接: Hyperlink
滑动条控件: Slider
菜单相关的控件和菜单栏选项控件: MenuBar & Menu & MenuItem
标签栏控件和标签页控件: Tab & TabItem

由于各个控件类因为是继承自IWintControl，因此每个控件类都拥有通用控件的所有操作和属性方法。以CheckBox控件类举例：

CheckBox控件有一个操作方法——toggleCheck()用于设置勾选状态; 一个属性方法checkState()用于判断CheckBox的勾选状态。true表示勾选，false代表未勾选，indeterminate代表中间状态:

JavaScript

Python

export interface IWinCheckBox extends IWintControl {    
	toggleCheck(checkState: boolean | 'indeterminate'): Promise<void>
	checkState(): Promise<boolean | 'indeterminate'>
}

class WinCheckBox(WinControl):
	def check(checked: bool) -> None
	def checkState() -> Union[bool, str]
	def toggleCheck(checkState: Union[bool, str]) -> None

但实际上CheckBox除了这两个方法，还从IWintControl基类继承了所有的方法，所以CheckBox的方法实际上应该包含了基类的方法：

JavaScript

export interface IWinCheckBox extends IWintControl {
	
	// CheckBox的操作方法
	toggleCheck(checkState: boolean): Promise<void>
	// 继承自基类的操作方法
	click(x?: number, y?: number, mousekey?: MouseKey): Promise<void>;
	dblClick(x?: number, y?: number, mousekey?: MouseKey): Promise<void>;
	moveMouse(x?: number, y?: number, seconds?: number): Promise<void>
	wheel(value: number): Promise<void>;
	exists(time?: number): Promise<boolean>;
	hScroll(value: number | ScrollAmount): Promise<void>;
	vScroll(value: number | ScrollAmount): Promise<void>;
	property(propertyIds: PropertyIds | string): Promise<string | boolean | number | Rect>;
	checkImage(options?: CompareOptions): Promise<void>;
	checkProperty(propertyName: string, expectedValue: string | number | boolean | RegExp, message: string): Promise<void>;
	checkProperty(propertyName: string, expectedValue: string | number | boolean | RegExp, options: {message: string, operation: any}): Promise<void>;
	waitProperty(propertyIds: PropertyIds, value: string, timeoutSeconds?: number/* default value 5 seconds */): Promise<boolean>;
	drop(x?: number, y?: number, seconds?: number): Promise<void>;
	drag(x?: number, y?: number): Promise<void>;
	pressKeys(keys: string, opt?: PressKeysOptions | number): Promise<void>;
	takeScreenshot(filePath?: string): Promise<void | string>;
	highlight(duration?: number);
	firstChild(controlType?: ControlType): Promise<IWinControl>;
	lastChild(controlType?: ControlType): Promise<IWinControl>;
	next(controlType?: ControlType): Promise<IWinControl>;
	previous(controlType?: ControlType): Promise<IWinControl>;
	parent(): Promise<IWinControl>;
	all(): Promise<IWinControl[]>;
	findControls(...conditions: ConditionFilter[]): Promise<IWinControl[]>; //used to be getControls
	modelImage(options?: {encoding: 'buffer' | 'base64'}): Promise<string | Buffer>;  //base64 is the default
	modelProperties(all?: boolean): {[x: string]: any};
	allProperties(): Promise<object>;
	doDefaultAction(): Promise<void>;
	rawText(): Promise<string>

	// CheckBox的属性
	checkState(): Promise<boolean>
	// 继承自基类的属性方法
	type(): Promise<string>;
	text(): Promise<string>;
	name(): Promise<string>;
	hwnd(): Promise<number>;
	x(): Promise<number>;
	y(): Promise<number>;
	height(): Promise<number>;
	width(): Promise<number>;
	enabled(): Promise<boolean>;
	focused(): Promise<boolean>;
	helpText(): Promise<string>;
	labeledText(): Promise<string>;
	value(): Promise<string | number>;
	processId(): Promise<number>;
	rect(): Promise<Rect>;
	visible(): Promise<boolean>;
}

如果一个对象不包含任何操作和属性方法，代表它只适用其基类——也就是IWintControl和IWintContainer中的操作和属性方法而没有自己特有的，比如Button控件。

基础控件类介绍

按钮控件: Button

针对普通的按钮控件，模型管理器提供了Button对象类型。

JavaScript

Python

export interface IWinButton extends IWintControl {

}

class WinButton(WinControl):
	...

由于Button控件的操作和属性方法与基类IWintControl的一致，没有自己特有的方法，因此为空。它的操作方法可以参考基类方法介绍。

窗口控件: Window

针对应用窗口控件，模型管理器提供了Window对象类型。

方法名	描述
activate	激活目标窗口，使目标窗口出现在桌面最上层。
close	关闭目标窗口。
maximize	最大化目标窗口。
minimize	最小化目标窗口。
restore	恢复目标窗口到正常状态。
isModal	获取指定窗口是否为模态窗口的值。
interactionState	获取窗口的交互状态。
visualState	获取当前窗口的视觉状态。

JavaScript

Python

export interface IWinWindow extends IWintControl {
	activate(): Promise<void>;
	close(): Promise<void>;
	maximize(): Promise<void>;
	minimize(): Promise<void>;
	restore(): Promise<void>;
	isModal(): Promise<boolean>;
	interactionState(): Promise<string>;
	visualState(): Promise<string>;
}

class WinWindow(WinControl):
	def activate() -> None
	def close() -> None
	def maximize() -> None
	def minimize() -> None
	def restore() -> None
	def isModal() -> bool
	def interactionState() -> str
	def visualState() -> str

activate()

激活目标窗口，使目标窗口出现在桌面最上层，避免被其它窗口遮盖。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 激活记事本窗口，使其显示在最前面
await model.getWindow("记事本").activate();

# 激活记事本窗口，使其显示在最前面
model.getWindow("记事本").activate()

close()

关闭目标窗口。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 关闭记事本窗口
await model.getWindow("记事本").close();

# 关闭记事本窗口
model.getWindow("记事本").close()

maximize()

最大化目标窗口。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 最大化记事本窗口
await model.getWindow("记事本").maximize();

# 最大化记事本窗口
model.getWindow("记事本").maximize()

minimize()

最小化目标窗口。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 最小化记事本窗口
await model.getWindow("记事本").minimize();

# 最小化记事本窗口
model.getWindow("记事本").minimize()

restore()

恢复目标窗口。当目标最小化以后可以使用这个方法恢复为正常状态。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 先最小化窗口
await model.getWindow("记事本").minimize();
// 然后恢复窗口到正常状态
await model.getWindow("记事本").restore();

# 先最小化窗口
model.getWindow("记事本").minimize()
# 然后恢复窗口到正常状态
model.getWindow("记事本").restore()

isModal()

获取指定窗口是否为模态窗口的值。isModal返回false不一定代表窗口不是模态窗口，推荐使用interactionState来判断。

返回值:

boolean类型，异步返回布尔值（true或false），表示窗口是否为模态窗口。如果返回值为true，则表示该窗口是一个模态窗口；如果返回值为false，则表示该窗口可能不是一个模态窗口。

使用示例

JavaScript

Python

// 检查文件资源管理器窗口是否为模态窗口
let isModal = await model.getWindow("文件资源管理器").isModal();
console.log(`窗口是否为模态: ${isModal}`);

# 检查文件资源管理器窗口是否为模态窗口
is_modal = model.getWindow("文件资源管理器").isModal()
print(f"窗口是否为模态: {is_modal}")

interactionState()

表示窗口的交互状态。

返回值:

string类型，返回值可以是这些:
- Running：窗口正在运行。这并不保证窗口已经准备好进行用户交互或正在响应。
- ReadyForUserInteraction：窗口已经准备好进行用户交互。
- BlockedByModalWindow：窗口被模态窗口阻塞。
- Closing：窗口正在关闭。
- NotResponding：窗口没有响应。

使用示例

JavaScript

Python

// 检查窗口的交互状态
let state = await model.getWindow("记事本").interactionState();
console.log(`窗口交互状态: ${state}`);

# 检查窗口的交互状态
state = model.getWindow("记事本").interactionState()
print(f"窗口交互状态: {state}")

visualState()

表示当前窗口的视觉状态。

返回值:

string类型，Minimized、Maximized或Normal。

使用示例

JavaScript

Python

// 获取窗口的视觉状态
let state = await model.getWindow("记事本").visualState();
console.log(`窗口视觉状态: ${state}`);

# 获取窗口的视觉状态
state = model.getWindow("记事本").visualState()
print(f"窗口视觉状态: {state}")

综合示例

在Windows环境中打开记事本，菜单栏点击【文件】选择【打开】来打开文件资源管理器窗口：

JavaScript

Python

let isModal;
let interactionState;
let visualState;

// 检查文件资源管理器是否为模态窗口
isModal = await model.getWindow("文件资源管理器").isModal();
console.log(isModal); // 返回true

// 检查文件资源管理器的交互状态
interactionState = await model.getWindow("文件资源管理器").interactionState();
console.log(interactionState); // 返回 ReadyForUserInteraction

// 检查记事本的交互状态（被模态窗口阻塞）
interactionState = await model.getWindow("记事本").interactionState();
console.log(interactionState); // 返回 BlockedByModalWindow

// 检查文件资源管理器的视觉状态
visualState = await model.getWindow("文件资源管理器").visualState();
console.log(visualState); // 返回 Normal

# 检查文件资源管理器是否为模态窗口
is_modal = model.getWindow("文件资源管理器").isModal()
print(is_modal)  # 返回True

# 检查文件资源管理器的交互状态
interaction_state = model.getWindow("文件资源管理器").interactionState()
print(interaction_state)  # 返回 ReadyForUserInteraction

# 检查记事本的交互状态（被模态窗口阻塞）
interaction_state = model.getWindow("记事本").interactionState()
print(interaction_state)  # 返回 BlockedByModalWindow

# 检查文件资源管理器的视觉状态
visual_state = model.getWindow("文件资源管理器").visualState()
print(visual_state)  # 返回 Normal

输入框控件: Edit与Document

针对用于接收用户输入的输入框控件Edit，而多行输入框有时为Document。提供的操作方法和属性方法都是针对输入框中的值。

方法名	描述
set	设置输入框中的值。
clearAll	清除输入框中的值。
readOnly	检查当前输入框是否为只读。

JavaScript

Python

export interface IWinEdit extends IWintControl {
	set(value: string): Promise<void>;
	clearAll(): Promise<void>;
	readOnly(): Promise<boolean>;
}
export interface IWinDocument extends IWinControl {
	set(value: string): Promise<void>;
	clearAll(): Promise<void>;
	readOnly(): Promise<boolean>;
}

class WinEdit(WinControl):
	def set(value: str) -> None
	def clearAll() -> None
	def readOnly() -> bool
class WinDocument(WinControl):
	def set(value: str) -> None
	def clearAll() -> None
	def readOnly() -> bool

另外，文本框控件Text和容器控件Pane在一些情况下也是可编辑的，因此也提供了set方法，用法与Edit、Document一致。

JavaScript

Python

export interface IWinText extends IWinControl {
	set(value: string): Promise<void>;
}
export interface IWinPane extends IWinControl {
	set(value: string): Promise<void>;
}

class WinText(WinControl):
	def set(value: str) -> None
class WinPane(WinControl):
	def set(value: str) -> None

set(value)

设置输入框中的值。将目标输入框中的值替换为传入的字符串。

参数:

value: string类型，期望写入到输入框的值。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 在用户名输入框中输入文本
await model.getEdit("用户名").set("admin");

# 在用户名输入框中输入文本
model.getEdit("用户名").set("admin")

clearAll()

清除输入框中的值。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 清空输入框内容
await model.getEdit("用户名").clearAll();

# 清空输入框内容
model.getEdit("用户名").clearAll()

readOnly()

当前输入框是否为只读。只读返回true，可读写返回false。

返回值:

boolean类型，异步返回输入框是否为只读状态。

使用示例

JavaScript

Python

// 检查输入框是否为只读
let isReadOnly = await model.getEdit("用户名").readOnly();
if (!isReadOnly) {
	// 如果不是只读，则可以输入内容
	await model.getEdit("用户名").set("admin");
}

# 检查输入框是否为只读
is_read_only = model.getEdit("用户名").readOnly()
if not is_read_only:
	# 如果不是只读，则可以输入内容
	model.getEdit("用户名").set("admin")

单选按钮控件: RadioButton

针对单选按钮的RadioButton控件，按照使用逻辑提供了选中和获取选中状态的方法。

方法名	描述
check	选中目标单选按钮。
checked	获取目标单选按钮的选中状态。

JavaScript

Python

export interface IWinRadioButton extends IWintControl {
	check(): Promise<void>;
	checked(): Promise<boolean>;
}

class WinRadioButton(WinControl):
	def checked() -> Union[bool, str]
	def check() -> None

check()

选中目标单选按钮。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 选中"男"单选按钮
await model.getRadioButton("男").check();

# 选中"男"单选按钮
model.getRadioButton("男").check()

checked()

获取目标单选按钮的选中状态，true代表已选中，false代表未选中。

返回值:

boolean类型，异步返回目标单选按钮是否选中。

使用示例

JavaScript

Python

// 检查单选按钮是否被选中
let isChecked = await model.getRadioButton("男").checked();
console.log(`单选按钮是否选中: ${isChecked}`);

# 检查单选按钮是否被选中
is_checked = model.getRadioButton("男").checked()
print(f"单选按钮是否选中: {is_checked}")

复选框控件: CheckBox

针对复选框控件的CheckBox控件，能够直接设定选中状态，当然也可以获取状态。

方法名	描述
toggleCheck	设置目标复选框的选中状态。
checkState	获取目标复选框的选中状态。

JavaScript

Python

export interface IWinCheckBox extends IWintControl {
	toggleCheck(checkState: boolean | 'indeterminate'): Promise<void>
	checkState(): Promise<boolean | 'indeterminate'>
}

class WinCheckBox():
	def check(checked: bool) -> None
	def checkState() -> Union[bool, str]
	def toggleCheck(checkState: Union[bool, str]) -> None

checkState是为了Windows复选框创建的类，支持的值有true|false|'indeterminate'三种，true代表选中复选框，false代表取消选中目标复选框。'indeterminate'代表中间值。因为Windows复选框有时候存在三种状态，无法直接用布尔型boolean表示。

toggleCheck(checkState)

设置目标复选框的选中状态。

参数:

checkState: boolean | 'indeterminate'类型，true代表选中，false代表取消选中，'indeterminate'代表中间状态。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 选中复选框
await model.getCheckBox("记住密码").toggleCheck(true);

// 取消选中复选框
await model.getCheckBox("记住密码").toggleCheck(false);

// 设置为中间状态（如果支持）
await model.getCheckBox("全选").toggleCheck('indeterminate');

# 选中复选框
model.getCheckBox("记住密码").toggleCheck(True)

# 取消选中复选框
model.getCheckBox("记住密码").toggleCheck(False)

# 设置为中间状态（如果支持）
model.getCheckBox("全选").toggleCheck('indeterminate')

checkState()

获取目标复选框的选中状态。

返回值:

boolean | 'indeterminate'类型，异步返回复选框的状态。

使用示例

JavaScript

Python

// 获取复选框的状态
let state = await model.getCheckBox("记住密码").checkState();
if (state === true) {
	console.log("复选框已选中");
} else if (state === false) {
	console.log("复选框未选中");
} else {
	console.log("复选框处于中间状态");
}

# 获取复选框的状态
state = model.getCheckBox("记住密码").checkState()
if state == True:
	print("复选框已选中")
elif state == False:
	print("复选框未选中")
else:
	print("复选框处于中间状态")

组合/下拉框: ComboBox

针对带下拉框的一类特殊输入框的ComboBox控件，提供了选择指定下拉选项的操作方法。

方法名	描述
open	展开下拉框。
select	选择下拉框中的指定选项。
selectedName	获取当前选中的值。
options	获取目标组合框中所有可选选项的名称。
itemCount	获取目标组合框中所有可选选项的数量。

JavaScript

Python

export interface IWinComboBox extends IWintControl {
	open(): Promise<void>;
	select(nameOrIndex: String | number): Promise<void>;
	options(index: number): Promise<string | string[]>;
	itemCount(): Promise<number>;
	selectedName(): Promise<string>;
}

class WinComboBox(WinControl):
	def options(index: Optional[int]=None) -> Union[str, List[str]]
	def itemCount() -> int
	def selectedName() -> str
	def select(value: Union[str, int]) -> None
	def open() -> None

open()

展开下拉框，可以视作触发了目标右侧的▼按钮。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 展开下拉框
await model.getComboBox("城市选择").open();

# 展开下拉框
model.getComboBox("城市选择").open()

select(nameOrIndex)

选择下拉框中的指定选项。

参数:

nameOrIndex: number或string类型。如果为数字，则会选中下拉框中相应索引位置的选项；如果为字符串，则会选择下拉框中相应名称的选项。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 通过索引选择第一个选项
await model.getComboBox("城市选择").select(0);

// 通过名称选择选项
await model.getComboBox("城市选择").select("北京");

# 通过索引选择第一个选项
model.getComboBox("城市选择").select(0)

# 通过名称选择选项
model.getComboBox("城市选择").select("北京")

selectedName()

获取当前选中的值。

返回值:

string类型，异步返回当前选中的值。

使用示例

JavaScript

Python

// 获取当前选中的选项
let selected = await model.getComboBox("城市选择").selectedName();
console.log(`当前选中: ${selected}`);

# 获取当前选中的选项
selected = model.getComboBox("城市选择").selectedName()
print(f"当前选中: {selected}")

options()

获取目标组合框中所有可选选项的名称。

返回值:

string[]类型，异步返回所有可选选项的名称组成的字符串数组。

使用示例

JavaScript

Python

// 获取所有选项
let allOptions = await model.getComboBox("城市选择").options();
console.log(`可选项: ${allOptions.join(', ')}`);

# 获取所有选项
all_options = model.getComboBox("城市选择").options()
print(f"可选项: {', '.join(all_options)}")

itemCount()

获取目标组合框中所有可选选项的数量。可以理解为options()方法返回数组的长度。

返回值:

number类型，异步返回选项数量。

使用示例

JavaScript

Python

// 获取选项数量
let count = await model.getComboBox("城市选择").itemCount();
console.log(`总共有 ${count} 个选项`);

# 获取选项数量
count = model.getComboBox("城市选择").itemCount()
print(f"总共有 {count} 个选项")

选值框: Spinner

针对应用中带上下箭头的选值框Spinner控件，提供了与输入框Edit控件类似的输入、编辑和清空的方法。并另外提供了单步增加/减少值的操作API。

方法名	描述
set	设置输入框中的值。
clearAll	清除输入框中的值。
readOnly	检查当前输入框是否为只读。
increment	使取值框的值增加一个单位。
decrement	使取值框的值减少一个单位。

该控件的类型定义如下:

JavaScript

Python

export interface IWinSpinner extends IWinEdit {
	set(value: string): Promise<void>;
	clearAll(): Promise<void>;
	readOnly(): Promise<boolean>;
	increment(): Promise<void>;
	decrement(): Promise<void>;
}

class WinSpinner(WinControl):
	def set(value: str) -> None
	def clearAll() -> None
	def readOnly() -> bool
	def increment() -> None
	def decrement() -> None

set(value)

见set()方法。如果输入字符串会失效，因为控件只接受数值参数。

也可以使用pressKeys()方法完成输入。

clearAll()

见clearAll()方法。

readOnly()

见readOnly()方法。

increment()

使取值框的值增加一个单位，单位大小取决于应用中的设置。可以理解为触发了一次取值框中的上箭头。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 增加数值
await model.getSpinner("数量").increment();
// 连续增加多次
for (let i = 0; i < 5; i++) {
	await model.getSpinner("数量").increment();
}

# 增加数值
model.getSpinner("数量").increment()
# 连续增加多次
for i in range(5):
	model.getSpinner("数量").increment()

decrement()

使取值框的值减少一个单位，单位大小取决于应用中的设置。可以理解为触发了一次取值框中的下箭头。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 减少数值
await model.getSpinner("数量").decrement();
// 连续减少多次
for (let i = 0; i < 3; i++) {
	await model.getSpinner("数量").decrement();
}

# 减少数值
model.getSpinner("数量").decrement()
# 连续减少多次
for i in range(3):
	model.getSpinner("数量").decrement()

滑动条: Slider

用于滑动调整数值的滑动条控件。

方法名	描述
setPosition	调整滑动条的值。
position	获取滑动条的值。
maximum	获取滑动条的最大值。
minimum	获取滑动条的最小值。
readOnly	检查滑动条是否可调整。

JavaScript

export interface WinSlider extends WinControl {
	setPosition(value: number): Promise<void>;
	position(): Promise<number>;
	maximum(): Promise<number>;
	minimum(): Promise<number>;
	readOnly(): Promise<boolean>;
}

setPosition(value)

调整滑动条的值。无法超出最大值。

参数:

value: number类型，滑动条的目标值。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 设置滑动条的值为50
await model.getSlider("音量").setPosition(50);

# 设置滑动条的值为50
model.getSlider("音量").setPosition(50)

position()

获取滑动条的值。

返回值:

number类型，异步返回滑动条的当前值。

使用示例

JavaScript

Python

// 获取滑动条的当前值
let currentValue = await model.getSlider("音量").position();
console.log(`当前音量: ${currentValue}`);

# 获取滑动条的当前值
current_value = model.getSlider("音量").position()
print(f"当前音量: {current_value}")

maximum()

获取滑动条的最大值。

返回值:

number类型，异步返回滑动条的最大值。

使用示例

JavaScript

Python

// 获取滑动条的最大值
let maxValue = await model.getSlider("音量").maximum();
console.log(`最大值: ${maxValue}`);

# 获取滑动条的最大值
max_value = model.getSlider("音量").maximum()
print(f"最大值: {max_value}")

minimum()

获取滑动条的最小值。

返回值:

number类型，异步返回滑动条的最小值。

使用示例

JavaScript

Python

// 获取滑动条的最小值
let minValue = await model.getSlider("音量").minimum();
console.log(`最小值: ${minValue}`);

# 获取滑动条的最小值
min_value = model.getSlider("音量").minimum()
print(f"最小值: {min_value}")

readOnly()

滑动条是否可调整。

返回值:

boolean类型，异步返回是否可调整。

使用示例

JavaScript

Python

// 检查滑动条是否可调整
let isReadOnly = await model.getSlider("音量").readOnly();
if (!isReadOnly) {
	// 如果可调整，则设置值
	await model.getSlider("音量").setPosition(75);
}

# 检查滑动条是否可调整
is_read_only = model.getSlider("音量").readOnly()
if not is_read_only:
	# 如果可调整，则设置值
	model.getSlider("音量").setPosition(75)

滚动条控件: ScrollBar

针对操作滚动区域中的滚动条控件，但需要滚动操作时，识别到该区域的滚动条控件，再通过调用滚动条上的方法来完成区域的滚动操作是一种非常方便的选择。

滚动条控件实际上是一种特殊的滑动条。

类型文件如下:

JavaScript

Python

export interface IWinScrollBar extends IWinControl {
	setValue(value: number): void; 
	isTop(): Promise<boolean>;
	isBottom(): Promise<boolean>;
	lineUp(): Promise<void>;
	lineDown(): Promise<void>;
	pageUp(): Promise<void>;
	pageDown(): Promise<void>;
	scrollToTop(): Promise<void>;
	scrollToBottom(): Promise<void>;
}

class WinScrollBar(WinControl):
	def setValue(value: int) -> None
	def isTop() -> bool
	def isBottom() -> bool
	def lineUp() -> None
	def lineDown() -> None
	def pageUp() -> None
	def pageDown() -> None
	def scrollToTop() -> None
	def scrollToBottom() -> None

setValue(value)

设置滚动条的值，将滑块拖拽至指定值的位置，但不会超出最大值。单位可以理解为滚轮格数。

参数:

value: number类型，将滑块拖拽至指定值的位置。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 设置滚动条的位置
await model.getScrollBar("垂直滚动条").setValue(100);

# 设置滚动条的位置
model.getScrollBar("垂直滚动条").setValue(100)

lineUp()

向上/左滚动一个单位，单位可以当作滚轮格数，也就是按下一次上/左方向键滚动的量。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 向上滚动一行
await model.getScrollBar("垂直滚动条").lineUp();

# 向上滚动一行
model.getScrollBar("垂直滚动条").lineUp()

lineDown()

向下/右滚动一个单位，单位可以当作滚轮格数，也就是按下一次下/右方向键滚动的量。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 向下滚动一行
await model.getScrollBar("垂直滚动条").lineDown();

# 向下滚动一行
model.getScrollBar("垂直滚动条").lineDown()

pageUp()

向上/左滚动一页，也就是按下一次PageUp键滚动的量。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 向上翻页
await model.getScrollBar("垂直滚动条").pageUp();

# 向上翻页
model.getScrollBar("垂直滚动条").pageUp()

pageDown()

向下/右滚动一页，也就是按下一次PageDown键滚动的量。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 向下翻页
await model.getScrollBar("垂直滚动条").pageDown();

# 向下翻页
model.getScrollBar("垂直滚动条").pageDown()

scrollToTop()

将滚动条滚动到顶部。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 滚动到顶部
await model.getScrollBar("垂直滚动条").scrollToTop();

# 滚动到顶部
model.getScrollBar("垂直滚动条").scrollToTop()

scrollToBottom()

将滚动条滚动到底部。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 滚动到底部
await model.getScrollBar("垂直滚动条").scrollToBottom();

# 滚动到底部
model.getScrollBar("垂直滚动条").scrollToBottom()

isTop()

滚动条是否处在顶部。

返回值:

boolean类型，异步返回滚动条是否处在顶部。

使用示例

JavaScript

Python

// 检查是否在顶部
let atTop = await model.getScrollBar("垂直滚动条").isTop();
if (atTop) {
	console.log("已经在顶部");
}

# 检查是否在顶部
at_top = model.getScrollBar("垂直滚动条").isTop()
if at_top:
	print("已经在顶部")

isBottom()

滚动条是否处在底部。

返回值:

boolean类型，异步返回滚动条是否处在底部。

使用示例

JavaScript

Python

// 检查是否在底部
let atBottom = await model.getScrollBar("垂直滚动条").isBottom();
if (atBottom) {
	console.log("已经在底部");
}

# 检查是否在底部
at_bottom = model.getScrollBar("垂直滚动条").isBottom()
if at_bottom:
	print("已经在底部")

图片控件: Image

图片控件。

方法名	描述
visualText	使用OCR识别图片中的文本。

JavaScript

export interface IWinImage extends IWintControl {    
	visualText(): Promise<string>;
}

visualText()

使用OCR识别图片中的文本。

返回值:

string类型，异步返回图片控件中的文本内容。

使用示例

JavaScript

Python

// 使用OCR识别图片中的文字
let text = await model.getImage("验证码").visualText();
console.log(`识别到的文本: ${text}`);

# 使用OCR识别图片中的文字
text = model.getImage("验证码").visualText()
print(f"识别到的文本: {text}")

超链接控件: Link/HyperLink

超链接控件。

方法名	描述
url	获取超链接指向的地址。

JavaScript

export interface IWinLink extends IWintControl {    
	url(): Promise<string>;
}
export interface IWinHyperlink extends IWinLink {    
}

url()

获取超链接指向的地址。

返回值:

string类型，异步返回链接的地址。

使用示例

JavaScript

Python

// 获取超链接的URL
let linkUrl = await model.getHyperlink("帮助文档").url();
console.log(`链接地址: ${linkUrl}`);

# 获取超链接的URL
link_url = model.getHyperlink("帮助文档").url()
print(f"链接地址: {link_url}")

针对应用中的菜单操作相关的有MenuBar、Menu和MenuItem三种控件。其中前两个控件都属于容器控件（菜单栏容器与展开菜单容器），实际可以点击的选项都是MenuItem控件。

MenuBar 控件方法:

方法名	描述
itemNames	获取目标索引值的菜单项名称。
open	展开目标菜单项。
itemCount	获取菜单栏中菜单项总数。

Menu 控件方法:

方法名	描述
select	选中目标菜单项。
itemCount	获取菜单容器中菜单项总数。
itemName	获取目标索引值的菜单项名称。
itemNames	获取所有菜单项的名称。

MenuItem 控件方法:

方法名	描述
invoke	点击/触发菜单项。
open	展开菜单项所在的菜单容器。

JavaScript

Python

export interface IWinMenuBar extends IWintControl {    
	itemNames(index:number) : Promise<string>;
	open(itemNameOrIndex: string | number): Promise<void>;
	//Get the menu item count
	itemCount(): Promise<number>;
}
export interface IWinMenu extends IWintControl {
	select(menuPath: string): Promise<boolean>;  
	
	itemCount(menuPath:string): Promise<number>; 
	itemName(menuPath:string): Promise<string>;
	itemNames(): Promise<string[]>;
}
export interface IWinMenuItem extends IWintControl {
	invoke(): Promise<void>;
	open(): Promise<void>
}

class WinMenuBar(WinControl):
	def itemNames(index: int) -> str
	def open(itemNameOrndex: Union[str, int]) -> None
	def itemCount() -> int
class WinMenu(WinControl):
	def itemCount(menuPath: str) -> int
	def itemName(menuPath: str) -> str
	def itemNames() -> List[str]
	def select(menuPath: str) -> bool
class WinMenuItem(WinControl):
	def invoke() -> None
	def open() -> None

菜单栏MenuBar的API介绍

itemNames(index)

获取目标索引值的菜单项名称。

参数:

index: number类型，目标菜单项的索引值。

返回值:

string类型，异步返回目标索引值对应的菜单项名称。

使用示例

JavaScript

Python

// 获取第一个菜单项的名称
let menuName = await model.getMenuBar("菜单栏").itemNames(0);
console.log(`菜单项名称: ${menuName}`);

# 获取第一个菜单项的名称
menu_name = model.getMenuBar("菜单栏").itemNames(0)
print(f"菜单项名称: {menu_name}")

open(itemNameOrIndex)

展开目标菜单项。

参数:

itemNameOrIndex: number或string类型，目标菜单项的索引值或名称。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 通过名称展开菜单
await model.getMenuBar("菜单栏").open("文件");

// 通过索引展开菜单
await model.getMenuBar("菜单栏").open(0);

# 通过名称展开菜单
model.getMenuBar("菜单栏").open("文件")

# 通过索引展开菜单
model.getMenuBar("菜单栏").open(0)

itemCount()

获取菜单栏中菜单项总数。

返回值:

number类型，异步返回菜单项数量。

使用示例

JavaScript

Python

// 获取菜单栏中的菜单项数量
let count = await model.getMenuBar("菜单栏").itemCount();
console.log(`菜单项总数: ${count}`);

# 获取菜单栏中的菜单项数量
count = model.getMenuBar("菜单栏").itemCount()
print(f"菜单项总数: {count}")

菜单容器Menu的API介绍

获取菜单容器中菜单项总数。

返回值:

number类型，异步返回菜单项数量。

使用示例

JavaScript

Python

// 获取菜单中的菜单项数量
let count = await model.getMenu("文件").itemCount();
console.log(`菜单项总数: ${count}`);

# 获取菜单中的菜单项数量
count = model.getMenu("文件").itemCount()
print(f"菜单项总数: {count}")

获取目标索引值的菜单项名称。

参数:

menuPath: number类型，目标菜单项的索引值。

返回值:

string类型，异步返回目标索引值对应的菜单项名称。

使用示例

JavaScript

Python

// 获取指定索引的菜单项名称
let itemName = await model.getMenu("文件").itemName(0);
console.log(`菜单项名称: ${itemName}`);

# 获取指定索引的菜单项名称
item_name = model.getMenu("文件").itemName(0)
print(f"菜单项名称: {item_name}")

获取所有菜单项的名称。

返回值:

string[]类型，异步返回菜单中所有菜单项的名称。

使用示例

JavaScript

Python

// 获取所有菜单项的名称
let allItems = await model.getMenu("文件").itemNames();
console.log(`所有菜单项: ${allItems.join(', ')}`);

# 获取所有菜单项的名称
all_items = model.getMenu("文件").itemNames()
print(f"所有菜单项: {', '.join(all_items)}")

选中目标菜单项。

参数:

menuPath: string类型，目标菜单项的路径。

返回值:

boolean类型，异步返回目标是否成功选中。

使用示例

JavaScript

Python

// 选中指定的菜单项
let success = await model.getMenu("文件").select("新建");
if (success) {
	console.log("菜单项选中成功");
}

# 选中指定的菜单项
success = model.getMenu("文件").select("新建")
if success:
	print("菜单项选中成功")

菜单项MenuItem的API介绍

open()

展开菜单项所在的菜单容器。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 展开菜单项
await model.getMenuItem("文件").open();

# 展开菜单项
model.getMenuItem("文件").open()

invoke()

点击/触发菜单项。建议先使用open()方法展开菜单，再进行点击。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 先展开菜单，然后点击菜单项
await model.getMenuItem("文件").open();
await model.getMenuItem("新建").invoke();

# 先展开菜单，然后点击菜单项
model.getMenuItem("文件").open()
model.getMenuItem("新建").invoke()

子菜单的点击方法:
对于一些需要悬停展开后才能点击到的子菜单项，可以先调用父菜单项上的.moveMouse()通用方法将鼠标移动到该位置上，再点击子菜单。
这是因为两次点击之前的鼠标轨迹是不能确定的，部分控件的点击是不会移动鼠标的，此时如果需要鼠标光标出现在确定的位置，则最好使用.moveMouse()来手动的移动光标。

标签栏控件和标签页控件: Tab & TabItem

针对应用中的标签页的控件，Tab和TabItem，进行标签页的切换。

Tab 控件方法:

方法名	描述
findItem	获取指定标签页的自动化对象。
activate	激活目标标签页。
activeIndex	获取当前界面中被激活的标签索引值。
activeName	获取当前界面中被激活的标签名称。
tabNames	获取所有标签页的标题。
count	获取标签栏中的标签页数量。

TabItem 控件方法:

方法名	描述
activate	激活标签页。
text	获取标签页标题。
itemIndex	获取标签页在整个标签栏中的次序。

关于标签栏控件的定义如下:

JavaScript

Python

export interface IWinTab extends IWintControl {
	activate(nameOrIndex: string | number): Promise<void>;
	tabNames(index: number): Promise<string[] | string>;
	findItem(nameOrIndex: string | number): Promise<IWinTabItem>;

	activeName(): Promise<string>;
	activeIndex(): Promise<number>;
	count(): Promise<number>;
}
export interface IWinTabItem extends IWintControl {
	activate(): Promise<void>;
	text(): Promise<string>;
	itemIndex(): Promise<number>;
}

class WinTab(WinControl):
	def activate(nameOrndex: Union[str, int]) -> None
	def tabNames(index: Optional[int]=None) -> Union[str, List[str]]
	def findItem(nameOrndex: Union[str, int]) -> "WinTabItem"
	def select(item: Union[str, int]) -> None
	def activeName() -> str
	def activendex() -> int
	def count() -> int
class WinTabItem(WinControl):
	def activate() -> None
	def text() -> str
	def itemndex() -> int

findItem(itemNameOrIndex)

获取指定标签页的自动化对象，传入标签页的索引值或标题。

参数:

itemNameOrIndex: number或string类型，目标标签页的索引值或标签页标题。

返回值:

TabItem类型，同步返回一个TabItem类型的操作对象。

使用示例

JavaScript

Python

// 获取指定的标签页对象
let tabItem = await model.getTab("标签栏").findItem("首页");

# 获取指定的标签页对象
tab_item = model.getTab("标签栏").findItem("首页")

activate(itemNameOrIndex)

激活目标标签页，传入标签页的索引值或标题。

如果是TabItem上的activate()方法则不需要传入任何参数。

参数:

itemNameOrIndex: number或string类型，目标标签页的索引值或标签页标题。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 通过名称激活标签页
await model.getTab("标签栏").activate("设置");

// 通过索引激活标签页
await model.getTab("标签栏").activate(1);

# 通过名称激活标签页
model.getTab("标签栏").activate("设置")

# 通过索引激活标签页
model.getTab("标签栏").activate(1)

activeIndex()

获取当前界面中被激活的标签索引值。

返回值:

number类型，异步返回标签页索引值。

使用示例

JavaScript

Python

// 获取当前激活的标签页索引
let index = await model.getTab("标签栏").activeIndex();
console.log(`当前激活的标签页索引: ${index}`);

# 获取当前激活的标签页索引
index = model.getTab("标签栏").activeIndex()
print(f"当前激活的标签页索引: {index}")

activeName()

获取当前界面中被激活的标签名称。

返回值:

string类型，异步返回标签页的名称。

使用示例

JavaScript

Python

// 获取当前激活的标签页名称
let name = await model.getTab("标签栏").activeName();
console.log(`当前激活的标签页: ${name}`);

# 获取当前激活的标签页名称
name = model.getTab("标签栏").activeName()
print(f"当前激活的标签页: {name}")

tabNames(index)

获取所有标签页的标题，如果传入数字，则获取对应索引值的标签页标题。

参数:

index: number类型，目标标签页的索引值，默认值为-1，会获取全部标题。

返回值:

当index为-1时，为string[]，为所有标签页标题组成的字符串数组；当index为其它值时，为string，返回目标索引值对应的标签页标题。

使用示例

JavaScript

Python

// 获取所有标签页的标题
let allTabs = await model.getTab("标签栏").tabNames(-1);
console.log(`所有标签页: ${allTabs.join(', ')}`);

// 获取指定索引的标签页标题
let tabName = await model.getTab("标签栏").tabNames(0);
console.log(`第一个标签页: ${tabName}`);

# 获取所有标签页的标题
all_tabs = model.getTab("标签栏").tabNames(-1)
print(f"所有标签页: {', '.join(all_tabs)}")

# 获取指定索引的标签页标题
tab_name = model.getTab("标签栏").tabNames(0)
print(f"第一个标签页: {tab_name}")

count()

获取标签栏中的标签页数量。

返回值:

number类型，异步返回标签页的数量。

使用示例

JavaScript

Python

// 获取标签页的总数
let count = await model.getTab("标签栏").count();
console.log(`标签页总数: ${count}`);

# 获取标签页的总数
count = model.getTab("标签栏").count()
print(f"标签页总数: {count}")

以下是TabItem对象的方法。

activate()

激活标签页。

返回值:

不返回任何值的异步方法。

使用示例

JavaScript

Python

// 激活指定的标签页
await model.getTabItem("设置").activate();

# 激活指定的标签页
model.getTabItem("设置").activate()

text()

重写自基类的text()方法，获取标签页标题。

返回值:

string类型，返回标签页的标题。

使用示例

校验获取到的标签页标题：

JavaScript

Python

// 获取标签页标题并验证
let title = await model.getTabItem("One").text();
assert.equal(title, 'One');

# 获取标签页标题并验证
title = model.getTabItem("One").text()
assert title == 'One'

itemIndex()

获取标签页在整个标签栏中的次序。

返回值:

number类型，异步返回标签页的索引值。

使用示例

JavaScript

Python

// 获取标签页的索引位置
let index = await model.getTabItem("设置").itemIndex();
console.log(`标签页索引: ${index}`);

# 获取标签页的索引位置
index = model.getTabItem("设置").itemIndex()
print(f"标签页索引: {index}")

results matching ""

全部 API Walkthrough 其他

基本类型对象

基础控件类介绍

按钮控件: Button

窗口控件: Window

activate()

close()

maximize()

minimize()

restore()

isModal()

interactionState()

visualState()

输入框控件: Edit与Document

set(value)

clearAll()

readOnly()

单选按钮控件: RadioButton

check()

checked()

复选框控件: CheckBox

toggleCheck(checkState)

checkState()

组合/下拉框: ComboBox

open()

select(nameOrIndex)

selectedName()

options()

itemCount()

选值框: Spinner

set(value)

clearAll()

readOnly()

increment()

decrement()

滑动条: Slider

setPosition(value)

position()

maximum()

minimum()

readOnly()

滚动条控件: ScrollBar

setValue(value)

lineUp()

lineDown()

pageUp()

pageDown()

scrollToTop()

scrollToBottom()

isTop()

isBottom()

图片控件: Image

visualText()

超链接控件: Link/HyperLink

url()

菜单相关的控件和菜单栏选项控件: MenuBar & Menu & MenuItem

itemNames(index)

open(itemNameOrIndex)

itemCount()

itemCount()

itemName(menuPath)

itemNames()

select(menuPath)

open()

invoke()

标签栏控件和标签页控件: Tab & TabItem

findItem(itemNameOrIndex)

activate(itemNameOrIndex)

activeIndex()

activeName()

tabNames(index)

count()

activate()

text()

itemIndex()

results matching ""

No results matching ""