列表类型对象

CukeTest为Qt中的列表及其列表项提供了 List和ListItem控件。围绕这些控件，由于列表视图属于复合结构，CukeTest还提供了一系列API，用于获取和编辑列表中的数据，满足不同的操作需求。相关类型定义如下：

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

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

列表视图控件: List

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

方法名 描述
getItem 返回指定索引上的ListItem对象。
select 选择控件，可以根据控件的索引值选择（例如0，3），也可以使用name属性。
selectedIndex 返回选中行索引。
findItem 搜索文本，并返回ListItem对象，如果搜索不到返回null。
data 返回表格数据内容。
itemCount 获取列表中项的总数。
scrollToTop 滚动到列表顶部。
scrollTo 滚动到指定的项。
scrollToBottom 滚动到列表底部。

类型文件中的定义

JavaScript
Python
export interface IQList extends IQtControl {
    getItem(nameOrIndex: number | string): IQListItem;
    select(index: number): Promise<void>;
    selectedIndex(): Promise<number>;
    findItem(text: string): Promise<IQListItem | null>;

    data(): Promise<string[]>;
    itemCount(): Promise<number>;
    scrollToTop(): Promise<void>;
    scrollTo(index: number): Promise<IQListItem>;
    scrollToBottom(): Promise<void>;
}
class QList(QItemView):
	def data() -> List[str]
	def getItem(nameOrIndex: Union[str, int]) -> "QListItem"
	def select(nameOrIndex: Union[str, int]) -> "QListItem"
	def selectedIndex() -> int
	def findItem(text: str, options: Optional[FindItemOptional]=None) -> "QListItem"
	def itemCount() -> int
	def scrollToTop() -> None
	def scrollTo(index: int) -> "QListItem"
	def scrollToBottom() -> None

对象操作API

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

getItem(nameOrIndex)

获取指定索引位置的列表项对应的自动化对象。

参数

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

返回值

  • IQListItem对象，即ListItem控件的自动化对象。注意这是一个同步方法，不需要await关键字，也不会匹配应用中的控件。只有在执行对象上的异步方法时才会进行匹配。
  • 如果未找到，则抛出Error: 1005: 列表中没有这一项, "ListItem"错误。

示例代码

JavaScript
Python
// 获取第3个列表项（索引为2）
let item = await model.getList("QListView").getItem(2);
# 获取第3个列表项（索引为2）
item = model.getList("QListView").getItem(2)

select(nameOrIndex)

选中指定索引位置或名称的列表项。

参数

  • nameOrIndex: number或string型，number类型时代表列表项处在列表中的第几项（如果是第一项则为0）；string类型时代表目标列表项的名称，即使多个时也只会选中第一个。

返回值

示例代码

JavaScript
Python
// 选中第3个列表项
await model.getList("QListView").select(2);
# 选中第3个列表项
item = model.getList("QListView").select(2)

selectedIndex()

获得列表视图中的选中选项的索引位置。

返回值

  • Promise<number>类型，表示选中选项的索引位置。需要使用await关键字取出其中的结果。

示例代码

JavaScript
Python
// 获取选中项的索引
let index = await model.getList("QListView").selectedIndex();
console.log(index);
# 获取选中项的索引
index = model.getList("QListView").selectedIndex()
print(index)

findItem(text, options)

根据名称搜索目标列表项，返回目标列表项的自动化对象ListItem，默认采取模糊搜索，不区分大小写，返回部分匹配的第一个结果，如果没有搜索到则返回null。

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

参数

  • text: string类型，期望目标列表项的内容或者文本；
  • options：（可选）搜索选项，是一个对象，可以包含以下属性：
    • exact: 精确匹配选项，boolean类型，默认为false。设为true后会从模糊搜索改为精确搜索，只返回完全匹配的第一个结果，否则返回null。

返回值

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

示例代码

JavaScript
Python
// 查找名称中包含 'Windows' 的列表项
await model.getList("QListView").findItem('Windows');
# 查找名称中包含 'Windows' 的列表项
item = model.getList("QListView").findItem('Windows')

data()

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

返回值

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

示例代码

JavaScript
Python
// 获取列表数据
let data = await model.getList("QListView").data();
console.log(data);
# 获取列表数据
data = model.getList("QListView").data()
print(data)

itemCount()

获取列表中项的总数。如果列表视图采取了批次加载（或者可以理解为延迟加载方式），则只会计算已加载的数据，未加载的数据不会被计入。

返回值

  • Promise<number>类型，表示当前列表中的选项数量。需要使用await关键字取出其中的结果。

示例代码

JavaScript
Python
// 获取列表项总数
let count = await model.getList("QListView").itemCount();
console.log(`列表项总数: ${count}`);
# 获取列表项总数
count = model.getList("QListView").itemCount()
print(f"列表项总数: {count}")

