@hzab/form-render

formily schema 表单渲染组件

安装

pnpm add @hzab/form-render

本包同时发布到公共 npm（registry.npmjs.org，public access）与企业私有源（ld / old）。 默认源可直接安装，无需额外配置；若团队要求走内网源，见消费方接入指南。

消费方需自备 peerDependencies：@hzab/utils、antd、axios、react、react-dom（本包不会随包安装）。

引入方式见下方「组件」章节。

发布形态：本包在本仓以源码直出方式发布——main 指向 src，由消费方打包器编译 TypeScript 与 .less 样式；@hzab/form-render/src/* 深路径同样可直接引用。随包发布的 dist/ 仅用于 类型解析（types → dist/index.d.ts），不是运行时入口。

组件

Tips

• antd 组件样式需要手动引入

自研组件

| x-component | 说明 | 文档 | | ------------------------------ | ----------------------------------- | ----------------------------------------------- | | Upload | 文件上传（OSS / 私有化等） | README | | LocationPicker | 地图选点 | README | | LocationListPicker | 多地址 / 点位列表选择 | README | | RichEditor / Editor | 富文本编辑器 | README | | TreeCheckbox | 树形多选复选框 | README | | UserSelect | 人员下拉（本地 options） | README | | PersonnelSelect / RemoteSelect | 远程人员搜索下拉 | README | | DatePicker | 日期选择（含 RangePicker 拆分字段） | README | | RadioGroupWithTip | 带描述的单选 | README | | CheckboxWithTip | 带描述的多选 | README | | ArrayTable | 自增表格 | README | | ArrayCards | 自增卡片 | README | | Text | 只读文本展示 | README |

内置 antd / c-formily-antd 组件（Input、Select、FormGrid 等）通过 FormRender 注册，Schema 约定见下方 Schema 章节。

示例

项目初始化时挂载全局组件

import { setFormilyGlobalComponents } from "@hzab/utils/src/formily/global-components";

// 挂载 Test1 组件到 formRender 组件
setFormilyGlobalComponents({
  Test1() {
    return <div>Test1</div>;
  },
});

// 挂载 Test2 组件到 formRender 组件
setFormilyGlobalComponents({
  Test2() {
    return <div>Test2</div>;
  },
  Test3() {
    return <div>Test3</div>;
  },
});

import FormRender from "@hzab/form-render";

// testSchema 为 formily 生成的 schema json
<FormRender schema={testSchema} />;

组件远程数据

• 使用 schemaScope 传入全局配置变量，在响应器的动作响应中调用

// schema
{
  "form": {
    "labelCol": 6,
    "wrapperCol": 12
  },
  "schema": {
    "type": "object",
    "properties": {
      "parentId": {
        "type": "string",
        "title": "上级菜单",
        "x-decorator": "FormItem",
        "x-component": "TreeSelect",
        "x-validator": [],
        "x-component-props": {},
        "x-decorator-props": {},
        "x-reactions": {
          "fulfill": {
            "run": "fetchMenuTree($self);"
          }
        },
        "name": "parentId",
        "x-designable-id": "i012z5nbd5z",
        "x-index": 0
      }
    }
  }
}

// formRender
  <FormRender
    schema={testSchema}
    schemaScope={{
      fetchMenuTree(field) {
        // 模拟请求
        setTimeout(() => {
          // field 目标组件的 配置参数
          // 通过 field.component[1] 可以动态配置目标组件的 props
          // 树选择器 数据源
          field.component[1].treeData = [{ value: 1, label: 1 }];
        }, 1000)
      },
    }}
  />

自定义组件

• 使用 components 传入自定义组件，在 schema 中 x-component 配置对应的组件名称

// schema
{
  "form": {
    "labelCol": 6,
    "wrapperCol": 12
  },
  "schema": {
    "type": "object",
    "properties": {
      "parentId": {
        "type": "string",
        "title": "图标选择器",
        "x-decorator": "FormItem",
        "x-component": "IconSelect",
        "x-validator": [],
        "x-component-props": {},
        "x-decorator-props": {},
        "x-reactions": {},
        "name": "parentId",
        "x-designable-id": "i012z5nbd5z",
        "x-index": 0
      }
    }
  }
}

// formRender
  <FormRender
    schema={testSchema}
    components={{
      // 自定义组件
      IconSelect() {
        return "IconSelect";
      },
    }}
  />

API

FormRender Attributes

| 参数 | 类型 | 必填 | 默认值 | 说明 | | ------------------ | -------- | ---- | ---------- | ------------------------------------------------------------------------------------------ | | schema | Object | 是 | - | 数据信息的 schema | | schemaScope | Object | 否 | - | 全局作用域，用于实现协议表达式变量注入 | | layout | Object | 否 | horizontal | 表单布局，horizontal vertical \ inline | | initialValues | Object | 否 | - | form 初始值 | | components | Object | 否 | - | 自定义组件 | | formOptions | Object | 否 | - | createForm 的参数 | | emptyValue | string | 否 | N/A | 只读模式 PreviewText emptyValue 配置 | | disabled | boolean | 否 | - | 禁用状态 | | readOnly | boolean | 否 | - | 只读状态 | | onFormValuesChange | Function | 否 | - | 表单事件 (form)=>{} https://core.formilyjs.org/zh-CN/api/entry/form-effect-hooks | | onFieldValueChange | Function | 否 | - | 表单项事件 (field, form)=>{} https://core.formilyjs.org/zh-CN/api/entry/field-effect-hooks |

方法 Methods

| 名称 | 参数 | 说明 | | ---- | --------- | -------------- | | init | form 实例 | 组件初始化执行 |

全局配置（缩略图 / 预览域名）

项目初始化时可配置上传预览相关全局参数（见 src/globalConfig.ts）：

import {
  setFormRenderPCGlobalServeConfig,
  setFormRenderPCGlobalServeConfigs,
  getFormRenderPCGlobalServeConfig,
} from "@hzab/form-render/src/globalConfig";

// 设置单个配置
setFormRenderPCGlobalServeConfig("serverUrl", "/api/v1/user/oss/getWebOssConfig");

// 批量设置
setFormRenderPCGlobalServeConfigs({
  serverUrl: "/api/v1/user/oss/getWebOssConfig",
  // 其他如缩略图相关配置
});

getFormRenderPCGlobalServeConfig();

Schema

• 使用 表单编辑器生成：https://designable-antd.formilyjs.org/

{
  "form": {
    "labelCol": 6,
    "wrapperCol": 12
  },
  "schema": {
    "type": "object",
    "properties": {
      // 参数 key
      "parentId": {
        "type": "string",
        // 参数 label
        "title": "上级菜单",
        "x-decorator": "FormItem",
        // 渲染的组件
        "x-component": "TreeSelect",
        // 组件校验
        "x-validator": [],
        // 组件配置
        "x-component-props": {
          "virtual": true,
          "allowClear": true,
          "showSearch": true
        },
        // 容器配置
        "x-decorator-props": {},
        // 响应器
        "x-reactions": {
          // 依赖字段
          "dependencies": [
            {
              "property": "value",
              "type": "any"
            }
          ],
          // 响应动作
          "fulfill": {
            // 属性响应，只支持 JS 表达式
            "state": {
              "visible": "{{$deps.menuType === \"C\" || $deps.menuType === \"F\"}}"
            },
            // 动作响应，支持 JS 语句
            "run": "fetchMenuTree($self);"
          }
        },
        // 参数 key
        "name": "parentId",
        // 组件在编辑器中的 ID（必须唯一）
        "x-designable-id": "i012z5nbd5z",
        // 组件在表单中的顺序（必须唯一）
        "x-index": 0,
        // 是否在 table 中展示，目前需要手动添加配置
        "inTable": false
      }
    }
  }
}