cloud-web-corejs 1.0.54-dev.81 → 1.0.54-dev.811

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

@@ -0,0 +1,528 @@
+# xform H5 —— P0 实现规格
+
+> 日期：2026-08-25
+> 上位文档：`2026-08 xform 移动端布局对齐 bill_setting 方案.md`（决策 1/2/4/5 + 缺陷 5.1/5.2）
+> 状态：**规格已细化，未编码**
+> P0 边界：纯样式 + 一个字段选项。**不改数据结构、不改提交、不改取数**，可独立上线。
+
+P0 交付 4 件事：
+
+1. 根类 `.xform-h5` 由 form-render 输出（决策 1）
+2. 包内样式基线 `src/components/xform/styles/h5.scss`（决策 2）
+3. 字段排布 CSS 复刻 + 字段级 `h5Span` 半宽选项（决策 4/5）
+4. 卡片皮肤微调 + 修 5.1（customClass 漏绑）/ 5.2（m2 死规则）
+
+---
+
+## 一、根类落地
+
+### 1.1 现状
+
+`form-render/index.vue:13-22`：
+
+```html
+<el-form
+  :label-position="labelPosition"
+  :size="size"
+  :class="[customClass]"
+  class="render-form"
+  ...
+>
+```
+
+`customClass` 来自 `form-render/indexMixin.js:335`，只取 `formConfig.customClass`。
+`formConfig` 是 computed（`indexMixin.js:303`，返回 `this.formJsonObj.formConfig`），可直接用。
+
+### 1.2 改法
+
+`indexMixin.js` 新增 computed（紧挨 `customClass` 放）：
+
+```js
+    /** H5 版式根类：所有 H5 样式都收在 .xform-h5 作用域下，见 styles/h5.scss */
+    h5RootClass() {
+      return !!this.formConfig && this.formConfig.layoutType === "H5"
+        ? "xform-h5"
+        : "";
+    },
+```
+
+`index.vue` 的 el-form：
+
+```html
+  :class="[customClass, h5RootClass]"
+```
+
+### 1.3 为什么不复用现有两个开关
+
+| 现有开关 | 加在哪 | 为什么不够 |
+|---|---|---|
+| `.designer-view.h5-layout` | `views/user/form/vform/render.vue:4` | 只有这一个宿主壳会加。表单还从 `formDialog` / `formDrawer` / `outLink/form_view` / 微前端子应用渲染，那几条路径拿不到根类 —— 现有 `formDialog.vue:319`、`searchFormDialog.vue:488`、`fileReferenceDialog.vue:277` 里的 `::v-deep .H5 .h5-fixed-bottom-btns` 补丁就是漂移证据 |
+| `#app.mobileApp` | `App.vue:2`，UA 判定 | 与 layoutType 正交：H5 表单会在 PC 浏览器里预览，PC 表单也会在手机上打开 |
+
+宿主壳的 `.h5-layout` 与 `.mobileApp` **都保持不动**，只是不再依赖它们。
+
+---
+
+## 二、样式基线文件
+
+### 2.1 位置与引入
+
+- 新建：`src/components/xform/styles/h5.scss`
+- 引入：`form-render/index.vue` 的 `<style lang="scss">`（**必须非 scoped** —— 要穿透到各
+  field-widget 内部的 `.el-form-item`）：
+
+```html
+<style lang="scss">
+@import "../styles/h5.scss";
+</style>
+```
+
+> 现有 `index.vue` 底部那个 `<style lang="scss" scoped>` 块保留不动，新增一个非 scoped 块。
+
+- 变量（`$baseColor` 等）由 vue.config 的 sass `additionalData` 注入的 `styles/global.scss` 提供，
+  两个应用的 vue.config 已约定一致，直接用即可。
+
+### 2.2 特异度策略（**必读，否则样式会随机失效**）
+
+现有 H5 样式写在 `resources/css/style.scss` 的裸类名下（`.h5-detail-wrap .h5-item ...`），
+它经 `src/styles/index.scss` 全局引入。新文件通过组件 `<style>` 注入，
+**两者的加载先后在 webpack 下不可靠**，不能靠「后写覆盖先写」。
+
+因此本文所有覆盖规则遵守两条硬约束：
+
+1. 凡是要覆盖 style.scss 同名规则的选择器，**特异度必须严格更高**。
+   现有典型是 `.h5-detail-wrap .h5-item .el-form-item__label`（0,3,0），
+   新规则写 `.xform-h5 .h5-detail-wrap .h5-item .el-form-item__label`（0,4,0）即可稳压。
+2. 凡是对方带 `!important` 的（下表标注），**本方也必须带 `!important`**，特异度再高也压不过。
+
+### 2.3 必须覆盖的现有规则对照
+
+| 现有规则（`style.scss` 行号） | 现值 | 目标值 | 覆盖要点 |
+|---|---|---|---|
+| `.h5-detail-wrap .h5-item .el-form-item__label`（13860 附近）的 `&:after{display:none}` | 冒号被关掉 | `content:":"` 显示 | **这条最容易踩**：要先把 `display` 打开再给 content |
+| 同上 `line-height: 38px` / `text-align:left !important` | 38px | 1.4，左对齐保持 | `text-align` 对方带 `!important`，本方也要带 |
+| `.h5-item .el-input .el-input__inner`（13868 附近） | `height:38px!important; line-height:38px!important; border-radius:8px` | 无边框、右对齐、贴合 48px 行 | 三条都要 `!important` 回压 |
+| `.h5-detail-wrap{padding-bottom:68px}`（13765） | 给 fixed 底栏让位 | P0 暂留（骨架改到 P1） | P0 不动，避免与 P1 冲突 |
+| `.h5-form-box .form-widget-list.m2`（13806） | 死规则 | 删除 | 见 五、5.2 |
+| `.h5-form-box .el-upload-list__item{width:102px}`（13818 起） | 102px | P2 统一为 74px | P0 不动 |
+
+### 2.4 规则清单
+
+按块给出，实现时逐块落。**全部包在 `.xform-h5 { }` 内。**
+
+**块 A —— 变量**
+
+```scss
+$xformH5HeaderHeight: 38px;   // 标题栏
+$xformH5FooterHeight: 56px;   // 底部动作栏（P1 用）
+$xformH5DialogChrome: 73px;   // 弹框 header+padding 占位（P1 用）
+$xformH5RowHeight: 48px;      // 字段行高
+$xformH5LabelWidth: 80px;     // 标签宽
+$xformH5RowBorder: #f3f3f3;   // 行分隔线
+$xformH5CardRadius: 12px;
+```
+
+> 这几个常量正是为了收掉 bill_setting 散在 4 处 5 个值的 `calc(100vh - N)`（见上位文档 5.4）。
+> **不要把 bill_setting 的具体数值抄过来**，以本表为准。
+
+**块 B —— 分组卡片（对齐 `.c-item / .tit`）**
+
+```scss
+.xform-h5 {
+  .h5-item {
+    background: #fff;
+    border-radius: $xformH5CardRadius;
+    margin: 12px 8px 0;
+    padding-bottom: 6px;
+    overflow: hidden;
+
+    .h5-title {
+      line-height: 45px;
+      padding: 0 12px;
+      border-bottom: 1px solid #f6f6f6;
+      position: relative;
+      b { font-size: 14px; font-weight: 600; color: #323232; }
+      &::after {          // 左侧竖色条，对齐 bill_setting 的 .tit>b::before
+        content: "";
+        position: absolute;
+        left: 0; top: 16px;
+        width: 4px; height: 13px;
+        background: $baseColor;
+        border-radius: 4px;
+      }
+    }
+  }
+}
+```
+
+**块 C —— 字段行（核心，决策 4 的 CSS 复刻）**
+
+```scss
+.xform-h5 .h5-detail-wrap .h5-item .h5-form-box {
+  padding: 12px;
+
+  .form-widget-list { display: flex; flex-wrap: wrap; }
+  .field-wrapper { width: 100%; }
+  .field-wrapper.h5-half { width: 50%; }
+
+  .el-form-item {
+    display: flex;
+    align-items: flex-start;
+    min-height: $xformH5RowHeight;
+    padding: 6px 0;
+    margin-bottom: 0;
+    border-bottom: 1px solid $xformH5RowBorder;
+
+    .el-form-item__label {
+      width: $xformH5LabelWidth;
+      padding: 0 5px 0 0;
+      margin: 0;
+      line-height: 1.4;
+      height: auto;
+      overflow: hidden;
+      text-align: left !important;   // 压 style.scss 的 !important
+      color: #808080;
+      &::after {
+        display: inline !important;  // style.scss 把它 display:none 了
+        content: ":";
+      }
+    }
+
+    .el-form-item__content {
+      flex: 1;
+      line-height: 1.4;
+      text-align: right;
+      word-break: break-word;
+    }
+
+    &:last-child { border-bottom: none; }
+  }
+}
+```
+
+**块 D —— 输入控件归一（去边框、右对齐）**
+
+```scss
+.xform-h5 .h5-detail-wrap .h5-item .h5-form-box .el-form-item__content {
+  .el-input, .el-select { width: 100% !important; }
+
+  .el-input .el-input__inner,
+  .el-textarea .el-textarea__inner {
+    height: auto !important;
+    line-height: 1.4 !important;
+    min-height: 34px;
+    border: none !important;
+    border-radius: 0 !important;
+    padding: 0;
+    text-align: right;
+  }
+
+  .el-input .el-input__suffix,
+  .el-input .el-input__prefix {
+    .el-input__icon { line-height: 34px !important; }
+  }
+
+  .el-radio-group .el-radio,
+  .el-checkbox-group .el-checkbox {
+    margin: 0 0 0 8px;
+    .el-radio__label, .el-checkbox__label { padding-left: 4px; }
+  }
+}
+```
+
+**块 E —— 必填星号与校验错误位**
+
+字段行改成 flex 后，Element 的必填星号（`.el-form-item__label::before`）和错误提示会错位，
+必须显式定位（bill_setting 的 `&:before{position:absolute}` 是同一处理）：
+
+```scss
+.xform-h5 .h5-detail-wrap .h5-item .h5-form-box .el-form-item {
+  position: relative;
+  &.is-required .el-form-item__label::before {
+    position: absolute;
+    left: -8px;
+    margin: 0;
+  }
+  .el-form-item__error {
+    position: static;
+    text-align: right;
+    padding-top: 2px;
+  }
+}
+```
+
+**块 F —— 半宽相邻行的分隔线**
+
+两个半宽字段并排时，块 C 的 `border-bottom` 会各画一条、视觉上是一条；
+但当一行只有一个半宽字段（末尾落单）时右半边缺线。P0 接受该表现，
+如需补齐在 `.field-wrapper.h5-half` 上加 `&:nth-child(odd):last-child { width: 100%; }`。
+**该行为需 UI 确认**（见 六、待确认）。
+
+---
+
+## 三、`h5Span` 字段选项
+
+### 3.1 数据落点
+
+`hasConfig`（`designer.js:1082`）判断属性面板显不显示某编辑器，
+读的是 **widgetsConfig 里原型 widget 的 options**，不是当前实例。
+所以 `h5Span` 必须进原型。
+
+字段原型共 42 个（`grep -c "formItemFlag: !0"`），另有 extension 通过
+`addBasicFieldSchema` / `addAdvancedFieldSchema` / `addCustomWidgetSchema` 动态注册的。
+
+**推荐做法：一处后处理，而不是 42 处手工展开 `...defaultH5Config`。**
+
+在 `widgetsConfig.js` 尾部（`customFields` 声明之后、`add*Schema` 函数之前）加：
+
+```js
+/** H5 版式：所有表单字段统一具备 h5Span（整宽/半宽），见 docs/2026-08 xform H5 P0 实现规格.md */
+export const defaultH5Config = {
+  h5Span: "full", // 'full' | 'half'
+};
+
+function applyH5FieldDefaults(schema) {
+  if (!schema || !schema.formItemFlag || !schema.options) return schema;
+  if (!Object.prototype.hasOwnProperty.call(schema.options, "h5Span")) {
+    Object.assign(schema.options, defaultH5Config);
+  }
+  return schema;
+}
+
+[basicFields, advancedFields, businessFields, customFields].forEach((list) =>
+  list.forEach(applyH5FieldDefaults)
+);
+```
+
+并在四个注册函数里各补一行（保证 extension 注册的组件也有）：
+
+```js
+export function addBasicFieldSchema(fieldSchema) {
+  basicFields.push(applyH5FieldDefaults(fieldSchema));
+}
+```
+
+> **TDZ 注意**：文件头部已有一条血泪注释（`widgetsConfig.js:1-6`）——
+> Babel 转译后 `const` 提升会丢 TDZ，`...xxx` 展开 undefined。
+> 本方案用的是**函数调用**而非展开，且放在所有数组声明之后，不踩这个坑。
+> 但 `defaultH5Config` 的声明位置仍需在 `applyH5FieldDefaults` 之前。
+
+### 3.2 老表单兼容（**必读**）
+
+`upgradeWidgetConfig`（`designer.js:1114`）给老表单补新增 options 时：
+
+```js
+        Object.keys(newWidget.options).forEach((ck) => {
+          if (!oldWidget.options.hasOwnProperty(ck)) {
+            let value = newWidget.options[ck];
+            let nullValue = Array.isArray(value) ? [] : null;
+            oldWidget.options[ck] = nullValue;      // ← 补 null，不是补默认值
+          }
+        });
+```
+
+两条推论：
+
+1. **老表单在设计器里打开后，`h5Span` 是 `null`，不是 `"full"`。**
+2. **运行时渲染根本不跑这段**（它只在 `form-designer/indexMixin.js:456` 的
+   `upgradeFormJson` 里调），数据库存的老 formJson 里压根没有 `h5Span` 键，运行时读到 `undefined`。
+
+所以渲染侧与编辑器侧**一律只判等于 `'half'`，绝不判「不等于 full」**：
+
+```js
+// 正确
+field.options.h5Span === "half"
+// 错误：null / undefined 会被当成 half，老表单全变两列
+field.options.h5Span !== "full"
+```
+
+### 3.3 属性面板挂点
+
+三步，全部是既有机制，无需改框架：
+
+1. **注册属性名 → 编辑器名**：`setting-panel/propertyRegister.js` 的 `COMMON_PROPERTIES`
+   里，「字段」区块（`labelWidth` / `labelHidden` 附近）加一行：
+
+   ```js
+   h5Span: "h5Span-editor",
+   ```
+
+2. **新建编辑器组件**：`setting-panel/property-editor/h5Span-editor.vue`。
+   该目录由 `property-editor/index.js` 的 `require.context('./', true, /\w+\.vue$/)`
+   **自动收集并按 `comp.name` 注册**，不需要手工 import。
+   → 组件的 `name` 必须严格等于 `"h5Span-editor"`。
+
+3. **显示条件**：仅 `formConfig.layoutType === 'H5'` 时显示（参照
+   `container-grid-col/grid-col-span-editor.vue` 的 `formConfig` computed 写法）。
+
+### 3.4 编辑器组件骨架
+
+以 `fixedQuery-editor.vue` 为模板（同为「条件显示 + tooltip」型）：
+
+```html
+<template>
+  <!-- 仅 H5 版式下显示：PC/Pad 版式该选项无作用 -->
+  <el-form-item
+    v-if="showEditor"
+    :label="i18nt('designer.setting.h5Span')"
+    class="form-item-label-top"
+  >
+    <el-tooltip
+      :enterable="false"
+      effect="dark"
+      :content="i18nt('designer.setting.h5SpanHelp')"
+      placement="top"
+      popper-class="tooltip-skin"
+    >
+      <el-radio-group v-model="optionModel.h5Span" size="mini">
+        <el-radio-button label="full">{{ i18nt('designer.setting.h5SpanFull') }}</el-radio-button>
+        <el-radio-button label="half">{{ i18nt('designer.setting.h5SpanHalf') }}</el-radio-button>
+      </el-radio-group>
+    </el-tooltip>
+  </el-form-item>
+</template>
+
+<script>
+import i18n from "../../../../../components/xform/utils/i18n";
+
+export default {
+  name: "h5Span-editor",
+  mixins: [i18n],
+  props: {
+    designer: Object,
+    selectedWidget: Object,
+    optionModel: Object,
+  },
+  computed: {
+    showEditor() {
+      return (
+        !!this.designer &&
+        !!this.designer.formConfig &&
+        this.designer.formConfig.layoutType === "H5"
+      );
+    },
+  },
+};
+</script>
+
+<style scoped></style>
+```
+
+> 老表单打开时 `optionModel.h5Span` 是 `null`（见 3.2），两个 radio 都不选中 ——
+> 这是**可接受**表现（等价于整宽），用户点一次即定值。
+> 不要在 editor 里 `created` 时自动写 `"full"`，那会把所有老表单标记成已修改。
+
+### 3.5 i18n 词条
+
+- `src/components/xform/lang/zh-CN.js`，`designer.setting` 下（`fixedQuery` 在 347 行附近，就近放）：
+
+  ```js
+  h5Span: "H5 占宽",
+  h5SpanFull: "整宽",
+  h5SpanHalf: "半宽",
+  h5SpanHelp: "仅 H5 版式生效。半宽时两个字段并排一行，对应移动端的紧凑两列版式。",
+  ```
+
+- `src/components/xform/lang/en-US.js` 同结构补 4 条（`fixedQuery` 在 193 行附近）。
+
+### 3.6 渲染落点
+
+`form-item-wrapper.vue:11-15` 现状：
+
+```html
+  <div
+    class="field-wrapper"
+    :class="{ 'design-time-bottom-margin': !!this.designer }"
+    v-show="!field.options.hidden || designState === true"
+  >
+```
+
+改为（注意 3.2 的判等口径）：
+
+```html
+  <div
+    class="field-wrapper"
+    :class="[
+      { 'design-time-bottom-margin': !!this.designer },
+      field.options.h5Span === 'half' ? 'h5-half' : '',
+    ]"
+    v-show="!field.options.hidden || designState === true"
+  >
+```
+
+> `form-item-wrapper` 是所有字段的公共入口，改这里一处即全量生效（设计器与运行时同一组件）。
+> `.h5-half` 只在 `.xform-h5` 作用域内有样式（块 C），PC 下是个无害的空 class。
+
+---
+
+## 四、卡片皮肤微调
+
+按块 B 落即可。另需修 `h5-card-pane-item.vue`（缺陷 5.1）：
+
+现状 `h5-card-pane-item.vue:2`：
+
+```html
+  <div class="h5-item">
+```
+
+组件里定义了 `customClass` computed 却从未使用，
+而设计器侧 `h5-card-pane-widget.vue:2` 是绑了的 —— 导致设计器配的 class 到运行期丢失。改为：
+
+```html
+  <div class="h5-item" :class="[customClass]">
+```
+
+---
+
+## 五、删除死代码
+
+**5.2**：`resources/css/style.scss:13806` 的
+
+```scss
+      .form-widget-list {
+        &.m2 { ... }
+      }
+```
+
+`form-widget-list` 的 class 是写死在 `transition-group` 上的，
+customClass 落在 `.grid-cell` 或 `el-form-item` 上，这条选择器**永远命中不了**。
+两列布局由块 C 的 `.field-wrapper.h5-half` 接管，此规则整块删除。
+
+---
+
+## 六、自测清单
+
+设计器侧：
+
+1. 版式切 PC → 字段属性面板**无**「H5 占宽」；切 H5 → 出现；
+2. 新建字段默认「整宽」；打开老表单，该字段两个 radio 均未选中，点一次能存住；
+3. 选「半宽」后，设计器画布内两个半宽字段并排（设计器与运行时共用 form-item-wrapper，应一致）。
+
+运行时侧（同一张表单分别以 PC / H5 版式渲染）：
+
+4. PC 版式下 DOM 根 `el-form` **不含** `xform-h5`，全部 H5 样式不生效（回归底线）；
+5. H5 版式下：字段行高 48px、标签宽 80px 且带冒号、值右对齐、输入框无边框无圆角；
+6. 必填字段星号不与标签文字重叠；
+7. 触发校验，错误文案在值下方右对齐，不把行撑破/不遮挡下一行；
+8. 长文本值换行后行高自适应，不溢出卡片；
+9. 半宽字段两列不错位；末尾落单的半宽字段表现符合 六、待确认 1 的结论；
+10. 卡片圆角 12、标题左侧竖色条位置正确；
+11. 从 `formDialog` / `formDrawer` / `outLink/form_view` 三条路径打开同一张 H5 表单，样式一致
+    （这是决策 1 的验证点 —— 旧的 `.h5-layout` 在这三条路径下拿不到）。
+
+回归：
+
+12. `npm run lint`；
+13. `npm run test:unit`（P0 无逻辑分支，主要看没有误伤既有用例）。
+
+---
+
+## 七、待确认
+
+1. **末尾落单的半宽字段**是撑满整行还是留半行空白？（块 F）
+2. **`h5Span` 的默认值**在 UI 上要不要给老表单显式回填 `"full"`？
+   本规格选择「不回填」，理由见 3.4 注释。若产品要求面板必须有选中态，
+   则应在 `upgradeWidgetConfig` 之外单独做一次性迁移，而不是在 editor 里写。
+3. 块 D 把输入框边框全去掉后，**可编辑字段与只读字段在视觉上不可区分**
+   （bill_setting 也是这个表现，靠 `showSaveButton` 整表切换编辑/只读）。
+   若需要区分，建议 P1 给可编辑态加一条下划线而不是恢复边框。