@hzab/form-render 1.7.17 → 1.7.18

package/CHANGELOG.md

@@ -1,6 +1,14 @@
+# @hzab/form-render@1.7.18
+
+feat: 添加 afterUpload 函数
+
+# @hzab/form-render@1.7.17
+
+feat: previewConfig 预览相关配置
+
 # @hzab/form-render@1.7.16
 
-fix: 增加带描述和支持单个option禁用的radio和checkbox组件
+fix: 增加带描述和支持单个 option 禁用的 radio 和 checkbox 组件
 
 # @hzab/form-render@1.7.15
 

package/README.md

@@ -8,8 +8,40 @@ formily schema 表单渲染组件
 
 - antd 组件样式需要手动引入
 
+## 自研组件
+
+| x-component | 说明 | 文档 |
+| ----------- | ---- | ---- |
+| Upload | 文件上传（OSS / 私有化等） | [README](docs/components/Upload.md) |
+| LocationPicker | 地图选点 | [README](docs/components/LocationPicker.md) |
+| LocationListPicker | 多地址 / 点位列表选择 | [README](docs/components/LocationListPicker.md) |
+| RichEditor / Editor | 富文本编辑器 | [README](docs/components/RichEditor.md) |
+| TreeCheckbox | 树形多选复选框 | [README](docs/components/TreeCheckbox.md) |
+| UserSelect | 人员下拉（本地 options） | [README](docs/components/UserSelect.md) |
+| PersonnelSelect / RemoteSelect | 远程人员搜索下拉 | [README](docs/components/PersonnelSelect.md) |
+| DatePicker | 日期选择（含 RangePicker 拆分字段） | [README](docs/components/DatePicker.md) |
+| RadioGroupWithTip | 带描述的单选 | [README](docs/components/RadioGroupWithTip.md) |
+| CheckboxWithTip | 带描述的多选 | [README](docs/components/CheckboxWithTip.md) |
+| ArrayTable | 自增表格 | [README](docs/components/ArrayTable.md) |
+| ArrayCards | 自增卡片 | [README](docs/components/ArrayCards.md) |
+| Text | 只读文本展示 | [README](docs/components/Text.md) |
+
+内置 antd / c-formily-antd 组件（Input、Select、FormGrid 等）通过 `FormRender` 注册，Schema 约定见下方 Schema 章节。
+
 ## 示例
 
+本地文档站（antd 风格）：左侧组件列表，组件页上方为 Demo、下方为 API。
+
+```bash
+npm run dev
+```
+
+打开 http://localhost:3000 （HashRouter，路径形如 `/#/components/upload`）：
+
+- `/#/` 组件总览
+- `/#/components/*` 各组件 Demo + API
+- `/#/lab/*` 综合 / 场景示例
+
 #### 项目初始化时挂载全局组件
 
 ```jsx
@@ -137,7 +169,7 @@ import FormRender from "@hzab/form-render";
 
 ## API
 
-### InfoPanel Attributes
+### FormRender Attributes
 
 | 参数               | 类型     | 必填 | 默认值     | 说明                                                                                       |
 | ------------------ | -------- | ---- | ---------- | ------------------------------------------------------------------------------------------ |
@@ -159,6 +191,29 @@ import FormRender from "@hzab/form-render";
 | ---- | --------- | -------------- |
 | init | form 实例 | 组件初始化执行 |
 
+### 全局配置（缩略图 / 预览域名）
+
+项目初始化时可配置上传预览相关全局参数（见 `src/globalConfig.ts`）：
+
+```js
+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/
@@ -231,14 +286,18 @@ import FormRender from "@hzab/form-render";
 
 ## 文件目录
 
-- example 本地测试代码
+- example 本地 demo / 手工测试页面
 - src 组件源码
+- docs 组件文档
+- tests 单元测试
 
 ## 命令
 
-- 生成文档：npm run docs
 - 本地运行：npm run dev
 - 打包编译：npm run build
+- 单元测试：npm test
+- 测试监听：npm run test:watch
+- 测试覆盖率：npm run test:coverage
 
 ## 发布
 

package/docs/README.md

@@ -0,0 +1,21 @@
+# 组件文档
+
+自研表单组件说明，与源码目录分离，位于仓库根目录 `docs/`。
+
+| 组件 | 文档 |
+| ---- | ---- |
+| Upload | [Upload.md](./components/Upload.md) |
+| LocationPicker | [LocationPicker.md](./components/LocationPicker.md) |
+| LocationListPicker | [LocationListPicker.md](./components/LocationListPicker.md) |
+| RichEditor | [RichEditor.md](./components/RichEditor.md) |
+| TreeCheckbox | [TreeCheckbox.md](./components/TreeCheckbox.md) |
+| UserSelect | [UserSelect.md](./components/UserSelect.md) |
+| PersonnelSelect | [PersonnelSelect.md](./components/PersonnelSelect.md) |
+| DatePicker | [DatePicker.md](./components/DatePicker.md) |
+| RadioGroupWithTip | [RadioGroupWithTip.md](./components/RadioGroupWithTip.md) |
+| CheckboxWithTip | [CheckboxWithTip.md](./components/CheckboxWithTip.md) |
+| ArrayTable | [ArrayTable.md](./components/ArrayTable.md) |
+| ArrayCards | [ArrayCards.md](./components/ArrayCards.md) |
+| Text | [Text.md](./components/Text.md) |
+
+FormRender 总览见根目录 [README.md](../README.md)。

package/docs/components/ArrayCards.md

