@jxyszb/jxy-form-designer 0.1.0

package/docs/field-suffix-extension.md

@@ -0,0 +1,289 @@
+# JXY 表单字段右侧扩展位使用说明
+
+## 功能定位
+
+字段右侧扩展位用于在表单控件右边渲染由业务页面提供的附加内容，例如评价按钮、查看详情、辅助计算或状态提示。
+
+JXY Form Designer 只负责：
+
+- 在 Schema 中记录字段是否启用扩展位及扩展位宽度。
+- 在 Runtime 中提供统一的 `field-suffix` 作用域插槽。
+- 向插槽回传当前字段节点、字段标识、字段值和运行时状态。
+- 隔离扩展组件与宿主 `el-form-item` 的校验上下文。
+
+组件不会内置具体业务按钮，也不会将扩展组件的数据合并进表单 `formData`。
+
+## 设计器配置
+
+在右侧“表单配置”页签中可以设置整张表单的默认扩展位宽度：
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| 右侧扩展位宽度(px) | `60` | 当前表单所有字段的默认扩展位宽度 |
+
+在设计器画布中选中一个字段，打开右侧“属性面板”，可以配置：
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| 启用右侧扩展位 | 关闭 | 控制当前字段是否允许渲染 `field-suffix` 插槽内容 |
+| 右侧扩展位宽度(px) | 空 | 留空时继承表单配置，填写后仅覆盖当前字段，单位为 px |
+
+开启后，设计器画布会在字段右侧显示“扩展位”占位。占位仅用于表示布局，不会在画布内运行真实业务组件。
+
+实际预览时还必须由调用方提供 `field-suffix` 插槽；只开启配置但没有传入插槽，不会产生空白区域。
+
+![image-20260804102608368](C:\Users\36383\AppData\Roaming\Typora\typora-user-images\image-20260804102608368.png)
+
+## Schema 结构
+
+扩展位配置保存在每个 `field` 节点的 `extensions.suffix` 中：
+
+```js
+{
+  config: {
+    suffixWidth: 60
+  },
+  nodes: [
+    {
+      id: 'field_name',
+      nodeType: 'field',
+      prop: 'name',
+      label: '姓名',
+      type: 'text',
+      extensions: {
+        suffix: {
+          enabled: true,
+          width: ''
+        }
+      }
+    }
+  ]
+}
+```
+
+宽度解析优先级为：
+
+```text
+field.extensions.suffix.width
+  > schema.config.suffixWidth
+  > 内置兜底 60px
+```
+
+表单级 `suffixWidth` 必须是大于等于 `0` 的数字。字段级 `width` 可以为空，非空时必须是大于等于 `0` 的数字。旧 Schema 加载后会补充表单默认值 `60`，字段宽度补为空以继承表单配置。
+
+## 插槽参数
+
+`JXYFormRuntime` 提供唯一的字段右侧扩展插槽：
+
+```vue
+<template #field-suffix="scope">
+  <!-- 业务组件 -->
+</template>
+```
+
+`scope` 包含以下参数：
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| `field` | `JxyFieldNode` | 当前字段的完整 Schema 节点 |
+| `fieldId` | `string` | 当前字段节点 ID，适合用作扩展数据主键 |
+| `prop` | `string` | 当前字段标识，对应 `formData` 的 key |
+| `label` | `string` | 当前字段标题 |
+| `value` | `unknown` | 当前字段的实时值，只建议读取 |
+| `disabled` | `boolean` | 字段合并静态配置、表单配置和联动规则后的禁用状态 |
+| `required` | `boolean` | 字段合并静态配置和联动规则后的必填状态 |
+
+插槽不提供修改字段值的方法。字段值仍应通过 Runtime 的 `v-model`、`setData()` 或正常表单交互修改。
+
+## Runtime 接入示例
+
+下面示例将扩展数据按 `fieldId` 独立保存：
+
+```vue
+<template>
+  <JXYFormRuntime
+    ref="runtimeRef"
+    v-model="formData"
+    :schema="publishedSchema"
+  >
+    <template #field-suffix="scope">
+      <FieldReview
+        :model-value="reviews[scope.fieldId]"
+        :field-id="scope.fieldId"
+        :field-prop="scope.prop"
+        :field-label="scope.label"
+        :field-value="scope.value"
+        :disabled="scope.disabled"
+        @update:model-value="value => updateReview(scope, value)"
+      />
+    </template>
+  </JXYFormRuntime>
+</template>
+
+<script setup>
+import { reactive, ref } from 'vue';
+import { JXYFormRuntime } from '@jxyszb/jxy-form-designer';
+import FieldReview from './FieldReview.vue';
+
+const runtimeRef = ref();
+const formData = ref({});
+const publishedSchema = ref({});
+const reviews = reactive({});
+
+function updateReview(scope, value) {
+  reviews[scope.fieldId] = {
+    fieldId: scope.fieldId,
+    prop: scope.prop,
+    label: scope.label,
+    ...value
+  };
+}
+
+async function submit() {
+  await runtimeRef.value.validate();
+
+  const payload = {
+    formData: runtimeRef.value.getData(),
+    reviews: JSON.parse(JSON.stringify(reviews))
+  };
+
+  // 调用方根据后端接口要求提交 payload。
+  console.log(payload);
+}
+</script>
+```
+
+推荐使用 `fieldId` 作为扩展数据主键。设计器修改字段 `prop` 时，节点 ID 通常保持不变，可以避免评价数据因字段标识调整而失去关联。
+
+## 编写扩展组件
+
+扩展组件应将字段信息视为只读上下文，将自己的业务值通过独立的 `v-model` 交给调用方管理。
+
+下面是一个简化的 Checkbox 多选加输入框组件：
+
+**截图**
+
+![image-20260804101653363](C:\Users\36383\AppData\Roaming\Typora\typora-user-images\image-20260804101653363.png)
+
+![image-20260804101706742](C:\Users\36383\AppData\Roaming\Typora\typora-user-images\image-20260804101706742.png)
+
+**代码**
+
+```vue
+<template>
+  <el-popover placement="right" :width="320" trigger="click">
+    <template #reference>
+      <el-button size="small" :disabled="disabled">评价</el-button>
+    </template>
+
+    <div class="field-review">
+      <div>{{ fieldLabel }}（{{ fieldProp }}）</div>
+      <div>当前字段值：{{ displayValue }}</div>
+
+      <el-checkbox-group
+        :model-value="review.checkedValues"
+        :validate-event="false"
+        @update:model-value="updateCheckedValues"
+      >
+        <el-checkbox value="accurate">准确</el-checkbox>
+        <el-checkbox value="complete">完整</el-checkbox>
+        <el-checkbox value="standard">规范</el-checkbox>
+      </el-checkbox-group>
+
+      <el-input
+        :model-value="review.comment"
+        type="textarea"
+        :rows="3"
+        :validate-event="false"
+        placeholder="请输入评价说明"
+        @update:model-value="updateComment"
+      />
+    </div>
+  </el-popover>
+</template>
+
+<script setup>
+import { computed } from 'vue';
+
+const props = defineProps({
+  modelValue: {
+    type: Object,
+    default: () => ({ checkedValues: [], comment: '' })
+  },
+  fieldId: { type: String, required: true },
+  fieldProp: { type: String, default: '' },
+  fieldLabel: { type: String, default: '' },
+  fieldValue: { default: undefined },
+  disabled: { type: Boolean, default: false }
+});
+
+const emit = defineEmits(['update:modelValue']);
+
+const review = computed(() => ({
+  checkedValues: Array.isArray(props.modelValue?.checkedValues)
+    ? props.modelValue.checkedValues
+    : [],
+  comment: typeof props.modelValue?.comment === 'string'
+    ? props.modelValue.comment
+    : ''
+}));
+
+const displayValue = computed(() => {
+  if (typeof props.fieldValue === 'string') return props.fieldValue || '(空)';
+  return JSON.stringify(props.fieldValue);
+});
+
+function updateCheckedValues(checkedValues) {
+  emit('update:modelValue', {
+    checkedValues: [...checkedValues],
+    comment: review.value.comment
+  });
+}
+
+function updateComment(comment) {
+  emit('update:modelValue', {
+    checkedValues: [...review.value.checkedValues],
+    comment
+  });
+}
+</script>
+```
+
+不要监听 `fieldValue` 后重置扩展组件的业务数据。这样字段值变化、`setData()` 或 `resetFields()` 都只影响表单本身，不会意外覆盖评价内容。
+
+Runtime 已在扩展位边界隔离外层 `el-form-item` 上下文。示例中的 `validate-event="false"` 仍建议保留，用于明确表达扩展控件不参与宿主字段校验。
+
+## Designer 和预览接入
+
+`JXYFormDesigner` 的全屏预览和 `JXYRuntimePreviewPanel` 使用同一个 `field-suffix` 插槽契约：
+
+```vue
+<JXYFormDesigner :data-source-provider="previewProvider">
+  <template #field-suffix="scope">
+    <FieldReview
+      :model-value="reviews[scope.fieldId]"
+      :field-id="scope.fieldId"
+      :field-prop="scope.prop"
+      :field-value="scope.value"
+      @update:model-value="value => updateReview(scope, value)"
+    />
+  </template>
+</JXYFormDesigner>
+```
+
+设计器画布只显示扩展位占位；全屏预览和 Runtime 才会运行外部组件。调用方没有提供插槽时，即使字段启用了扩展位也不会渲染空容器。
+
+## 数据与生命周期边界
+
+- 字段隐藏时，字段控件和扩展位都不会渲染。
+- 字段禁用状态通过 `disabled` 参数传递，是否禁用扩展组件由业务组件决定。
+- 字段值变化会更新插槽参数 `value`，但不会自动修改扩展组件自己的值。
+- `validate()`、`resetFields()` 和 `getData()` 只处理 Runtime 表单数据。
+- 扩展数据的校验、保存、恢复和提交由业务页面负责。
+- 表单宽度是默认值，字段宽度非空时优先；扩展组件应适配容器宽度，避免写死超过扩展位的最小宽度。
+
+## Playground 测试说明
+
+当前 playground 中的 `FieldEvaluation.vue` 只用于验证插槽参数、Checkbox 多选和独立数据管理，不属于正式组件能力，也不会打入 npm 包的 `dist`。
+
+需要移除测试功能时，删除 playground 中的评价组件以及 `field-suffix`、`preview-actions` 测试插槽即可，不需要修改 Runtime。

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@jxyszb/jxy-form-designer",
+  "version": "0.1.0",
+  "description": "A schema-driven form designer and runtime for Vue 3, Pinia, and Element Plus.",
+  "type": "module",
+  "module": "./dist/index.js",
+  "types": "./types/index.d.ts",
+  "license": "MIT",
+  "author": "jxyszb",
+  "keywords": [
+    "vue3",
+    "element-plus",
+    "form-designer",
+    "form-builder",
+    "schema-form"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist",
+    "types",
+    "docs/field-suffix-extension.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./designer": {
+      "types": "./types/designer.d.ts",
+      "import": "./dist/designer.js"
+    },
+    "./runtime": {
+      "types": "./types/runtime.d.ts",
+      "import": "./dist/runtime.js"
+    },
+    "./schema": {
+      "types": "./types/schema.d.ts",
+      "import": "./dist/schema.js"
+    },
+    "./testing": {
+      "types": "./types/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./style.css": "./dist/style.css"
+  },
+  "typesVersions": {
+    "*": {
+      "designer": [
+        "types/designer.d.ts"
+      ],
+      "runtime": [
+        "types/runtime.d.ts"
+      ],
+      "schema": [
+        "types/schema.d.ts"
+      ],
+      "testing": [
+        "types/testing.d.ts"
+      ]
+    }
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "dev": "vite --config playground/vite.config.js",
+    "test": "vitest run --threads=false",
+    "typecheck": "tsc --noEmit && node ./scripts/check-sfc.mjs",
+    "build": "vite build",
+    "check:dist": "node ./scripts/check-dist.mjs",
+    "pack:dry-run": "npm pack --dry-run",
+    "prepack": "npm run test && npm run typecheck && npm run build && npm run check:dist"
+  },
+  "peerDependencies": {
+    "element-plus": ">=2.7.0 <3",
+    "pinia": ">=2.0.22 <3",
+    "vue": ">=3.2.45 <4"
+  },
+  "dependencies": {
+    "@element-plus/icons-vue": "~2.3.0",
+    "vuedraggable": "^4.1.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "4.0.0",
+    "@vue/compiler-sfc": "3.2.45",
+    "element-plus": "~2.7.0",
+    "pinia": "2.0.22",
+    "sass": "1.56.1",
+    "typescript": "4.9.5",
+    "vite": "4.3.1",
+    "vitest": "0.29.7",
+    "vue": "3.2.45"
+  }
+}

package/types/designer.d.ts

@@ -0,0 +1,12 @@
+export { JXYFormDesigner, useFormDesignerStore } from './index';
+export type {
+  JxyFormDesignerProps,
+  JxyFormDesignerExpose,
+  JxyFieldSuffixSlotScope,
+  JxyFieldSuffixSlots,
+  JxyPreviewActionSlots,
+  JxyFormDesignerSlots,
+  JxyFormDesignerStoreState,
+  JxyFormDesignerStoreActions
+} from './index';
+export { JXYFormDesigner as default } from './index';