列表类型对象

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

列表视图控件: List

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

类型文件中的定义

  1. export interface IWinList extends IWintControl {
  2. select(value: string): Promise<void>;
  3. itemName(index: number): Promise<string>;
  4. columnName(index: number): Promise<string>;
  5. columnItemValue(item: string | number, column: string | number): Promise<string>;
  6. scrollTo(value: number | string): Promise<IWinListItem>;
  7. scrollToTop(): Promise<void>;
  8. scrollToBottom(): Promise<void>;
  9. findItem(value: string | ((value: string) => Promise<boolean>)): Promise<IWinListItem>;
  10. data(): Promise<string[]>;
  11. columnCount(): Promise<number>;
  12. columnHeaders(): Promise<string[]>;
  13. selectedName(): Promise<string>;
  14. itemCount(): Promise<number>;
  15. }

对象操作API

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

findItem(text): Promise<IWinListItem | null>

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

  • text: string类型,期望目标列表项的内容或者文本;
  • 返回值: Promise<IWinListItem>Promise<null>类型,异步的搜索应用中的目标列表项,如果没有搜索到则返回null

findItem(callback(value)): Promise<IWinListItem | null>

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

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

select(index): Promise<void>

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

  • index: number型,代表列表项处在列表中的第几项。如果是第一项则为0。
  • 返回值: 不返回任何值的异步方法。

itemName(index: number): Promise<string>

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

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

columnName(index: number): Promise<string>

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

  • index: number类型,目标列表头的索引值(即第index列表头)。
  • 返回值: Promise<string>类型,异步的返回目标索引值对应的列表头名称。

scrollTo(index): Promise<void>

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

  • index: number型,代表列表项处在列表中的第几项。如果是第一项则为0。
  • 返回值: 不返回任何值的异步方法。

scrollToTop(): Promise<void>

滚动到列表顶部。

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

scrollToBottom(): Promise<void>

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

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

data(): Promise<string[]>

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

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

columnItemValue(item: string | number, column: string | number): Promise<string>

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

  • item: number类型或string类型,指定哪一行,可以是列表项名称或项目索引。下面的column参数也是。
  • column: number类型或string类型,指定哪一列,可以是目标列名称或项目索引。
  • 返回值: Promise<string>类型,异步的返回目标列表项的值。

columnCount(): Promise<number>

获取列的数量。

  • 返回值: Promise<number>类型,异步的返回列表中的列数。

columnHeaders(): Promise<string[]>

获取所有列的名称。

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

selectedName(): Promise<string>

获取当前选中列的名称。

  • 返回值: Promise<string>,异步的返回被选中列表项的名称。

itemCount(): Promise<number>

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

  • 返回值: Promise<number>类型,异步的返回列表项的数量。

列表项控件: ListItem

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

类型文件定义

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

对象操作API

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

select(): Promise<void>

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

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

setSelect(select): Promise<void>

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

  • select: Boolean类型,true代表选中复选框,false代表取消选中目标复选框。
  • 返回值: 不返回任何值的异步方法。

scrollIntoView(): Promise<void>

滚动到列表项位置。

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