@@ -0,0 +1,68 @@
+# ArrayCards
+
+自增卡片列表，基于 Formily ArrayCards，通过 ArrayBase mixin 提供增删改排序子组件。
+
+ArrayBase 回调（`onAdd` / `onRemove` / `onSortStart` 等）与导出 hooks 说明见 [ArrayTable README](./ArrayTable.md)。
+
+## Schema 示例
+
+```json
+{
+  "type": "array",
+  "x-component": "ArrayCards",
+  "x-component-props": {
+    "title": "卡片"
+  },
+  "items": {
+    "type": "object",
+    "properties": {
+      "index": { "type": "void", "x-component": "ArrayCards.Index" },
+      "name": {
+        "type": "string",
+        "title": "名称",
+        "x-decorator": "FormItem",
+        "x-component": "Input"
+      },
+      "remove": { "type": "void", "x-component": "ArrayCards.Remove" },
+      "moveDown": { "type": "void", "x-component": "ArrayCards.MoveDown" },
+      "moveUp": { "type": "void", "x-component": "ArrayCards.MoveUp" }
+    }
+  },
+  "properties": {
+    "addition": {
+      "type": "void",
+      "title": "添加条目",
+      "x-component": "ArrayCards.Addition"
+    }
+  }
+}
+```
+
+### ArrayCards Attributes
+
+| 参数                  | 类型     | 必填 | 默认值 | 说明 |
+| --------------------- | -------- | ---- | ------ | ---- |
+| title                 | ReactNode | 否  | -      | 卡片标题（可与 Index 组合） |
+| onAdd                 | Function | 否   | -      | 新增回调 |
+| onCopy                | Function | 否   | -      | 复制回调 |
+| onRemove              | Function | 否   | -      | 删除回调 |
+| onMoveDown            | Function | 否   | -      | 下移回调 |
+| onMoveUp              | Function | 否   | -      | 上移回调 |
+| deletePopconfirm      | boolean  | 否   | -      | 删除是否二次确认 |
+| deletePopconfirmTitle | Function\|ReactNode | 否 | - | 删除确认文案 |
+| disabled              | boolean  | 否   | -      | 禁用 |
+
+其余 props 透传 antd Card。
+
+### 子组件（x-component）
+
+| 名称                 | 说明 |
+| -------------------- | ---- |
+| ArrayCards.Index     | 序号 |
+| ArrayCards.Remove    | 删除 |
+| ArrayCards.Copy      | 复制 |
+| ArrayCards.MoveDown  | 下移 |
+| ArrayCards.MoveUp    | 上移 |
+| ArrayCards.Addition  | 新增卡片 |
+
+完整交互示例见 `example/pages/array-base-demo`。

package/docs/components/ArrayTable.md

@@ -0,0 +1,111 @@
+# ArrayTable
+
+自增表格，基于 Formily ArrayTable 扩展，支持分页、拖拽排序回调，并通过 ArrayBase mixin 暴露增删改操作子组件。
+
+## Schema 示例
+
+```json
+{
+  "type": "array",
+  "x-component": "ArrayTable",
+  "x-component-props": {
+    "onSortStart": "{{onSortStart}}",
+    "onSortEnd": "{{onSortEnd}}",
+    "deletePopconfirm": true
+  },
+  "items": {
+    "type": "object",
+    "properties": {
+      "column1": {
+        "type": "void",
+        "x-component": "ArrayTable.Column",
+        "x-component-props": { "title": "排序", "width": 50 },
+        "properties": {
+          "sort": { "type": "void", "x-component": "ArrayTable.SortHandle" }
+        }
+      },
+      "column2": {
+        "type": "void",
+        "x-component": "ArrayTable.Column",
+        "x-component-props": { "title": "序号", "width": 50 },
+        "properties": {
+          "index": { "type": "void", "x-component": "ArrayTable.Index" }
+        }
+      },
+      "name": {
+        "type": "void",
+        "x-component": "ArrayTable.Column",
+        "x-component-props": { "title": "名称" },
+        "properties": {
+          "name": {
+            "type": "string",
+            "x-decorator": "FormItem",
+            "x-component": "Input"
+          }
+        }
+      },
+      "operations": {
+        "type": "void",
+        "x-component": "ArrayTable.Column",
+        "x-component-props": { "title": "操作" },
+        "properties": {
+          "remove": { "type": "void", "x-component": "ArrayTable.Remove" },
+          "moveDown": { "type": "void", "x-component": "ArrayTable.MoveDown" },
+          "moveUp": { "type": "void", "x-component": "ArrayTable.MoveUp" }
+        }
+      }
+    }
+  },
+  "properties": {
+    "addition": {
+      "type": "void",
+      "title": "添加条目",
+      "x-component": "ArrayTable.Addition"
+    }
+  }
+}
+```
+
+### ArrayTable Attributes
+
+| 参数                  | 类型     | 必填 | 默认值 | 说明 |
+| --------------------- | -------- | ---- | ------ | ---- |
+| onAdd                 | Function | 否   | -      | 新增回调 `(index) => void` |
+| onCopy                | Function | 否   | -      | 复制回调 |
+| onRemove              | Function | 否   | -      | 删除回调 |
+| onMoveDown            | Function | 否   | -      | 下移回调 |
+| onMoveUp              | Function | 否   | -      | 上移回调 |
+| onSortStart           | Function | 否   | -      | 拖拽排序开始 |
+| onSortEnd             | Function | 否   | -      | 拖拽排序结束 |
+| deletePopconfirm      | boolean  | 否   | -      | 删除是否二次确认 |
+| deletePopconfirmTitle | Function\|ReactNode | 否 | - | 删除确认文案 |
+| disabled              | boolean  | 否   | -      | 禁用 |
+
+其余 props 透传 antd Table。
+
+### 子组件（x-component）
+
+| 名称                    | 说明 |
+| ----------------------- | ---- |
+| ArrayTable.Column       | 列容器 |
+| ArrayTable.SortHandle   | 拖拽排序手柄 |
+| ArrayTable.Index        | 行序号 |
+| ArrayTable.Remove       | 删除 |
+| ArrayTable.MoveDown     | 下移 |
+| ArrayTable.MoveUp       | 上移 |
+| ArrayTable.Addition     | 新增行 |
+
+### 从 ArrayTable 导出的 API（ArrayBase）
+
+可通过 `ArrayTable`（或直接从包内 ArrayBase 相关导出）使用：
+
+| 名称                | 说明 |
+| ------------------- | ---- |
+| useArray            | 获取当前 Array 上下文 |
+| useIndex            | 获取当前行 index |
+| useRecord           | 获取当前行 record |
+| isAdditionComponent | 判断 schema 是否为 Addition 组件 |
+| isColumnComponent   | 判断是否为 Column |
+| isOperationsComponent | 判断是否为 Operations |
+
+完整交互示例见 `example/pages/array-base-demo`。

