列表类型对象

针对列表控件以及列表项控件，CukeTest提供了List和ListItem两个对象类型。由于列表视图属于复合结构，因此CukeTest提供了很多方法，可以结合表格视图控件Table和树视图控件Tree理解。

列表视图控件: List

用于描述列表视图控件的对象类型——List，由于是Qt的一种视图组件，作为一种列表项的容器而存在的。

方法名	描述
select	选择控件，可以根据控件的索引值选择（例如0，3），也可以使用name属性。
itemName	获得List中的项目名称。
columnName	获取目标索引值的列表头的名称。
columnItemValue	在列表中获取项目值，item可以是项目名称或项目索引，column可以是列名称或列索引。
scrollTo	滚动到指定位置。
scrollToTop	滚动到顶部。
scrollToBottom	滚动到底部。
findItem	搜索并返回单元格对象。未搜索到返回null。value参考可为被搜索值，或为每个值的回调函数。模型管理器中会选中对象。代码中需调用select方法选中。
data	返回列表的数据内容。
columnCount	返回列表的列数。
columnHeaders	返回列表列标题的数组。
selectedName	被选中的控件名。
itemCount	控件个数。

类型定义

JavaScript

Python

export interface IWinList extends IWintControl {
    select(value: string): Promise<void>;
    itemName(index: number): Promise<string>;
    columnName(index: number): Promise<string>;
    columnItemValue(item: string | number, column: string | number): Promise<string>;
    scrollTo(value: number | string): Promise<IWinListItem>;
    scrollToTop(): Promise<void>;
    scrollToBottom(): Promise<void>;
    
    findItem(value: string | ((value: string) => Promise<boolean>)): Promise<IWinListItem>;
    
    data(): Promise<string[]>;
    columnCount(): Promise<number>;
    columnHeaders(): Promise<string[]>;
    selectedName(): Promise<string>;
    itemCount(): Promise<number>;
}

class WinList(WinControl):
	def itemName(index: int) -> str
	def columnName(index: int) -> str
	def columnHeaders() -> List[str]
	def columnItemValue(item: Union[str, int], column: Union[str, int]) -> str
	def columnCount() -> int
	def data() -> List[str]
	def findItem(value: str) -> "WinListItem"
	def itemCount() -> int
	def select(value: str) -> "WinListItem"
	def selectedName() -> str
	def scrollTo(value: Union[str, int]) -> "WinListItem"
	def scrollToTop() -> None
	def scrollToBottom() -> None

对象操作API

下面是针对List控件的对象操作API。

findItem(text)

根据名称搜索目标列表项，返回目标列表项的自动化对象，如果没有搜索到则返回null。

参数

text: string类型，期望目标列表项的内容或者文本。

返回值

Promise<IWinListItem>或Promise<null>类型，异步的搜索应用中的目标列表项，如果没有搜索到则返回null。

示例代码

JavaScript

Python

let findArg = 'addressbook.exe';
// 查找名称为 'addressbook.exe' 的列表项
const item = await model.getList("List").findItem(findArg);
// 验证找到的列表项的值
assert.equal(await item.value(), findArg);

findArg = 'addressbook.exe'
# 查找名称为 'addressbook.exe' 的列表项
item = model.getList("List").findItem(findArg)
# 验证找到的列表项的值
assert item.value() == findArg

findItem(callback)

高级的搜索列表项的方法，当直接查找目标列表项的名称不足以满足需求的时候，可以传入一个函数作为搜索条件。比如查询包含"有限公司"字符串的列表项，又或是查询名称为手机号码的列表项，验证其是否符合正则表达式/\d{11}/等等。

参数

callback: 用于测试列表中每一项名称的函数，会遍历当前的列表，直到函数返回true，输入输出如下：
- value: string类型，callback函数的输入，当前正在处理的列表项的名称字符串。
- 输出: Promise<boolean>类型，接受异步的布尔型返回值。当输出为true时会停止遍历。false或没有返回都会继续遍历列表，直到到达列表底部。

返回值

Promise<IWinListItem|null>类型，异步的返回满足测试函数（测试函数返回true）时的列表项，没有找到则返回null。

示例代码

JavaScript

Python

// 查找名称包含 "有限公司" 的列表项
let item = await model.getList("List").findItem(async (value) => {
    return value.includes("有限公司");
});
// 如果找到，高亮显示该项
if (item) {
    await item.highlight();
}

# 查找名称包含 "有限公司" 的列表项
item = model.getList("List").findItem(lambda value: "有限公司" in value)
# 如果找到，高亮显示该项
if item:
    item.highlight()

