@microi.net/cli 5.5.8 → 5.6.0

package/skills/microi-form-engine/references/data-source-events.md

@@ -1,124 +1,124 @@
-# 字段数据源、属性与事件
-
-## 数据源类型
-
-| 类型 | 适用场景 | 配置要点 |
-|---|---|---|
-| `Data` | 显示值和保存值相同的固定数组 | 适合少量稳定枚举 |
-| `KeyValue` | 保存 Key、显示 Label | 推荐；便于翻译和状态演进 |
-| `Sql` | 基于当前库的受控查询 | 参数化、限制条数、选择明确字段 |
-| `DataSource` | 复用数据源引擎 | 使用稳定 DataSourceId/Key |
-| `ApiEngine` | 复杂权限、跨表或外部数据 | 接口返回稳定的 Label/Value 字段 |
-
-KeyValue 示例：
-
-```text
-draft|草稿,enabled|启用,disabled|禁用
-```
-
-对应核心语义：
-
-```json
-{
-  "DataSource": "KeyValue",
-  "SelectLabel": "Value",
-  "SelectSaveField": "Key"
-}
-```
-
-动态 SQL 示例只选择必要字段并限制返回量：
-
-```json
-{
-  "DataSource": "Sql",
-  "Sql": "select Id,Name from biz_customer where Name like '%$Keyword$%' limit 0,20",
-  "SelectLabel": "Name",
-  "SelectSaveField": "Id",
-  "DataSourceSqlRemote": true
-}
-```
-
-SQL 仍必须经过平台受控数据源；不要把用户文本拼成标识符或任意 SQL。复杂权限、
-跨库或外部服务使用数据源引擎/接口引擎。
-
-## 动态联动
-
-字段值变化时可用前端 V8 更新另一个字段的数据源：
-
-```javascript
-if (V8.LoadMode === 'Design') return;
-
-var result = await V8.FormEngine.GetTableData('biz_contact', {
-  _SelectFields: ['Id', 'Name'],
-  _Where: [['CustomerId', '=', V8.ThisValue]],
-  _PageIndex: 1,
-  _PageSize: 100
-});
-
-V8.FieldSet('ContactId', 'Data', result.Code === 1 ? result.Data : []);
-```
-
-前端联动不能替代后端权限和提交校验。
-
-## 表单生命周期
-
-| 配置 | 运行端 | 用途 |
-|---|---|---|
-| `InFormV8` | 前端 | 默认值、字段显隐、初始化交互 |
-| `SubmitFormV8` | 前端 | 即时校验；HTTP 直调不会触发 |
-| `SubmitBeforeServerV8` | 后端事务内 | 最终校验、加工、阻止提交 |
-| `SubmitAfterServerV8` | 后端事务内 | 同事务联动其它表 |
-| `OutFormV8` | 前端 | 关闭后刷新/跳转 |
-| `DataFilterV8` | 后端 | 每行脱敏/展示加工 |
-
-事件代码、版本和表单属性都必须从当前 `diy_table/diy_field` 回读。后端阻止提交：
-
-```javascript
-if (!V8.Form.Name) return { Code: 0, Msg: '名称不能为空' };
-```
-
-## 字段属性
-
-常用属性包括 `Visible`、`AppVisible`、`Required`、`Readonly`、`Data`、
-`Config`、`FormWidth`、`TableWidth`、`Tab`、角色绑定和前端事件代码。
-
-- 除非明确隐藏，`Visible=1`、`AppVisible=1`。
-- 角色绑定只缩小界面可见性，不能代替服务器数据权限。
-- 修改防抖编辑器/代码字段前必须刷新待保存值，避免最后一次输入未入库。
-- `Data/Config` 修改后回读并刷新 schema 缓存。
-
-### 历史字段 V8 双存储兼容
-
-- `diy_field.V8Code` 是历史租户和官方应用包实际使用的物理列，按钮点击/字段值变更代码可能只存在于该列；`Config.V8Code` 是部分新版前端使用的镜像，不能假定它是唯一事实源。
-- 后端 `DiyField` 实体、字段查询投影和 `DiyFieldParam` 必须保留 `V8Code`，否则数据库代码虽然仍在，设计器列表和单字段回读都会表现成“0 字”。
-- 前端回读顺序固定为：先安全解码历史 Base64，再取“非空物理 `V8Code` 优先、否则 `Config.V8Code`”，最后同步两处。禁止用空镜像覆盖非空物理代码；保存和显式清空时则必须同步写入两处。
-- 回归至少包含一个 `Component=Button`、根级 `V8Code` 非空而 `Config.V8Code` 为空的官方包字段，并验证列表回读、选中编辑、保存、刷新后代码仍完整。
-
-## DevComponent 定制组件
-
-定制组件至少处理：
-
-- `value/modelValue` 的输入与变更通知；
-- 当前字段模型、表单模型、表单模式和只读状态；
-- 校验错误、清空、禁用、加载与销毁；
-- Add/Edit/View 回显；
-- PC、移动端和暗色主题；
-- 组件内部请求的 Token/OsClient 传递与错误态。
-
-定制组件需要修改并发布主前端。若只服务单一租户、包含多个字段或复杂页面，
-优先创建 MicroService 页面，通过 `V8.OpenAppDialog` 与宿主交互。
-
-历史 Options API 定制组件可通过宿主 facade 调用数据源引擎：
-
-```javascript
-this.Microi.DataSourceEngine.Run('customer_summary', { Id: customerId }, (result) => {
-  if (this.Microi.CheckResult(result)) {
-    this.summary = result.Data;
-  }
-});
-```
-
-`Microi.DataSourceEngine.Run` 是回调式宿主接口，`Microi.CheckResult` 负责按
-DosResult 约定判断并展示错误。组件卸载后要阻止迟到回调继续写状态；新页面
-优先使用项目现有的组合式 facade，不要假定 `this.Microi` 在任意 Vue 组件中
-都存在。
+# 字段数据源、属性与事件
+
+## 数据源类型
+
+| 类型 | 适用场景 | 配置要点 |
+|---|---|---|
+| `Data` | 显示值和保存值相同的固定数组 | 适合少量稳定枚举 |
+| `KeyValue` | 保存 Key、显示 Label | 推荐；便于翻译和状态演进 |
+| `Sql` | 基于当前库的受控查询 | 参数化、限制条数、选择明确字段 |
+| `DataSource` | 复用数据源引擎 | 使用稳定 DataSourceId/Key |
+| `ApiEngine` | 复杂权限、跨表或外部数据 | 接口返回稳定的 Label/Value 字段 |
+
+KeyValue 示例：
+
+```text
+draft|草稿,enabled|启用,disabled|禁用
+```
+
+对应核心语义：
+
+```json
+{
+  "DataSource": "KeyValue",
+  "SelectLabel": "Value",
+  "SelectSaveField": "Key"
+}
+```
+
+动态 SQL 示例只选择必要字段并限制返回量：
+
+```json
+{
+  "DataSource": "Sql",
+  "Sql": "select Id,Name from biz_customer where Name like '%$Keyword$%' limit 0,20",
+  "SelectLabel": "Name",
+  "SelectSaveField": "Id",
+  "DataSourceSqlRemote": true
+}
+```
+
+SQL 仍必须经过平台受控数据源；不要把用户文本拼成标识符或任意 SQL。复杂权限、
+跨库或外部服务使用数据源引擎/接口引擎。
+
+## 动态联动
+
+字段值变化时可用前端 V8 更新另一个字段的数据源：
+
+```javascript
+if (V8.LoadMode === 'Design') return;
+
+var result = await V8.FormEngine.GetTableData('biz_contact', {
+  _SelectFields: ['Id', 'Name'],
+  _Where: [['CustomerId', '=', V8.ThisValue]],
+  _PageIndex: 1,
+  _PageSize: 100
+});
+
+V8.FieldSet('ContactId', 'Data', result.Code === 1 ? result.Data : []);
+```
+
+前端联动不能替代后端权限和提交校验。
+
+## 表单生命周期
+
+| 配置 | 运行端 | 用途 |
+|---|---|---|
+| `InFormV8` | 前端 | 默认值、字段显隐、初始化交互 |
+| `SubmitFormV8` | 前端 | 即时校验；HTTP 直调不会触发 |
+| `SubmitBeforeServerV8` | 后端事务内 | 最终校验、加工、阻止提交 |
+| `SubmitAfterServerV8` | 后端事务内 | 同事务联动其它表 |
+| `OutFormV8` | 前端 | 关闭后刷新/跳转 |
+| `DataFilterV8` | 后端 | 每行脱敏/展示加工 |
+
+事件代码、版本和表单属性都必须从当前 `diy_table/diy_field` 回读。后端阻止提交：
+
+```javascript
+if (!V8.Form.Name) return { Code: 0, Msg: '名称不能为空' };
+```
+
+## 字段属性
+
+常用属性包括 `Visible`、`AppVisible`、`Required`、`Readonly`、`Data`、
+`Config`、`FormWidth`、`TableWidth`、`Tab`、角色绑定和前端事件代码。
+
+- 除非明确隐藏，`Visible=1`、`AppVisible=1`。
+- 角色绑定只缩小界面可见性，不能代替服务器数据权限。
+- 修改防抖编辑器/代码字段前必须刷新待保存值，避免最后一次输入未入库。
+- `Data/Config` 修改后回读并刷新 schema 缓存。
+
+### 历史字段 V8 双存储兼容
+
+- `diy_field.V8Code` 是历史租户和官方应用包实际使用的物理列，按钮点击/字段值变更代码可能只存在于该列；`Config.V8Code` 是部分新版前端使用的镜像，不能假定它是唯一事实源。
+- 后端 `DiyField` 实体、字段查询投影和 `DiyFieldParam` 必须保留 `V8Code`，否则数据库代码虽然仍在，设计器列表和单字段回读都会表现成“0 字”。
+- 前端回读顺序固定为：先安全解码历史 Base64，再取“非空物理 `V8Code` 优先、否则 `Config.V8Code`”，最后同步两处。禁止用空镜像覆盖非空物理代码；保存和显式清空时则必须同步写入两处。
+- 回归至少包含一个 `Component=Button`、根级 `V8Code` 非空而 `Config.V8Code` 为空的官方包字段，并验证列表回读、选中编辑、保存、刷新后代码仍完整。
+
+## DevComponent 定制组件
+
+定制组件至少处理：
+
+- `value/modelValue` 的输入与变更通知；
+- 当前字段模型、表单模型、表单模式和只读状态；
+- 校验错误、清空、禁用、加载与销毁；
+- Add/Edit/View 回显；
+- PC、移动端和暗色主题；
+- 组件内部请求的 Token/OsClient 传递与错误态。
+
+定制组件需要修改并发布主前端。若只服务单一租户、包含多个字段或复杂页面，
+优先创建 MicroService 页面，通过 `V8.OpenAppDialog` 与宿主交互。
+
+历史 Options API 定制组件可通过宿主 facade 调用数据源引擎：
+
+```javascript
+this.Microi.DataSourceEngine.Run('customer_summary', { Id: customerId }, (result) => {
+  if (this.Microi.CheckResult(result)) {
+    this.summary = result.Data;
+  }
+});
+```
+
+`Microi.DataSourceEngine.Run` 是回调式宿主接口，`Microi.CheckResult` 负责按
+DosResult 约定判断并展示错误。组件卸载后要阻止迟到回调继续写状态；新页面
+优先使用项目现有的组合式 facade，不要假定 `this.Microi` 在任意 Vue 组件中
+都存在。

