uni-smart-form

uni-smart-form 是一个表单设计、填写渲染、结果展示组件库。它提供 WorkBench、Render、Result 三类入口，并支持通过插件协议接入第三方业务组件。

当前版本：4.0.0

安装

pnpm add uni-smart-form

运行环境：

• 浏览器环境
• 支持 ES2015 及以上语法

说明：当前构建未把 Vue、Ant Design Vue 配置为外部依赖，它们会进入包构建产物。业务项目使用本包时无需额外安装 Vue 或 Ant Design Vue。

引入

import {
  UniSmartFormWorkBench,
  UniSmartFormRender,
  UniSmartFormResult,
  configureUniSmartFormResources,
  configureUniSmartFormPlugins
} from 'uni-smart-form';
import 'uni-smart-form/style.css';

必须引入 uni-smart-form/style.css。该文件包含 uni-smart-form 自身样式和必要的移动端组件样式；Ant Design Vue 组件样式由组件运行时生成。库内部 Ant Design Vue 使用 uni-smart-ant 前缀隔离，避免和业务项目中的 Ant Design Vue 样式互相影响。

快速开始

const workbench = new UniSmartFormWorkBench('#workbench', {
  name: '活动报名表',
  description: '请填写报名信息',
  autoSave: false,
  theme: '#1677ff'
});

workbench.on('save', event => {
  console.log(event.model, event.jsonUrl);
});

const render = new UniSmartFormRender('#render', {
  model,
  isShowName: true,
  theme: '#1677ff'
});

const result = await render.getRenderValue();

new UniSmartFormResult('#result', {
  model: result.model,
  result: result.formDataResult,
  showSeq: true
});

资源配置

资源配置用于上传文件、解析私有 URL、下载文件。全局配置只作为兜底；如果 WorkBench、Render、Result 的上传或 JSON 读写能力不同，应在实例参数里分别传入。

configureUniSmartFormResources({
  uploadFile: async (file, context) => {
    const result = await uploadFile(file);
    return result.url;
  },
  resolveUrl: async (url, context) => {
    return getSignedUrl(url);
  },
  downloadFile: async (url, name, context) => {
    await downloadFile(url, name);
  }
});

资源适配器类型：

interface UniSmartFormResourceAdapter {
  uploadFile?: (file: File, context: UniSmartFormResourceContext) => Promise<string>;
  resolveUrl?: (url: string, context?: UniSmartFormResourceContext) => Promise<string>;
  downloadFile?: (url: string, name: string, context?: UniSmartFormResourceContext) => void | Promise<void>;
}

interface UniSmartFormResourceContext {
  [key: string]: unknown;
}

实例级资源配置示例：

new UniSmartFormWorkBench('#workbench', {
  resources: workbenchFieldResources,
  formJsonResources: workbenchFormJsonResources,
  jsonResources: workbenchJsonResources
});

new UniSmartFormRender('#render', {
  model,
  resources: renderFieldResources,
  jsonResources: renderJsonResources
});

new UniSmartFormResult('#result', {
  model,
  result,
  resources: resultResources,
  jsonResources: resultJsonResources
});

参数含义：

| 参数 | 使用场景 | | --- | --- | | resources | 字段组件、图片、附件、第三方业务组件使用 | | formJsonResources | WorkBench 保存表单结构 JSON 使用 | | jsonResources | 读取表单结构 JSON 使用 |

WorkBench 表单设计器

用于创建和编辑表单结构。

const workbench = new UniSmartFormWorkBench('#workbench', {
  name: '活动报名表',
  description: '表单描述',
  previewTitle: '预览',
  autoSave: false,
  isOssJson: false,
  theme: '#1677ff'
});

构造参数

| 参数 | 类型 | 说明 | | --- | --- | --- | | name | string | 表单名称 | | description | string | 表单描述 | | saveLoading | boolean | 保存按钮 loading | | canDelete | boolean | 是否允许删除字段 | | previewTitle | string | 预览弹窗标题 | | descPlaceholder | string | 字段描述占位文案 | | include | string[] | 只展示指定字段 key | | exclude | string[] | 排除指定字段 key | | hideSeq | boolean | 隐藏“显示题目序号”配置 | | hideDescription | boolean | 隐藏字段描述配置 | | autoSave | boolean | 是否自动保存，默认 true | | defaultValue | string | 默认表单 JSON 字符串或远端 JSON 地址 | | isOssJson | boolean | defaultValue 和保存结果是否走远端 JSON | | theme | SmartFormTheme | 主题配置 | | resources | UniSmartFormResourceAdapter | 字段资源能力 | | formJsonResources | UniSmartFormResourceAdapter | 保存表单结构 JSON 的资源能力 | | jsonResources | UniSmartFormResourceAdapter | 读取表单结构 JSON 的资源能力 |

方法

| 方法 | 参数 | 返回值 | 说明 | | --- | --- | --- | --- | | on('save', fn) | (event: UniSmartFormWorkBenchSaveEvent) => unknown | void | 监听保存 | | on('preview', fn) | (model: SmartForm) => unknown | void | 接管 WorkBench 预览 | | setDefaultValue(model) | SmartForm | void | 设置表单结构 | | setSingleFillBlankDefaultValueAutoGetSource(source) | { label: string; value: string \| number }[] | void | 设置单项填空自动获取来源 | | unmount() | 无 | void | 卸载实例 |

保存事件：

interface UniSmartFormWorkBenchSaveEvent {
  model: SmartForm;
  jsonUrl?: string;
}

保存说明：

• 手动保存和 autoSave 自动保存都会触发 save 事件。
• autoSave 为 true 时，Workbench 会定时检查结构变化；有变化且校验通过后触发保存。
• jsonUrl 仅在 isOssJson 为 true 且表单结构 JSON 上传成功后返回。

