列表

列表是用于展示模型数据的视图组件，基于分页查询机制实现数据的高效加载和展示。它负责数据的筛选、分页加载和用户交互，支持自定义字段显示、排序规则和各类操作按钮，提供完整的数据列表展示解决方案。

列表元素分层结构为Meta（components.Meta） → Type（components.List） → 实例，开发者可通过JitAI的可视化开发工具快捷地创建列表实例元素。

当然，开发者也可以创建自己的Type元素，或者在自己的App中改写JitAi官方提供的components.ListType元素，以实现自己的封装。

快速开始

基础配置示例

基础列表配置

{
  "fullName": "components.List",
  "type": "components.List", 
  "name": "CustomerList",
  "title": "客户列表",
  "config": {
    "requireElements": [
      {
        "title": "客户数据模型",
        "type": "models.Meta",
        "name": "models.CustomerModel",
        "filter": "",
        "orderBy": ""
      }
    ],
    "fieldIdList": [
      "id",
      "custName", 
      "phone",
      "company"
    ],
    "defaultRender": true,
    "title": [],
    "abstract": [
      "custName"
    ]
  },
  "showTitle": true
}

配置属性说明

属性名	类型	JitAI类型	说明	示例值
requireElements	Array	-	必需元素配置，指定数据模型	[{...}]
fieldIdList	Array	List	显示的字段列表	["id", "name"]
defaultRender	Boolean	Checkbox	是否使用默认渲染	true
title	Array	List	标题配置	[]
abstract	Array	List	摘要字段配置	["custName"]
actionBtn	Array	List	操作按钮配置	[{...}]
toolLeftBtn	Array	List	左侧工具按钮	[{...}]
toolRightBtn	Array	List	右侧工具按钮	[{...}]
bottomBtn	Array	List	底部按钮配置	[{...}]
couldClickRow	Boolean	Checkbox	是否允许点击行	true

变量

displayRowList

类型：RowList<T>
说明：展示多行的数据，只读变量，包含当前页面显示的所有数据行。

获取展示数据

// 获取当前显示的数据列表
const dataList = listComponent.displayRowList.value;

// 获取数据数量
const count = listComponent.displayRowList.length;

// 获取第一行数据
const firstRow = listComponent.displayRowList.firstRow;

activeRow

类型：RowData<T>
说明：操作的单行数据，只读变量，通常在点击行事件中设置。

访问当前行数据

// 获取当前操作的行数据
const currentRow = listComponent.activeRow.value;

// 获取行数据的特定字段
const customerName = listComponent.activeRow.custName?.value;

filter

类型：QFilter
说明：筛选条件，只读变量，用于控制数据查询的过滤条件。

使用筛选条件

// 通过call方法设置筛选条件
await listComponent.call("Q(status='active')");

// 获取当前筛选条件
const currentFilter = listComponent.filter.value;

loading

类型：Numeric
说明：加载状态标识，0表示未加载，1表示正在加载。

监控加载状态

// 检查是否正在加载
const isLoading = listComponent.loading.value === 1;

方法

bindApp

绑定应用实例，通常由框架自动调用。

参数详解

参数名	类型	JitAI类型	必需	说明	示例值
app	Object	-	是	应用实例	app

使用示例

绑定应用实例

// 绑定应用实例（通常由框架自动调用）
listComponent.bindApp(app);

bindPage

绑定页面实例，通常由框架自动调用。

参数详解

参数名	类型	JitAI类型	必需	说明	示例值
page	Object	-	是	页面实例	page

使用示例

绑定页面实例

// 绑定页面实例（通常由框架自动调用）
listComponent.bindPage(page);

call

刷新列表数据，支持传入新的筛选条件。

参数详解

参数名	类型	JitAI类型	必需	说明	示例值
qFilter	String	QFilter	否	筛选条件，Q表达式字符串	"Q(status='active')"

返回值

类型：Promise<void>
说明：异步方法，无返回值。

使用示例

刷新列表数据

// 无条件刷新
await listComponent.call();

// 带筛选条件刷新
await listComponent.call("Q(status='active')");

// 复合条件筛选
await listComponent.call("Q(createTime__range=('2024-01-01', '2024-12-31')) & Q(status__in=['active', 'pending'])");

destroy

销毁组件实例，清理所有资源和事件监听。

使用示例

销毁组件

// 组件销毁时调用，清理资源
listComponent.destroy();

getDataList

获取列表数据的内部方法，支持分页和权限过滤。

返回值

类型：Promise<void>
说明：异步方法，内部使用，会更新displayRowList变量。

使用示例

手动触发数据加载

// 通常由框架自动调用，也可手动调用
await listComponent.getDataList();

getPermConfig

获取组件权限配置。

返回值

类型：Record<string, any> | undefined
说明：返回权限配置对象，无权限时返回undefined。

使用示例

获取权限配置

// 获取当前组件的权限配置
const permConfig = listComponent.getPermConfig();
if (permConfig) {
  console.log('权限配置：', permConfig);
}

publishEvent

发布组件事件。

参数详解

参数名	类型	JitAI类型	必需	说明	示例值
name	String	Stext	是	事件名称	"refresh"
ex	Object	JitDict	否	额外数据	{key: "value"}

返回值

类型：Promise<void>
说明：异步方法，无返回值。

使用示例

发布自定义事件

// 发布刷新事件
await listComponent.publishEvent('refresh');

// 发布带数据的事件
await listComponent.publishEvent('customEvent', {data: 'test'});

runCode

在页面上下文中执行代码字符串。

参数详解

参数名	类型	JitAI类型	必需	说明	示例值
code	String	Stext	是	要执行的代码字符串	"return this.app.name"

返回值

