# TriwebForm 组件库文档

## 项目概述

**TriwebForm** 是一个基于 React + TypeScript 的企业级表单组件库，基于 RSuite UI 框架构建，支持动态表单引擎、多种表单组件、表格、树形控件等企业级应用常用组件。

### 技术栈

- **框架**: React 16+ / TypeScript
- **UI 库**: RSuite
- **构建工具**: microbundle / craco
- **编辑器**: Monaco Editor / Jodit React (富文本)
- **工具库**: lodash, moment, axios

---

## 目录结构

```
src/
├── 0components/          # 组件实现
│   ├── 0comp/            # 基础组件
│   ├── 1custom/          # 自定义组件
│   ├── 2formItem/        # 表单元素组件
│   ├── 3formEngine/      # 表单引擎
│   ├── 4rsuitImpl/       # RSuite 属性转换器
│   ├── 5tableOperate/    # 表格操作组件
│   └── 6style/           # 样式文件
├── 1properties/          # 属性定义
│   ├── 0define/          # 接口定义
│   └── 1engine/          # 引擎属性
├── 3config/              # 配置文件
├── 4common/              # 公共工具
├── 5test/                # 测试示例
└── index.tsx             # 入口文件
```

---

## 快速开始

### 安装

```bash
npm install
```

### 构建

```bash
# 生产构建
npm run build

# 测试构建
npm run buildTest

# 开发模式
npm run start

# CRA 开发模式
npm run startDev
```

### 初始化

```tsx
import { install } from 'twform';

// 在应用入口初始化
install(true, {
  saveCall: (data) => {
    // 日志保存回调
  },
});
```

---

## 核心组件

### TwForm - 表单组件

表单容器组件，支持动态字段渲染、表单验证、布局控制等功能。

| 属性     | 类型                       | 说明           |
| -------- | -------------------------- | -------------- |
| items    | IFormItem[]                | 表单项配置数组 |
| value    | object                     | 表单值         |
| onChange | function                   | 值变更回调     |
| layout   | 'horizontal' \| 'vertical' | 布局模式       |
| rules    | object                     | 验证规则       |

### TwFormEngine - 表单引擎

动态表单引擎，支持运行时动态渲染和配置表单项。

### TwStep - 步骤条

分步表单组件，用于多步骤流程引导。

| 属性         | 类型        | 说明         |
| ------------ | ----------- | ------------ |
| current      | number      | 当前步骤     |
| onStepChange | function    | 步骤变更回调 |
| items        | IStepItem[] | 步骤配置     |

---

## 表单元素组件

### TwInput - 输入框

文本输入组件，支持前缀/后缀图标、字数限制等。

| 属性        | 类型      | 说明     |
| ----------- | --------- | -------- |
| placeholder | string    | 占位文本 |
| prefix      | ReactNode | 前缀图标 |
| suffix      | ReactNode | 后缀图标 |
| maxLength   | number    | 最大长度 |
| disabled    | boolean   | 是否禁用 |

### TwText - 文本显示

只读文本显示组件，支持字典值回显。

| 属性      | 类型     | 说明       |
| --------- | -------- | ---------- |
| value     | string   | 显示值     |
| dictCode  | string   | 字典编码   |
| formatter | function | 格式化函数 |

### TwCheckBox - 复选框

多选框组件，支持单选和多选模式。

| 属性     | 类型                | 说明     |
| -------- | ------------------- | -------- |
| value    | boolean \| string[] | 值       |
| options  | IOption[]           | 选项配置 |
| disabled | boolean             | 是否禁用 |

### TwRadio - 单选框

单选框组件。

| 属性     | 类型      | 说明     |
| -------- | --------- | -------- |
| value    | string    | 选中值   |
| options  | IOption[] | 选项配置 |
| disabled | boolean   | 是否禁用 |

### TwSelect - 下拉选择

下拉选择组件，支持单选、多选、远程搜索。

| 属性       | 类型                   | 说明         |
| ---------- | ---------------------- | ------------ |
| value      | string \| string[]     | 值           |
| options    | IOption[]              | 选项列表     |
| mode       | 'single' \| 'multiple' | 选择模式     |
| searchable | boolean                | 是否可搜索   |
| remote     | boolean                | 是否远程加载 |

### TwCascader - 级联选择

多级联动选择组件。

| 属性        | 类型              | 说明     |
| ----------- | ----------------- | -------- |
| value       | string[]          | 选中值   |
| options     | ICascaderOption[] | 级联数据 |
| placeholder | string            | 占位文本 |

