Troy 动态表单 web 设计器

基于 FormCreate 的表单生成器的二次封装

如何使用

Vue3

安装

pnpm install troy-form-designer --save

其他依赖

设计器依赖以下第三方库，如果工程中没有引入这些第三库将会无法正常使用，需自行安装。

pnpm install element-plus --save
pnpm install @element-plus/icons-vue --save

快速使用

<template>
  <troy-form-designer ref="designer" @onSave="handleSave" />
</template>

<script>
import { ref } from "vue";
import { TroyFormDesigner, TroyFormCreate } from "troy-form-designer";
const designer = ref(null);

const handleSave = (data) => {
  console.log("data", data);
};

onMounted(() => {
  // 访问 fc-designer 实例
  console.log("fc-designer 实例:", designer.value.$ref);

  // 可通过designer.value.$ref调用表单设计器实例方法
});
</script>

<template>
  <troy-form-create
    v-model="formData"
    v-model:api="api"
    :rule="rule"
    :option="option"
    @submit="onSubmit"
  />
</template>
<script>
import { ref } from "vue";
import { TroyFormCreate } from "troy-form-designer";
const api = ref({});
const option = ref(
  TroyFormCreate.parseJson(
    '{"form":{"inline":false,"hideRequiredAsterisk":false,"labelPosition":"right","size":"default","labelWidth":"125px"},"resetBtn":{"show":false,"innerText":"重置"},"submitBtn":{"show":true,"innerText":"提交"},"formData":{"name":"100"}}'
  )
);
const rule = ref(
  TroyFormCreate.parseJson(
    '[{"type":"input","field":"name","title":"名称","info":"","$required":false,"props":{"disabled":false,"type":"text"},"_fc_id":"id_Fz6tmalz6bbcafc","name":"ref_Fx6ymalz6bbcagc","display":true,"hidden":false,"_fc_drag_tag":"input","control":[{"handle":"[[FORM-CREATE-PREFIX-function(val, api) {\\n    return false;\\n  }-FORM-CREATE-SUFFIX]]","method":"if","rule":["name"]}]},{"type":"input","field":"Fqfzmam3zcdaapc","title":"多行输入框","info":"","$required":false,"props":{"type":"textarea"},"_fc_id":"id_Fkcamam3zcdaaqc","name":"ref_F3xymam3zcdaarc","display":true,"hidden":false,"_fc_drag_tag":"textarea"},{"type":"inputNumber","field":"Fwpbmam3zf55asc","title":"计数器","info":"","$required":false,"_fc_id":"id_Fow9mam3zf55atc","name":"ref_F5y0mam3zf55auc","display":true,"hidden":false,"_fc_drag_tag":"inputNumber"}]'
  )
);
const onSubmit = (formData) => {
  //提交表单
};
</script>

设计器配置

| 属性名 | 描述 | 类型 | | ------ | --------------------------------------------------------------------------------------------------------------------- | --------------- | | height | 设计器组件的高度。可以使用字符串（如 500px, 100vh）或数字（如 500）。指定设计器的显示高度。默认为 100vh | string / number | | config | 配置设计器内的模块显示状态和默认规则。通过此配置，可以控制哪些模块可见，查看完整配置说明。 | Config | | handle | 设计器顶部的扩展操作按钮。Handle 是一个包含按钮名称和回调函数的数组。通过此配置，可以添加自定义操作按钮并指定其行为。 | Handle |

Config