scrollToTop()

滚动到列表顶部。

返回值

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

示例代码

JavaScript
Python
// 滚动到顶部
await model.getList("QListView").scrollToTop();
# 滚动到顶部
model.getList("QListView").scrollToTop()

scrollTo(index)

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

参数

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

返回值

示例代码

JavaScript
Python
// 滚动到第2个列表项
await model.getList("QListView").scrollTo(1);
# 滚动到第2个列表项
model.getList("QListView").scrollTo(1)

scrollToBottom()

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

返回值

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

示例代码

JavaScript
Python
// 滚动到底部
await model.getList("QListView").scrollToBottom();
# 滚动到底部
model.getList("QListView").scrollToBottom()

列表项控件: ListItem

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

方法名 描述
value 控件值。
data 读取列表项的数据。
select 选中列表项。
scrollIntoView 滚动到视图位置。
toggleCheck 设置选中的值: "true" 为选中, "false" 取消选中，"partial"部分选中。
editable 是否可编辑。
selected 是否已选中。
checkState 检查控件是否被选中，"true"选中，"false"未选中，"partial"部分选中。

类型文件定义

JavaScript
Python
export interface IQListItem extends IQtControl {
    value(): Promise<string>;
    data(roleId?: number): Promise<string>;
    select(): Promise<void>;
    scrollIntoView(): Promise<void>;
    editable(): Promise<boolean>;
    selected(): Promise<boolean>;
    toggleCheck(checkState: boolean | 'partial'): Promise<void>;
    checkState(): Promise<boolean | 'partial'>;
}
class QListItem(QItemViewItem):
    def value() -> str
    def data(roleId: Optional[int] = None) -> str
    def select() -> None
    def scrollIntoView() -> None
    def editable() -> bool
    def selected() -> bool
	  def toggleCheck(checkState: bool) -> None
    def checkState() -> bool

对象操作API

value()

获得列表项的内容。

返回值

  • Promise<string>类型，列表项的内容。需要使用await关键字取出其中的结果。

示例代码

JavaScript
Python
// 获取项的值
const value = await model.getListItem("item").value();
console.log(value);
# 获取项的值
value = model.getListItem("item").value()
print(value)

data(roleId)

获取列表项在指定 roleId 下的数据。缺省 roleId = 0（DisplayRole）。

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

参数:

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

返回值

  • Promise<string>类型，列表项的数据。

示例代码

JavaScript
Python
// 读取数据
let text = await model.getListItem("item").data();
let custom = await model.getListItem("item").data(257); // 读取自定义 role（如 257）
# 读取数据
text = model.getListItem("item").data()
custom = model.getListItem("item").data(257) # 读取自定义 role（如 257）

select()

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

返回值

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

示例代码

JavaScript
Python
// 选中项
await model.getListItem("item").select();
# 选中项
model.getListItem("item").select()

editable()

列表项是否可以被编辑，可编辑为true，不可编辑为false。

返回值

  • boolean类型，是否可编辑。

示例代码

JavaScript
Python
// 检查是否可编辑
const editable = await model.getListItem("item").editable();
console.log(editable);
# 检查是否可编辑
editable = model.getListItem("item").editable()
print(editable)

selected()

列表项的选中情况，已选中为true，未选中(折叠)为false。

返回值

  • boolean类型，是否已选中。

示例代码

JavaScript
Python
// 检查是否已选中
const selected = await model.getListItem("item").selected();
console.log(selected);
# 检查是否已选中
selected = model.getListItem("item").selected()
print(selected)

scrollIntoView()

滚动到列表项位置。

返回值

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

示例代码

JavaScript
Python
// 滚动到视图内
await model.getListItem("item").scrollIntoView();
# 滚动到视图内
model.getListItem("item").scrollIntoView()

toggleCheck(checkState)

选中或是取消选中列表项中的复选框。

参数

  • checkState: boolean类型或是partial字符串。true代表选中，false代表未选中，"partial"代表部分选中（常见于含子选项的复选框）。

返回值

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

示例代码

JavaScript
Python
// 切换勾选状态
await model.getListItem("item").toggleCheck(true);
await model.getListItem("item").toggleCheck(false);
# 切换勾选状态
model.getListItem("item").toggleCheck(True)
model.getListItem("item").toggleCheck(False)

checkState()

获取列表项中的复选框选中状态。

返回值

  • boolean类型或是partial字符串。true代表选中，false代表未选中，"partial"代表部分选中（常见于含子选项的复选框）。

示例代码

JavaScript
Python
// 获取勾选状态
const state = await model.getListItem("item").checkState();
console.log(state);
# 获取勾选状态
state = model.getListItem("item").checkState()
print(state)

results matching ""

全部 API Walkthrough 其他

    No results matching ""