### TwDatePicker - 日期选择

日期/时间选择组件。

| 属性     | 类型    | 说明         |
| -------- | ------- | ------------ |
| value    | moment  | 选中日期     |
| format   | string  | 日期格式     |
| showTime | boolean | 是否显示时间 |
| range    | boolean | 是否范围选择 |

### TwToggle - 开关

开关切换组件。

| 属性     | 类型     | 说明     |
| -------- | -------- | -------- |
| checked  | boolean  | 是否选中 |
| onChange | function | 变更回调 |
| disabled | boolean  | 是否禁用 |

### TwEditor - 富文本编辑器

基于 Jodit 的富文本编辑器组件。

| 属性      | 类型     | 说明         |
| --------- | -------- | ------------ |
| value     | string   | HTML 内容    |
| onChange  | function | 内容变更回调 |
| height    | number   | 编辑器高度   |
| uploadUrl | string   | 图片上传接口 |

### TwUpload - 文件上传

文件上传组件，支持多文件上传。

| 属性     | 类型    | 说明             |
| -------- | ------- | ---------------- |
| value    | IFile[] | 已上传文件       |
| action   | string  | 上传接口地址     |
| multiple | boolean | 是否多选         |
| accept   | string  | 接受文件类型     |
| maxSize  | number  | 文件大小限制(MB) |

### TwButton - 按钮

按钮组件，支持权限控制。

| 属性       | 类型                             | 说明     |
| ---------- | -------------------------------- | -------- |
| text       | string                           | 按钮文本 |
| icon       | string                           | 图标名称 |
| type       | 'primary' \| 'default' \| 'link' | 按钮类型 |
| permission | string                           | 权限编码 |

### TwLayer - 布局层

表单布局组件，支持栅格布局。

| 属性    | 类型   | 说明 |
| ------- | ------ | ---- |
| columns | number | 列数 |
| gap     | number | 间距 |

### TwEmptyLine - 空行

占位空行组件。

| 属性   | 类型   | 说明     |
| ------ | ------ | -------- |
| height | number | 高度(px) |

---

## 基础组件

### TwTable - 高级表格

功能丰富的表格组件，支持排序、分页、搜索、单元格编辑。

| 属性         | 类型           | 说明         |
| ------------ | -------------- | ------------ |
| columns      | ITableColumn[] | 列配置       |
| data         | any[]          | 数据源       |
| remote       | boolean        | 是否远程数据 |
| editable     | boolean        | 是否可编辑   |
| selectable   | boolean        | 是否可选择   |
| pagination   | boolean        | 是否分页     |
| pageSize     | number         | 每页条数     |
| onSelect     | function       | 选择回调     |
| onSort       | function       | 排序回调     |
| onPageChange | function       | 分页回调     |

### TwTree - 树形控件

树形数据结构展示和选择组件。

| 属性     | 类型        | 说明     |
| -------- | ----------- | -------- |
| data     | ITreeNode[] | 树数据   |
| selected | string[]    | 选中节点 |
| multiple | boolean     | 是否多选 |
| onSelect | function    | 选择回调 |
| onExpand | function    | 展开回调 |

### TwDialog - 对话框

模态对话框组件，支持 Modal 和 Drawer 模式。

| 属性    | 类型                | 说明     |
| ------- | ------------------- | -------- |
| visible | boolean             | 是否显示 |
| title   | string              | 标题     |
| mode    | 'modal' \| 'drawer' | 显示模式 |
| width   | number \| string    | 宽度     |
| onClose | function            | 关闭回调 |
| footer  | ReactNode           | 底部内容 |

### TwTab - 标签页

标签页切换组件。

| 属性      | 类型       | 说明         |
| --------- | ---------- | ------------ |
| activeKey | string     | 当前激活标签 |
| items     | ITabItem[] | 标签配置     |
| onChange  | function   | 切换回调     |

### TwTreeSelect - 树形选择

树形下拉选择组件。

### TwPopper - 弹出层

基础弹出层组件。

### TwConfirmButton - 确认按钮

带确认弹窗的按钮组件。

| 属性      | 类型     | 说明     |
| --------- | -------- | -------- |
| text      | string   | 按钮文本 |
| title     | string   | 确认标题 |
| content   | string   | 确认内容 |
| onConfirm | function | 确认回调 |

### TwAlert - 消息提示

消息提示组件（静态调用）。