export interface Config {
  //扩展图标选择
  icons?: string[];
  //配置设计区域显示方式
  device?: Device;
  //是否可以切换组件类型,或者可以相互切换的字段
  switchType?: false | Array<string[]>;
  //是否自动选中拖入的组件
  autoActive?: boolean;
  //多语言种类
  localeOptions?: Array<{
    value: string,
    label: string,
  }>;
  //删除组件前置事件, 返回 false 终止删除
  beforeRemoveRule?: (data: { rule: Rule }) => false | void;
  //选中组件前置事件, 返回 false 终止选中
  beforeActiveRule?: (data: { rule: Rule }) => false | void;
  //排序组件配置项的顺序
  configFormOrder?: Array<
    "base" | "advanced" | "props" | "slots" | "style" | "event" | "validate"
  >;
  //判断组件是否可以拖入
  checkDrag?: (drag: {
    rule: Rule | undefined,
    menu: DragRule,
    toRule: Rule,
    toMenu: DragRule,
  }) => boolean;
  //是否开启快捷键,默认开启
  hotKey?: boolean;
  //是否在复制时自动重置组件的name,默认开启
  autoResetName?: boolean;
  //右侧配置更新方式
  updateConfigOnBlur?: boolean;
  //是否生成vue2语法的模板组件
  useTemplate?: boolean;
  //定义表单配置默认值
  formOptions?: Object;
  //配置field是否可以编辑
  fieldReadonly?: boolean;
  //field选择项,支持多级
  fieldList?: FieldItem[];
  //子表单组件是否可以选择`fieldList`中的最后一级
  fieldLeafSelectable?: boolean;
  //控制子表单组件字段是否和子表单字段联动, 默认开启
  relationField?: boolean;
  //自定义变量列表
  varList?: VarItem[];
  //隐藏拖拽操作按钮
  hiddenDragMenu?: boolean;
  //隐藏拖拽按钮
  hiddenDragBtn?: boolean;
  //隐藏部分菜单
  hiddenMenu?: MenuName[];
  //隐藏部分组件
  hiddenItem?: string[];
  //隐藏组件的部分配置项
  hiddenItemConfig?: {
    default?: string[],
    //拖拽规则name: 隐藏的字段名
    [id: string]: string[],
  };
  //禁用组件的部分配置项
  disabledItemConfig?: {
    default?: string[],
    //拖拽规则name: 禁用的字段名
    [id: string]: string[],
  };
  //可拖入的组件列表
  allowDrag?: {
    //拖拽规则name: 可拖入的规则
    [id: string]: AllowDrag,
  };
  //不可拖入的组件列表
  denyDrag?: {
    //拖拽规则name: 不可拖入的规则
    [id: string]: DenyDrag,
  };
  //是否显示左侧
  showMenuBar?: boolean;
  //是否显示快速排序按钮
  showQuickLayout?: boolean;
  //是否显示保存按钮
  showSaveBtn?: boolean;
  //是否显示辅助线按钮
  showGridLine?: boolean;
  //是否显示预览按钮
  showPreviewBtn?: boolean;
  //是否显示打印按钮
  showPrintBtn?: boolean;
  //是否显示右侧的配置界面
  showConfig?: boolean;
  //是否显示组件的基础配置表单
  showBaseForm?: boolean;
  //是否显示组件的编号
  showComponentName?: boolean;
  //是否显示组件联动
  showControl?: boolean;
  //是否显示绑定变量
  showVariable?: boolean;
  //是否显示json预览按钮
  showJsonPreview?: boolean;
  //是否显示自定义props按钮
  showCustomProps?: boolean;
  //是否显示模块管理
  showPageManage?: boolean;
  //是否显示组件的高级配置表单
  showAdvancedForm?: boolean;
  //是否显示组件的属性配置表单
  showPropsForm?: boolean;
  //是否显示组件的样式配置表单
  showStyleForm?: boolean;
  //是否显示组件的事件配置表单
  showEventForm?: boolean;
  //是否显示组件的验证配置表单
  showValidateForm?: boolean;
  //是否显示表单配置
  showFormConfig?: boolean;
  //是否显示左侧的模板列表
  showTemplate?: boolean;
  //是否显示多端适配选项
  showDevice?: boolean;
  //是否显示录入按钮
  showInputData?: boolean;
  //是否显示国际化配置
  showLanguage?: boolean;
  //定义渲染规则所需的formData
  appendConfigData?: string[] | ((rule: Rule) => Object);
  //基础配置的渲染规则,可以覆盖默认规则.append为true时追加到默认规则后面
  baseRule?: extendRule;
  //验证配置的渲染规则,可以覆盖默认规则.append为true时追加到默认规则后面
  validateRule?: extendRule;
  //表单的渲染规则,可以覆盖默认规则.append为true时追加到默认规则后面
  formRule?: extendRule;
  //组件配置的渲染规则,可以覆盖默认规则.append为true时追加到默认规则后面
  componentRule?: {
    default: (
      rule: Rule,
      arg: { t: t }
    ) =>
      | Rule[]
      | {
          rule: (rule: Rule, arg: { t: t }) => Rule[],
          append?: boolean,
          prepend?: boolean,
        },
    //组件拖拽组件规则的id,rule为当前组件的生成规则
    [id: string]: (
      rule: Rule,
      arg: { t: t }
    ) =>
      | Rule[]
      | {
          rule: (rule: Rule, arg: { t: t }) => Rule[],
          append?: boolean,
          prepend?: boolean,
        },
  };
  updateDefaultRule?: {
    //组件拖拽组件规则的id, 设置组件的初始化规则
    [id: string]:
      | Partial<Omit<Rule, "field" | "children" | "component">>
      | ((Rule) => void),
  };
}

