进阶对象操作API介绍——表格

针对被测应用中的表格提供的对象，CukeTest提供了三个控件:

• Table: 表格控件，作为表格外部容器控件，也是CukeTest推荐使用的;
• TableRow: 表格行控件，代表表格中的一行数据，可以进一步获取其中的单元格，也就是TableCell控件;
• TableCell: 单元格控件，代表表格中的最小控件单元，这些单元格包含数据，并且在很多时候都是可以双击切换到编辑状态进行编辑的。

这个三个不同的控件互相配合就可以完美完成针对表格应用的自动化。

事实上CukeTest还提供了另一个表格控件DataGrid，它与Table控件的区别在于:
Table和DataGrid两个控件是针对两种不同的框架在表格实现上不一致准备的: 在WinForm、WPF框架的应用中，表格会被识别为DataGrid控件；而Qt框架中为Table控件。

表格控件: Table

用于描述表格视图控件的对象类型——Table。

在大多数情况下，由于表格中的单元格能够提供的识别属性较少，并且在操作单元格之前一一识别被操作的单元格也不是一种合适的自动化方式。因此CukeTest将大部分表格及表格内的操作、属性方法都包含了，针对表格的自动化直接在Table对象上完成即可。比如:

假设有在第2行第3列位置有个单元格，需要修改该单元格内的值为targetValue，如果按照常规的自动化开发流程，应该是如下:

// 在识别单元格为`TargetCell`后
await model.getTableCell('TargetCell').set(targetValue);

# 在识别单元格为`TargetCell`后
model.getTableCell('TargetCell').set(targetValue)

而建议的方法是这样的:

await model.getTable('Table').setCellValue(1, 2, targetValue);

model.getTable('Table').setCellValue(1, 2, targetValue)

通过这种方式，能够在不用识别被操作单元格的前提下操作单元格，使得你只需要知道表格的行、列数量，就可以遍历整张表中的所有单元格了。这就是为什么建议你在Table对象上进行操作而不是在单元格的对象上。

类型文件定义

export interface IWinTable extends IWinControl {
    clickCell(rowIndex: number, columnNameOrIndex: string | number): Promise<void>;
    cellValue(rowIndex: number, columnNameOrIndex: string | number): Promise<string>;
    setCellValue(rowIndex: number, columnNameOrIndex: string | number, value: string): Promise<void>;
    showHeader(nameOrIndex: string | number): Promise<IWinTableCell>;
    
    select(rowIndex: number, columnName: string | number): Promise<IWinTableCell>;
    scrollTo(rowIndex: number, columnName: string | number): Promise<IWinTableCell>;
    scrollLeft(): Promise<void>;
    scrollToTop(): Promise<void>;
    scrollToBottom(): Promise<void>;
    findItemInColumn(columnNameOrIndex: string | number, 
        valueOrListener: string | ((element) => Promise<boolean>))
        : Promise<IWinTableCell>

    columnName(index: number): Promise<string>;
    columnHeaders(): Promise<string[]>;
    columnCount(): Promise<number>;
    rowCount(): Promise<number>;
    row(rowIndex: number): Promise<IWinTableRow>;
    rowData(rowIndex: number): Promise<string[]>;
}  

export interface IWinDataGrid extends IWinTable {

}

class WinTable(WinControl):
	def clickCell(rowndex: int, columnNameOrndex: Union[str, int]) -> None
	def cellValue(rowndex: int, columnNameOrndex: Union[str, int]) -> str
	def setCellValue(rowndex: int, columnNameOrndex: Union[str, int], value: str) -> None
	def showHeader(nameOrndex: Union[str, int]) -> "WinTableCell"
	def select(rowndex: int, columnNameOrndex: Union[str, int]) -> "WinTableCell"
	def scrollTo(rowndex: int, columnNameOrndex: Union[str, int]) -> "WinTableCell"
	def scrollLeft() -> None
	def scrollToTop() -> None
	def scrollToBottom() -> None
	def findItemInColumn(columnNameOrIndex: Union[str, int], valueOrListener: str) -> "WinTableCell"
	def columnName(index: int) -> str
	def columnHeaders() -> List[str]
	def columnCount() -> int
	def rowCount() -> int
	def row(rowndex: int) -> "WinTableRow"
	def rowData(rowndex: int) -> List[str]

