视图列表配置总览

视图列表是实体对象数据的浏览器，配置列、搜索、排序、按钮等元素，决定用户在列表页看到和能做什么。

概述

视图列表（MetaView）挂在实体对象下，用于以表格形式展示对象数据。一个对象可以有多个视图列表，例如「全部数据」「我的待办」「已归档」分别对应一个列表，供不同场景使用。

在 开发中心 → 对象配置 → 视图列表 中维护某个对象下的视图列表：新建、编辑、复制、查看详情，点击名称即可进入视图列表编辑器进行布局配置。

与对象、字段的关系

视图列表只能使用所属实体对象已定义的字段作为列与搜索项；视图列表本身不创造数据，它引用对象的字段来展示和筛选数据。因此配置视图列表前，应先完成对象与字段的建模。

视图列表与对象、字段、按钮的关系

创建视图列表

进入目标实体对象的对象配置页面，打开「视图列表」页签。
点击 创建视图，填写名称、标题、描述后提交。
创建成功后会自动打开该视图列表的编辑器（只有「创建」会自动跳转，编辑不会）。
在编辑器中依次配置数据列表列、功能按钮、批量操作按钮、列表行按钮与视图列表设置。
点击保存提交布局，页面会刷新以加载最新配置。

编辑器界面结构

编辑器顶部为操作区，下方分为四个配置卡片：

区域	说明
顶部操作区	预览、操作授权、移动端设置、视图列表设置、保存
视图按钮配置	配置列表工具栏上的功能按钮
批量操作按钮配置	配置勾选数据后显示的批量操作按钮
列表配置	左侧勾选字段，右侧拖动排列列顺序
列表行按钮配置	配置每条数据行上的操作按钮

顶部操作区按钮：

按钮	说明
预览	以弹窗预览当前视图列表的实际效果
操作授权	跳转到应用授权页面，为该视图列表配置资源权限
移动端设置	配置移动端的页面模板与卡片点击事件流
视图列表设置	配置视图标题、分页、隐藏搜索/工具栏等
保存	保存当前布局（连同按钮、列、设置一起提交）

元素类型速览

视图列表由四类可配置元素构成，各自的配置方法见对应文档：

元素类型	模型	说明	文档
数据列表	`ListViewItem`	配置展示哪些字段列、列搜索与排序	数据列表
功能按钮	`MetaViewButtonItem`	列表工具栏上的主功能按钮	功能按钮
批量操作按钮	`MetaViewBatchButtonItem`	勾选数据后出现的批量操作按钮	批量操作按钮
列表行按钮	`MetaViewListButtonItem`	每行数据上的操作按钮，支持动态显隐	列表行按钮

视图列表设置

点击顶部 视图列表设置 可配置视图列表级别的基础属性：

配置项	说明
视图标题	视图列表页面标题，为空时回退到名称
列表标题	表格区域的标题
自定义查询数据接口	覆盖默认查询逻辑的接口，需为「数据组件数据源」类接口
默认分页大小	每页条数，可选 15 / 30 / 45 / 60 / 100，默认 15
列最小宽度	列的全局最小宽度（px），0–300
展示序号列	是否在首列展示行序号
固定首列	水平滚动时是否将第一列固定在左侧
隐藏搜索按钮	是否隐藏搜索区
隐藏工具栏	是否隐藏工具栏

移动端设置 包含：

配置项	说明
移动端页面模板	每行数据在移动端渲染所用的页面模板
移动端卡片点击事件流	移动端点击单行卡片时执行的事件流

自定义查询数据源

在「视图列表设置」中选择自定义查询数据接口，可覆盖默认的列表查询逻辑，该接口需为「数据组件数据源」类接口。适用于跨表关联查询、数据计算后展示、复杂权限过滤、从外部系统取数等场景。

搜索默认值

列的「搜索默认值」（SearchDefaultValue）在执行搜索时动态解析，支持特殊内置值：

默认值类型	说明	应用场景
当前时间	动态解析为当前时间	日期字段的默认筛选值
当前用户	动态解析为当前登录用户	按创建人筛选
当前组织	动态解析为当前用户所属组织	按部门筛选

不同字段类型可用的搜索方式不同，详见数据列表。

数据导出

通过功能按钮或批量操作按钮配置「数据导出」动作即可导出数据：

配置项	说明
导出格式	Excel（.xlsx）
导出字段	默认导出可见列
异步导出	数据量大时建议开启，避免请求超时

大数据量导出建议使用异步导出任务，完成后通知用户下载；敏感数据注意权限控制与脱敏；导出文件由服务端生成并提供下载链接。

最佳实践

列设计：控制列数量（建议不超过 10 列），重要字段靠左，操作列固定右侧，必要时开启「固定首列」。
筛选设计：常用筛选项 3–5 个，复杂筛选折叠到「更多筛选」，为筛选项设置合理的默认值。
按钮布局：主要操作靠左、危险操作靠右，并开启「展示为危险按钮」与二次确认。
性能优化：始终使用服务端分页，只加载必要字段，复杂计算交由后端接口处理。

常见问题

如何让某些列始终可见？ 在「视图列表设置」中开启「固定首列」，或在列配置中设置列最小宽度。