```tsx
TwAlert.success('操作成功');
TwAlert.error('操作失败');
TwAlert.info('提示信息');
TwAlert.warning('警告');
```

### TwToolTip - 工具提示

鼠标悬停提示组件。

| 属性      | 类型   | 说明     |
| --------- | ------ | -------- |
| title     | string | 提示内容 |
| placement | string | 显示位置 |

### TwIcon - 图标

图标组件，基于 RSuite 图标库。

| 属性 | 类型                 | 说明     |
| ---- | -------------------- | -------- |
| name | string               | 图标名称 |
| size | 'sm' \| 'md' \| 'lg' | 尺寸     |

### TwBadge - 徽章

红点标记组件。

| 属性    | 类型      | 说明 |
| ------- | --------- | ---- |
| content | ReactNode | 内容 |
| count   | number    | 数字 |

### TwBreadcrumb - 面包屑

面包屑导航组件。

| 属性      | 类型              | 说明   |
| --------- | ----------------- | ------ |
| items     | IBreadcrumbItem[] | 导航项 |
| separator | ReactNode         | 分隔符 |

### TwPanel - 面板

面板容器组件。

| 属性            | 类型    | 说明       |
| --------------- | ------- | ---------- |
| title           | string  | 标题       |
| collapsible     | boolean | 是否可折叠 |
| defaultExpanded | boolean | 默认展开   |

### TwLoader - 加载器

加载状态指示组件。

| 属性    | 类型    | 说明       |
| ------- | ------- | ---------- |
| loading | boolean | 是否加载中 |
| tip     | string  | 加载提示   |

### TwDropdown - 下拉菜单

下拉菜单组件。

### TwDivider - 分割线

分割线组件。

### TwList - 列表

列表展示组件。

### TwHelp - 帮助提示

帮助信息提示组件。

---

## 自定义组件

### RelationSelect - 关联选择

支持动态搜索和远程数据的关联选择组件。

| 属性       | 类型     | 说明         |
| ---------- | -------- | ------------ |
| value      | string   | 选中值       |
| url        | string   | 数据接口地址 |
| labelField | string   | 标签字段     |
| valueField | string   | 值字段       |
| searchable | boolean  | 是否可搜索   |
| onSearch   | function | 搜索回调     |

### CustomSelect - 自定义弹窗选择

自定义弹窗选择组件，支持复杂选项展示。

### Resize - 尺寸监听

高阶组件，用于监听窗口尺寸变化。

### Editor - 富文本编辑器

基于 Jodit 的富文本编辑器封装。

### Tab - 自定义标签页

自定义标签页组件。

### Text - 自定义文本

自定义文本显示组件。

---

## 配置组件

### TwConst - 系统常量

系统常量配置组件，用于显示系统定义的常量值。

### TwOptions - 选项配置

选项配置组件，统一管理下拉选项。

### TwFieldPropGroup - 字段属性分组

字段属性分组配置组件。

### AOptionsComp - 选项基类

选项组件基类，处理字典和远程数据加载。

---

## 表格操作组件

### TwCustomSearch - 自定义搜索

表格自定义搜索组件，支持多种搜索条件组合。

---

## 工具函数

### ComUtil - 通用工具类

| 方法                     | 说明               |
| ------------------------ | ------------------ |
| isEmpty(val)             | 判断是否为空       |
| isUndefined(val)         | 判断是否 undefined |
| uuid()                   | 生成 UUID          |
| listToMap(list, key)     | 列表转 Map         |
| promiseOk(promise)       | Promise 包装       |
| formatDate(date, format) | 日期格式化         |
| downloadFile(url, name)  | 下载文件           |

### HttpService - HTTP 服务

基于 axios 封装的 HTTP 服务类。

| 方法                      | 说明        |
| ------------------------- | ----------- |
| get(url, params)          | GET 请求    |
| post(url, data)           | POST 请求   |
| put(url, data)            | PUT 请求    |
| delete(url, params)       | DELETE 请求 |
| upload(url, file, params) | 文件上传    |

### ValidatorFC - 表单验证器

| 规则           | 说明       |
| -------------- | ---------- |
| required       | 必填验证   |
| email          | 邮箱验证   |
| phone          | 手机号验证 |
| url            | URL 验证   |
| number         | 数字验证   |
| min(length)    | 最小长度   |
| max(length)    | 最大长度   |
| pattern(regex) | 正则验证   |

### Logger - 日志服务