class WinDataGrid(WinTable):
    ...

对象操作API介绍

clickCell(rowIndex: number, columnNameOrIndex: string | number): Promise<void>

单击目标索引位置的单元格。如果目标位置还不在屏幕内，会将其滚动到可见位置并点击。

• rowIndex: number类型，代表目标单元格的行位置索引，从0开始计算位置；
• colIndex: number类型，代表目标单元格的列位置索引，从0开始计算位置；
• 返回值: 不返回任何值的异步方法。

showHeader(nameOrIndex: string | number): Promise<IWinTableCell>

将目标表头（列头）滚动到可视位置，并返回目标位置的单元格对象。比columnHeader()方法多出了滚动到目标表头的操作，并且返回的是对象而不是值。

• nameOrIndex: number类型或string类型，代表列的索引或列的名称，从0开始计算位置；
• 返回值: Promise<TableCell>类型，异步的返回该表头的单元格对象。

select(rowIndex: number, columnName: string | number): Promise<IWinTableCell>

点击目标单元格，并返回该单元格的TableCell对象，相比于下面的scrollTo()方法，这个方法多出了一个实际点击/选中单元格的操作。

• rowIndex: number类型，代表目标单元格的行位置索引，从0开始计算位置；
• colIndex: number类型，代表目标单元格的列位置索引，从0开始计算位置；
• 返回值: Promise<TableCell>类型，异步的返回目标位置单元格的对象。

scrollTo(rowIndex, colIndex): Promise<TableCell>

滚动到目标索引位置，并返回目标位置的单元格对象。如果目标位置还未加载，会一直加载到目标索引位置加载为止。

• rowIndex: number类型，代表目标单元格的行位置索引，从0开始计算位置；
• colIndex: number类型，代表目标单元格的列位置索引，从0开始计算位置；
• 返回值: Promise<TableCell>类型，异步的返回目标位置单元格的对象。

scrollLeft(): Promise<void>

滚动到表格最左侧。

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

scrollToTop(): Promise<void>

滚动到表格顶部。

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

scrollToBottom(): Promise<void>

滚动到表格底部。

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

cellValue(rowIndex, columnNameOrIndex): Promise<string>

获取目标行列单元格的值，可以理解为setCellValue()方法相对的Getter方法。

• rowIndex: number类型，代表目标单元格的行位置索引，从0开始计算位置；
• colNameOrIndex: number类型或者string类型，代表目标单元格的列位置索引，从0开始计算位置；也可以传入表头中目标列的名字，比如"Name"、'ID"之类的。
• 返回值: Promise<string>类型，异步的返回string类型的结果，无论目标单元格内是什么内容。如果行列位置超出，或者传入的列名不存在，则会抛出1006: OutOfRange。

setCellValue(rowIndex, columnNameOrIndex, value): Promise<void>

编辑目标行列单元格的值，列位置也可以传入字符串，如果这么做，则会在表头中寻找相应的列位置。

• rowIndex: number类型，代表目标单元格的行位置索引，从0开始计算位置；
• colNameOrIndex: number类型或者string类型，代表目标单元格的列位置索引，从0开始计算位置；也可以传入表头中目标列的名字，比如"Name"、'ID"之类的。
• value: string类型或number类型，期望的单元格值。
• 返回值: 不返回任何值的异步方法。如果行列位置超出，或者传入的列名不存在，则会抛出1006: OutOfRange。

findItemInColumn(columnNameOrIndex: string | number, valueOrListener: string | callback(value)): Promise<IWinTableCell>

搜索目标列中符合条件的单元格。可以根据单元格名称来搜索，也可以使用测试函数callback来完成更复杂的查找。

• columnNameOrIndex: string类型或number类型。代表目标列的名称或索引。
• valueOrListener: string类型或函数类型。如果传入的是字符串，则会自动的搜索与该字符串值相等的单元格。如果是函数，则会将当前列表项的值传入到函数中进行测试:
  • callback: 测试函数，用于测试输入的内容。
    • value: 输入参数，sring类型，在表格中被调用时，会自动的往callback函数中传入当前单元格的值。
    • 返回值: 测试函数运行的结果，boollean类型，当返回值为false时会继续下一个测试；否则回调就会结束并退出。