package/docs/components/CheckboxWithTip.md

@@ -0,0 +1,43 @@
+# CheckboxWithTip
+
+带描述文案、支持单项禁用的多选组。数据优先取 `dataSource`，否则取 Formily `field.dataSource`（schema `enum`）。
+
+## Schema 示例
+
+```json
+{
+  "x-component": "CheckboxWithTip",
+  "enum": [
+    {
+      "label": "人力填报",
+      "value": 1,
+      "desc": "由人力在后台填报信息。"
+    },
+    {
+      "label": "个人填报",
+      "value": 2,
+      "desc": "由个人在移动端填报信息。",
+      "disabled": true
+    }
+  ]
+}
+```
+
+### CheckboxWithTip Attributes
+
+| 参数       | 类型     | 必填 | 默认值 | 说明 |
+| ---------- | -------- | ---- | ------ | ---- |
+| value      | Array    | 否   | -      | 当前选中值数组 |
+| onChange   | Function | 否   | -      | 选中变化回调 |
+| dataSource | Array    | 否   | field.dataSource | 选项列表，见下表 |
+
+其余 props 透传 antd `Checkbox.Group`。
+
+### dataSource / enum 子项
+
+| 参数     | 类型           | 必填 | 默认值 | 说明 |
+| -------- | -------------- | ---- | ------ | ---- |
+| label    | string         | 是   | -      | 主标题 |
+| value    | string\|number | 是   | -      | 选项值 |
+| desc     | string         | 否   | -      | 描述文案 |
+| disabled | boolean        | 否   | false  | 单项禁用 |

package/docs/components/DatePicker.md

@@ -0,0 +1,54 @@
+# DatePicker
+
+基于 `c-formily-antd` DatePicker 的封装，统一日期格式化；`RangePicker` 支持将起止时间拆分写入同级字段。
+
+## Schema 示例
+
+```json
+{
+  "x-component": "DatePicker",
+  "x-component-props": {
+    "showTime": true
+  }
+}
+```
+
+```json
+{
+  "x-component": "DatePicker.RangePicker",
+  "x-component-props": {
+    "isSplitTimes": true,
+    "startKey": "startTime",
+    "endKey": "endTime"
+  }
+}
+```
+
+### DatePicker Attributes
+
+| 参数     | 类型    | 必填 | 默认值 | 说明 |
+| -------- | ------- | ---- | ------ | ---- |
+| format   | string  | 否   | 按 picker / showTime 推导 | 日期展示与解析格式 |
+| picker   | string  | 否   | date   | `date` / `week` / `month` / `quarter` / `year` |
+| showTime | boolean | 否   | false  | 是否显示时间；为 true 时默认 format 为 `YYYY-MM-DD HH:mm:ss` |
+
+未传 `format` 时的默认值：
+
+| picker / showTime | 默认 format |
+| ----------------- | ----------- |
+| month             | `YYYY-MM` |
+| quarter           | `YYYY-\QQ` |
+| year              | `YYYY` |
+| week              | `gggg-wo` |
+| showTime=true     | `YYYY-MM-DD HH:mm:ss` |
+| 其他              | `YYYY-MM-DD` |
+
+### DatePicker.RangePicker Attributes
+
+| 参数         | 类型    | 必填 | 默认值      | 说明 |
+| ------------ | ------- | ---- | ----------- | ---- |
+| isSplitTimes | boolean | 否   | false       | 为 true 时，将起止时间写入同级 `startKey` / `endKey` 字段 |
+| startKey     | string  | 否   | startTime   | 拆分后的开始时间字段名 |
+| endKey       | string  | 否   | endTime     | 拆分后的结束时间字段名 |
+
+嵌套在 `ArrayTable` / `ArrayCards` 内时，拆分结果写入当前行（父级）对象。

package/docs/components/LocationListPicker.md

@@ -0,0 +1,41 @@
+# LocationListPicker
+
+多地址 / 点位列表选择器，基于高德地图，支持点位与多边形绘制。
+
+## 使用前安装依赖
+
+```bash
+npm install @amap/amap-jsapi-loader
+```
+
+## Schema 示例
+
+```json
+{
+  "x-component": "LocationListPicker",
+  "x-component-props": {
+    "hasPoint": true,
+    "hasPolygon": false,
+    "isAutoSearch": true
+  }
+}
+```
+
+### LocationListPicker Attributes
+
+| 参数           | 类型     | 必填 | 默认值 | 说明 |
+| -------------- | -------- | ---- | ------ | ---- |
+| value          | Array    | 否   | -      | 地址列表数据 |
+| readOnly       | boolean  | 否   | false  | 只读 |
+| disabled       | boolean  | 否   | false  | 禁用 |
+| hasPoint       | boolean  | 否   | true   | 是否支持新增点位 |
+| hasPolygon     | boolean  | 否   | false  | 是否支持新增多边形 |
+| isAutoSearch   | boolean  | 否   | -      | 搜索框是否自动搜索 |
+| listProps      | Object   | 否   | -      | 左侧地址列表区域配置 |
+| popupProps     | Object   | 否   | -      | 弹层 / 编辑弹窗配置 |
+| ItemRender     | Function | 否   | -      | 自定义列表项渲染 |
+| markerIconConf | Object   | 否   | -      | marker 图标配置 |
+| loading        | boolean  | 否   | false  | 加载态 |
+| onChange       | Function | 否   | -      | 列表变化回调 |
+
+表单值一般为地址对象数组（组件会为缺失项自动补 `id`）。

