Add docs (alibaba#150)

* index on add-docs: 965fb8c chore(release): publish * feat: add docs * docs: improve docs * docs: fix * docs: fix redundancy docs * docs: fix remove scripts package.json * docs: ice-design * docs: fix several documentations * docs: update QA * docs: about and form * docs: add git * docs: api-commnuicate * docs: fix iceworks description * docs: remove unneed doc * docs: problems for review * docs: remove node-jieba
mopsky · Feb 28, 2018 · f48340a · f48340a
1 parent 116a856
commit f48340a
Show file tree

Hide file tree

Showing 20 changed files with 1,785 additions and 14 deletions.
diff --git a/.prettierignore b/.prettierignore
@@ -0,0 +1 @@
+package.json
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,33 @@
+> 在修改文档之前，请先阅读此文章
+
+### 目录结构
+
+```
+- foo.md      文档内容, 可以有文件夹嵌套
+- yoo.md
+```
+
+### 文档结构
+
+```markdown
+---
+title: 文档标题(必须有)
+order: 可选, 文档顺序, 数字越小越在前面, 否则按照字母序
+hide: 可选, 布尔值, 是否隐藏文档
+category: 可选, 字符串, 一级分类
+cover: 可选, 建议有, 封面图
+---
+
+markdown 格式的文档内容
+```
+
+### 词汇表述
+
+请注意大小写和复数形式
+
+* `ICE`: 品牌名, 中文称之为 `飞冰`
+* `Iceworks`: 配套 GUI 软件
+* `物料 - marterial`: 包含区块, 布局, 模板和组件
+* `区块 - block`: 复用的最小代码片段
+* `布局 - layout`: 为 ICE 提供整体布局方案的代码
+* `模板 - scaffold`: 整站示例, 脚手架
diff --git a/docs/about.md b/docs/about.md
@@ -0,0 +1,40 @@
+---
+title: 关于 ICE
+order: 1
+cover: https://gw.alicdn.com/tfs/TB1vBRYaVOWBuNjy0FiXXXFxVXa-2558-1306.jpg
+---
+
+## 目标和愿景
+
+ICE 是一套基于 React 的中后台应用解决方案，在阿里巴巴内部，已经有 270 多个来自几乎所有 BU 的项目在使用。经过 2 年的发展，ICE 已经是中后台 2.0 体系，这个阶段中我们的目标是赋能企业、组织搭建自己的中后台体系。ICE 包含了一条从设计端到开发端的完整链路，帮助我们的用户快速搭建属于自己的中后台应用。
+
+我们希望中后台应用的开发能变得更高效。面向**设计者**端，我们提供了 ICE Design 设计语言，来给我们的 UI 界面提供专业的视觉指导。面向**开发者**端，我们提供了 Iceworks 工具，这是一个图形化界面的开发平台，它承载了 ICE 的物料体系和开发体验，获取更多信息您可以立即[点击这里](#/iceworks)下载体验。同时，我们还提供了独有的**服务体系**，在物料与工具这一基础之上进行服务的配套。我们将构建一个面向开发者的服务体系。针对每一个使用 ICE 体系的企业或个人，我们会安排专人客服进行一对一的对接，一旦有问题可以随时找到我们，第一时间帮助解决问题。
+
+## 初心
+
+在整个阿里体系内，面向卖家、运营小二以及达人有数不尽的后台，并且这些后台一直在持续不断的增长着，但是随着时间的推移，这些项目或多或少的存在着以下这些问题：
+
+* 每个后台相互独立，同类功能也需要重复开发，前期开发成本较高
+* 技术方案差异大，人员变动后维护成本非常高
+* 视觉质量参差不齐，使用效率大打折扣
+* ...
+
+ICE 就是为了解决这些问题而诞生。ICE 由淘宝前端团队发起，与淘宝 UED 及后端开发同学共同打造，旨在「提高中后台系统的开发效率」。
+
+## 物料体系
+
+在 ICE 中，组件、区块、布局、模板等统称为物料，由 ICE 团队维护，在内部有一套完整的开发规范和工具，目前也正在逐步对外开放中；基于此，你可以参与共建 ICE，也可以自建私有的物料体系。
+
+* 组件：最基础的物料，目前 ICE 的基础组件达到 55+，具有高度可复用性。
+
+* 区块：通过对大量的中后台系统常用的场景进行分类、对比和抽象，基于基础组件组合而成，目前 ICE 的区块达到 110+，可以通过 iceworks 进行快速组合搭建应用，减少重复的开发，提升效率。
+
+* 布局：在中后台系统中布局通常较为统一，以 `顶部-侧边布局-通栏` 模式为主，为此我们提供了 4+ 常见的布局，支持 `light` 和 `dark` 两套主题。
+
+* 模板：基于已有的区块搭建而成，目前提供了 4+ 的特定领域的模板，可以从零开始搭建应用，也可以选择特定类型的模板开始使用。
+
+## 联系我们
+
+* 邮件：<mailto:[email protected]>
+* 反馈/建议：<https://github.com/alibaba/ice/issues/new>
+* 答疑钉钉群：<img src="https://gw.alicdn.com/tfs/TB1iLI8kxPI8KJjSspoXXX6MFXa-1242-1602.jpg" width="300" />
diff --git a/docs/advanced/how-to-make-form.md b/docs/advanced/how-to-make-form.md
@@ -0,0 +1,223 @@
+---
+title: 如何制作表单
+order: 4
+category: 进阶指南
+---
+
+在中后台前端应用中，表单是一个非常常见的需求，用于填写一些信息、校验、编辑、提交等。本文档专门介绍如何使用 ICE 快速实现常见的后台表单类需求。
+
+为了简化使用，提高开发效率，我们推荐使用 ICE 表单粘合剂组件 `@icedesign/form-binder` 配合 ICE 提供的一系列表单类组件(如 Input, Select 等) 的组合来进行开发。
+
+在这里我们准备了非常常见的业务场景作为演示，**模态框 + 表格 + 表单** 组合的业务场景。
+
+![](https://img.alicdn.com/tps/TB1GZQhNFXXXXatXpXXXXXXXXXX-1420-506.png)
+
+在各个表单组件包裹 `FormBinder` 组件，并声明对应的 `name` `FormBinder` 会自动与这些组件的数据进行关联，之后我们就要利用 `FormBinder` 自带的功能进行获取、校验、回填处理。
+
+## 回填数据
+
+在使用 `FormBinder` 组件后，我们不需要为单独的表单组件（如 Input，Radio 等）进行 value 值的回填。我们可以在 `FormBinderWrapper` 上用 `value` 统一进行回填，使用对象的形式，其中键值会自动与 `FormBinder` 上的 `name` 进行关联，就像 HTML5 标准表单一样：
+
+```jsx
+import {
+  FormBinderWrapper,
+  FormBinder,
+  FormError,
+} from '@icedesign/form-binder';
+
+<FormBinderWrapper
+  value={{
+    id: '1'
+    name: '卓凌',
+    age: 20,
+    sex: 'male'
+  }}
+  // 声明 ref 以获得表单组件的引用
+  ref="formInstance"
+>
+  <div>
+    <FormBinder name="id">
+      <Input htmlType="hidden" />
+    </FormBinder>
+    <FormBinder name="name">
+      <Input label="姓名：" />
+    </FormBinder>
+    <FormBinder name="age">
+      <NumberPicker label="年龄：" />
+    </FormBinder>
+    <FormBinder name="sex">
+      <RadioGroup label="性别：">
+        <Radio value="male">男</Radio>
+        <Radio value="female">女</Radio>
+      </RadioGroup>
+    </FormBinder>
+    <FormBinder name="hobby">
+      <CheckboxGroup label="爱好：" dataSource={hobbies} />
+    </FormBinder>
+  </div>
+</FormBinderWrapper>
+```
+
+由于 Form 此时是一个受控组件，清空数据等操作可以对 `value` 赋空值进行：
+
+```jsx
+class Demo extends Component {
+  state = {
+    formValue: {
+      id: '1'
+      name: '卓凌',
+      age: 20,
+      sex: 'male'
+    }
+  };
+
+  clearForm = () => {
+    this.setState({
+      formValue: {}
+    });
+  };
+
+  render() {
+    return (
+      <FormBinderWrapper
+        value={this.state.formValue}
+        // 声明 ref 以获得表单组件的引用
+        ref="formInstance"
+      >
+        <div>
+          <FormBinder name="id">
+            <Input htmlType="hidden" />
+          </FormBinder>
+          <FormBinder name="name">
+            <Input label="姓名：" />
+          </FormBinder>
+          <FormBinder name="age">
+            <NumberPicker label="年龄：" />
+          </FormBinder>
+          <FormBinder name="sex">
+            <RadioGroup label="性别：">
+              <Radio value="male">男</Radio>
+              <Radio value="female">女</Radio>
+            </RadioGroup>
+          </FormBinder>
+          <FormBinder name="hobby">
+            <CheckboxGroup label="爱好：" dataSource={hobbies} />
+          </FormBinder>
+          <Button onClick={this.clearForm}>清空表单值</Button>
+        </div>
+      </FormBinderWrapper>
+    );
+  }
+}
+```
+
+## 主动触发校验
+
+如果想要主动校验全部表单，则需要在 FormBinderWrapper 组件上面添加 ref，在合适的地方调用实现，全部校验发现报错表单会自动跳转到对应表单。
+
+```jsx
+import {
+  FormBinderWrapper,
+  FormBinder,
+  FormError,
+} from '@icedesign/form-binder';
+
+validateForm = () => {
+  this.form.validateAll((errors, values) => {
+    console.log('errors', errors, 'values', values);
+  });
+};
+
+<FormBinderWrapper
+  ref={(ref) => { this.form = ref; }}
+  value={value}
+  onChange={this.formChange}
+>
+  ...
+</FormBinderWrapper>
+<Button onClick={this.validateForm}>校验</Button>
+```
+
+### 校验规则的类型陷阱
+
+在前端开发中，有一些类型陷阱是需要开发者特别注意的。用户输入的 `Input` 等，它的类型默认都是字符串 `String`，当然你可以回填一个 `Number` 类型的数据给 `Input`，但是在取值的时候它会被转换成字符串。
+
+```jsx
+<FormBinder name="id">
+  <Input >
+</FormBinder>
+```
+
+## 总结
+
+至此，已经讲解完了如何使用 `FormBinder` 组件并进行相关操作，以及可能遇到的问题。简单的回顾：
+
+1. 首先使用 `FormBinderWrapper` 包裹所有表单项。
+2. 在 `FormBinder` 组件上使用 `name` 进行数据关联，配置校验规则。
+3. 使用 `FormBinderWrapper` 的 `value` 属性进行数据回填。
+4. 使用 ref 上的 `valildateAll` 方法校验当前表单数据并进行后续操作。
+
+## FAQ
+
+### Q：表单作为一个子组件的时候，我怎么把需要回填的值传递下去并回填？
+
+React 组件有一个生命周期 componentWillReceiveProps 是在当前组件 props 变动的时候触发，此时可以在这个生命周期方法中传递 value：
+
+```jsx
+class Demo extends React.Component {
+
+  ...
+
+  state = {
+    formValue: {}
+  };
+
+  componentWillReceiveProps(nextProps) {
+    // nextProps 是上层传下来需要回填的数据
+    if(nextProps.name) {
+      const { formValue } = this.state;
+      this.setState({
+        formValue: {
+          ...formValue,
+          name
+        }
+      });
+    }
+  }
+
+  render() {
+    return (
+      ...
+    );
+
+  }
+}
+```
+
+### Q：如何在表单组件 onChange 的时候做一些额外的事情？
+
+直接使用表单组件的 `onChange` 或者 FormBinderWrapper 的 `onChange` 即可，没有任何魔法。
+
+```jsx
+handleInputChange = (input) => {
+  console.log('Input 的值现在是', input);
+};
+// ...
+<Input onChange={this.handleInputChange} />;
+```
+
+```jsx
+handleFormChange = (value, changedByName) => {
+  const changedValue = value[changedByName];
+  console.log('由于' + changedByName + '变成了' + changedValue);
+  console.log('表单的值现在是', value);
+};
+// ...
+<FormBinderWrapper onChange={this.handleFormChange}>
+  <div>
+    <FormBinder name="foo">
+      <Input placeholder="bar" />
+    </FormBinder>
+  </div>
+</FormBinderWrapper>;
+```
diff --git a/docs/advanced/version-rules.md b/docs/advanced/version-rules.md
@@ -0,0 +1,89 @@
+---
+title: 组件版本号规则说明
+order: 2
+category: 进阶指南
+---
+
+## 版本号规则
+
+组件的版本以 `major.minor.patch` 形式表示 `主版本号.次版本号.修订号` 比如： `0.1.0` `0.3.1`。
+
+版本号递增规则如下：
+
+1. 主版本号：不兼容的 API 修改，
+2. 次版本号：向下兼容的功能性新增，
+3. 修订号：向下兼容的问题修正。
+
+## 版本控制规范
+
+目前项目内用到的主要有以下两种规则：
+
+### patch 位自动升级
+
+标识符：`~`
+
+依赖版本表示为 `~0.1.0`
+
+如：
+
+```js
+{
+  "dependencies": {
+    "foo": "~2.0.0"
+  }
+}
+```
+
+当 `foo` 发布了 `2.0.30` 版本，表示做了向下兼容的问题修正（BUG fix 等）， 在开发与构建时则会安装 `2.0.30`。
+
+如果 `foo` 存在 `2.1.0` 版本，根据标识符 `~` 也不会安装此版本。
+
+#### 优点：
+
+自动更新升级项目内组件依赖版本（patch），当组件开发者发布了新版本修复存在的现有问题，可自动升级。
+
+### minor 位自动升级
+
+标识符：`^`
+
+依赖版本表示为 `^0.1.0`
+
+> 温馨提示：包含 patch 自动升级
+
+如：
+
+```js
+{
+  "dependencies": {
+    "foo": "^2.0.0"
+  }
+}
+```
+
+当 `foo` 发布了 `2.0.30` 版本，表示做了向下兼容的问题修正（BUG fix 等）， 在开发与构建时则会安装 `2.0.30`
+
+如果 `foo` 存在 `2.1.0` 版本，根据标识符 `^` 则会安装 `2.1.0`。
+
+#### 优点：
+
+自动更新升级项目内组件依赖版本（minor），当组件开发者发布了新的特性、API 等，可升级到相应的版本。同时也包含升级 （patch）的功能。
+
+### 固定版本号
+
+固定版本号则需要项目开发者维护版本依赖，无标识符。
+
+如：
+
+```js
+{
+  "dependencies": {
+    "foo": "2.0.0"
+  }
+}
+```
+
+表示只安装 `foo` `2.0.0` 版本，不会在开发与构建时安装其他版本。
+
+#### 优点：
+
+项目内的组件依赖都是固定的版本，完全保证项目代码一致性。如当组件含有 BUG 时，需开发者手动刚更新组件依赖的版本。