配置扩展

您可以通过 props.handle 配置扩展操作按钮。每个按钮都有一个 label 和一个 handle 函数，用于定义按钮的行为。

<template>
    <troy-form-designer ref="designer" :handle="handle"></troy-form-designer>
</template>
<script>
    export default {
        name: 'app',
        data() {
            return {
                handle: [
                    {
                        // 自定义操作按钮：中英切换
                        label: '中英切换',
                        handle: () => {
                            // 处理中英文切换逻辑
                            console.log('中英切换按钮被点击');
                            // 例如，切换界面语言
                        },
                    },
                    {
                        // 自定义操作按钮：选择表单
                        label: '选择表单',
                        handle: () => {
                            // 处理选择表单逻辑
                            console.log('选择表单按钮被点击');
                            // 例如，打开表单选择对话框
                        },
                    },
                ],
            };
        }
    };
</script>

表单实例方法

| 方法名 | 描述 | 类型定义 | | ---------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------- | | addComponent | 将一个或多个组件模板或拖拽组件添加到设计器，并根据 menu 字段自动归类到对应菜单下。 | AddComponent | | setMenuItem | 将拖拽组件覆盖添加到指定的菜单下，menuName 为目标菜单名称。 | (menuName: string, list: MenuList) => void | | addMenu | 向设计器左侧菜单栏添加一个新的菜单项。 | (menu: Menu) => void | | setRule | 设置表单生成的规则，支持字符串或规则对象数组。 | (rule: string Rule[]) => void | | setOption | 设置表单的配置选项（如布局、标签宽度）。 别名方法：setOptions。 | (opt: Options) => void | | mergeOptions | 通过合并方式更新表单配置选项。 | (opt: Options) => void | | getRule | 获取当前表单的渲染规则（数组形式）。 | () => Rule[] | | getJson | 获取当前表单的配置对象。 | () => string | | getOption | 获取当前表单的配置对象。 | () => Options | | getOptionsJson | 获取当前表单的 JSON 配置（字符串形式）。 | () => string | | getFormData | 获取当前表单的 formData 对象 | () => Object | | setFormData | 设置表单的 formData 对象（用于预填充数据）。 | (formData: Object) => void | | getDescription | 获取表单的层级结构数据。 | () => TreeData | | getFormDescription | 获取表单组件的层级结构数据。 | () => TreeData | | openPreview | 打开表单预览模式。 | () => void | | openInputData | 开启或关闭数据录入模式（true 开启，false 关闭）。 | (open: boolean) => void | | clearDragRule | 清空设计器中的所有表单组件。 | () => void | | fields | 获取设计器中所有字段的名称列表。 | () => string[] | | triggerActive | 选中指定组件（支持规则对象或 field/name/_fc_id）。 | (rule: Rule / string) => void | | clearActiveRule | 清除当前选中的组件状态。 | (rule: () => Rule[], append: boolean) => void | | setFormRuleConfig | 设置表单配置规则（同 config.formRule）。 | (rule: () => Rule[], append: boolean) => void | | setBaseRuleConfig | 设置组件基础配置规则（同 config.baseRule）。 | (rule: () => Rule[], append: boolean) => void | | setComponentRuleConfig | 设置指定组件的属性配置规则（同 config.componentRule）。 | (rule: () => Rule[], append: boolean) => void | | setGlobalData | 预设全局数据源（用于设计器）。 | (data: GlobalData) => void | | setGlobalEvent | 预设全局样式（用于设计器）。 | (class: GlobalClass) => void | | openGlobalEventDialog | 开启全局事件弹窗。 | () => void | | openGlobalFetchDialog | 开启全局数据源弹窗。 | () => void | | openGlobalClassDialog | 开启全局样式弹窗。 | () => void |