+
+# FormRender
+
+
+
+
+> 通过 JSON Schema 生成标准 Form，常用于自定义搭建配置界面生成
+
+## Topics
+
+- 文档官网
+- Form Render Demo
+- 升级日志
+
+
+
+## Features
+
+- 支持 Ant Design 和 Fusion Design 主流的视觉主题
+- 使用 JSON Schema 标准协议描述表单配置，并搭配丰富类型且可扩展的组件
+- 支持 1 排 N、横纵排、支持对象无限嵌套、自定义正则校验、自定义样式组件、列表拖拽等特性
+- 已在内部不少场景使用，可简单使用同时支持复杂场景使用
+- 使用上有详细文档，维护上有专人支持
+
+## 思路
+
+Form Render 底层引擎用原生 JS 来实现，通过解析 JSON Schema 配置，并支持渲染原生的 HTML 表单，通过 UiSchema 来配置 Widget 组件，在此基础上处理好上层 Antd 或 Fusion 组件 Widget 和 Input Format 的对应关系，最后还可以做到无缝接入其他组件体系的好处
+
+
+
+## Installation
+
+```sh
+tnpm i @ali/form-render -S
+```
+
+## Usage
+
+详细使用可见 [开始开始](xxx)
+
+```react
+import React from 'react';
+
+// antd 是这样使用(使用3.x版本)
+import 'antd/dist/antd.css';
+import FormRender from '@ali/form-render/lib/antd.js';
+
+// fusion 这样使用(使用开源版本)
+//import '@alifd/next/dist/next.min.css';
+//import FormRender from '@ali/form-render/lib/fusion';
+
+// propsSchema 是配置 Form Render 的必备参数，使用标准的 JSON Schema 来描述表单结构
+const propSchema = {
+ type: 'object',
+ properties: {
+ stringDemo: {
+ title: '字符串',
+ description: '英文或数字组合',
+ type: 'string',
+ pattern: '^[A-Za-z0-9]+$'
+ },
+ dateDemo: {
+ title: '时间',
+ format: 'dateTime',
+ type: 'string'
+ },
+ },
+ required: [
+ 'stringDemo'
+ ]
+};
+
+//通过uiSchema可以增强 Form Render 展示的丰富性，比如说日历视图
+const uiSchema = {
+ dateDemo: {
+ 'ui:widget': 'date'
+ }
+};
+
+class Playground extends React.Component {
+ constructor() {
+ super();
+ this.state = {
+ formData: {}
+ };
+ }
+
+ // 数据变化回调
+ onChange = value => {
+ this.setState({
+ formData: value
+ });
+ }
+
+ // 数据格式校验回调
+ onValidate = list => {
+ console.log(list);
+ }
+
+ render() {
+ const { formData } = this.state;
+ return (
+
+
+# Form Render
+
+> 通过 JSON Schema 生成标准 Form，常用于自定义搭建配置界面生成
+
+[快速开始](README)
diff --git a/docs/_navbar.md b/docs/_navbar.md
new file mode 100644
index 0000000..e69de29
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
new file mode 100644
index 0000000..3462f3d
--- /dev/null
+++ b/docs/_sidebar.md
@@ -0,0 +1,13 @@
+- **基础使用**
+ - [快速开始](README)
+ - [propSchema 配置](docs/prop-schema)
+ - [uiSchema 配置](docs/ui-schema)
+ - [pattern 自定义正则校验](docs/pattern)
+- **高级配置**
+ - [样式覆盖](docs/css)
+ - [自定义组件](docs/widget)
+ - [表达式依赖决定显示表单](docs/depend)
+- **也许需要**
+ - [常见问题](docs/question)
+- [**欢迎贡献代码**](CONTRIBUTING)
+- [**升级日志**](CHANGELOG)
diff --git a/docs/css.md b/docs/css.md
new file mode 100644
index 0000000..1384401
--- /dev/null
+++ b/docs/css.md
@@ -0,0 +1,10 @@
+# 样式覆盖
+
+### 概述
+- Form Render 其实是有一个默认的布局样式，比如说表单之间的间距，label 字号、颜色等场景
+- 假如使用上有特殊定制，或者认为不符合要求的地方，可以通过常规 CSS 样式覆盖的方式，写到业务 global 样式代码中
+
+### 如何使用
+
+
+
diff --git a/docs/depend.md b/docs/depend.md
new file mode 100644
index 0000000..f4b02f8
--- /dev/null
+++ b/docs/depend.md
@@ -0,0 +1,21 @@
+# 通过表达式的方式来控制某个表单是否显示
+
+### 概述
+
+- 有一些场景中存在当选项为某个值的时候才显示某一项目的场景，如下所示
+ 
+
+### 如何使用
+
+- 比如说，如上例子，当勾选字段 isLike 为 true 的时候，才显示下面的颜色选择，直接通过在需要控制的 uiWidget 上面加入`ui:dependShow`属性，写上他对应的表达式即可
+- 此处需要主要，由于表达式最终会解析成 String 去执行，请确保所有的都通过字符串来表示，否则执行`true==='true'`或者`A=='A'`这一类型会报错(如 A 变量找不到)
+
+```json
+"uiSchema": {
+ "objDemo": {
+ "background": {
+ "ui:dependShow": "'{{objDemo.isLike}}' == 'true'"
+ }
+ }
+ },
+```
diff --git a/docs/pattern.md b/docs/pattern.md
new file mode 100644
index 0000000..b175356
--- /dev/null
+++ b/docs/pattern.md
@@ -0,0 +1,42 @@
+# pattern 自定义正则校验
+
+### 概述
+- 简单的长度校验推荐使用 propSchema 中的属性
+- pattern 是存在于 propSchema 中属性的一个字段，长用在当长度限制还不满足要求的场景，可通过正则的方式来对用户输入项进行校验
+- pattern 和 required、minLength、maxLength 等这一类显示为`&&`的关系，当有一个不满足时候，onValidate 回调中将会返回不符合的数组项
+
+### 格式
+
+- 格式和 JS 正则的格式保持一致，实际为此正则类中的 pattern 字段 `new RegExp(pattern).test(value)`
+
+### 常见 pattern 规则：
+
+| 字符 | 含意 |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| \ | 将下一个字符标记为一个特殊字符、或一个原义字符、或一个后向引用、或一个八进制转义符。 例如，’n’ 匹配字符 “n”。’\n’ 匹配一个换行符。序列 ‘' 匹配 “” 而 “\(” 则匹配 “(“。 |
+| ^ | 匹配输入字符串的开始位置。如果设置了 RegExp 对象的 Multiline 属性，^ 也匹配 ‘\n’ 或 ‘\r’ 之后的位置。 |
+| \$ | 匹配输入字符串的结束位置。如果设置了 RegExp 对象的 Multiline 属性，\$ 也匹配 ‘\n’ 或 ‘\r’ 之前的位置。 |
+| \* | 匹配前面的子表达式零次或多次。例如，zo* 能匹配 “z” 以及 “zoo”。 * 等价于{0,}。 |
+| + | 匹配前面的子表达式一次或多次。例如，’zo+’ 能匹配 “zo” 以及 “zoo”，但不能匹配 “z”。+ 等价于 {1,}。 |
+| ? | 匹配前面的子表达式零次或一次。例如，”do(es)?” 可以匹配 “do” 或 “does” 中的”do” 。? 等价于 {0,1}。 |
+| {n} | n 是一个非负整数。匹配确定的 n 次。例如，’o{2}’ 不能匹配 “Bob” 中的 ‘o’，但是能匹配 “food” 中的两个 o。 |
+| {n,} | n 是一个非负整数。至少匹配 n 次。 例如: ‘o{2,}’ 不能匹配 “Bob” 中的 ‘o’，但能匹配 “foooood” 中的所有 o。 ‘o{1,}’ 等价于 ‘o+’。’o{0,}’ 则等价于 ‘o\*’。 |
+| {n,m} | m 和 n 均为非负整数，其中 n <= m。最少匹配 n 次且最多匹配 m 次。例如: “o{1,3}” 将匹配 “fooooood” 中的前三个 o。’o{0,1}’ 等价于 ‘o?’。请注意在逗号和两个数之间不能有空格。 |
+| ? | 当该字符紧跟在任何一个其他限制符 (\*, +, ?, {n}, {n,}, {n,m}) 后面时，匹配模式是非贪婪的。 非贪婪模式尽可能少的匹配所搜索的字符串，而默认的贪婪模式则尽可能多的匹配所搜索的字符串。 例如，对于字符串 “oooo”，’o+?’ 将匹配单个 “o”，而 ‘o+’ 将匹配所有 ‘o’。 |
+| . | 匹配除 “\n” 之外的任何单个字符。要匹配包括 ‘\n’ 在内的任何字符，请使用象 ‘[.\n]’ 的模式。 |
+| (pattern) | 匹配 pattern 并获取这一匹配。 所获取的匹配可以从产生的 Matches 集合得到，要匹配圆括号字符，请使用 ‘‘或‘‘或‘’。 |
+| (?:pattern) | 匹配 pattern 但不获取匹配结果，也就是说这是一个非获取匹配，不进行存储供以后使用。 这在使用 “或” 字符 (\|) 来组合一个模式的各个部分是很有用。 例如， ‘industr(?:y\|ies) 就是一个比 ‘industry\|industries’ 更简略的表达式。 |
+| (?=pattern) | **肯定** 顺序环视 **：子表达式能够匹配右侧的文本**正向预查，在任何匹配 pattern 的字符串开始处匹配查找字符串。这是一个非获取匹配，也就是说，该匹配不需要获取供以后使用。例如， ‘Windows (?=95\|98\|NT\|2000)’ 能匹配 “Windows 2000” 中的 “Windows” ， 但不能匹配 “Windows 3.1” 中的 “Windows”。_预查不消耗字符，也就是说，在一个匹配发生后，在最后一次匹配之后立即开始下一次匹配的搜索， 而不是从包含预查的字符之后开始。_ |
+| (?!pattern) | **否定顺序环视：子表达式不能匹配右侧的文本**负向预查，在任何不匹配的字符串开始处匹配查找字符串。这是一个非获取匹配，也就是说，该匹配不需要获取供以后使用。例如’Windows (?!95\|98\|NT\|2000)’ 能匹配 “Windows 3.1” 中的 “Windows”， 但不能匹配 “Windows 2000” 中的 “Windows”。_预查不消耗字符，也就是说，在一个匹配发生后，在最后一次匹配之后立即开始下一次匹配的搜索， 而不是从包含预查的字符之后开始_ |
+| (?<=pattern))))) | **肯定逆序环视：子表达式能够匹配左侧的文本** |
+| (?Understanding JSON Schema是笔者认为最好的学习文档，同时也可去 Form Render Demo 折腾
+- 虽然这里我们只以 json 格式为例，但 javascript object 作为入参完全可以
+
+一个基础的 propsSchema 如下：
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "jobNumber": {
+ "title": "数字",
+ "type": "number"
+ }
+ }
+}
+```
+
+描述了一个 object 结构，其第一个属性为数字类型。最外层约定为 object 结构，所有 propsSchema 都需要如是写。
+
+### 通用参数
+
+对于每一个表单控件，我们都会使用如下的 schema 描述
+
+```json
+{
+ "title": "数字",
+ "type": "number"
+}
+```
+
+- `title`：表单的标题信息，作为 label 展示，注意 title 为""时占位，title 不写时不占位
+- `description`：表单的描述信息，常将填写注意点放入此参数
+- `type`：表单的类型，支持 string、number、boolean、array、object、range
+- `format`：用来描述输入框的格式，支持 image、dateTime、date、time
+- `pattern`：自定义正则校验，用于校验 string 或 number 数据是否合格，详细使用可见 pattern 自定义正则校验
+- `message` 校验提示自定义文案，与 pattern 共同使用
+
+#### String
+
+string 类对应的控件非常多：
+
+- 输入框：input、textarea
+
+ - `minLength`：字符串最小长度
+ - `maxLength`：字符串最大长度
+
+- 单选（类型也可能是 number）
+
+ - `enum` 选项值
+ - `enumNames` 选项的文案
+
+```json
+{
+ "title": "单选",
+ "type": "string",
+ "enum": ["hz", "wh", "gy"],
+ "enumNames": ["杭州", "武汉", "贵阳"]
+}
+```
+
+#### Number
+
+- `minimum`：数字最小值
+- `maximum`：数字最大值
+
+#### Object
+
+- `properties`：描述 object 的结构，必要属性
+- `required`：描述对象下哪些项必填，非必要属性。使用方法传入需要限制的 name 即可
+
+```json
+{
+ "title": "用户信息",
+ "type": "object",
+ "properties": {
+ "tickets": {
+ "title": "门票数",
+ "type": "number"
+ }
+ },
+ "required": ["tickets"]
+}
+```
+
+#### Array
+
+`Array`的数据结构可能是：列表 & 多选框
+
+- `items`：用于描述 Array 中每个 item 的结构、类型
+
+- 列表：
+ - `minItems`：最少数组项为几项
+ - `maxItems`：最多数组项为几项
+
+```json
+{
+ "title": "对象数组",
+ "type": "array",
+ "minItems": 1,
+ "maxItems": 3,
+ "items": {
+ "type": "object",
+ "properties": {
+ "tickets": {
+ "title": "门票数",
+ "type": "number"
+ }
+ }
+ }
+}
+```
+
+- 多选框
+
+ - `enum`：参考单选
+ - `enumNames`：参考单选
+
+```json
+{
+ "title": "多选",
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "enum": ["hz", "wh", "gy"],
+ "enumNames": ["杭州", "武汉", "贵阳"]
+}
+```
+
+#### Range
+
+长度为 2 的 array，目前支持的组件为时间范围
+
+```json
+{
+ "title": "日期范围",
+ "type": "range",
+ "format": "dateTime",
+ "ui:options": {
+ "placeholder": ["开始", "结束"]
+ }
+}
+```
+
+### 一个很全的结构
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "stringDemo": {
+ "title": "字符串",
+ "description": "英文或数字组合",
+ "type": "string",
+ "pattern": "^[A-Za-z0-9]+$",
+ "message": {
+ "pattern": "请输入正确格式"
+ }
+ },
+ "imgDemo": {
+ "title": "图片",
+ "type": "string",
+ "format": "image",
+ "default": "'https://img.alicdn.com/tfs/TB1P8p2uQyWBuNjy0FpXXassXXa-750-1334.png'"
+ },
+ "disabledDemo": {
+ "title": "不可用",
+ "type": "string",
+ "default": "我是一个被 disabled 的值"
+ },
+ "enumDemo": {
+ "title": "枚举",
+ "enum": ["A", "B"],
+ "enumNames": ["养成", "动作"]
+ },
+ "dateDemo": {
+ "title": "时间",
+ "format": "dateTime",
+ "type": "string"
+ },
+ "objDemo": {
+ "title": "单个对象",
+ "description": "这是一个对象类型",
+ "type": "object",
+ "properties": {
+ "isLike": {
+ "title": "单选项",
+ "type": "boolean",
+ "default": true
+ },
+ "background": {
+ "title": "颜色选择",
+ "description": "特殊面板",
+ "format": "color",
+ "type": "string"
+ }
+ }
+ },
+ "arrDemo": {
+ "title": "对象数组",
+ "description": "对象数组嵌套功能",
+ "type": "array",
+ "minItems": 1,
+ "maxItems": 3,
+ "items": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "title": "字符名称",
+ "description": "string类型",
+ "type": "string",
+ "pattern": "^[A-Za-z0-9]+$"
+ },
+ "num": {
+ "title": "数字参数",
+ "description": "number类型",
+ "type": "number"
+ }
+ }
+ }
+ }
+ },
+ "required": ["stringDemo", "dateDemo"]
+}
+```
diff --git a/docs/question.md b/docs/question.md
new file mode 100644
index 0000000..5c3e71a
--- /dev/null
+++ b/docs/question.md
@@ -0,0 +1,18 @@
+# 常见问题
+
+### 1. 我引入了组件，但发现无论如何都显示不出来？
+
+- 首先去 Demo 探索 中去将对于的参数填入进去，看是否可以正常出现
+- 假如可以，检查一下 onChange 回调里面是否对 formData 进行了 setState，没有的话，可能由于初始化问题没有显示，加上即可
+
+### 2. 我的 FormRender 可以正常渲染，但是貌似 antd 的样式都没有生效？
+
+- 在原有的 jsx 文件中，检测是否有默认 antd 的样式，或者是否引入了两个 antd 版本
+- 若无样式，则加入 `import 'antd/dist/antd.css';` 样式即可
+- 若两个版本，直接 `tnpm update` 即可
+
+### 3.tooltip 如果在有其他层级元素内部，就会被遮挡，我试了调 z-index 也没用?
+
+- 应该是父容器设置了 overflow 为 hidden，修改成 auto 应该就好了
+
+如果有新问题，欢迎提交 PR 来补充，遇到不能解决的问题，可以添加钉钉群，寻找远程协助。
diff --git a/docs/ui-schema.md b/docs/ui-schema.md
new file mode 100644
index 0000000..48addbc
--- /dev/null
+++ b/docs/ui-schema.md
@@ -0,0 +1,141 @@
+# uiSchema 配置
+
+### 概述
+
+- uiSchema 虽然不是必备参数，但是通过它可以增强 Form Render 展示的丰富性
+- 通过 uiSchema 可以覆盖 propSchema 中 type 对应的默认 widget 组件
+- 通过 `ui:disabled`、`ui:readonly`、`ui:hidden` 属性来控制表单项的 UI 展示
+- 通过 `ui:options` 属性能够实现大量特定的 ui 展示选项
+
+### 书写规范
+
+- uiSchema 里所有的字段都以 `ui:` 开始，如 `ui:widget`。
+- 为了满足各用户的使用偏好，uiSchema 可以单独书写，也可以完全归并到 propsSchema，例如：
+
+```json
+{
+ "propsSchema": {
+ "type": "object",
+ "properties": {
+ "string": {
+ "title": "字符串",
+ "type": "string"
+ }
+ }
+ },
+ "uiSchema": {
+ "string": {
+ "ui:width": "50%"
+ }
+ }
+}
+```
+
+可以合并为
+
+```json
+{
+ "propsSchema": {
+ "type": "object",
+ "properties": {
+ "string": {
+ "title": "字符串",
+ "type": "string",
+ "ui:width": "50%"
+ }
+ }
+ }
+}
+```
+
+事实上 form-render 内部处理 schema 时第一件事就是将 propsSchema 和 uiSchema 合并，所以上述两种 schema 的渲染效果是一致的。前者适用于遵循 json schema 的团队无缝接入，后者在书写上更为高效。
+
+### 覆盖 propSchema 中表单项对应的默认 UI Widget
+
+| 类型 | type | 默认 widget | 其他支持 widget(备注) |
+| ------ | :------------------------: | :---------: | :-------------------: |
+| 布尔值 | boolean | checkbox | switch、radio |
+| 字符串 | string | input | color、date、textarea |
+| 数字 | number | number | slider |
+| 单选项 | string/number(带属性 enum) | select | radio |
+| 多选 | array(带属性 enum) | checkboxes | multiSelect |
+
+### 控制表单项的 UI 展示（共通配置）
+
+- `ui:disabled`: 可控制 input、number、date、checkbox、radio、select、switch 对于组件的 disabled 属性(变灰不可点击)
+- `ui:readonly`：可控制 input、number 组件中的 readonly 属性(不可编辑，但不变灰)
+- `ui:hidden`：可控制所有基础组件是否显示，可使用 true/false 或表达式，例如：
+- `ui:className`：添加组件 root 元素的 className（和 fr-field 这个 className 在同级），用于自定义单独组件的样式
+
+```json
+"age": {
+ "ui:hidden": false
+}
+// 或
+"age": {
+ "ui:hidden": "agree==false && personType!=2"
+}
+```
+
+如果使用如上表达式， age 元素将在 agree 元素的值为 false 且 personType 元素不等于 2 时隐藏。
+注：目前`ui:hidden`支持`==`，`!=`，`>`和`<`四种运算符和`&&`（且），`||`（或）两种关系符，使用的判断字段（表达式左侧）必须是组件的同级字段。
+
+- `ui:width`：单个基础组件的长度，建议使用百分比例如`"ui:width":"50%"`。
+
+### Options
+
+- `ui:options` 里存放特定元素的特定配置。例如`textarea`的`rows`
+
+```json
+"textareaDemo": {
+ "ui:widget": "textarea",
+ "ui:options": {
+ "rows": 5
+ }
+}
+```
+
+基本上所有`antd`文档中组件的 props 都可以使用 `ui:options` 的方式来直接使用。除此之外我们还提供了一些特别 options：
+
+| option | 类型 | 可用组件 | 说明 |
+| -------- | :-----: | :-----------: | :----------------------------------------: |
+| foldable | boolean | 列表（array） | `{ foldable: true }`用于长列表的收起和展开 |
+
+### 如何编写 uiSchema 设置
+
+```json
+{
+ "disabledDemo": {
+ "ui:disabled": true
+ },
+ "dateDemo": {
+ "ui:widget": "date"
+ },
+ "objDemo": {
+ // 覆盖object里面的元素对应的组件
+ "background": {
+ "ui:widget": "color"
+ }
+ },
+ "arrDemo": {
+ // 数组列表除了默认的新增按钮外，自定义的按钮组（每个按钮点击时会执行对应的callback，使用前请先咨询@侑夕）
+ "ui:extraButtons": [
+ {
+ "text": "Excel导入",
+ "icon": "copy",
+ "callback": "onCallback1"
+ },
+ {
+ "text": "删除全部",
+ "icon": "delete",
+ "callback": "clearAll"
+ },
+ {
+ "text": "复制上个",
+ "icon": "copy",
+ "callback": "copyLast"
+ }
+ ]
+ }
+}
+```
diff --git a/docs/widget.md b/docs/widget.md
new file mode 100644
index 0000000..265e0b1
--- /dev/null
+++ b/docs/widget.md
@@ -0,0 +1,86 @@
+# 自定义组件
+
+当 form-render 提供的组件无法 100%满足用户需求时，可以考虑自己写一个。自定义组件功能使 form-render 佣有无限的扩展性。可能的应用场景如下：
+
+1. 我需要写一个异步加载的搜索输入框（普适性不高/难以用 schema 描述的组件）
+2. 我们团队使用 xxx ui，与 antd/fusion 不搭，希望能适配一套 xxx ui 组件的 form-render（欢迎 Pull Request）
+3. 我需要在表单内部写一个 excel 上传按钮（完全定制化的需求）
+
+注：如果是新增一个常用组件，建议给 Form Render 维护的同学来提 Pull Request，这样可以更好扩展其生态
+
+## 如何使用
+
+### 写自定义组件
+
+1. 可以 clone 下对应 git 代码，然后参考 `widget/antd` 或者 `widget/fusion`里面对应的组件写法。
+
+- 组件接收到的 props:
+
+ - **default**: 对应 `default` 字段
+ - **description**：对应 `description`
+ - **displayType**：值为 row 和 column，用于处理在横竖模式下组件显示不同的情况
+ - **disabled**：对应 `ui:disable`
+ - **hidden**：对应 `ui:hidden`
+ - **name**：对应 `title` 字段
+ - **onChange**：函数，接收 name/value 两个入参，调用可修改 formData 里对应名字字段的值（见下例）
+ - **options**：对应 `ui:options` 字段，所有的其他字段没有 cover 到的参数都建议放在 options 里
+ - **readonly**：对应 `ui:readonly` 字段
+ - **required**：组件是否是必填的
+ - **rootValue**：组件对应键值对所在的 data 树从父级开始的所有值
+ - **schema**：组件对应的子 schema
+ - **value**：组件的值
+
+简单的说，通过`title`、`description`、`default`、`ui:hidden`、`ui:disable` 和 `ui:readonly`等 schema 字段定义的值在`this.props`中可直接获得，剩下的字段也可以在`schema`（注意这个是组件对应的子 schema）中获得，比如`schema.type`。更多细节的入参，建议不要新添特殊字段，而统一放在`ui:options`这个对象中传递。
+
+例如一个简单的 checkbox 自定义组件
+
+```js
+// MyCheckbox.js
+import React from 'react';
+import Checkbox from '../Checkbox';
+
+export default function Checkbox({ name, value, onChange, options }) {
+ return (
+