全局日志记录服务，支持开发和生产环境。

| 方法       | 说明     |
| ---------- | -------- |
| log(msg)   | 普通日志 |
| info(msg)  | 信息日志 |
| warn(msg)  | 警告日志 |
| error(msg) | 错误日志 |

### GlobalConfig - 全局配置

全局配置类，定义表格行高、列高等默认配置。

### Base64 - 加密工具

Base64 编解码工具。

### IntlProvider - 国际化

国际化包装组件。

---

## 属性转换器 (4rsuitImpl)

每个组件都有对应的属性转换器，用于将配置属性转换为 RSuite 组件属性：

| 转换器              | 对应组件       |
| ------------------- | -------------- |
| InputTranslate      | TwInput        |
| SelectTranslate     | TwSelect       |
| CheckBoxTranslate   | TwCheckBox     |
| RadioTranslate      | TwRadio        |
| DatePickerTranslate | TwDatePicker   |
| ToggleProTranslate  | TwToggle       |
| CascaderTranslate   | TwCascader     |
| UploaderTranslate   | TwUpload       |
| EditorTranslate     | TwEditor       |
| UEditorTranslate    | UEditor        |
| StepTranstranslate  | TwStep         |
| TableTranslate      | TwTable        |
| TreeTranslate       | TwTree         |
| TabProTranslate     | TwTab          |
| DialogTranslate     | TwDialog       |
| PanelTranslate      | TwPanel        |
| MenuTranslate       | TwDropdown     |
| IconTranslate       | TwIcon         |
| LoaderTranslate     | TwLoader       |
| PopperTranslate     | TwPopper       |
| TooltipTranslate    | TwToolTip      |
| ListTranslate       | TwList         |
| DividerTranslate    | TwDivider      |
| BadgeTranslate      | TwBadge        |
| BrecTranslate       | TwBreadcrumb   |
| TextProTranslate    | TwText         |
| EmptyProTranslate   | TwEmptyLine    |
| LayerProTranslate   | TwLayer        |
| HelpTranslate       | TwHelp         |
| RtSelectTranslate   | RelationSelect |

---

## 架构设计

### 设计模式

1. **IOC 容器模式**: `TranslateIoc` 统一管理所有组件转换器
2. **属性转换模式**: 配置属性通过转换器转换为 RSuite 组件属性
3. **基类继承模式**: 表单组件继承 `FormComponent` 基类，统一处理属性转换
4. **权限控制模式**: `TwPermission` 基类统一处理权限校验

### 组件继承关系

```
FormComponent (表单组件基类)
├── TwInput
├── TwSelect
├── TwCheckBox
├── TwRadio
├── TwDatePicker
├── TwToggle
├── TwEditor
├── TwUpload
└── ...

PropertyComponent (属性转换基类)
└── 各转换器实现
```

---

## 使用示例

### 基础表单

```tsx
import { TwForm, TwInput, TwSelect, TwButton } from 'twform';

const MyForm = () => {
  const handleSubmit = (values) => {
    console.log(values);
  };

  return (
    <TwForm onFinish={handleSubmit}>
      <TwInput name="username" label="用户名" required />
      <TwSelect
        name="gender"
        label="性别"
        options={[
          { value: '1', label: '男' },
          { value: '2', label: '女' },
        ]}
      />
      <TwButton type="primary" htmlType="submit">
        提交
      </TwButton>
    </TwForm>
  );
};
```

### 带验证的表单

```tsx
import { TwForm, TwInput, TwValidator } from 'twform';

const items = [
  {
    field: 'email',
    label: '邮箱',
    view: 'Input',
    rules: [{ required: true, message: '请输入邮箱' }, { validator: TwValidator.email }],
  },
  {
    field: 'phone',
    label: '手机号',
    view: 'Input',
    rules: [{ validator: TwValidator.phone }],
  },
];
```

### 高级表格

```tsx
import { TwTable } from 'twform';

const columns = [
  { key: 'name', title: '姓名', sortable: true },
  { key: 'age', title: '年龄', editable: true },
  { key: 'status', title: '状态', dictCode: 'status' },
];

<TwTable columns={columns} data={data} remote pagination onSelect={handleSelect} />;
```

---

## 注意事项

1. 使用前请先调用 `install()` 进行初始化
2. 组件属性遵循 RSuite 规范
3. 表单组件支持响应式布局
4. 支持自定义主题样式覆盖
5. 国际化支持通过 `IntlProvider` 配置