select(index)

选中指定索引位置的列表项。对于比较长的列表，会先滚动到顶部，再滚动到目标列表项位置。

参数

index: number型，代表列表项处在列表中的第几项。如果是第一项则为0。

返回值

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

示例代码

JavaScript

Python

// 选中名为 "addressbook.exe" 的列表项
await modelWin.getList("List").select("addressbook.exe");

# 选中名为 "addressbook.exe" 的列表项
modelWin.getList("List").select("addressbook.exe")

itemName(index)

获取目标索引值的列表项名称。

参数

index: number类型，目标列表项的索引值。

返回值

Promise<string>类型，异步的返回目标索引值对应的列表项名称。

示例代码

JavaScript

Python

// 获取索引为 2 的列表项名称
const itemName = await modelWin.getList("List").itemName(2);
assert.equal(itemName, "addressbook.exe");

# 获取索引为 2 的列表项名称
itemName = modelWin.getList("List").itemName(2)
assert itemName == "addressbook.exe"

columnName(index)

获取目标索引值的列表头的名称（如果有的话）。

参数

index: number类型，目标列表头的索引值（即第index列表头）。

返回值

Promise<string>类型，异步的返回目标索引值对应的列表头名称。

示例代码

JavaScript

Python

// 获取第一个列表头的名称
const columnName = await modelWin.getList("List").columnName(0);

# 获取第一个列表头的名称
columnName = modelWin.getList("List").columnName(0)

scrollTo(index)

滚动到目标索引位置。如果目标位置还未加载，会一直加载到目标索引位置加载为止。

参数

index: number型，代表列表项处在列表中的第几项。如果是第一项则为0。

返回值

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

示例代码

JavaScript

Python

// 滚动到第 3 个列表项（索引为 2）
await modelWin.getList("List").scrollTo(2);

# 滚动到第 3 个列表项（索引为 2）
modelWin.getList("List").scrollTo(2)

scrollToTop()

滚动到列表顶部。

返回值

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

示例代码

JavaScript

Python

// 滚动到列表顶部
await modelWin.getList("List").scrollToTop();

# 滚动到列表顶部
modelWin.getList("List").scrollToTop()

scrollToBottom()

滚动到列表底部。这里的列表底部指的是已加载列表的底部，是为了避免非常长的列表带来的性能问题。

返回值

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

示例代码

JavaScript

Python

// 滚动到列表底部
await modelWin.getList("List").scrollToBottom();

# 滚动到列表底部
modelWin.getList("List").scrollToBottom()

data()

获得列表视图中的数据并返回。会自动的滚动列表直到底部，直到遍历所有的列表项。如果列表视图采取了批次加载（或者可以理解为延迟加载方式），则只会获得已加载的数据，未加载的数据无法被获取到。

返回值

Promise<string[]>类型，由列表选项值组成的字符串数组。需要使用await关键字取出其中的结果。

示例代码

JavaScript

Python

// 获取列表中的所有数据
const data = await modelWin.getList("List").data();
assert.deepEqual(JSON.stringify(data), '["addressbook.exe", "notepad.exe", "cmd.exe"]');

# 获取列表中的所有数据
data = modelWin.getList("List").data()
assert data == ["addressbook.exe", "notepad.exe", "cmd.exe"]

columnItemValue(item, column)

获取指定行、列的列表项的值（通常为列表项的名称）。

参数

item: number类型或string类型，指定哪一行，可以是列表项名称或项目索引。
column: number类型或string类型，指定哪一列，可以是目标列名称或项目索引。

返回值

Promise<string>类型，异步的返回目标列表项的值。

示例代码

JavaScript

Python

// 获取第1行第1列的值
let value = await modelWin.getList("List").columnItemValue(0, 0);
// 获取列表项 "addressbook.exe" 在第1列的值
value = await modelWin.getList("List").columnItemValue("addressbook.exe", 0);
assert.equal(value, "addressbook.exe");

# 获取第1行第1列的值
value = modelWin.getList("List").columnItemValue(0, 0)
# 获取列表项 "addressbook.exe" 在第1列的值
value = modelWin.getList("List").columnItemValue("addressbook.exe", 0)
assert value == "addressbook.exe"

columnCount()

获取列的数量。

返回值

Promise<number>类型，异步的返回列表中的列数。

示例代码

JavaScript

Python

// 获取列表的列数
const count = await modelWin.getList("List").columnCount();
assert.equal(count, 1);

# 获取列表的列数
count = modelWin.getList("List").columnCount()
assert count == 1

columnHeaders()

获取所有列的名称。

返回值