如何实现跨页批量操作？ 批量操作仅针对当前页已勾选的数据；如需跨页操作，建议使用功能按钮结合事件流实现。

筛选条件太多怎么办？ 将常用筛选条件设为「默认展示在搜索区」，其余字段保留搜索能力但不默认展示。

下一步

数据列表 - 配置展示字段列、列搜索与排序
功能按钮 - 配置列表工具栏按钮
批量操作按钮 - 配置批量操作
列表行按钮 - 配置行内操作与动态显隐
行按钮脚本 API - 行按钮动态显示脚本
列表行自定义渲染 - 用 HTML/JavaScript 渲染列
视图列表 - 视图列表概念文档

属性明细

以下内容面向技术实现与 AI 检索，说明视图列表模型的属性类型、含义与存储。

视图列表属性

视图列表对应实体 MetaView（数据表 system_metaview）：

属性名	类型	含义	取值/存储值
`_id`	string(GUID)	视图列表主键	例：`9f1c0b2e-...`
`AppId`	string(GUID)	所属应用	应用主键
`MetaObjectId`	string(GUID)	所属实体对象	对象主键
`Name`	string	视图列表名称	显示名称，必填
`Title`	string	视图列表标题	为空时前端回退到 `Name`
`TableTitle`	string	列表标题	纯文本，可为空
`DefaultPageSize`	int	默认页大小	默认 `15`，可选 15/30/45/60/100
`Description`	string	描述	纯文本，可为空
`Customized`	bool	是否被自定义过	系统内置视图修改后为 `true`
`CustomCreated`	bool	是否由用户创建	用户新建为 `true`
`FirstColumnFixed`	bool	首列是否固定	`true`/`false`
`GetListInterfaceId`	string(GUID)	自定义查询数据接口	数据组件数据源类接口主键，为空则用默认查询
`ListItems`	List<MetaViewListItem>	数据列表列配置	JSON 序列化存储
`ButtonItems`	List<MetaViewButtonItem>	功能按钮	JSON 序列化存储
`BatchButtonItems`	List<MetaViewBatchButtonItem>	批量操作按钮	JSON 序列化存储
`ListButtonItems`	List<MetaViewListButtonItem>	列表行按钮	JSON 序列化存储
`IsQuickInitialization`	bool	是否快速初始化	`true`/`false`
`Properties`	MetaViewProperties	扩展属性	JSON 序列化存储

扩展属性 MetaViewProperties

属性名	类型	含义	取值/存储值
`DisplayIndex`	bool	是否展示序号列	`true`/`false`
`ColumnMinWidth`	int?	列最小宽度	0–300（px）
`HideSearch`	bool	隐藏搜索功能	`true`/`false`
`HideToolbar`	bool	隐藏工具栏	`true`/`false`
`MobileItemRenderTemplate`	string(GUID)	移动端行渲染页面模板	`MetaView` 分类的页面模板主键
`MobileItemClickActionPipeline`	string	移动端卡片点击事件流	事件流 JSON 字符串

存储示例

{
  "_id": "3c9a1e02-6b7d-4f2a-9e11-8a2b6c4d0f31",
  "AppId": "9f1c0b2e-2d3a-4e6f-9c11-0f7a5b8d2e10",
  "MetaObjectId": "a1b2c3d4-1111-2222-3333-444455556666",
  "Name": "全部图书",
  "Title": "图书列表",
  "TableTitle": "在架图书",
  "DefaultPageSize": 30,
  "FirstColumnFixed": true,
  "GetListInterfaceId": null,
  "Customized": false,
  "CustomCreated": true,
  "IsQuickInitialization": false,
  "ListItems": [
    {
      "MetaFieldId": "book-name",
      "Code": "name",
      "Name": "书名",
      "MetaFieldType": 2,
      "ListIsHide": false,
      "SearchDefaultDisplay": true,
      "SearchType": "ct",
      "SortEnable": true,
      "SortType": "ascend",
      "SortPriority": 0
    }
  ],
  "ButtonItems": [],
  "BatchButtonItems": [],
  "ListButtonItems": [],
  "Properties": {
    "DisplayIndex": true,
    "ColumnMinWidth": 100,
    "HideSearch": false,
    "HideToolbar": false,
    "MobileItemRenderTemplate": null,
    "MobileItemClickActionPipeline": "[]"
  }
}

接口	说明
`POST /api/MetaView/Create`	创建视图列表，返回新视图 `_id`
`POST /api/MetaView/Edit`	编辑视图列表基础信息
`POST /api/MetaView/SaveLayout`	保存布局（列、按钮、设置）
`POST /api/MetaView/Copy?id={id}`	复制视图列表
`GET /api/MetaView/Get?id={id}`	开发者视角获取详情（含完整布局）
`GET /api/MetaView/GetForUser?id={id}`	用户视角获取详情
`POST /api/MetaView/GetListAsync`	分页获取视图列表集合

概述​

视图列表与对象、字段、按钮的关系​

创建视图列表​

编辑器界面结构​

元素类型速览​

视图列表设置​

自定义查询数据源​

搜索默认值​

数据导出​

最佳实践​

常见问题​

下一步​

属性明细​

视图列表属性​

扩展属性 MetaViewProperties​

存储示例​

相关接口​

概述