weaver-e10-builder 1.6.16 → 1.7.0

package/skill-docs/references/ebuilder-designer/guide-list.md

@@ -0,0 +1,339 @@
+# 页面列表组件配置指南
+
+## 功能介绍与阅读导航
+
+本指南统一说明普通页面 NList 列表的数据来源、显示字段与样式、数据权限、分组统计、扩展列、过滤排序、搜索、操作按钮、事件、表头勾选、展示分组及上下级。适用于 PC 与移动端；终端配置分别读取和修改，不能从某次设计器双端同步推断所有设置自动同步。
+
+三个配置层次分别处理：数据源决定记录来源及查询结果；展示与交互决定字段排布、分组树、搜索和操作；页面/组件/按钮权限决定入口和操作范围，不能用隐藏或禁用代替数据权限。
+
+| 内容 | 本文位置 | 命令入口 |
+|---|---|---|
+| 数据来源、数据权限、字段、统计与扩展、运行设置和视图切换 | 列表高级配置 | designer list advanced |
+| 固定过滤、排序、普通/快捷/分类搜索、按钮属性与权限 | 列表过滤、搜索与操作按钮 | designer list controls |
+| 表头、勾选禁用、展示分组、上下级与层级限制 | 列表表头、勾选、分组与上下级 | designer list advanced presentation |
+| 列表/数据/按钮点击动作 | 本文对应事件小节，并参阅事件指南 | designer event |
+
+各节包含原生字段、明确码表、配置方式、一般示例及适用边界。已知码表直接使用；来源字段、选项和原生对象通过当前环境查询，不把示例中的名称、数量或类型当成平台限制。尚未明确的配置含义在相应小节说明，不影响已有原生配置的保留。
+
+## 列表高级配置
+
+NList 列表可设置显示样式、数据源权限及范围、数据分组统计、计算扩展和数据点击事件。查询分组统计改变返回数据结构；展示层 enableGroup 只是列表展示分组，两者分别配置。
+
+### 命令
+
+```sh
+e10-cli designer list advanced get <pageId> --comp <compId> --terminal pc
+e10-cli designer list advanced fields <pageId> --comp <compId> --terminal pc
+e10-cli designer list advanced set <pageId> --comp <compId> --terminal pc --config @list.json --apply
+```
+
+支持 pc/mobile，分别配置真实组件 ID。省略 --apply 仅预览。get 返回完整原生配置；fields 查询当前数据源字段，包括字段类型、浏览参数和可用条件等。不要根据示例固定候选字段或聚合项数量。
+
+配置对象包含四个可选入口：
+
+| 入口 | 作用 |
+|---|---|
+| config | 原生列表配置局部合并；对象递归合并、数组整段替换、null 显式写入 |
+| dataSetup | 局部合并 dataset.ebuilderDataConfig.dataSetup |
+| groups | 完整替换 dataset.dataGroupConfig；[] 清空 |
+| extensions | 完整替换 dataset.dataExtConfig；[] 清空 |
+
+事件、权限、组件类型和布局位置不能通过 config 覆盖，使用对应命令。其他平台字段允许原生配置，不将抓包出现的几个字段作为能力白名单。
+
+### 显示与数据范围
+
+列表样式由 `config.mode` 控制，显示字段与数据源范围分别设置。
+
+| 列表样式 | mode |
+|---|---|
+| 表格式 | `9` |
+| 列表式 | `12` |
+| 左图式 | `13` |
+| 上图式 | `15` |
+| 横向列表式 | `14` |
+| 网格列表式 | `17` |
+
+切换卡片类样式还涉及 listField/cardLayout 等字段，不能认为只改 mode 就能完整生成卡片。应使用对应配置定义或已有完整样式配置。
+
+```json
+{"config":{"pageSize":20},"dataSetup":{"dataPermission":"HAVE_PERMISSION_DATA","dataType":"ALL","listDataRange":"ALL"}}
+```
+
+数据源设置中的三项分别配置：
+
+| 页面设置 | 字段 | 可选值 |
+|---|---|---|
+| 数据权限 | dataPermission | ALL 所有数据；HAVE_PERMISSION_DATA 有权限的数据 |
+| 数据类型 | dataType | ALL 全部；CONCERNED_DATA 我关注的数据；SHARED_DATA 共享给我的数据 |
+| 数据范围 | listDataRange | ALL 全部；FORM 仅卡片数据；FLOW 仅流程数据 |
+
+三项位于 dataset.ebuilderDataConfig.dataSetup，控制记录范围，不是显示字段。enableDensensitization 是原生开关字段，实际启用效果和权限依赖需按环境核对。
+
+### 查询分组统计
+
+GROUP 为分组维度，CALCULATE 为统计计算行。字段聚合 fType=dataField；自定义计算 fType=calField。聚合码表：COUNT 计数、SUM 求和、MAX 最大值、MIN 最小值、AVG 平均值。此为明确码表，不等同于任意字段都能使用所有聚合。
+
+字段行保留完整 field 描述，选用 fields 返回值；fieldId 使用来源字段名，shortKey 是输出字段标识，不是原字段 ID。每行 id 唯一，输出标识在排序、过滤、计算式引用中保持一致。
+
+```json
+{"groups":[{"id":"group-category","type":"GROUP","fieldId":"<sourceFieldName>","shortKey":"group_category","field":{"id":"<fieldId>","name":"<sourceFieldName>","compType":"<componentType>"},"showName":{"nameAlias":"分类"}}]}
+```
+
+示例 field 只展示形状，实际使用完整查询对象。自定义计算保存 cusCalConf.calName/calStr；不能依据一条示例公式推断公式语法、聚合类型或可引用字段的全部规则。
+
+修改 groups 后核查 tableField/listField/cardLayout、order、filter、personalFields、searchConditions、enableGroup、checkboxDisabledSet、CLICKDATA 事件等关联配置。平台设计器会重建其中部分配置；CLI 不自动清空，需在同一次 config 中提供适配后的关联设置。保留不适用旧字段会影响运行结果，保存回读无法代替业务结果检查。
+
+### 数据扩展
+
+extensions 使用完整原生行，包含唯一 id、shortKey、type 以及对应扩展参数。当前日志中的本地计算扩展示例使用 type=EXTENSION、extType=local、extTableType=local；extFieldType 描述输出类型，scale 为精度，extTitle.nameAlias 为标题；joinDatasource.queryFields 保存可引用字段，extCalConf 保存 calName/calStr/calField。名称为 joinDatasource 不代表日志已覆盖跨表关联扩展。
+
+可通过 get 读取原规则后修改、重排、删除；[] 清空。其他扩展类型保留通用写入通道，但需具备对应真实结构和字段依赖，不能把本地计算形状套给所有扩展类型。
+
+### 每条数据点击事件
+
+```sh
+e10-cli designer event get <pageId> --comp <compId> --terminal pc
+e10-cli designer event set <pageId> --comp <compId> --terminal pc --trigger CLICKDATA --config @action.json --apply
+```
+
+CLICKDATA 仅用于列表整体事件定位，独立于 CLICK/DIDMOUNT；每种触发支持有序多动作及递归条件分支。动作查询、配置、启停、删除沿用 [事件指南](events/guide-events.md)，不限定打开页面。行上下文参数使用该动作实际数据结构，不能猜测字段占位表达式。
+
+### 保存与检查
+
+保存完整布局前检查编辑状态和并发变化；保存后检查列表配置、其他组件、源码与另一终端，释放本次软锁。字段使用缓存的时间与标识允许由服务端更新。字段计算结果、聚合统计值、数据权限实际范围及前台样式仍需用真实数据检查。
+
+### 其他表字段列
+
+扩展类型 `extType:"other"` 为其他表字段列，区别于当前表计算列的 local。保存字段结构为：
+
+- `joinDatasource.dataset`：选择的其他数据源完整描述。
+- `joinDatasource.joinConditions`：关联条件数组，每行含唯一 id、mainField（当前源的转换字段）、subField（其他源的对应字段），均保留完整字段描述。
+- `joinDatasource.queryFields`：其他源中要显示的字段数组，字段保留 shortKey 等输出标识。
+- `joinDatasource.aggregations`：关联取值的聚合配置，本次样例为空数组，不能推断非空聚合码表。
+- `extFieldType`：扩展输出类型；`extTitle.nameAlias` 为列名称，id/shortKey/fieldAlias 为规则与输出标识。
+
+先查询当前和其他数据源的字段，再选择匹配字段及输出字段。不要固定转换字段只能为文本，或固定只能关联一行条件。本次样例为当前源名称匹配其他表项目名称并返回关联客户，不应据此固定业务字段。
+
+`designer list advanced fields` 默认把现有扩展规则放入字段接口 params，可读取扩展后的字段；`--params @rules.json` 显式提供待查询规则数组。查询字段元数据不等于规则已保存。扩展写入仍使用 `set --config` 的 extensions 数组；其他表字段列的完整规则保存于 dataset.dataExtConfig，并同步 dataExtMemoTime 和 hasChangeExtConfig。CLI 自动写入变更标志及时间；完整布局保存后重新读取核对。字段接口接受规则不代表关联结果正确，仍需使用实际数据检查。
+
+其他表字段列在字段查询请求与最终保存中使用同一 joinDatasource 结构，包括 dataset、joinConditions、queryFields、aggregations。不要将 mainField/subField 误作布尔标记：此处它们是关联左右字段对象，各自内部也可能有 mainField 布尔属性。转换字段来自当前列表源，对应字段和显示字段来自其他源。输出类型可为 Ebuilder 等关联类型，不能只开放文本和数字。
+
+数据源变更标志：数据权限变更 hasChangePermissions，分组变更 hasChangeGroupFilter，扩展变更 hasChangeExtConfig。命令分别同步对应标志，不把原来的 false 原样保留。多条命中时如何取值、非空 aggregations 的配置及其支持字段仍需进一步明确；不从空数组样例推断这些行为。
+
+### 功能入口与配置层次
+
+数据源选择窗口负责选择来源：e-Builder、数据加工、业务模块、外部数据源、数据集合、互通资源。来源记录使用各自真实 groupId/id/type 等描述，不能把所有来源都固定成 EB 表单。`designer list dataset-set` 是表单绑定快捷命令；其他来源可通过 advanced set 的 config.dataset 提供平台完整来源对象。现有字段查询以所选 dataset 描述发起请求，不固定为示例表。
+
+选定来源后的数据源设置包括三个页签：数据权限、数据分组、数据扩展。数据分组页面上方的数据过滤与分组维度、汇总字段一起影响查询；分组字段包含字段、分组设置、别名，汇总字段包含字段类型、字段、计算方式、别名。分组设置的具体值应使用所选字段的完整配置，不从分类字段示例推断所有字段的分组方式。
+
+数据扩展有两类：当前表计算列（名称、数据表类型、计算公式、输出字段类型等），其他表字段列（名称、数据源、转换字段、对应字段、显示字段）。前者通过 extCalConf 表达计算，后者通过 joinDatasource 表达关联，两者结构不能互相套用。输出字段可为文本、数值、关联等平台提供的类型，不把截图默认的单行文本作为固定限制。
+
+显示字段属于展示层：表格式使用 tableField，其他样式还涉及 listField/cardLayout。输出查询字段变化后，应更新展示层引用，而不是通过 listDataRange 选择列。示例中的名称、字段、数量和计算表达式均可自行替换，保留真实字段描述、类型依赖和关联引用即可。
+
+### 列表运行与视图切换
+
+这些设置通过 advanced set 的 config 对象局部合并写入，PC/移动端分别配置。开启视图切换不等同于改变当前默认列表 mode；每个备选视图携带自己的 viewSet。
+
+| 原生字段 | 作用及结构 |
+|---|---|
+| pageMode / customPage | pageMode：part 页码分页、more 点击加载更多、scroll 滚动分页、none 隐藏分页 |
+| autoScroll | visible 开关、scrollDirection 方向、scrollRate.second/item 滚动间隔及条数 |
+| showCount | 显示总数，使用原生字符串值 |
+| timedRefresh | time 刷新档位，`-1` 表示不刷新；customTime 自定义时间，customTimeUnit 单位 |
+| emptyCustomData | hideForNoData、showForNoData，以及 tipCustom 自定义无数据展示 |
+| dataPreLoad | 数据预加载开关 |
+| dataLazyLoad | enable 延迟加载开关；等待触发数据加载时可选不显示 loading 或显示 loading，showLoading：1 不显示 loading、2 显示 loading |
+| enableSwitchView | enable 开关、viewName 默认视图名、viewList 备选视图数组 |
+
+```json
+{"config":{"autoScroll":{"visible":true,"scrollDirection":"bottom","scrollRate":{"second":3,"item":2}},"showCount":"1","emptyCustomData":{"hideForNoData":false,"showForNoData":true,"tipCustom":{"settingMethod":"RichText","selectPage":"","richText":"<p>暂无业务数据</p>","btnList":[]}},"dataPreLoad":true,"dataLazyLoad":{"enable":true,"showLoading":"2"}}}
+```
+
+数字与文本仅为一般示例，不固定滚动间隔、条数、提示内容或视图数量。settingMethod=RichText 使用 richText；其他展示方式需使用各自完整结构，不把此样例作为唯一支持方式。
+
+viewList 每项包含唯一 id、viewIcon、viewType、enable、viewName.nameAlias 及 viewSet。viewSet 可包含 mode、enableGroup.groupField、superiorField 等对应视图设置，字段使用真实来源描述。视图类型有列表式、分组表格。本次 viewType=2 的配置包含 enableGroup.groupField，可作为分组表格的结构参考；viewType：1 列表式、2 分组表格。
+
+viewList 数组整体替换可实现新增、修改、删除、重排，空数组清空备选项；修改时保留其他项的 ID 和未知配置。enableGroup 是显示层分组，区别于 dataset.dataGroupConfig 的查询聚合。列表组件 PC 开启备选视图不应自动覆盖移动端的关闭状态。
+
+运行设置与视图配置有完整布局保存结构；实际定时刷新、滚动、无数据展示及视图交互仍需前台检查。time=-1 明确为不刷新；showLoading=1 不显示、2 显示；viewType=1 列表式、2 分组表格。分页原生字段使用 part/more/scroll/none 字符串码，不能写入选项序号。
+
+## 列表过滤、搜索与操作按钮
+
+这些设置决定列表固定显示哪些数据、按什么顺序排列、用户如何搜索，以及能执行哪些操作。固定过滤、用户搜索和按钮条件是不同层次，不能用其中一项替代另一项。与 [数据源分组统计](guide-list.md) 分开维护。
+
+### 命令
+
+`designer list controls <section> <action> <pageId> --comp <id> --terminal pc|mobile`，默认 pc，写命令默认预览，加 --apply 保存。配置支持内联 JSON 或 @文件。
+
+| section | action | 配置 |
+|---|---|---|
+| filter | get/set/clear | set --config 为完整原生条件树 |
+| order | get/set/clear | set --config 为完整多字段排序数组 |
+| search | get/set/clear | set --config 为搜索配置对象；未提供类别保留，数组整段替换 |
+| button | get/add/update/remove/order | 增改 --config，修改删除 --item；order 为全部按钮 ID 数组 |
+
+fields 使用 `designer list advanced fields` 查询来源字段、操作符及浏览参数，不固定可选字段类型或数量。
+
+### 固定过滤与排序
+
+固定过滤保存为 config.filter。AND/OR 原生关系在本列表条件中为 relationship=1/0，支持混合嵌套。叶子包含完整字段描述及 conditions，条件值按所选字段类型提供。候选操作符与实际保存码可能不同：数值区间保存 func=range、value=[下界,上界]；人员当前用户样例为 func=eq、value="{userid}"。不能把此形状直接套给其他字段。filter clear 保存空对象。
+
+排序数组保留字段 id/name/objId/text/type/compType 等描述以及 orderType。本次降序为 DESC；其他码值以平台配置为准，不把旧快捷命令中的小写值当成本入口通用码表。order clear 保存空数组。
+
+### 用户搜索
+
+searchConditions 的 commonFilters 是普通搜索字段，quickFilters 是快捷搜索字段，groupFilters 是分类搜索，commonFilterGroups 为普通搜索分组，hiddenFieldsForOther 为其他搜索隐藏字段。
+
+每行保留 fieldId、字段类型、componentKey、conditionTypeValue、显示名和 listFilterDefaultSets 等字段。字段的 options、列表分类选项和默认值按来源查询，不能使用示例里的选项 ID。设置某类数组为 [] 可单独清空；search clear 清空全部搜索设置。
+
+人员分类的 customFilterOptions 是 JSON 字符串，包含 employee 按人员、department 按部门、myUnderlings 我的下属、myFollow 我关注的人；每项 isChecked/enable 控制选中及可用状态。自定义分类使用 GroupCustom 字段及独立 ID，不能复用普通字段 ID。
+
+搜索整体配置包括 commonSearchType、needCondition、noneOfShow、searchRelationEnable、manualFilter、fixedCol/fixedColCount、fieldVerticalLayout、needOtherCustom、filterContraction、showSearchLabel 等。值为原生字符串/数值，不统一转为布尔。下面的便捷设置采用与表格视图共用的纯构造逻辑；原生值仍保留，不把各开关统一按布尔写入。未知配置字段可以在原生对象中保留。
+
+### 列表按钮
+
+系统按钮由当前列表模板返回，保留 buttonKey、system、pluginName/pluginFunc 等实现字段。当前样例包含 SwitchView 切换视图、ExportButton 导出、Personalization 个性化设置、QuickSort 快速排序、DataAnalysis 自助式分析；这不是完整按钮白名单。系统按钮可改属性/启停，但不能删除或替换内置实现。新增自定义按钮无需指定 ID，命令生成。
+
+```json
+{"name":"业务操作","enable":1,"onlyIcon":0,"showPosition":["rightTopBatch","LineEndDropDown"],"iconPath":"{\"path\":\"#icon-eBuilder-o\"}"}
+```
+
+显示位置：rightTop 右上直接展示、rightTopDropDown 右上下拉、rightTopBatch 批量操作区、lineEnd 行末直接展示、LineEndDropDown 行末下拉。保留大小写；按钮带有 btnPositionData 时以其可用位置为准，scope 为支持终端，不能跨端强制设置。启停与位置修改会同步 hasLineEndButton/hasLineEndDropButton；SwitchView 启停同步 enableSwitchView.enable。已有按钮中的其他联动如表头快捷操作模式仍需按配置定义处理。
+
+按钮属性还可包含 conditionEnable、condition、operateType、dataFilterType、useCheckedData、tipsMessage、filterTitle 等原生字段。使用完整原生条件配置，条件位于 condition.filter，其他选项位于 condition 外；dataFilterType 为 1 弹出窗口、0 直接在列表过滤；operateType 的准确界面含义仍待明确，保留原值。
+
+权限为按钮自身 permissions，与列表组件 rights 分开。add/update 可使用 `--subjects @subjects.json` 提供普通主体数组，格式沿用 [组件权限](component-permission.md)，命令解析真实对象并生成 permissions；空数组清空。也可在配置中提供完整原生 permissions，用于已有矩阵等规则的保留与修改。
+
+### 按钮动作
+
+```sh
+e10-cli designer event schema
+e10-cli designer event set <pageId> --comp <listId> --collection listButtons --item <buttonId> --terminal pc --trigger CLICK --config @action.json --apply
+```
+
+按钮事件原生容器为 actions，命令自动映射，不写入按钮 eventGroup。支持已有动作体系，查询资源与结构见 [事件指南](events/guide-events.md)。get/enable/remove 同样支持 listButtons 定位。系统按钮的内置动作不允许由此覆盖；自定义按钮事件与列表整体 CLICK/CLICKDATA 相互独立。
+
+### 检查与边界
+
+配置保存采用完整布局局部修改、并发检查、回读及释放软锁。PC/移动端分别设置，保留另一端。保存回读证明结构保存，不替代过滤结果、搜索交互、分类计数、按钮权限和点击效果检查。
+
+待明确的内容包括 fieldVerticalLayout 的准确界面含义、分类搜索显示位置的终端差异、operateType 及 dataFilterType 之外其他过滤选项的业务含义、按钮特殊模式的其他联动。原生结构通道仍可配置已取得的真实值，不因为未做中文简写而阻断完整规则写入。
+
+### 搜索便捷配置
+
+```sh
+e10-cli designer list controls search configure <pageId> --comp <listId> --config @search.json --apply
+```
+
+`settings` 局部修改搜索整体设置，`fields` 为按顺序执行的字段配置操作数组。已有其他搜索字段、类别和未提供设置保持不变。
+
+| settings 属性 | 含义 | 原生字段 |
+|---|---|---|
+| searchMode | 字符串 `1` 筛选、`0` 高级搜索 | commonSearchType |
+| showLabel | 显示字段名称 | showSearchLabel |
+| relation | 显示条件关系 | searchRelationEnable |
+| otherConds | 启用其他条件 | needOtherCustom |
+| collapse | 搜索后收起面板 | filterContraction |
+| manual | 手动触发筛选 | manualFilter |
+| fixedCols / colCount | 固定列数开关 / 正整数列数 | fixedCol / fixedColCount |
+| hideSwitch | 隐藏所有条件/任一条件切换 | noneOfShow |
+| hideEmpty | 更多下拉框无字段时不显示；开启写 `0`、关闭写 `1` | needCondition |
+| prompt | 快捷搜索提示文字 | quickPlaceHolder.nameAlias |
+
+除 searchMode、colCount、prompt 外，便捷属性均传布尔值，由命令转换为本入口原生码。
+
+```json
+{"settings":{"hideEmpty":true,"relation":true,"showLabel":true},"fields":[{"kind":"common","field":"<fieldId>","options":{"showName":"名称","required":true}},{"kind":"quick","field":"<fieldId>"},{"kind":"group","field":"<categoryFieldId>","options":{"position":"0","tabStyle":"select"}}]}
+```
+
+kind 为 common 普通搜索、quick 快捷搜索、group 分类搜索；action 为 add（默认）、update、remove、order。增改使用 field 指定真实字段 ID，新增也可用唯一平台字段名；排序使用 ids 数组完整列出该类别字段 ID。修改和删除优先使用 get 返回的 fieldId。
+
+字段元数据使用组件 fieldUsage[].fields，包含业务及系统字段。普通/快捷搜索的默认操作符取字段 conditionType 的第一项，显式 options.operator 也需在此字段清单内。不要一律使用 like。options 可配置 required、showName、defaultType、startValue、fullMatch、showArchiveOption；普通位置 position=`0` 平铺、`1` 更多下拉框。分类的 tabStyle=`tab` 平铺、`select` 下拉；不同字段类型的选项、日期粒度与浏览默认配置由已有表格搜索构造函数处理。
+
+更复杂的默认值或分类原生属性可通过单行 properties 提供，不能覆盖字段身份。完全原生结构仍可用 search set，不因便捷构造支持范围而限制平台其他字段类型。
+
+### 按钮编辑面板便捷属性
+
+| 属性 | 页面含义 | 原生字段 |
+|---|---|---|
+| tooltip | 提示内容字符串 | tipsMessage.nameAlias |
+| filterEnabled | 启用数据过滤 | conditionEnable，布尔转换为1/0 |
+| checkedData | 带入勾选数据 | useCheckedData，布尔 |
+| iconOnly | 仅显示图标 | onlyIcon，布尔转换为1/0 |
+| enabled | 启用 | enable，布尔转换为1/0 |
+| dialogTitle | 弹窗标题文字，保留已有标题图标 | filterTitle.title.nameAlias |
+
+数据过滤方式中 `dataFilterType:"1"` 对应弹出窗口；dataFilterType=0 对应直接在列表过滤。过滤条件使用 condition.filter 的完整条件树，外围保留 filterIsNull/isFilterSub 等设置。数据过滤与带入勾选数据不是同一开关，分别维护。显示位置仍由 showPosition 提供数组，支持批量区与行末下拉同时显示。
+
+界面的新建按钮组、嵌套分组及分组动作尚没有完整配置样例，不把单按钮结构直接充当按钮组协议；已有 groupBtns/batchBtns 原生结构可以保留，新增组需进一步明确其结构。
+
+#### 已明确的界面选项
+
+分类搜索显示位置为顶部、左侧；原生 showPosition 为 0 顶部、1 左侧，结合当前终端配置使用，不把左侧称为普通搜索的更多下拉框。分类展示方式 tabStyle（平铺/下拉）与显示位置是两个设置。
+
+自定义按钮的数据过滤方式为弹出窗口、直接在列表过滤。dataFilterType=1 表示弹出窗口；dataFilterType=0 表示直接在列表过滤。其余按钮配置和已保存的原生码保持可读写。
+
+## 列表表头、勾选、分组与上下级
+
+这些是列表展示与行选择能力。展示分组 enableGroup 不等同于数据源查询聚合 dataGroupConfig。上下级使用列表数据源中的关联上级记录字段，不能用任意文本字段充当父子关系。
+
+```sh
+e10-cli designer list advanced presentation <pageId> --comp <listId> --terminal pc --config @presentation.json --apply
+```
+
+默认预览，--apply 保存；终端 pc/mobile 分别配置。命令查询当前数据源真实字段，field 可传唯一字段 ID 或平台字段名，也可提供完整字段对象。
+
+| 属性 | 原生字段与含义 |
+|---|---|
+| headerQuick | tableHeaderOperation，表头快捷操作模式 |
+| hideHeader | hideTableHeader，隐藏表头 |
+| hideCheckbox | hideCheckbox，隐藏勾选框 |
+| checkboxCondition | checkboxDisabledSet，勾选框禁用条件树；{} 清空 |
+| group | enableGroup，显示分组设置；field 转换为 groupField |
+| hierarchy | superiorField，上下级设置；field 为关联 EBuilder 字段 |
+
+```json
+{"headerQuick":true,"hideHeader":false,"hideCheckbox":false,"hierarchy":{"enable":true,"field":"<parentFieldId>","expandLevel":"2","levelSelection":"-1","levelRange":""}}
+```
+
+准备上下级字段：在数据源表单新增单选关联 EBuilder 字段，关联当前表单，表示每条记录的上级记录。通过 form add-field 的 --sform-id 指向本表 objId，--data-title 使用本表名称字段。刷新页面设计器后重新读取字段候选。关系数据需填写真实上级记录，根记录留空；避免自关联和循环关系。创建字段不等于已经产生父子数据。
+
+启用上下级时必须存在有效关联字段。expandLevel 为默认展开级数，使用正整数。levelSelection：`-1` 不限制、`1` 按可选层级、`2` 按禁选层级。levelRange 为层级列表：`1` 第1层、`2` 第2层，以此类推；多个用英文逗号分隔，如 `1,2,3`。叶子节点用 `{leaflevel}`，可与数字层级组合，如 `1,{leaflevel}`。不限制时清空 levelRange；限制层级时提供非空列表。展示分组支持 enable、field，以及 showType、expandFirstFew、isDelay 等原生属性；showType=2 的准确展开选项仍需说明。
+
+禁用勾选条件使用完整字段条件树，不固定为当前人员。原生样例的人员条件 func=eq、value="{userid}"，其他字段按真实元数据与保存协议处理。隐藏勾选框与禁用某行勾选不同；隐藏后批量操作的交互还需实际检查。
+
+表头快捷操作模式可能影响切换视图、快速排序按钮，其原生 helpTip 已提示该模式下部分开关不生效，不能仅检查按钮 enable。命令只修改指定设置，保留数据源统计、搜索、按钮、事件及另一终端。复杂原生设置仍可使用 advanced set。
+
+```json
+{"hierarchy":{"enable":true,"field":"<parentFieldId>","expandLevel":"3","levelSelection":"1","levelRange":"1,2,{leaflevel}"}}
+```
+
+按可选层级限制可被选择的节点层；按禁选层级指定不允许选择的节点层。该限制不应解释成删除其他层的数据。上下级字段使用关联本表的上级记录，展示样式为树形；根记录可不填写上级。
+
+## 列表运行设置便捷入口
+
+```sh
+e10-cli designer list advanced runtime <pageId> --comp <listId> --terminal pc --config @runtime.json --apply
+```
+
+| 便捷属性 | 对应原生配置 |
+|---|---|
+| pageSize | 正整数每页行数 |
+| pageMode | part 页码分页、more 点击加载更多、scroll 滚动分页、none 隐藏分页 |
+| showCount | 布尔值，自动写原生字符串1/0 |
+| refresh | timedRefresh 原生对象；time=-1不刷新，180s三分钟、300s五分钟，其他正整数秒使用Ns；保留未修改的自定义时间信息 |
+| scroll | autoScroll，visible布尔开关，方向top向上/bottom向下，scrollRate.second/item为间隔秒数/条数 |
+| empty | emptyCustomData 原生对象，保留其他无数据展示方式 |
+| preload | 布尔值，dataPreLoad |
+| lazy | dataLazyLoad，enable布尔开关、showLoading=1不显示/2显示 |
+| views | enableSwitchView，含enable/viewName/viewList，保留完整视图类型和viewSet |
+
+```json
+{"pageSize":20,"pageMode":"part","showCount":true,"refresh":{"time":"-1"},"scroll":{"visible":false,"scrollDirection":"bottom","scrollRate":{"second":3,"item":2}},"preload":true,"lazy":{"enable":true,"showLoading":"2"},"views":{"enable":true}}
+```
+
+设置 views.enable 时同步当前终端已有 SwitchView 系统按钮的 enable；没有该按钮时不伪造系统按钮。按钮入口修改 SwitchView 的 enable 也同步视图开关，实现两侧一致。关闭视图切换保留 viewList，再次开启可复用；显式 viewList=[] 清空备选视图。视图ID不可重复，类型不限制为某个示例码值，viewSet使用对应类型的完整配置。
+
+runtime 省略 --apply 预览，加 --apply 保存并回读。仅修改所选终端，保留其他组件和PC/移动另一端。原生 config 通道仍保留，runtime的基本校验不代表覆盖所有平台未来码值。自定义刷新控件如何生成 time 的具体规则仍需完整交互对照，不能把 customTime/customTimeUnit 改动自动当作已生效刷新。
+
+列表按钮 `--subjects` 的部门/分部主体以及岗位指定部门/分部，使用组件权限的统一对象解析：模块 `destData` → HRM `destData` → HRM 分页列表。按真实 ID 匹配，无法取得时停止，不仅凭名称构造权限对象。见 [组件权限的组织对象解析](component-permission.md#部门与分部对象解析)。直接提供原生 `permissions` 数组时，不执行此自动查询，需要提供完整有效的对象。