package/skills/microi-form-layout/SKILL.md

@@ -22,15 +22,15 @@ Microi 吾码低代码提供 **三种** 表单分组能力，但每种都有明
 
 `CollapseGroup` 的运行态视觉统一使用清爽的白色/主题表面卡片：短主题色指示条、紧凑
 标题、可选图标、单行副标题、标题旁轻量 `x 项` 文案，以及最右侧无底色的折叠箭头。
-不得使用整块主题色填充、蓝色大描边或醒目的实心数量胶囊；分组内容与标题属于同一张
-卡片，展开后不再嵌套第二套外框。深色模式使用 Element 主题变量，不能写死白色/蓝色。
-
-## 配置类表单的二级分组硬规则
-
-- `sys_config`、`sys_user`、SaaS 设置、接口参数、打印/工作流设置等“配置类表单”不能因为已经有表级 Tab 就停止信息架构审计。表级 Tab 只负责一级领域；同一 Tab 内存在 **7 个以上可见设置**或 **2 个以上明确语义域**时，必须继续按语义放入 `CollapseGroup`。
-- 水印、主题、菜单、登录入口、安全策略、桌面偏好等一组相互关联的开关/参数必须由一个带图标、说明、计数的 CollapseGroup 包裹；不能把 5~20 个设置直接平铺在 Tab 中，也不能让每个小设置单独占一个 Tab。
-- 新增设置字段时必须同时审计所在 Tab 的现有字段，而不只是包住本次新增字段。若相邻设置已形成稳定语义域，应一次性补齐该域的 CollapseGroup；隐藏兼容字段继续保留但不计入可见项数。
-- 配置表采用“表级 Tab + Tab 内 CollapseGroup”时，CollapseGroup 必须与成员字段写入同一个 `Tab`，并用连续 `Sort` 保证作用范围在下一个布局节点前结束。发布前必须打开真实编辑表单验证，不能只凭元数据字符串判断布局成功。
+不得使用整块主题色填充、蓝色大描边或醒目的实心数量胶囊；分组内容与标题属于同一张
+卡片，展开后不再嵌套第二套外框。深色模式使用 Element 主题变量，不能写死白色/蓝色。
+
+## 配置类表单的二级分组硬规则
+
+- `sys_config`、`sys_user`、SaaS 设置、接口参数、打印/工作流设置等“配置类表单”不能因为已经有表级 Tab 就停止信息架构审计。表级 Tab 只负责一级领域；同一 Tab 内存在 **7 个以上可见设置**或 **2 个以上明确语义域**时，必须继续按语义放入 `CollapseGroup`。
+- 水印、主题、菜单、登录入口、安全策略、桌面偏好等一组相互关联的开关/参数必须由一个带图标、说明、计数的 CollapseGroup 包裹；不能把 5~20 个设置直接平铺在 Tab 中，也不能让每个小设置单独占一个 Tab。
+- 新增设置字段时必须同时审计所在 Tab 的现有字段，而不只是包住本次新增字段。若相邻设置已形成稳定语义域，应一次性补齐该域的 CollapseGroup；隐藏兼容字段继续保留但不计入可见项数。
+- 配置表采用“表级 Tab + Tab 内 CollapseGroup”时，CollapseGroup 必须与成员字段写入同一个 `Tab`，并用连续 `Sort` 保证作用范围在下一个布局节点前结束。发布前必须打开真实编辑表单验证，不能只凭元数据字符串判断布局成功。
 
 <!-- microi-progressive:begin -->
 <!-- microi-progressive:chunk id=microi-form-layout-000 sha256=79fcf1787c0fbdbe51363f25fcf72b060b714eed9cbc5593760f9080cff48e31 -->