package/docs/components/LocationPicker.md

@@ -0,0 +1,67 @@
+# LocationPicker
+
+地图选点组件，基于高德地图。支持弹窗 / 内嵌展示，以及点、线、面绘制。
+
+## 使用前安装依赖
+
+```bash
+npm install @amap/amap-jsapi-loader
+```
+
+## 注意事项
+
+- `isObjectRes` 在 `@hzab/form-render@0.5.0` 版本中去除，结果全部存放在对象中
+- `changeMode` 在 `@hzab/form-render@0.5.1` 版本中去除，仅允许点击地图选点
+
+## Schema 示例
+
+```json
+{
+  "x-component": "LocationPicker",
+  "x-component-props": {
+    "mode": "dialog",
+    "hasSearch": true,
+    "lonKey": "longitude",
+    "latKey": "latitude",
+    "addrKey": "address"
+  }
+}
+```
+
+独立使用：
+
+```jsx
+import { LocationPicker } from "@hzab/form-render/src/components";
+
+export default function Demo() {
+  return <LocationPicker mode="dialog" hasSearch />;
+}
+```
+
+### LocationPicker Attributes
+
+| 参数               | 类型    | 必填 | 默认值    | 说明 |
+| ------------------ | ------- | ---- | --------- | ---- |
+| mode               | string  | 否   | dialog    | 地图显示类型：`dialog` 弹窗、`show` 直接显示 |
+| element            | string  | 否   | Polypoint | 地图绘制元素：`Polypoint` / `Polyline` / `Polygon` |
+| layout             | string  | 否   | ver       | 选择器与地图布局：`hor` 水平、`ver` 垂直 |
+| hasSearch          | boolean | 否   | true      | 是否允许搜索 |
+| isAutoFixAddr      | boolean | 否   | false     | 打开地图时是否根据经纬度自动修正已填地址 |
+| lonKey             | string  | 否   | longitude | 经度字段 key |
+| latKey             | string  | 否   | latitude  | 纬度字段 key |
+| addrKey            | string  | 否   | address   | 地址字段 key |
+| pointsKey          | string  | 否   | points    | 点位集合字段 key |
+| isAutoSearch       | boolean | 否   | true      | 搜索框是否自动搜索 |
+| modalConf          | Object  | 否   | -         | 弹窗额外配置 |
+| markerIconConf     | Object  | 否   | -         | marker icon 配置对象 |
+| icons              | Object  | 否   | -         | icon 图片配置，见下表 |
+| getCurPositionConf | Object  | 否   | -         | `getCurrentPosition` 配置 |
+
+#### icons
+
+| 参数         | 类型   | 必填 | 默认值 | 说明 |
+| ------------ | ------ | ---- | ------ | ---- |
+| markerIcon   | string | 否   | -      | marker icon 图片地址 |
+| pickerIcon   | string | 否   | -      | 选点 icon 图片地址或元素 |
+| positionIcon | string | 否   | -      | 定位 icon 图片地址或元素 |
+| resetIcon    | string | 否   | -      | 重置 icon 图片地址或元素 |

package/docs/components/PersonnelSelect.md

@@ -0,0 +1,77 @@
+# PersonnelSelect / RemoteSelect
+
+远程人员搜索下拉框。`PersonnelSelect` 为 Formily `connect` 包装；底层实现为 `RemoteSelect`，支持远程分页加载、搜索与自定义列表项。
+
+## Schema 示例
+
+```jsx
+<FormRender
+  schema={schema}
+  schemaScope={{
+    loadPersonnel(search, pagination) {
+      return Promise.resolve({
+        list: [{ userId: "1", userName: "张三", phoneNumber: "13800000000" }],
+        pagination: { ...pagination, total: 1 },
+      });
+    },
+  }}
+/>
+```
+
+```json
+{
+  "x-component": "PersonnelSelect",
+  "x-component-props": {
+    "mode": "multiple",
+    "labelInValue": true,
+    "loadData": "{{loadPersonnel}}"
+  }
+}
+```
+
+也可直接使用 `RemoteSelect`：
+
+```json
+{
+  "x-component": "RemoteSelect",
+  "x-component-props": {
+    "mode": "tags",
+    "loadData": "{{loadPersonnel}}"
+  }
+}
+```
+
+### Attributes
+
+| 参数              | 类型     | 必填 | 默认值 | 说明 |
+| ----------------- | -------- | ---- | ------ | ---- |
+| loadData          | Function | 是   | -      | `(search, pagination) => Promise<{ list, pagination }>` |
+| searchData        | Function | 否   | -      | 额外查询函数 |
+| mode              | string   | 是   | -      | `multiple` 或多选 tags 模式（`tags`） |
+| labelKey          | string   | 否   | userName | 列表项 label 字段 |
+| valueKey          | string   | 否   | userId   | 列表项 value 字段 |
+| disabledKey       | string   | 否   | disabled | 禁用字段 |
+| labelInValue      | boolean  | 否   | false  | 是否以 `{ label, value }` 形式回传 |
+| isClearable       | boolean  | 否   | false  | 下拉收起时是否清空列表缓存 |
+| initialPagination | Object   | 否   | `{ pageNum: 1, pageSize: 10 }` | 初始分页 |
+| listItemConfigs   | Array    | 否   | 姓名/主部门/主驻点/手机号/身份证 | 列表项展示字段配置 `{ label, key }[]` |
+| renderItem        | Function | 否   | -      | 自定义列表项渲染 |
+| customItemNode    | ReactNode\|Function | 否 | - | 自定义列表项中附加节点 |
+| avataProps        | Object   | 否   | -      | antd Avatar props |
+| disabledStyle     | Function | 否   | -      | `(disabled) => CSSProperties` |
+
+其余 props 透传 antd Select（如 `placeholder`、`disabled`）。
+
+### loadData 返回
+
+```ts
+{
+  list: Array<{ label?: string; value?: string | number; [key: string]: any }>;
+  pagination: {
+    pageNum: number;
+    pageSize: number;
+    total?: number;
+    hasMore?: boolean;
+  };
+}
+```

