表格类型对象

CukeTest为Qt中的表格及其单元格提供了 Table、TableItem 和 HeaderItem 控件。围绕这些控件，CukeTest还提供了一系列API，用于获取和编辑表格数据，满足不同的操作需求。相关类型定义如下：

此外，CukeTest还提供了针对表格控件的演练教程——演练：操作Qt应用中的Table，有助于更深入理解API的使用。

除下面列出的表格控件特有的方法，您还可以使用通用控件方法对表格控件进行更灵活的操作。

表格控件：Table

Table控件用于描述表格视图组件的对象类型。它是Qt中的一种视图组件，能够执行如获取单元格值、设置值、排序等操作。作为一个复合容器，Table控件管理表格中的行和列，并提供对每个单元格的访问和操作。

类型定义

export interface IQTable extends IQtControl {
    cellValue(rowIndex: number, columnNameOrIndex: number | string): Promise<string>;
    setCellValue(rowIndex: number, columnNameOrIndex: number | string, value: string): Promise<void>;
    data(): Promise<string[][]>;
    getItem(rowIndex: number, columnIndex: number): IQTableItem;
    findItem(text: string, options?: {exact?: boolean}): Promise<IQTableItem | null>;
    select(rowIndex: number, columnIndex: number): Promise<IQTableItem>;
    columnData(nameOrIndex: string | number): Promise<string[]>;
    rowData(rowIndex: number): Promise<string[]>;
    scrollToTop(): Promise<void>;
    scrollTo(rowIndex: number, columnIndex: number): Promise<IQTableItem>;
    scrollToBottom(): Promise<void>;

    columnHeaders(): Promise<string[]>;
    rowHeaders(): Promise<string[]>;
    rowCount(): Promise<number>;
    columnCount(): Promise<number>;
}

class QTable(QtControl):
	def cellValue(rowIndex: int, columnNameOrIndex: Union[str, int]) -> str
	def setCellValue(rowIndex: int, columnNameOrIndex: Union[str, int], value: str) -> None
	def data() -> List[List[str]]
	def getItem(rowIndex: int, columnIndex: int) -> "QTableItem"
	def findItem(text: str, options: Optional[FindItemOptional]=None) -> "QTableItem"
	def select(rowIndex: int, columnIndex: int) -> "QTableItem"
    def columnData(nameOrIndex: Union[str, int]) -> List[str]
	def rowData(rowIndex: int) -> List[str]
	def scrollToTop() -> None
	def scrollTo(rowIndex: int, columnIndex: int) -> "QTableItem"
	def scrollToBottom() -> None

	def columnHeaders() -> List[str]
	def rowHeaders() -> List[str]:
	def rowCount() -> int
	def columnCount() -> int

cellValue(rowIndex, columnNameOrIndex)

获取指定行列的单元格值。

参数:

• rowIndex: number - 行索引。
• columnNameOrIndex: string | number - 列名或列索引。

返回值:

• Promise<string> - 返回单元格内容。
• 如果行列位置超出，或者传入的列名不存在，则会抛出1006: OutOfRange。

示例代码

let value = await model.getTable("table").cellValue(1, "Name"); // cellValue with column name
let value = await model.getTable("table").cellValue(1, 1); // cellValue with column index

value = model.getTable("table").cellValue(1, "Name") # cellValue with column name
value = model.getTable("table").cellValue(1, 1) # cellValue with column index

setCellValue(rowIndex, columnNameOrIndex, value)

设置指定单元格的值。

参数:

• rowIndex: number - 行索引。
• columnNameOrIndex: string | number - 列名或列索引。
• value: string - 要设置的值。

返回值:

• Promise<void> - 无返回值。
• 如果行列位置超出，或者传入的列名不存在，则会抛出1006: OutOfRange。

示例代码

await model.getTable("table").setCellValue(1, "Name", "John Doe"); // set cell value with column name
await model.getTable("table").setCellValue(1, 1, "John Doe"); // set cell value with column index

table.setCellValue(1, "Name", "John Doe") # set cell value with column name
table.setCellValue(1, 1, "John Doe") # set cell value with column index

data()

获取整个表格的数据，返回每个单元格的数据作为二维数组。

返回值:

• Promise<string[][]> - 返回表格数据的二维数组。

示例代码

let tableData = await model.getTable("table").data();

table_data = model.getTable("table").data()

假如表格数据如下:

那么data()方法返回的数组如下:

[  
    ['0001', '小王', '男'],  
    ['0002', '小明', '男'],  
    ['0003', '小红', '女']  
]

getItem(rowIndex, columnIndex)