类型：any
说明：返回代码执行结果。

使用示例

执行动态代码

// 执行代码获取应用信息
const appName = listComponent.runCode('return this.app.name');

// 执行复杂逻辑
const result = listComponent.runCode(`
  const data = this.displayRowList.value;
  return data.filter(item => item.status?.value === 'active').length;
`);

setConfig

设置组件配置。

参数详解

参数名	类型	JitAI类型	必需	说明	示例值
next	Object	JitDict	是	新的配置对象	{fieldIdList: [...]}
clean	Boolean	Checkbox	否	是否完全替换配置	false

返回值

类型：void
说明：无返回值。

使用示例

更新组件配置

// 部分更新配置
listComponent.setConfig({
  fieldIdList: ['id', 'name', 'status']
});

// 完全替换配置
listComponent.setConfig(newConfig, true);

subscribeEvent

订阅组件事件。

参数详解

参数名	类型	JitAI类型	必需	说明	示例值
name	String	Stext	是	事件名称	"clickRow"
evtCb	Function	-	是	事件回调函数	async (data) => {}
unSubscribeExist	Boolean	Checkbox	否	是否取消已存在的订阅	true

返回值

类型：string
说明：返回订阅句柄ID。

使用示例

订阅事件

// 订阅行点击事件
const handleId = listComponent.subscribeEvent('clickRow', async (data) => {
  console.log('行被点击', data.activeRow);
});

unSubscribeEvent

取消订阅组件事件。

参数详解

参数名	类型	JitAI类型	必需	说明	示例值
id	String	Stext	是	订阅句柄ID	"handle-123"

返回值

类型：void
说明：无返回值。

使用示例

取消事件订阅

// 取消特定订阅
listComponent.unSubscribeEvent(handleId);

updateConfig

更新组件配置并触发刷新。

参数详解

参数名	类型	JitAI类型	必需	说明	示例值
config	Object	JitDict	是	新的配置对象	{fieldIdList: [...]}

返回值

类型：void
说明：无返回值，会自动触发refresh事件。

使用示例

更新配置并刷新

// 更新配置并自动刷新组件
listComponent.updateConfig({
  fieldIdList: ['id', 'custName', 'phone'],
  couldClickRow: true
});

属性

allFieldDict

类型：Record<string, DataTypeConfig>
说明：所有字段的配置字典，只读属性。

访问字段配置

// 获取特定字段配置
const nameFieldConfig = listComponent.allFieldDict.custName;

// 遍历所有字段
Object.keys(listComponent.allFieldDict).forEach(fieldName => {
  const fieldConfig = listComponent.allFieldDict[fieldName];
  console.log(`字段：${fieldName}，标题：${fieldConfig.title}`);
});

app

类型：App
说明：当前应用实例。

compType

类型：COMPONENT_TYPE
说明：组件类型枚举。

config

类型：ComponentConfig
说明：组件配置对象。

count

类型：number
说明：数据总数，只读属性。

获取总数信息

// 获取数据总数
const totalCount = listComponent.count;

// 计算总页数
const totalPages = Math.ceil(totalCount / listComponent.pageSize);

ModelClass

类型：typeof Jit.BaseModel
说明：关联的数据模型类，只读属性。

访问模型类

// 获取模型类
const ModelClass = listComponent.ModelClass;

// 通过模型类进行数据操作
const result = await ModelClass.query();

name

类型：string
说明：组件名称。

page

类型：BasePage
说明：当前页面实例。

pageNumber

类型：number
说明：当前页码，从1开始，可读写属性。

分页控制

// 获取当前页码
const currentPage = listComponent.pageNumber;

// 设置页码（通常通过call方法重新加载）
listComponent.pageNumber = 2;
await listComponent.getDataList();

pageSize

类型：number
说明：每页数据量，默认为20，可读写属性。

设置页面大小

// 设置每页显示50条数据
listComponent.pageSize = 50;
await listComponent.call();

primaryKey

类型：string
说明：主键字段名，默认为"id"，只读属性。

获取主键信息

// 获取主键字段名
const pkField = listComponent.primaryKey;

showTitle

类型：boolean
说明：是否显示组件标题。

控制标题显示

// 检查是否显示标题
if (listComponent.showTitle) {
  console.log('组件标题：', listComponent.title);
}

title

类型：string
说明：组件标题。

type

类型：string
说明：组件类型标识。

获取组件类型

// 获取组件类型
const componentType = listComponent.type; // "components.List"

事件

clickRow

触发时机：用户点击列表行时触发
数据：activeRow - 被点击的行数据
说明：当配置中couldClickRow不为false时可用。

监听行点击事件

// 订阅行点击事件
listComponent.subscribeEvent('clickRow', async (data) => {
  const clickedRow = data.activeRow;
  console.log('点击的行数据：', clickedRow.value);
});

按钮点击事件

触发时机：用户点击配置的按钮时触发
事件名称：动态生成，格式为click{ButtonId}的驼峰形式
说明：根据actionBtn、toolLeftBtn、toolRightBtn、bottomBtn配置自动生成。

监听按钮点击事件

// 假设有一个id为"add"的按钮，事件名为"clickAdd"
listComponent.subscribeEvent('clickAdd', async () => {
  console.log('添加按钮被点击');
});

// 假设有一个id为"batch-delete"的按钮，事件名为"clickBatchDelete"  
listComponent.subscribeEvent('clickBatchDelete', async () => {
  console.log('批量删除按钮被点击');
});

refresh

触发时机：数据刷新完成后触发
数据：无
说明：在getDataList方法执行完成后自动触发。

监听刷新事件

// 订阅刷新事件
listComponent.subscribeEvent('refresh', async () => {
  console.log('列表数据已刷新');
});