package/docs/components/RadioGroupWithTip.md

@@ -0,0 +1,43 @@
+# RadioGroupWithTip
+
+带描述文案、支持单项禁用的单选组。数据优先取 `dataSource`，否则取 Formily `field.dataSource`（schema `enum`）。
+
+## Schema 示例
+
+```json
+{
+  "x-component": "RadioGroupWithTip",
+  "enum": [
+    {
+      "label": "单次采集",
+      "value": 1,
+      "desc": "以人员为单位开展信息采集。"
+    },
+    {
+      "label": "按月采集",
+      "value": 2,
+      "desc": "以自然月为周期定期采集。",
+      "disabled": true
+    }
+  ]
+}
+```
+
+### RadioGroupWithTip Attributes
+
+| 参数       | 类型           | 必填 | 默认值 | 说明 |
+| ---------- | -------------- | ---- | ------ | ---- |
+| value      | string\|number | 否   | -      | 当前选中值 |
+| onChange   | Function       | 否   | -      | 选中变化回调 |
+| dataSource | Array          | 否   | field.dataSource | 选项列表，见下表 |
+
+其余 props 透传 antd `Radio.Group`。
+
+### dataSource / enum 子项
+
+| 参数     | 类型           | 必填 | 默认值 | 说明 |
+| -------- | -------------- | ---- | ------ | ---- |
+| label    | string         | 是   | -      | 主标题 |
+| value    | string\|number | 是   | -      | 选项值 |
+| desc     | string         | 否   | -      | 描述文案 |
+| disabled | boolean        | 否   | false  | 单项禁用 |

package/docs/components/RichEditor.md