获取指定行列的单元格对象。

参数:

• rowIndex: number - 行索引。
• columnIndex: number - 列索引。

返回值:

• IQTableItem - 返回单元格对象。
• 如果行列位置对应的单元格无效，则会抛出1003: ObjectNotExist的错误。

示例代码

let item = model.getTable("table").getItem(1, 2);

item = model.getTable("table").getItem(1, 2)

findItem(text, options?)

查找包含指定文本的单元格。默认采取模糊搜索，不区分大小写，返回部分匹配的第一个结果。

虽然采取模糊匹配，但是如果有完全匹配的结果，则会最优先返回，无论是作为第几个结果。

参数:

• text: string - 要查找的文本。
• options: （可选）搜索选项。
  • exact: 精确匹配选项，boolean类型，默认为false。设为true后会从模糊搜索改为精确搜索，只返回完全匹配的第一个结果，否则返回null。

返回值:

• Promise<IQTableItem | null> - 找到匹配项则返回单元格对象，否则返回null。

示例代码

let foundItem = await model.getTable("table").findItem("Sample Text");

found_item = model.getTable("table").findItem("Sample Text")

select(rowIndex, columnIndex)

选择指定单元格。这里的选中只保证会触发单元格的聚焦事件，不一定能完全等效于点击单元格，因此有些事件不一定发生（比如选中单元格内的复选框）。

参数:

• rowIndex: number - 行索引。
• columnIndex: number - 列索引。

返回值:

• Promise<IQTableItem> - 返回选择的单元格对象。
• 如果行列位置对应的单元格无效，则会抛出1003: ObjectNotExist的错误。

示例代码

let selectedItem = await model.getTable("table").select(1, 2);

selected_item = model.getTable("table").select(1, 2)

columnData(nameOrIndex)

获取指定列的所有数据。

参数:

• nameOrIndex: string | number - 列名或列索引。

返回值:

• Promise<string[]> - 返回该列的所有单元格内容作为数组。

示例代码

let columnValues = await model.getTable("table").columnData("Name");

column_values = model.getTable("table").columnData("Name")

rowData(rowIndex)

获取指定行的所有数据。

参数:

• rowIndex: number - 行索引。

返回值:

• Promise<string[]> - 返回该行的所有单元格内容作为数组。

示例代码

let rowValues = await model.getTable("table").rowData(1);

row_values = model.getTable("table").rowData(1)

scrollToTop()

将表格滚动到顶部。

返回值:

• Promise<void> - 无返回值。

示例代码

await model.getTable("table").scrollToTop();

model.getTable("table").scrollToTop()

scrollTo(rowIndex, columnIndex)

滚动到指定的单元格位置，并返回该对象。

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

参数:

• rowIndex: number - 行索引。
• columnIndex: number - 列索引。

返回值:

• Promise<IQTableItem> - 返回滚动到的单元格对象。

示例代码

let scrolledItem = await model.getTable("table").scrollTo(5, 3);

scrolled_item = model.getTable("table").scrollTo(5, 3)

scrollToBottom()

将表格滚动到底部。

返回值:

• Promise<void> - 无返回值。

示例代码

await model.getTable("table").scrollToBottom();

table.scrollToBottom()

columnHeaders()

获取表格的列表头名称。

返回值:

• Promise<string[]> - 返回所有列表头名称作为数组。

示例代码

let headers = await model.getTable("table").columnHeaders();

headers = model.getTable("table").columnHeaders()

rowHeaders()

获取表格的行表头名称。

返回值:

• Promise<string[]> - 返回所有行表头名称作为数组。

示例代码

let rowHeaders = await model.getTable("table").rowHeaders();

row_headers = model.getTable("table").rowHeaders()

rowCount()

获取表格的行数。

如果表格含有未被加载的部分，则只会计算已加载的行数。

返回值:

• Promise<number> - 返回表格的总行数。

示例代码

let totalRows = await model.getTable("table").rowCount();

total_rows = model.getTable("table").rowCount()

columnCount()

获取表格的列数，值与columnHeaders()方法返回的数组长度一致。

返回值:

• Promise<number> - 返回表格的总列数。

示例代码

let totalColumns = await model.getTable("table").columnCount();

total_columns = model.getTable("table").columnCount()

单元格控件: TableItem

TableItem控件用于描述表格中的单元格对象，提供了一系列方法以便对单元格进行操作和获取其状态。

类型定义

export interface IQTableItem extends IQtControl {
    select(): Promise<void>;
    data(roleId?: number): Promise<string | number>;
    set(value: string): Promise<void>;
    toggleCheck(checkState: boolean | 'partial'): Promise<void>;