预览行为

workbench.on('preview', model => {
  openCustomPreview(model);
});

• 没有注册 workbench.on('preview') 时，WorkBench 使用内置 Drawer 预览。
• 已注册 workbench.on('preview') 时，点击预览只调用业务方方法，内置 Drawer 不再打开。
• 自定义预览收到的 model 是通过基础配置校验和插件 validateConfig 后的表单结构。
• preview 回调返回值不会影响框架行为。只要注册了该事件，预览逻辑就完全交给业务方。

Render 表单渲染器

用于根据表单结构渲染填写页面。

const render = new UniSmartFormRender('#render', {
  model,
  isShowName: true,
  defaultValues,
  theme: '#1677ff'
});

构造参数

| 参数 | 类型 | 说明 | | --- | --- | --- | | model | SmartForm | 表单结构 | | ossUrl | string | 远端表单结构地址 | | isShowName | boolean | 是否展示表单名称 | | defaultValues | Record<string, ValueBase<unknown>> | 默认填写值 | | defaultValuesFormFields | Partial<FormFieldsFormat>[] | 后端通用字段格式默认值 | | theme | SmartFormTheme | 主题配置 | | resources | UniSmartFormResourceAdapter | 字段资源能力 | | jsonResources | UniSmartFormResourceAdapter | 读取表单结构 JSON 的资源能力 | | commonDownloadFile | (url: string, name: string) => void | 附件下载方法 |

方法

| 方法 | 参数 | 返回值 | 说明 | | --- | --- | --- | --- | | on('rendered', fn) | () => void | void | 渲染完成回调 | | on('autoGet', fn) | (name: string) => string \| Promise<string> | void | 单项填空自动获取 | | getRenderValue() | 无 | unknown \| Promise<unknown> \| undefined | 校验并获取填写结果 | | getCurrentRenderValue() | 无 | unknown \| undefined | 不校验，获取当前填写结果 | | setDefaultValue(values) | Record<string, ValueBase<unknown>> | void | 设置默认填写值 | | setDefaultValueFormFields(fields) | Partial<FormFieldsFormat>[] | void | 设置后端通用字段默认值 | | unmount() | 无 | void | 卸载实例 |

Result 结果展示

用于展示 Render.getRenderValue() 返回的结果，或展示后端保存的通用结果 JSON。

new UniSmartFormResult('#result', {
  model,
  result,
  showSeq: true,
  theme: '#1677ff'
});

构造参数

| 参数 | 类型 | 说明 | | --- | --- | --- | | result | ValueBase<unknown>[] | 结果数据 | | model | SmartForm | 表单结构 | | showSeq | boolean | 是否展示序号 | | formDataJson | string | 后端保存的通用结果 JSON | | theme | SmartFormTheme | 主题配置 | | resources | UniSmartFormResourceAdapter | 字段资源能力 | | jsonResources | UniSmartFormResourceAdapter | 读取 JSON 的资源能力 | | commonDownloadFile | (url: string, name: string) => void | 附件下载方法 |

方法

| 方法 | 参数 | 返回值 | 说明 | | --- | --- | --- | --- | | unmount() | 无 | void | 卸载实例 |

第三方业务组件

第三方业务组件通过插件注册。

configureUniSmartFormPlugins({
  fields: [businessFieldPlugin]
});

插件必须在创建 WorkBench、Render、Result 实例之前注册。

最小插件结构：

const businessFieldPlugin = {
  key: 'businessField',
  name: '业务字段',
  category: '业务组件',
  type: 'TEXT',
  createField: () => ({
    title: '业务字段',
    customConfig: ''
  }),
  mountMenu(container, props) {
    return mountMenu(container, props);
  },
  mountWorkbench(container, props) {
    return mountWorkbench(container, props);
  },
  mountRender(container, props) {
    return mountRender(container, props);
  }
};

第三方字段新增时，框架会强制设置：

• required: true
• hasDescription: false

详细接入说明见 第三方业务组件接入说明。

主题

theme 支持主题色字符串，也支持 Ant Design Vue 风格的主题对象。

new UniSmartFormRender('#render', {
  model,
  theme: '#1677ff'
});

new UniSmartFormRender('#render', {
  model,
  theme: {
    token: {
      colorPrimary: '#1677ff',
      colorSuccess: '#52c41a'
    }
  }
});

说明：

• 支持 theme.primaryColor、theme.colorPrimary、theme.token.colorPrimary。
• 主题色会同步到 CSS 变量和 Ant Design Vue 主题。
• 组件内部关闭 Ant Design Vue 动画。
• 组件内部 Ant Design Vue 类名前缀为 uni-smart-ant，图标保持 Ant Design Icons 默认 anticon 前缀。

数据结构

interface SmartForm {
  name: string;
  description: string;
  list: SmartFormItem[];
  showSeq: boolean;
}

interface ValueBase<T> {
  value: T;
  displayValue: string | unknown;
  type?: string;
  id?: string | number;
  extra?: unknown;
  title?: string;
  seq?: number;
}

interface FormFieldsFormat {
  uuid: string;
  title: string;
  type: 'TEXT' | 'NUMBER' | 'URL_FILE';
  contents: Array<Partial<FormFieldsContent>>;
  leaf: boolean;
  children: Array<Partial<FormFieldsFormat>>;
}

本地开发

pnpm install
pnpm dev

构建：

pnpm build

说明：

• pnpm dev 启动 Vite 示例服务。
• pnpm build 使用 build.config.js 构建库文件和类型声明。
• pnpm test 当前是占位命令，不作为有效测试。

版本说明

4.0.0 升级说明见 4.0.0 升级说明。