@@ -0,0 +1,94 @@
+# RichEditor
+
+基于 wangEditor 的富文本编辑器，支持 OSS / 私有化上传。Schema 中可使用 `RichEditor` 或别名 `Editor`。
+
+## PC 使用前安装依赖
+
+```bash
+npm install @wangeditor/editor-for-react
+```
+
+## Schema 示例
+
+```json
+{
+  "x-component": "RichEditor",
+  "x-component-props": {
+    "height": "400px",
+    "uploadMode": "oss",
+    "toolbarConfig": {},
+    "editorConfig": {
+      "placeholder": "请输入内容..."
+    }
+  }
+}
+```
+
+独立使用：
+
+```jsx
+import { RichEditor } from "@hzab/form-render/src/components";
+import { useRef } from "react";
+
+export default function Demo() {
+  const editorRef = useRef();
+  return <RichEditor ref={editorRef} height="400px" />;
+}
+```
+
+向富文本 set 内容：`editorRef.current.setEditorContent(HtmlString)`
+
+获取富文本当前内容：`editorRef.current.getEditorContent()`
+
+### RichEditor Attributes
+
+| 参数              | 类型                    | 必填 | 默认值 | 说明 |
+| ----------------- | ----------------------- | ---- | ------ | ---- |
+| value             | string                  | 否   | -      | 编辑器 HTML 内容 |
+| onChange          | Function                | 否   | -      | 内容变化回调 |
+| height            | string                  | 否   | -      | 编辑器高度 |
+| toolbarConfig     | Partial\<IToolbarConfig\> | 否 | {}     | 工具栏配置 |
+| editorConfig      | Partial\<IEditorConfig\>  | 否 | `{ placeholder: '请输入内容...' }` | 编辑器配置 |
+| uploadMode        | string                  | 否   | oss    | 上传模式：`oss` / `offline` 等 |
+| ossOpt            | Object                  | 否   | -      | OSS 上传配置 |
+| uploadParams      | Object                  | 否   | {}     | 上传入参 |
+| ossServerUrl      | string                  | 否   | 全局配置或 `/api/v1/user/oss/getWebOssConfig` | 获取 OSS 配置接口 |
+| ossUrl            | string                  | 否   | 同 ossServerUrl | OSS 配置接口（兼容字段） |
+| offlineServerUrl  | string                  | 否   | -      | 私有化上传接口 |
+| offlinePreviewUrl | string                  | 否   | -      | 私有化预览前缀 |
+| customRequest     | Function                | 否   | -      | 自定义上传请求 |
+| zIndex            | number                  | 否   | 9999   | 编辑器层级 |
+
+图片上传可在 `editorConfig.MENU_CONF.uploadImage` 中配置，参考 [wangEditor 文档](https://www.wangeditor.com/v5/menu-config.html#upload-image)。
+
+```jsx
+editorConfig = {
+  MENU_CONF: {
+    uploadImage: {
+      server: "/api/upload",
+      fieldName: "your-custom-name",
+      maxFileSize: 1 * 1024 * 1024,
+      maxNumberOfFiles: 10,
+      allowedFileTypes: ["image/*"],
+      meta: { token: "xxx" },
+      headers: { Accept: "text/x-json" },
+      withCredentials: true,
+      timeout: 5 * 1000,
+    },
+  },
+};
+```
+
+## 移动端使用前安装依赖
+
+```bash
+npm install lib-flexible
+```
+
+```jsx
+import HandleMobile from "./components/handleMobileVw";
+
+export default function Demo() {
+  return <HandleMobile content={HtmlString} />;
+}
+```

package/docs/components/Text.md

@@ -0,0 +1,26 @@
+# Text
+
+只读文本展示组件，常用于 schema 合并、LocationListPicker 弹层等内部场景；也可在 schema 中直接使用。
+
+## Schema 示例
+
+```json
+{
+  "x-component": "Text",
+  "x-component-props": {
+    "content": "静态文案",
+    "mode": "div"
+  }
+}
+```
+
+表单字段有值时优先展示 `value`，否则展示 `content`。
+
+### Text Attributes
+
+| 参数      | 类型   | 必填 | 默认值 | 说明 |
+| --------- | ------ | ---- | ------ | ---- |
+| value     | any    | 否   | -      | 字段值，优先展示 |
+| content   | any    | 否   | -      | 无 value 时的静态内容 |
+| mode      | string | 否   | div    | 渲染标签名；`normal` 或不传时为 `div`，也可设为 `span` / `p` 等 |
+| className | string | 否   | -      | 附加 class，根节点带 `formily-text` |

package/docs/components/TreeCheckbox.md

@@ -0,0 +1,52 @@
+# TreeCheckbox
+
+树形多选复选框，支持按层级合并叶子节点，以及最外层 Tab 展示。
+
+## Schema 示例
+
+```json
+{
+  "x-component": "TreeCheckbox",
+  "x-component-props": {
+    "mergeLeaf": true,
+    "mergeFullLeaf": true,
+    "tabBox": false,
+    "fieldNames": {
+      "label": "label",
+      "value": "value",
+      "children": "children"
+    }
+  },
+  "enum": [
+    {
+      "label": "一级",
+      "value": "1",
+      "children": [
+        { "label": "二级-1", "value": "1-1" },
+        { "label": "二级-2", "value": "1-2" }
+      ]
+    }
+  ]
+}
+```
+
+数据也可通过 `x-component-props.dataSource` 或 `field.dataSource` 传入。
+
+### TreeCheckbox Attributes
+
+| 参数          | 类型    | 必填 | 默认值                                             | 说明 |
+| ------------- | ------- | ---- | -------------------------------------------------- | ---- |
+| dataSource    | Array   | 否   | field.dataSource                                   | 树数据 |
+| mergeFullLeaf | boolean | 否   | true                                               | 合并不存在 children 的层级 |
+| mergeLeaf     | boolean | 否   | true                                               | 合并每一层级的叶子节点 |
+| fieldNames    | Object  | 否   | `{ label, value, children }`                       | 自定义 options 中字段名 |
+| disabled      | boolean | 否   | false                                              | 禁用状态 |
+| readOnly      | boolean | 否   | false                                              | 只读状态 |
+| tabBox        | boolean | 否   | false                                              | 最外层使用 tab |
+| tabConfList   | Array   | 否   | -                                                  | tab 配置列表；存在时优先用于计算 tab 层级数 |
+| tabLevel      | number  | 否   | -                                                  | tab 层级数（`tabBox === true` 时为 1） |
+| labelKey      | string  | 否   | label                                              | 兼容旧字段，后续废弃 |
+| valueKey      | string  | 否   | value                                              | 兼容旧字段，后续废弃 |
+| childrenKey   | string  | 否   | children                                           | 兼容旧字段，后续废弃 |
+
+表单值为选中节点 `value` 组成的数组。

package/docs/components/UserSelect.md

@@ -0,0 +1,59 @@
+# UserSelect
+
+人员下拉选择器，基于 antd Select，支持头像、手机号、身份证号等扩展展示。
+
+## Schema 示例
+
+```json
+{
+  "x-component": "UserSelect",
+  "x-component-props": {
+    "isAvatar": true,
+    "avatarSize": "default",
+    "configKey": {
+      "phoneKey": "phone",
+      "idCardKey": "idCard"
+    }
+  },
+  "enum": [
+    {
+      "label": "张三",
+      "value": "1",
+      "phone": "13800000000",
+      "idCard": "3301**********1234",
+      "avatar": "https://example.com/avatar.png"
+    }
+  ]
+}
+```
+
+数据源也可通过 Formily `field.dataSource` 或 `x-component-props.options` 传入。
+
+### UserSelect Attributes
+
+| 参数       | 类型     | 必填 | 默认值  | 说明 |
+| ---------- | -------- | ---- | ------- | ---- |
+| options    | Array    | 否   | -       | 下拉数据；也可使用 schema `enum` / `field.dataSource` |
+| isAvatar   | boolean  | 否   | false   | 是否显示头像 |
+| avatarSize | AvatarSize | 否 | default | antd Avatar 尺寸 |
+| configKey  | Object   | 否   | -       | 自定义字段映射，见下表 |
+| InfoRender | Function | 否   | -       | 自定义 option 信息区渲染，入参为 option 对象 |
+
+其余 props 透传 antd Select。
+
+### configKey
+
+| 参数      | 类型   | 必填 | 默认值 | 说明 |
+| --------- | ------ | ---- | ------ | ---- |
+| phoneKey  | string | 否   | phone  | 手机号字段名 |
+| idCardKey | string | 否   | idCard | 身份证号字段名 |
+
+### options 子项
+
+| 参数   | 类型           | 必填 | 默认值 | 说明 |
+| ------ | -------------- | ---- | ------ | ---- |
+| label  | string         | 是   | -      | 展示名称 |
+| value  | string\|number | 是   | -      | 选项值 |
+| avatar | string         | 否   | -      | 头像 URL |
+| phone  | string         | 否   | -      | 手机号（可被 configKey 覆盖） |
+| idCard | string         | 否   | -      | 身份证号（可被 configKey 覆盖） |

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@hzab/form-render",
-  "version": "1.7.17",
+  "version": "1.7.18",
   "description": "",
   "main": "src",
   "scripts": {
     "dev": "webpack serve -c ./config/webpack.config.js --env local",
     "build": "webpack -c ./config/webpack.config.js --env production",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "version:alpha": "npm version prerelease --preid=alpha",
     "publish:alpha": "npm publish --tag alpha",
     "version:beta": "npm version prerelease --preid=beta",
@@ -17,6 +20,7 @@
   },
   "files": [
     "src",
+    "docs",
     "CHANGELOG.md"
   ],
   "keywords": [],
@@ -27,16 +31,21 @@
     "@hzab/permissions": "^0.1.1",
     "@hzab/utils": "^1.0.16",
     "@hzab/webpack-config": "0.0.12",
+    "@testing-library/jest-dom": "^5.17.0",
+    "@testing-library/react": "^12.1.5",
+    "@testing-library/user-event": "^13.5.0",
     "@types/react": "^17.0.62",
     "@types/react-dom": "^17.0.20",
     "antd": "^4.24.12",
     "dayjs": "1.11.10",
     "eslint": "^8.30.0",
+    "jsdom": "^30.0.1",
     "less": "^4.1.3",
     "react": "^17.0.2",
     "react-dom": "^17.0.2",
     "react-router-dom": "^6.8.1",
-    "typescript": "^4.9.4"
+    "typescript": "^4.9.4",
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "@hzab/utils": ">=1.0.6",

package/src/components/LocationListPicker/index.tsx

@@ -55,7 +55,7 @@ export const LocationListPicker = observer((props) => {
       // 取消监听
       mapUtilsRef.current?.off("click", onMapClick);
       mapUtilsRef.current?.off("dblclick", onMapDbClick);
-      mapDomRef.current.current.removeEventListener("mousemove", onMouseMove);
+      mapDomRef.current?.current?.removeEventListener?.("mousemove", onMouseMove);
     };
   }, []);
 