    value(): Promise<string>;
    rowIndex(): Promise<number>;
    columnIndex(): Promise<number>;
    editable(): Promise<boolean>;
    selected(): Promise<boolean>;
    checkState(): Promise<boolean | 'partial'>;
}

class QTableItem(QItemViewItem):
    def select() -> None
    def data(roleId: int = None) -> Union[str, int]
    def set(value: str) -> None
    def toggleCheck(checkState: bool) -> None
    
    def value() -> str
    def rowIndex() -> int
    def columnIndex() -> int
    def editable() -> bool
    def selected() -> bool
    def checkState() -> Union[bool, str]

select()

选择该单元格。

返回值:

• Promise<void> - 无返回值。

示例代码

await model.getTableItem("itemName").select();

model.getTableItem("itemName").select()

data(roleId?)

获取单元格的数据。缺省roleId=0，即DisplayRole。

role值可参考enum Qt::ItemDataRole，自定义的role从256（0x0100）开始。

参数:

• roleId: number - 可选，数据角色标识符。

返回值:

• Promise<string | number> - 返回单元格数据。

示例代码

let cellData = await model.getTableItem("itemName").data();
let customData = await model.getTableItem("itemName").data(257); // custom role

cell_data =  model.getTableItem("itemName").data()
custom_data = model.getTableItem("itemName").data(257) # custom role

set(value)

设置单元格的值。

参数:

• value: string - 要设置的新值。

返回值:

• Promise<void> - 无返回值。

示例代码

await model.getTableItem("itemName").set("New Value");

model.getTableItem("itemName").set("New Value")

toggleCheck(checkState)

切换单元格中复选框的选中状态。

参数:

• checkState: boolean | 'partial' - 选中状态，可以是true、false或'partial'。其中'partial'代表部分选中（常见于含子选项的复选框）。

返回值:

• Promise<void> - 无返回值。

示例代码

await model.getTableItem("itemName").toggleCheck(true);

model.getTableItem("itemName").toggleCheck(True)

value()

获取单元格的值。

返回值:

• Promise<string> - 返回单元格的值。

示例代码

let cellValue = await model.getTableItem("itemName").value();

cell_value =  model.getTableItem("itemName").value()

rowIndex()

获取单元格的行索引。

返回值:

• Promise<number> - 返回单元格的行索引。

示例代码

let rowIndex = await model.getTableItem("itemName").rowIndex();

row_index =  model.getTableItem("itemName").rowIndex()

columnIndex()

获取单元格的列索引。

返回值:

• Promise<number> - 返回单元格的列索引。

示例代码

let columnIndex = await model.getTableItem("itemName").columnIndex();

column_index =  model.getTableItem("itemName").columnIndex()

editable()

检查单元格是否可编辑。

返回值:

• Promise<boolean> - 返回true表示可编辑，false表示不可编辑。

示例代码

let isEditable = await model.getTableItem("itemName").editable();

is_editable =  model.getTableItem("itemName").editable()

selected()

检查单元格是否被选中。

返回值:

• Promise<boolean> - 返回true表示已选中，false表示未选中。

示例代码

let isSelected = await model.getTableItem("itemName").selected();

is_selected =  model.getTableItem("itemName").selected()

checkState()

获取单元格中的复选框选中状态。

返回值:

• Promise<boolean | 'partial'> - 返回true、false或'partial'。其中'partial'代表部分选中（常见于含子选项的复选框）。

示例代码

let state = await model.getTableItem("itemName").checkState();

check_state =  model.getTableItem("itemName").checkState()

表头控件: HeaderItem

HeaderItem控件用于描述表头中的各个元素，通常用于选择相应的行或列。此控件不仅适用于表格，还可用于某些树形结构的表头操作。

如果只需获取表头内容而无需进行实际操作，建议使用Table控件提供的rowHeaders()和columnHeaders()方法来直接获取表头内容的数组。

类型定义

export interface IQHeaderItem extends IQtControl {
    itemIndex(): Promise<number>;
    value(): Promise<string>;
}

class IQHeaderItem(IQtControl):
    def itemIndex() -> int
    def value() -> str

itemIndex()

获取表头项的索引。

返回值:

• Promise<number> - 返回表头项的索引。

示例代码

let index = await model.getHeaderItem("Name").itemIndex();

index = model.getHeaderItem("Name").itemIndex()

value()

获取表头项的值。

返回值:

• Promise<string> - 返回表头项的值。

示例代码

let headerValue = await model.getHeaderItem("Name").value();

header_value = model.getHeaderItem("Name").value()