cloud-web-corejs 1.0.280 → 1.1.0-dev.10

package/src/components/xform/docs/2026-08 xform H5 P1 /345/256/236/347/216/260/350/247/204/346/240/274.md"

@@ -0,0 +1,412 @@
+# xform H5 —— P1 实现规格
+
+> 日期：2026-08-25
+> 上位文档：`2026-08 xform 移动端布局对齐 bill_setting 方案.md`（决策 3 / 6 / 8）
+> 前置：`2026-08 xform H5 P0 实现规格.md`（根类 `.xform-h5` 与样式基线文件必须先落地）
+> 状态：**规格已细化，未编码**
+> P1 边界：**要改 vue 模板结构**（加滚动容器、按钮分流、卡片 DOM），有回归面，故与 P0 分期。
+
+P1 交付 3 件事：
+
+1. 骨架改 flex 列 + 内部滚动区，底栏回到流内（决策 3）
+2. 底栏胶囊皮肤 + 溢出收「更多」（决策 8）
+3. `list-h5` 明细卡片皮肤 + 行级变更标记（决策 6）
+
+**依赖**：三项的样式全部写进 P0 建的 `src/components/xform/styles/h5.scss`，
+沿用 P0 §2.2 的特异度策略（更高特异度 + 对方带 `!important` 己方也带）。
+
+---
+
+## 一、骨架滚动
+
+### 1.1 现状
+
+`detail-h5-item.vue` 的 DOM：
+
+```html
+<container-item-wrapper :widget="widget">          <!-- .container-wrapper -->
+  <div class="h5-detail-wrap grid-container" :class="[customClass]" :ref="widget.id">
+    <div class="h5-header">{{ widget.options.label }}</div>
+    <div>                                          <!-- ← 裸 div，未来的滚动容器 -->
+      <transition-group class="form-widget-list"> panes（内容） </transition-group>
+    </div>
+    <div class="h5-fixed-bottom-btns">
+      <transition-group class="form-widget-list"> widgetList（按钮） </transition-group>
+    </div>
+  </div>
+</container-item-wrapper>
+```
+
+样式（`style.scss`）：`.h5-detail-wrap{padding-bottom:68px}` + `.h5-fixed-bottom-btns{position:fixed;bottom:0;height:56px!important}`。
+即**整页滚 + 底栏钉在视口底部**。
+
+### 1.2 现状是有 bug 的（改动的直接理由）
+
+`formDialog.vue:319`、`searchFormDialog.vue:488`、`fileReferenceDialog.vue:277` 三处各写了：
+
+```scss
+::v-deep .H5 .h5-fixed-bottom-btns { bottom: 95px; }
+```
+
+意图是「弹框里把 fixed 底栏往上推」。但**三个文件都没有把 `H5` 这个类绑到任何元素上**
+（`layoutType` 只存在 data 里，模板中无 `:class` 引用）——
+即这三条选择器**一条都没生效**，全是死补丁。
+
+**所以当前真实表现是：H5 表单在这三个弹框里打开时，底栏 `position:fixed` 贴在屏幕底部，
+而不是弹框底部。** 骨架改成流内布局后此问题自然消失，三处补丁一并删除。
+
+### 1.3 目标 DOM
+
+```html
+<container-item-wrapper :widget="widget">
+  <div class="h5-detail-wrap grid-container" :class="[customClass]" :ref="widget.id">
+    <div class="h5-header">{{ widget.options.label }}</div>
+    <div class="h5-detail-body">                   <!-- 唯一滚动区 -->
+      <transition-group class="form-widget-list"> panes </transition-group>
+    </div>
+    <div class="h5-fixed-bottom-btns">…</div>       <!-- 流内，不再 fixed -->
+  </div>
+</container-item-wrapper>
+```
+
+模板改动只有一处：给那个裸 `<div>` 加 `class="h5-detail-body"`。
+
+### 1.4 样式（h5.scss 块 G）
+
+```scss
+.xform-h5 {
+  height: 100%;                       // el-form.render-form 自身
+
+  .container-wrapper { height: 100%; }  // container-item-wrapper 那层
+
+  .h5-detail-wrap {
+    display: flex;
+    flex-direction: column;
+    height: 100%;
+    min-height: 0;                    // 允许在 flex 父级下收缩
+    padding-bottom: 0 !important;     // 压掉 style.scss:13765 的 68px 让位补丁
+    background: #f1f5fb;
+  }
+
+  .h5-header { flex: none; height: $xformH5HeaderHeight; line-height: $xformH5HeaderHeight; }
+
+  .h5-detail-body {
+    flex: 1;
+    min-height: 0;                    // ★ 没有这行 flex 子项不会滚，会把父级撑破
+    overflow-y: auto;
+    -webkit-overflow-scrolling: touch;
+  }
+
+  .h5-fixed-bottom-btns {
+    position: static !important;      // 压掉 style.scss 的 position:fixed
+    flex: none;
+    height: $xformH5FooterHeight !important;
+  }
+}
+```
+
+> `min-height: 0` 是 flex 子项可滚动的必要条件（默认 `min-height:auto` 会被内容撑开，
+> 结果是父级溢出而不是子级滚动）。这条**必写**。
+
+### 1.5 高度从哪来（本项最大的落地风险）
+
+`height:100%` 要求父链每一层都有确定高度。父链是：
+
+```
+宿主容器 → el-form.render-form.xform-h5 → .container-wrapper → .h5-detail-wrap
+```
+
+后两层由块 G 补齐，**宿主那层是外部的**，分三类：
+
+| 宿主 | 位置 | 现有高度 | 需要做什么 |
+|---|---|---|---|
+| 页面态 | `views/user/form/vform/render.vue` 的 `.designer-view` | `style.scss` 已有 `.designer-view{height:100%}` | 无需改，验证即可 |
+| outLink 态 | `views/user/outLink/form_view.vue` scoped style | 已有 `.designer-view{height:calc(100vh - 33px)}` | 无需改，验证即可 |
+| 弹框态 | `formDialog` / `searchFormDialog` / `fileReferenceDialog` 的 `.cont` | 各自 `calc(100vh - N)`，值不一 | **需逐个验证**；缺高度的补一行 |
+
+**降级安全阀**：若某宿主确实拿不到高度，`height:100%` 会塌成 0（比现状更糟）。
+因此块 G 需要配一条兜底，二选一（实现时按真机结果定，见 六、待确认 1）：
+
+```scss
+// 方案 a：视口兜底（页面态友好，弹框里可能超出）
+.xform-h5 .h5-detail-wrap { min-height: 100vh; }
+// 方案 b：只在页面态兜底，弹框态不给（更保守）
+.xform-h5:not(.in-dialog) .h5-detail-wrap { min-height: 100vh; }
+```
+
+### 1.6 要删的东西
+
+1. `formDialog.vue:319`、`searchFormDialog.vue:488`、`fileReferenceDialog.vue:277`
+   三处 `::v-deep .H5 .h5-fixed-bottom-btns { bottom: 95px; }`（1.2 已证实是死补丁）；
+2. `style.scss:13765` 的 `.h5-detail-wrap{padding-bottom:68px}` —— 块 G 用 `!important` 压住即可，
+   **P1 不直接删该行**（`components/mobile/*` 手写页也可能用到 `.h5-detail-wrap`），
+   留到 P3 统一评估。
+
+---
+
+## 二、底栏胶囊 +「更多」
+
+### 2.1 胶囊样式（h5.scss 块 H）
+
+```scss
+.xform-h5 .h5-fixed-bottom-btns {
+  background: #fff;
+  padding: 8px 13px;
+  box-shadow: 0 0 10px rgba(0, 0, 0, 0.06);
+
+  .form-widget-list, .el-form { display: flex; }
+  .field-wrapper { flex: 1; margin: 0 5px; }
+
+  .button-sty, .el-button {
+    width: 100%;
+    height: 40px;
+    border-radius: 30px;
+    padding: 0;
+    i { margin-right: 4px; }
+  }
+}
+```
+
+### 2.2 溢出分流
+
+- `widgetsConfig.js` 的 `detail-h5.options` 加 `maxVisibleButtons: 2`
+  （默认值 2，对齐 bill_setting 的两按钮胶囊布局；B 层已拍「先按默认做，真机再调」）；
+- 属性面板：`propertyRegister.js` 的 `COMMON_PROPERTIES` 加
+  `maxVisibleButtons: "maxVisibleButtons-editor"`，
+  新建 `property-editor/maxVisibleButtons-editor.vue`（`el-input-number`，`name` 必须等于该编辑器名，
+  由 `property-editor/index.js` 的 `require.context` 自动注册 —— 机制同 P0 §3.3）；
+- `detail-h5-item.vue` 加两个 computed 把 `widget.widgetList` 切开：
+
+```js
+    visibleButtons() {
+      let max = this.widget.options.maxVisibleButtons;
+      let list = this.widget.widgetList || [];
+      // 老表单该 option 为 null/undefined（见 P0 §3.2），退回「全部平铺」
+      if (!max || max <= 0 || list.length <= max) return list;
+      return list.slice(0, max);
+    },
+    overflowButtons() {
+      let max = this.widget.options.maxVisibleButtons;
+      let list = this.widget.widgetList || [];
+      if (!max || max <= 0 || list.length <= max) return [];
+      return list.slice(max);
+    },
+```
+
+> **老表单口径同 P0 §3.2**：`upgradeWidgetConfig` 补的是 `null` 不是默认值，
+> 运行时更是读到 `undefined` —— 所以判空必须退回「全部平铺」，
+> 不能写成 `max = max || 2` 那样给老表单强行收起按钮。
+
+模板中把现有那个 `transition-group` 的遍历源从 `widget.widgetList` 换成 `visibleButtons`，
+后面追加：
+
+```html
+<el-dropdown v-if="overflowButtons.length > 0" popper-class="xform-h5-dropdown">
+  <el-button class="button-sty more-btn" type="warning" plain>
+    {{ i18nt('designer.setting.h5MoreButton') }}
+  </el-button>
+  <el-dropdown-menu slot="dropdown">
+    <el-dropdown-item v-for="(subWidget, swIdx) in overflowButtons" :key="swIdx">
+      <component :is="subWidget.type + '-widget'" :field="subWidget" :designer="null"
+                 :parent-list="widget.widgetList"
+                 :index-of-parent-list="swIdx" :parent-widget="widget" />
+    </el-dropdown-item>
+  </el-dropdown-menu>
+</el-dropdown>
+```
+
+### 2.3 ★ `el-dropdown-menu` 会被挪到 body 下
+
+Element UI 的 `el-dropdown-menu` 走 popper，**默认 append-to-body**。
+菜单 DOM 一旦挪到 `<body>` 下，就**不在 `.xform-h5` 作用域内了** ——
+所有写在 `.xform-h5 { ... }` 里的规则对菜单内的按钮全部失效。
+
+处理：给 `popper-class="xform-h5-dropdown"`，菜单样式**单独写成顶层选择器**，
+不要嵌在 `.xform-h5` 里：
+
+```scss
+/* 注意：不能嵌进 .xform-h5，菜单被 append 到 body 下了 */
+.xform-h5-dropdown.el-dropdown-menu {
+  .el-dropdown-menu__item { margin: 8px 0; }
+  .button-sty, .el-button { width: 100%; height: 36px; border-radius: 30px; }
+}
+```
+
+> 这不是猜测：bill_setting 用的就是这个模式 —— 它给菜单加 `class="mobileApp_dropdown"`，
+> 而 `style.scss:14538` 的 `.mobileApp_dropdown.el-dropdown-menu` 正是**顶层选择器**，
+> 没有嵌在 `.mobileApp` 里面。
+
+### 2.4 按钮进下拉后的注意点
+
+- **ref / refList 不受影响**：按钮仍在同一 Vue 组件树内，只是 DOM 位置变了，
+  `button-widget` 的 `ref="fieldEditor"` 与 `refMixin` 的注册照常；
+- **事件照常**：`button-widget` 的 `@click.native="handleButtonWidgetClick"` 绑在 `el-button` 上，
+  不依赖父容器；
+- **`el-dropdown-item` 默认会吞点击后自动收起菜单**，这是期望行为；
+- 若按钮 `options.hidden` 为真，`static-content-wrapper` 内部会 `v-show` 隐藏，
+  此时 `el-dropdown-item` 会留一个空条目 —— **分流前应先过滤掉 hidden 的按钮**，
+  否则「更多」里会出现空行（见 六、待确认 2）。
+
+---
+
+## 三、明细卡片皮肤
+
+### 3.1 先纠正一个预期
+
+上位方案里把这项描述成「`.h5-list-box .item` 是朴素列表行，要换成 `.pro-item` 卡片」。
+实际读代码后**差距比预期小**：`style.scss:14029` 起，`.h5-list-box .item` 已经是
+白底 + `radius 8` + `1px #eee` 边框 + 左侧 4px 竖条的卡片了。
+
+真正的差异只有 4 点：
+
+| 项 | 现状（`.h5-list-box .item`） | 目标（bill_setting `.pro-item`） |
+|---|---|---|
+| 圆角 | 8px | 12px |
+| 标题前缀 | 左侧 4px 竖条（`.t1::before`） | 5px 圆点（`inline-block` + `border-radius:50%`） |
+| 右上角 | `.status` 徽标（梯形底色块） | 圆形箭头角标：20px 圆底 + `content:"\e6e0"`（element-icons） |
+| 小字段区 | `.t2 > dl > dt/dd` | 同结构，字号 10-11px、`min-width:49%` 两列 |
+
+所以本项 **90% 是 CSS，模板只需加一个箭头角标元素**。
+
+### 3.2 `itemStyle` 选项
+
+- `widgetsConfig.js` 的 `list-h5.options` 加 `itemStyle: "plain"`（`'plain' | 'card'`），
+  **默认 `plain` 保持存量表现不变**；
+- 属性面板挂点同 2.2（`propertyRegister` 加一行 + 新建 editor，`require.context` 自动注册）；
+- `list-h5-item.vue` 的 `.h5-list-box > .item` 上加 class：
+
+```html
+<div class="item" :class="{ 'h5-item-card': widget.options.itemStyle === 'card' }" …>
+```
+
+> 判等口径同 P0 §3.2：只判 `=== 'card'`，老表单读到 `null`/`undefined` 时退回 plain。
+
+- 箭头角标（仅 card 模式渲染，放在 `.t1` 内）：
+
+```html
+<i class="h5-item-arrow" v-if="widget.options.itemStyle === 'card'"></i>
+```
+
+### 3.3 样式（h5.scss 块 I）
+
+```scss
+.xform-h5 .h5-list-box .item.h5-item-card {
+  border-radius: $xformH5CardRadius;
+
+  .t1 {
+    &::before {                        // 竖条 → 圆点
+      width: 5px !important;
+      height: 5px !important;
+      top: auto !important;
+      border-radius: 50% !important;
+      position: relative !important;
+      display: inline-block;
+      margin-right: 4px;
+    }
+    padding-right: 40px;               // 给箭头角标让位
+  }
+
+  .h5-item-arrow {
+    position: absolute;
+    right: 12px;
+    top: 10px;
+    width: 20px;
+    height: 20px;
+    line-height: 20px;
+    text-align: center;
+    font-size: 12px;
+    border-radius: 50%;
+    background: rgba(42, 100, 148, 0.12);
+    &::before { content: "\e6e0"; font-family: element-icons !important; }
+  }
+
+  .t2 > dl { min-width: 49%; font-size: 11px; }
+}
+```
+
+### 3.4 行级变更标记
+
+`indexMixin.js:2556` 已有 `getCompareRowClass(subFormName, row)`，返回
+`xform-compare-row-new` / `xform-compare-row-changed` / `""`，`data-table` 已在用
+（`data-table-mixin.js:1573`）。list-h5 直接复用：
+
+```js
+    getRowCompareClass(row) {
+      let formRef = this.getFormRef();
+      if (!formRef || !formRef.isCompare || !formRef.getCompareRowClass) return "";
+      return formRef.getCompareRowClass(this.getListFieldName(), row);
+    },
+```
+
+`subFormName` 取 list-h5 的字段名（`widget.options.name` / `keyName`，
+与 `data-table` 传给 `getCompareRowClass` 的口径保持一致 —— 实现时对齐
+`data-table-mixin.js:1573` 那里的 `self.fieldKeyName`）。
+
+样式上给 `.xform-h5 .h5-list-box .item.xform-compare-row-changed` 加右上角
+`el-icon-warning` 角标（对齐 bill_setting `.pro-item .t i.el-icon-warning`，色 `#ff731c`）。
+
+> `getCompareRowClass` 内部先过 `isCompareSubTable(subFormName)`，
+> 未参与对比的子表返回 `""`，不会满屏高亮 —— 这条保护已存在，不需重复实现。
+
+---
+
+## 四、i18n
+
+`lang/zh-CN.js` 与 `lang/en-US.js` 的 `designer.setting` 下补：
+
+```js
+h5MoreButton: "更多",
+maxVisibleButtons: "底栏按钮数",
+maxVisibleButtonsHelp: "仅 H5 版式生效。底部动作栏平铺显示的按钮个数，超出部分收进「更多」下拉。",
+itemStyle: "明细行样式",
+itemStyleHelp: "plain=朴素列表；card=卡片（带圆点标题与右侧箭头，点击进入明细详情）。",
+```
+
+---
+
+## 五、自测清单
+
+骨架：
+
+1. 页面态：内容区滚动时标题栏与底栏不动；
+2. 弹框态（`formDialog` / `searchFormDialog` / `fileReferenceDialog` 三条路径各验一次）：
+   底栏贴**弹框**底部而不是屏幕底部（**这是 1.2 那个现存 bug 的回归验证点**）；
+3. outLink 态：高度正确，无双滚动条；
+4. 手机真机：聚焦输入框调起键盘，底栏不被顶飞、不遮挡当前输入行；
+5. 内容不足一屏时，底栏仍在底部而不是浮在内容下方；
+6. `.h5-detail-wrap` 未塌成 0 高（1.5 的降级安全阀验证）。
+
+底栏：
+
+7. 按钮数 ≤ 阈值：全部平铺，无「更多」；
+8. 按钮数 > 阈值：超出部分进「更多」，点击能正常触发原按钮逻辑；
+9. **「更多」菜单里的按钮样式正确**（2.3 的 append-to-body 验证点）；
+10. 老表单（`maxVisibleButtons` 为 null/undefined）：全部平铺，不出现「更多」；
+11. hidden 按钮不在「更多」里留空行（见 六、待确认 2）。
+
+明细：
+
+12. `itemStyle=plain`（默认）：与改动前**像素级一致**（存量回归底线）；
+13. `itemStyle=card`：圆角 12、标题圆点、右侧圆形箭头角标；
+14. 点卡片仍能打开「明细详情」弹框（`list-h5-item.vue:426`）；
+15. 对比模式下变更行有角标、新增行有高亮；未参与对比的子表不高亮。
+
+回归：
+
+16. **PC 版式（layoutType≠H5）下 DOM 根不含 `xform-h5`，以上全部不生效**；
+17. `npm run lint`；`npm run test:unit`。
+
+---
+
+## 六、待确认
+
+1. **1.5 的降级安全阀取方案 a 还是 b？** 需要真机 + 三类宿主实测后定。
+   B 层已拍「先按默认做，真机再调」，实现时先取方案 a（`min-height:100vh`），
+   若弹框态超出再换 b。
+2. **hidden 按钮的分流时机**：`visibleButtons` / `overflowButtons` 里要不要先
+   `filter(w => !w.options.hidden)`？倾向：要。但注意 `hidden` 可能被脚本运行时改，
+   computed 依赖 `widget.widgetList` 的深层属性能否触发重算需实测
+   （若不触发，退回「不过滤 + 菜单项 `v-if`」）。
+3. **`.h5-detail-wrap` 的 `padding-bottom:68px`（`style.scss:13765`）**
+   P1 只用 `!important` 压住不删。若 P3 决定回收 style.scss 存量 H5 样式，
+   届时连同一并处理。