package/src/components/LocationPicker/Map/AMap/common/loader.ts

@@ -1,3 +1,5 @@
+import AMapLoader from "@amap/amap-jsapi-loader"
+
 const defaultVersion = "2.0";
 const defaultPlugins = ["AMap.Geocoder", "AMap.AutoComplete", "AMap.PolygonEditor", "AMap.PolylineEditor"];
 
@@ -33,9 +35,6 @@ function Loader(opt) {
 
     window._AMapLoaderTemp.plugins = plugins ? [...defaultPlugins, ...(plugins || [])] : defaultPlugins;
 
-    // 不用地图组件时可以不安装  "@amap/amap-jsapi-loader"
-    const AMapLoader = require("@amap/amap-jsapi-loader");
-
     window._AMapLoaderTemp.loading = true;
     window._AMapLoaderTemp.promise = AMapLoader.load({
       key: key || window._AMapLoaderTemp.key, // 申请好的Web端开发者Key，首次调用 load 时必填

package/src/components/Upload/uploader-input.jsx

@@ -1,5 +1,6 @@
 import { useState, useRef, useEffect, useMemo } from "react";
 import { Button, Modal, message } from "antd";
+import _ from "lodash";
 
 import ItemList from "./components/ItemList";
 
@@ -9,8 +10,6 @@ import { handleOssUpload } from "./common/ossUpload";
 
 import "./uploader.less";
 
-const _ = require("lodash");
-
 function Uploader(props) {
   const {
     name,

package/src/components/Upload/uploader.jsx

@@ -68,6 +68,7 @@ export function Uploader({ onChange, ...props }) {
     isFileJson = false,
     thumbnailParams = { image_process: "resize,w_200" },
     readPretty,
+    afterUpload
   } = props;
   const isPrivateStore =
     props.uploadParams?.fileAcl === "private" || props.ossOpt?.signatureParams?.fileAcl === "private";
@@ -119,6 +120,7 @@ export function Uploader({ onChange, ...props }) {
    * @returns
    */
   const handleChange = async ({ fileList, file, event }) => {
+
     setFileList(fileList);
     // 上传中不进行处理，结局 ossPromise 不存在的问题
     if (file.status !== "done") {
@@ -126,6 +128,7 @@ export function Uploader({ onChange, ...props }) {
     }
 
     let _files = [...fileList];
+
     // 取出异步 url
     for (let i = 0; i < _files.length; i++) {
       let _file = _files[i]?.originFileObj || _files[i];
@@ -155,8 +158,16 @@ export function Uploader({ onChange, ...props }) {
     });
 
     onChange && onChange?.(_files);
+    afterUpload && await afterUpload({
+      files: fileList,
+      urls: _files
+    })
+
+    setChecking(false);
+
   };
 
+
   useEffect(() => {
     const list = handleInputFileList(value, {
       ...fileListConf,
@@ -294,7 +305,6 @@ export function Uploader({ onChange, ...props }) {
           return AUpload.LIST_IGNORE;
         }
       }
-      setChecking(false);
     },
     customRequest,
     ...(props || {}),
@@ -335,6 +345,7 @@ export function Uploader({ onChange, ...props }) {
     // },
     ...(props || {}),
   };
+
   const isShowUploadBtn = useMemo(() => {
     if (disabled || readOnly || readPretty) {
       return null;
@@ -353,6 +364,8 @@ export function Uploader({ onChange, ...props }) {
       )
     ) : null;
   }, [maxCount, fileList, disabled, readOnly, readPretty, checking, btnText, listType]);
+
+
   return (
     <>
       <AUpload className="oss-uploader" {..._uploadProps}>

package/src/components/LocationPicker/README.md

@@ -1,44 +0,0 @@
-## 使用前安装依赖
-
-npm install @amap/amap-jsapi-loader
-
-## 注意事项
-
-- isObjectRes 在 @hzab/form-render0.5.0 版本中去除，结果全部存放在对象中
-- changeMode 在 @hzab/form-render0.5.1 版本中去除，仅允许点击地图选点
-
-## 引入
-
-```jsx
-import MapLocationPoint from "./mapLocationPoint";
-
-export default function AMap(props) {
-  return <MapLocationPoint hasSearch={true}></MapLocationPoint>;
-}
-```
-
-### InfoPanel Attributes
-
-| 参数               | 类型    | 必填 | 默认值    | 说明                                             |
-| ------------------ | ------- | ---- | --------- | ------------------------------------------------ |
-| mode               | string  | 否   | dialog    | 地图显示的类型， dialog 弹窗显示、 show 直接显示 |
-| element            | string  | 否   | Polypoint | 地图绘制的元素名Polypoint&Polyline&Polygon |
-| layout             | string  | 否   | ver       | 选择器和地图的布局 hor 水平、 ver 垂直           |
-| hasSearch          | boolean | 否   | true      | 是否允许搜索                                     |
-| isAutoFixAddr      | boolean | 否   | false     | 打开地图时是否根据经纬度自动修正已填的地址       |
-| lonKey             | string  | 否   | longitude | 经度字段 key                                     |
-| latKey             | string  | 否   | latitude  | 维度字段 key                                     |
-| addrKey            | string  | 否   | address   | 地址字段 key                                     |
-| isAutoSearch       | boolean | 否   | false     | 搜索框是否自动搜索                               |
-| markerIconConf     | Object  | 否   | -         | markerIcon 配置对象                              |
-| icons              | Object  | 否   | -         | icon 图片配置                                    |
-| getCurPositionConf | Object  | 否   | -         | getCurrentPosition Config                        |
-
-#### icons
-
-| 参数         | 类型   | 必填 | 默认值 | 说明                     |
-| ------------ | ------ | ---- | ------ | ------------------------ |
-| markerIcon   | string | 否   | dialog | marker icon 图片地址     |
-| pickerIcon   | string | 否   | dialog | 选点 icon 图片地址或元素 |
-| positionIcon | string | 否   | dialog | 定位 icon 图片地址或元素 |
-| resetIcon    | string | 否   | dialog | 重置 icon 图片地址或元素 |

package/src/components/RichEditor/README.md

@@ -1,82 +0,0 @@
-## PC使用前安装依赖
-
-npm install @wangeditor/editor-for-react
-
-## 引入
-
-```jsx
-import wangEditor from "./wangEditor";
-
-export default function AMap(props) {
-  return <wangEditor ref={editorRef}></wangEditor>;
-}
-```
-向富文本内set内容
-editorRef.current.setEditorContent(HtmlString)
-
-获取富文本当前内容
-editorRef.current.getEditorContent()
-
-
-### InfoPanel Attributes
-
-| 参数                | 类型                    | 必填  | 默认值    | 
-| ------------------ | ----------------------  | ---- | --------- | 
-| toolbarConfig      | Partial<IToolbarConfig> | 否   | {}  | 
-| editorConfig       | Partial<IEditorConfig>  | 否   | { placeholder: '请输入内容...' }   |   
-
-图片上传的配置
-```jsx
-editorConfig = {
-  MENU_CONF{
-    uploadImage:{
-
-    server: '/api/upload',
-
-    // form-data fieldName ，默认值 'wangeditor-uploaded-image'
-    fieldName: 'your-custom-name',
-
-    // 单个文件的最大体积限制，默认为 2M
-    maxFileSize: 1 * 1024 * 1024, // 1M
-
-    // 最多可上传几个文件，默认为 100
-    maxNumberOfFiles: 10,
-
-    // 选择文件时的类型限制，默认为 ['image/*'] 。如不想限制，则设置为 []
-    allowedFileTypes: ['image/*'],
-
-    // 自定义上传参数，例如传递验证的 token 等。参数会被添加到 formData 中，一起上传到服务端。
-    meta: {
-        token: 'xxx',
-        otherKey: 'yyy'
-    },
-
-    // 将 meta 拼接到 url 参数中，默认 false
-    metaWithUrl: false,
-
-    // 自定义增加 http  header
-    headers: {
-        Accept: 'text/x-json',
-        otherKey: 'xxx'
-    },
-
-    // 跨域是否传递 cookie ，默认为 false
-    withCredentials: true,
-
-    // 超时时间，默认为 10 秒
-    timeout: 5 * 1000, // 5 秒
-    }
-  }
-}
-```
-
-## 移动端使用前安装依赖
-npm install lib-flexible
-
-```jsx
-import wangEditor from "./wangEditor/handleMobile";
-
-export default function AMap(props) {
-  return <HandleMobile content={HtmlString}></HandleMobile>;
-}
-```

package/src/components/TreeCheckbox/README.md

@@ -1,11 +0,0 @@
-### InfoPanel Attributes
-
-| 参数          | 类型    | 必填 | 默认值                                             | 说明                                          |
-| ------------- | ------- | ---- | -------------------------------------------------- | --------------------------------------------- |
-| dataSource    | Array   | 是   | -                                                  | 树数据                                        |
-| mergeFullLeaf | boolean | 否   | true                                               | 合并不存在 children 的层级                    |
-| mergeLeaf     | boolean | 否   | true                                               | 合并每一层级的叶子节点                        |
-| fieldNames    | Object  | 否   | { label: label, value: value, children: children } | 自定义 options 中 label value children 的字段 |
-| disabled      | boolean | 否   | false                                              | 禁用状态                                      |
-| readOnly      | boolean | 否   | false                                              | 只读状态                                      |
-| tabBox        | boolean | 否   | false                                              | 最外层使用 tab                                |