列表类型对象

针对列表控件以及列表项控件，CukeTest提供了List和ListItem两个对象类型。由于列表视图属于复合结构，因此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>;
  10.     findItem(value: string | ((value: string) => Promise<boolean>)): Promise<IWinListItem>;
  12.     data(): Promise<string[]>;
  13.     columnCount(): Promise<number>;
  14.     columnHeaders(): Promise<string[]>;
  15.     selectedName(): Promise<string>;
  16.     itemCount(): Promise<number>;
  17. }

对象操作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>

滚动到列表项位置。

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