Promise<string[]>类型，异步的返回列表中所有列的名称。

示例代码

JavaScript

Python

// 获取所有列的标题
const headers = await modelWin.getList("List").columnHeaders();
assert.deepEqual(JSON.stringify(headers), '["Name"]');

# 获取所有列的标题
headers = modelWin.getList("List").columnHeaders()
assert headers == ["Name"]

selectedName()

获取当前选中列的名称。

返回值

Promise<string>，异步的返回被选中列表项的名称。

示例代码

JavaScript

Python

// 获取当前选中的列表项名称
const name = await modelWin.getList("List").selectedName();
assert.equal(name, "addressbook.exe");

# 获取当前选中的列表项名称
name = modelWin.getList("List").selectedName()
assert name == "addressbook.exe"

itemCount()

获得列表视图中的数据数量。会自动的滚动列表直到底部，直到遍历所有的列表项。如果列表视图采取了批次加载（或者可以理解为延迟加载方式），则只会获得已加载的数据，未加载的数据无法被获取到。

返回值

Promise<number>类型，异步的返回列表项的数量。

示例代码

JavaScript

Python

// 获取列表项的总数
const count = await modelWin.getList("List").itemCount();
assert.equal(count, 3);

# 获取列表项的总数
count = modelWin.getList("List").itemCount()
assert count == 3

列表项控件: ListItem

针对列表中的列表项控件，模型管理器提供了ListItem类型。与List对象的提供的操作列表项的方法（比如scrollTo()、select()不同，列表项控件自身就包含了位置信息，因此它的方法都不需要额外再传入参数。

方法名	描述
scrollIntoView	滚动到视图位置。
setSelect	设置成"true"勾选, "false"清除勾选。
select	选择控件，可以根据控件的索引值选择（例如0，3），也可以使用name属性。
selected	当前这一项是否被选中。

类型定义

JavaScript

Python

export interface IWinListItem extends IWintControl {
    scrollIntoView(): Promise<void>;
    setSelect(select: boolean): Promise<void>; //add to selection, works on some controls like file explorer
    select(select: boolean): Promise<void>;

    selected(): Promise<boolean>;
}

class WinListItem(WinControl):
	def scrollIntoView() -> None
	def select() -> None
	def selected() -> bool
	def setSelect(select: bool) -> None

对象操作API

select()

选中列表项。如果该项不在可视范围内，还会自动的滚动到该项所在的位置。

返回值

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

示例代码

JavaScript

Python

// 选中 "addressbook.exe" 列表项
await modelWin.getListItem("addressbook.exe").select();

# 选中 "addressbook.exe" 列表项
modelWin.getListItem("addressbook.exe").select()

setSelect(select)

当列表项默认为支持多选，或每个列表项包含一个复选框（来标识选中状态），那么setSelect()方法可以使得多个列表项同时被选中。最常见的场景是Windows文件管理器中的文件复选框。类似CheckBox控件的toggleCheck()方法。

参数

select: Boolean类型，true代表选中复选框，false代表取消选中目标复选框。

返回值

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

示例代码

JavaScript

Python

// 勾选 "addressbook.exe" 列表项
await modelWin.getListItem("addressbook.exe").setSelect(true);

# 勾选 "addressbook.exe" 列表项
modelWin.getListItem("addressbook.exe").setSelect(True)

scrollIntoView()

滚动到列表项位置。

返回值

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

示例代码

JavaScript

Python

// 滚动到 "addressbook.exe" 列表项位置
await modelWin.getListItem("addressbook.exe").scrollIntoView();

# 滚动到 "addressbook.exe" 列表项位置
modelWin.getListItem("addressbook.exe").scrollIntoView()

selected()

目标列表项是否被选中。

返回值

Promise<boolean>类型，异步的返回选中的结果。

示例代码

JavaScript

Python

// 检查 "addressbook.exe" 是否被选中
const selected = await modelWin.getListItem("addressbook.exe").selected();
assert.equal(selected, true);

# 检查 "addressbook.exe" 是否被选中
selected = modelWin.getListItem("addressbook.exe").selected()
assert selected == True

results matching ""

全部 API Walkthrough 其他

列表类型对象

列表视图控件: List

类型定义

对象操作API

findItem(text)

findItem(callback)

select(index)

itemName(index)

columnName(index)

scrollTo(index)

scrollToTop()

scrollToBottom()

data()

columnItemValue(item, column)

columnCount()

columnHeaders()

selectedName()

itemCount()

列表项控件: ListItem

类型定义

对象操作API

select()

setSelect(select)

scrollIntoView()

selected()

results matching ""

No results matching ""