@@ -145,10 +145,10 @@ V8 事件中可用 `V8.HideFormTab('tabId')` / `V8.ShowFormTab('tabId')` / `V8.C
 - 字段数 13~30 的表单，必须有可见的**业务分组**（Tab 或 CollapseGroup 二选一），不能让用户上下滚动 5 屏找字段。
 - 创建 CollapseGroup 分组时，必须设置 `Icon`（如 `fas fa-calculator` / `fas fa-info-circle`），不要默认空白。
 - 任何 Tab / CollapseGroup 都必须有 `Description` 解释分组用途，不要只放一个标题。
-- 每个 CollapseGroup 必须回读到 `FormWidth=24`；`Config.CollapseGroup.ShowFieldCount` 默认必须为 `true`。
-- 可扩展配置表或设置页的末尾 CollapseGroup 不得无边界使用 `ScopeMode=UntilNextGroup`。已知标准子项数量时必须改用 `ScopeMode=FieldCount` 并显式保存准确 `FieldCount`；否则必须增加后续分组边界，避免未来新增字段或租户扩展字段被末尾分组误吞。
-- 表级 Tab 与 CollapseGroup 的 `Description` 作为副标题显示；开启计数时统一追加 `x 项`，禁止继续显示 `x 个字段`。运行时动态显隐字段后必须重算计数，已有数字角标配置继续生效，不能被静态字段数覆盖。
-- 分组/Tab 的字段计数必须基于字段原始可见性（如 `_baseIsShow`），不能把“当前因折叠而隐藏”误判成不可见，否则收起后的分组会错误显示 `0 项`。
+- 每个 CollapseGroup 必须回读到 `FormWidth=24`；`Config.CollapseGroup.ShowFieldCount` 默认必须为 `true`。
+- 可扩展配置表或设置页的末尾 CollapseGroup 不得无边界使用 `ScopeMode=UntilNextGroup`。已知标准子项数量时必须改用 `ScopeMode=FieldCount` 并显式保存准确 `FieldCount`；否则必须增加后续分组边界，避免未来新增字段或租户扩展字段被末尾分组误吞。
+- 表级 Tab 与 CollapseGroup 的 `Description` 作为副标题显示；开启计数时统一追加 `x 项`，禁止继续显示 `x 个字段`。运行时动态显隐字段后必须重算计数，已有数字角标配置继续生效，不能被静态字段数覆盖。
+- 分组/Tab 的字段计数必须基于字段原始可见性（如 `_baseIsShow`），不能把“当前因折叠而隐藏”误判成不可见，否则收起后的分组会错误显示 `0 项`。
 - 表级分组方向完整支持 `TabsPosition=left/top/right/bottom`；每个方向都要检查标题、副标题、动态角标和选中指示线，纵向指示线端点固定为直角。
 - 修改 `diy_table.Tabs` 或 `diy_field.Tab` / `Config.CollapseGroup` / `Config.FieldTabs` 后，必须调用 `microi_refresh_schema_cache`。
 - Tab 内嵌套 CollapseGroup 时，CollapseGroup 必须设 `DefaultCollapsed=true`（默认收起），避免 Tab 内继续被折叠分组抢首屏空间。