columnName(index: number): Promise<string>

获取目标表头（列头）的值。

• index: number类型，代表列的索引，从0开始计算位置；
• 返回值: Promise<string>类型，异步的返回该表头的名称。

columnHeaders(): Promise<string[]>

获取表头的内容，并以字符串数组的形式返回。

• 返回值: Promise<string[]>类型，异步的返回string类型的数组，无论表头中是什么内容。

columnCount(): Promise<number>

获取所有表头的数量。数值等于columnCount()返回数组的长度。

• 返回值: Promise<number>类型，异步的返回表头的数量。

rowCount(): Promise<number>

获取整个表的行数，会自动滚动到表格底部以加载全部数据。

• 返回值: Promise<number>类型，异步的返回表的行数。

row(rowIndex: number): Promise<IWinTableRow>

获取目标行的对象，返回目标行的TableRow对象。

• 返回值: Promise<TableRow>类型，异步的目标行的对象。

rowData(rowIndex: number): Promise<string[]>

获取表格某一行中的所有内容，以字符串数组的形式返回。

• index: number类型，代表行的索引，从0开始计算位置。
• 返回值: Promise<string[]>类型，异步的返回string类型的数组，无论表头中是什么内容。

表格行控件TableRow

用于描述表格中的行的控件，通常由识别，或者由Table对象的row()方法返回。由于提供了类似双向链表的前后表格行对象获取方法next()和previous()，在遍历数据时（比如遍历的获取每一行数据）能够发挥非常好的效果。

类型文件

export interface IWinTableRow {
    next(): Promise<IWinTableRow>;
    previous(): Promise<IWinTableRow>;
    cell(index: number): Promise<IWinTableCell>;
    rowData(): Promise<string[]>;
}

class WinTableRow(WinControl):
	def cell(index: int) -> "WinTableCell"
	def rowData() -> List[str]
	def scrollntoView() -> None

对象操作API介绍

next(): Promise<IWinTableRow>

获取相邻的下一个行控件，也就是下一行的TableRow对象。

• 返回值: Promise<TablRow>，异步的返回下一行的TableRow对象。

previous(): Promise<IWinTableRow>

获取相邻的上一个行控件，也就是上一行的TableRow对象。与next()方法正好相反。

• 返回值: Promise<TablRow>，异步的返回上一行的TableRow对象。

cell(index: number): Promise<IWinTableCell>

获取当前行中指定索引的单元格。就像Table对象有获取行对象的row方法一样，TableRow对象也有获取单元格对象的cell方法。

• index: number类型，代表单元格的索引，从0开始计算位置；
• 返回值: Promise<TableCell>类型，异步的返回该单元格的对象。

rowData(): Promise<string[]>

获取当前行的所有数据，并以字符串数组的形式返回。

• 返回值: Promise<string>，异步的返回行中的所有数据。

单元格控件: TableCell

针对单元格控件的定义和方法。

类型文件定义

export interface IWinTableCell {
    value(): Promise<string>;
    select(): Promise<void>;
    set(value: string): Promise<void>;
    row(): Promise<IWinTableRow>;
    scrollIntoView(): Promise<void>;
}

class WinTableCell(WinControl):
	def value() -> str
	def select() -> None
	def set(value: str) -> None
	def row() -> Union[WinTableRow, WinTreeItem]
	def scrollntoView() -> None

对象操作API

下面是TableCell控件的对象方法。

select(): Promise<void>

选中目标单元格。并且会将目标单元格滚动到可视区域内。

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

set(value): Promise<void>

直接修改单元格的值。

• value: string类型，期望的单元格值。
• 返回值: 不返回任何值的异步方法。

value(): Promise<string>

获取单元格的值。

• 返回值: string类型，目标单元格中的值。

row(): Promise<TableRow>

获取目标单元格所在行的对象，也就是它的父对象，返回所在行的TableRow对象。

• 返回值: Promise<TableRow>类型，异步的目标行的对象。

scrollIntoView(): Promise<void>

滚动到目标单元格位置。

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