列表类型对象
针对列表控件以及列表项控件,模型管理器提供了List
和ListItem
两个对象类型。由于列表视图属于复合结构,因此CukeTest提供了很多方法,可以结合表格视图Table
和树视图Tree
理解。
针对列表控件还提供了相应的演练——演练:操作Qt应用中的List,能够大大加深对于API的理解程度。
列表视图控件: List
用于描述列表视图控件的对象类型——List
,由于是Qt的一种视图组件,作为一种列表项的容器而存在的。
类型文件中的定义
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: number | string): IQListItem
获取指定索引位置的列表项对应的自动化对象。
- nameOrIndex:
number
或string
型,代表列表项处在列表中的第几项。如果是第一项则为0。 - 返回值:
IQListItem
对象,即ListItem
控件的自动化对象。注意这是一个同步方法,不需要await
关键字,也不会匹配应用中的控件。只有在执行对象上的异步方法时才会进行匹配。
findItem(text: string, options?:object): Promise<IQListItem | null>
根据名称搜索目标列表项,返回目标列表项的自动化对象ListItem
,默认采取模糊搜索,不区分大小写,返回部分匹配的第一个结果,如果没有搜索到则返回null
。
虽然采取模糊匹配,但是如果有完全匹配的结果,则会最优先返回,无论是作为第几个结果。
- text:
string
类型,期望目标列表项的内容或者文本;- options: (可选)搜索选项。
- exact: 精确匹配选项,
boolean
类型,默认为false
。设为true
后会从模糊搜索改为精确搜索,只返回完全匹配的第一个结果,否则返回null
。- 返回值:
Promise<IQListItem>
或Promise<null>
类型,异步的搜索应用中的目标列表项,如果没有搜索到则返回null
。
select(nameOrIndex): Promise<IQListItem>
选中指定索引位置或名称的列表项。
- nameOrIndex:
number
或string
型,number
类型时代表列表项处在列表中的第几项(如果是第一项则为0);string
类型时代表目标列表项的名称,即使多个时也只会选中第一个。 - 返回值:
ListItem
类型,返回被选中列表项的对象。
scrollToTop(): Promise<void>
滚动到列表顶部。
- 返回值: 不返回任何值的异步方法。
scrollTo(index): Promise<IQListItem>
滚动到目标索引位置,并返回此对象。如果目标位置还未加载,会一直加载到目标索引位置加载为止。
- index:
number
型,代表列表项处在列表中的第几项。如果是第一项则为0。 - 返回值:
ListItem
类型,返回被选中列表项的对象。
scrollToBottom(): Promise<void>
滚动到列表底部。这里的列表底部指的是已加载列表的底部,是为了避免非常长的列表带来的性能问题。
- 返回值: 不返回任何值的异步方法。
data(): Promise<string[]>
获得列表视图中的数据并返回。如果列表视图采取了批次加载(或者可以理解为延迟加载方式),则只会获得已加载的数据,未加载的数据无法被获取到。
- 返回值:
Promise<string[]>
类型,由列表选项值组成的字符串数组。需要使用await
关键字取出其中的结果。
rowCount(): Promise<number>
获得列表视图中的选项数量。如果列表视图采取了批次加载(或者可以理解为延迟加载方式),则只会计算已加载的数据,未加载的数据不会被计入。
- 返回值:
Promise<number>
类型,表示当前列表中的选项数量。需要使用await
关键字取出其中的结果。
selectedIndex(): Promise<number>
获得列表视图中的选中选项的索引位置。
- 返回值:
Promise<number>
类型,表示选中选项的索引位置。需要使用await
关键字取出其中的结果。
列表项控件: ListItem
针对列表中的列表项控件,模型管理器提供了ListItem
类型。与List
对象的提供的操作列表项的方法(比如scrollTo()
、select()
不同,列表项控件自身就包含了位置信息,因此它的方法都不需要额外再传入参数。
类型文件定义
export interface IQListItem extends IQtControl {
select(): Promise<void>;
scrollIntoView(): Promise<void>;
toggleCheck(checkState: boolean | 'partial'): Promise<void>;
value(): Promise<string>;
editable(): Promise<boolean>;
selected(): Promise<boolean>;
checkState(): Promise<boolean | 'partial'>;
}
class QListItem(QItemViewItem):
def value() -> str
def select() -> None
def scrollIntoView() -> None
def itemIndex() -> int
def checkState() -> bool
def toggleCheck(checkState: bool) -> None
对象操作API
value(): Promise<string>
获得列表项的内容。
- 返回值:
Promise<string>
类型,列表项的内容。需要使用await
关键字取出其中的结果。
select(): Promise<void>
选中列表项。如果该项不在可视范围内,还会自动的滚动到该项所在的位置。
- 返回值: 不返回任何值的异步方法。
editable(): Promise<boolean>
列表项是否可以被编辑,可编辑为true
,不可编辑为false
。
- 返回值:
boolean
类型,是否可编辑。
selected(): Promise<boolean>
列表项的选中情况,已选中为true
,未选中(折叠)为false
。
- 返回值:
boolean
类型,是否已选中。
scrollIntoView(): Promise<void>
滚动到列表项位置。
- 返回值: 不返回任何值的异步方法。
toggleCheck(checkState: boolean | 'partial'): Promise<void>
选中或是取消选中列表项中的复选框。
- checkState:
boolean
类型或是partial
字符串。true
代表选中,false
代表未选中,"partial"
代表部分选中(常见于含子选项的复选框)。 - 返回值: 不返回任何值的异步方法。
checkState(): Promise<boolean | 'partial'>
获取列表项中的复选框选中状态。
- 返回值:
boolean
类型或是partial
字符串。true
代表选中,false
代表未选中,"partial"
代表部分选中(常见于含子选项的复选框)。