feat: publicize doc implemetation

2020-08-13 11:47:56 +08:00
parent 55b9b044f2
commit 1e5fcff6ad
372 changed files with 50636 additions and 0 deletions
--- a/one/docs/advanced/custom-rules.md
+++ b/one/docs/advanced/custom-rules.md
@@ -0,0 +1,89 @@
+# 自定义校验规则
+
+对于多值校验，[表单 › validators 属性](../components/form#属性)提供了比较完善的功能来实现自定义校验。对于单值校验，`Field` 组件内置了 7 种常见规则，具体参考[表单项 › rule 属性](../components/field#属性)。如果无法覆盖需求，`VEUI` 校验规则模块允许你添加自定义规则。
+
+## 示例
+
+```js
+import ruleManager from 'veui/manager/rule'
+ruleManager.addRule('range', {
+  validate (value, ruleValue) {
+    // 仅实现大小校验部分
+    let range = value.split('-')
+    return +range[0] >= ruleValue.floor && +range[1] <= ruleValue.ceil
+  },
+  message: '范围值必须在限定区间内',
+  priority: 100
+})
+```
+
+```html
+<veui-field
+  :rules=[{
+    triggers: 'change'
+    name: 'range',
+    value: {
+      ceil: 100,
+      floor: 50
+    }
+  }]
+  ...
+>...</veui-field>
+```
+
+## API
+
+| 名称 | 类型 | 描述 |
+| -- | -- | -- |
+| `validate` | `function(value: *, ruleValue: ?*=)` | 校验逻辑，`value` 为 `Field` 需要校验的值，`ruleValue` 可选，根据规则需要添加，表示规则的限定值。 |
+| `message` | `function|string` | [^message] |
+| `priority` | `number` | [^priority] |
+
+^^^message
+默认出错信息。
+
+若类型为 `string`，可以通过 `{ruleValue}` 引用 `ruleValue`、`{value}` 引用 `value`。例如：
+
+```js
+let minLengthRule = {
+  validate (value, ruleValue) {
+    return !isEmpty(value) ? val.length >= ruleValue : true
+  },
+  message: '字符长度不能短于 {ruleValue}，当前长度 {value}',
+  priority: 100
+}
+```
+
+若类型为 `function`，参数为 `(ruleValue: ?*=, value: *)`。例如：
+
+```js
+let minLengthRule = {
+  validate (value, ruleValue) {
+    return !isEmpty(value) ? val.length >= ruleValue : true
+  },
+  message (ruleValue, value) {
+    return `字符长度不能短于${ruleValue}，当前长度${value}`
+  },
+  priority: 100
+}
+```
+
+:::tip
+如果需要支持运行时切换语言，`message` 必须使用 `function` 类型。
+:::
+^^^
+
+^^^priority
+规则优先级。数值低优先级高。
+
+++目前内置的优先级
+| 名称 | 优先级 |
+| -- | -- | -- |
+| `required` | `0` |
+| `numeric` | `10` |
+| `pattern` | `50` |
+| `maxLength` | `100` |
+| `minLength` | `100` |
+| `max` | `200` |
+| `min` | `200` |
+++
--- a/one/docs/advanced/global-config.md
+++ b/one/docs/advanced/global-config.md
@@ -0,0 +1,61 @@
+# 全局配置
+
+VEUI 中很多组件都定义了全局配置项，允许开发者在使用时全局配置某个组件的行为细节。
+
+例如，`Uploader` 组件可以统一配置上传模式，用户可以根据项目前后端接口、需要支持浏览器版本的具体情况选择使用 iframe 回调方式还是 XHR2 方式传递数据，也可以统一配置远端数据格式的转换函数。
+
+VEUI 全局配置项可以通过 `veui/managers/config` 模块进行覆盖：
+
+```js
+import config from 'veui/managers/config'
+
+config.set('uploader.requestMode', 'iframe')
+config.set('uploader.convertResponse', ({ code, error, result }) => {
+  /**
+   * Transform from
+   *
+   * {
+   *   code: 0,
+   *   error: '...',
+   *   result: {
+   *     url: '...'
+   *   }
+   * }
+   *
+   * to
+   *
+   * {
+   *   success: true,
+   *   message: '...',
+   *   src: '...'
+   * }
+   */
+  return {
+    success: code === 0,
+    src: error ? null : result.url,
+    message: error || null
+  }
+})
+```
+
+如果需要一次修改同一个组件的多项设置，可以使用如下写法：
+
+```js
+import config from 'veui/managers/config'
+
+config.set({
+  requestMode: 'iframe',
+  convertResponse: data => data
+}, 'uploader')
+```
+
+`config.set()` 方法参数可为如下形式：
+
+* `(key: string, value: *, namespace: string)`
+* `(values: Object<{key: string, value: *}>, namespace: string)`
+
+当提供了 `namespace` 参数时，最终生成的配置项键名为 <code>\`${namespace}.${key}\`</code>。
+
+除此以外，还提供了相同参数列表的 `config.defaults()` 方法，区别在于当需要在配置项中写入的键值已经存在，则不会覆盖。
+
+每个组件、指令等支持的全局配置请查看对应组件、指令的详情页。
--- a/one/docs/advanced/overlay.md
+++ b/one/docs/advanced/overlay.md
@@ -0,0 +1,124 @@
+# 浮层管理
+
+在 VEUI 中，有大量组件使用到了浮层功能：
+
+* 各种类型的弹框：[对话框](../components/dialog)、[警告弹框](../components/alert-box)等；
+* [下拉选择](../components/select)；
+* ……
+
+针对这些组件，我们抽离了具备如下功能的浮层模块：
+
+* 能够浮于页面上所有普通元素之上；
+* 能够进行层叠顺序管理；
+* 能够基于指定元素定位。
+
+## 层叠覆盖
+
+为了避免浮层被上层 `overflow: hidden` 的元素意外遮盖，我们将浮层根元素直接置于 `<body>` 下统一管理。
+
+在[浮层组件](../components/overlay)中，`.veui-overlay-box` 对应了浮层根元素，该元素在组件初始化的时候，会被放置到 `<body>` 之下，组件销毁的时候，会被移除掉。
+
+## 层叠顺序管理
+
+在将浮层根元素置于 `<body>` 下后，原有的层级嵌套关系会丢失，同时也无法通过原生的层叠上下文机制来控制浮层的层叠顺序。比如：
+
+* 某个对话框组件 A 上有一个下拉选择组件 B，那么 B 组件浮层应该位于 A 组件浮层之上。
+* 警告框浮层应该位于普通对话框浮层之上。
+
+基于上述限制，浮层模块实现了自己的层叠顺序管理机制。整个浮层层级嵌套关系，是通过一棵树来表达的：
+
+<img class="preview hero" src="/images/development/advanced/overlay-tree.png">
+
+树中每一个蓝色节点都对应关联到具体的[浮层组件](../componets/overlay)实例。针对上图，树的构造顺序可以是：
+
+1. 弹出“对话框 1”，创建一个“对话框 1”节点，根据节点权重信息创建一个分组，然后将分组挂在 root 节点之下。
+2. 弹出“对话框 2”，创建一个“对话框 2”节点，发现已经存在相同权重的分组，就直接将“对话框 2”节点放置在该分组的末尾位置。
+3. 在“对话框 2”中实例化一个“下拉选择 1”组件实例，由于“对话框 2”组件实例是“下拉选择 1”组件实例的父级，因此对应的浮层节点也应当具备父子关系，因此按照类似于“步骤 1”的顺序在“对话框 2”节点下生成分组及“下拉选择 1”节点。
+4. 此时由于程序运行出现了故障，弹出了“警告弹框 1”，由于“警告弹框”类型的组件相对于“对话框”组件具备更高的层级权重，因此在 root 之下新建了一个靠右的分组，并将生成的“警告弹框 1”节点置于分组末尾。
+
+有了树之后，就会按照深度优先的遍历顺序生成每个节点的 `z-index` 值。
+
+其中，基准 `z-index` 值可以通过全局配置对象进行配置：
+
+```js
+import config from 'veui/managers/config'
+
+config.set('overlay.baseZIndex', 200)
+```
+
+:::warning
+必须在[浮层组件](../components/overlay)引入之前设置基准 `z-index`，不然不会生效。
+:::
+
+可以针对组件类型，甚至组件实例粒度设置层叠优先级，层叠优先级值越大，最终生成的 `z-index` 值就越大。具有相同层叠优先级的同级组件实例，越靠后实例化的组件，生成的 `z-index` 值越大。
+
+浮层组件、对话框组件、弹框组件等提供了 `priority` 属性，用于自定义组件实例的层叠优先级：
+
+```html
+<veui-dialog :priority="300"/>
+```
+
+一些比较特殊的组件，会提供基于组件类型粒度的层叠优先级配置：
+
+| 组件 | 配置字段 | 默认值 | 修改配置示例 |
+| -- | -- | -- | -- |
+| 警告弹框 | `alertbox.priority` | `100` | [^alert-box] |
+| 确认弹框 | `confirmbox.priority` | `100` | [^confirm-box] |
+| 输入弹框 | `promptbox.priority` | `100` | [^prompt-box] |
+
+^^^alert-box
+```js
+import config from 'veui/managers/config'
+
+config.set('alertbox.priority', 100)
+```
+^^^
+
+^^^confirm-box
+```js
+import config from 'veui/managers/config'
+
+config.set('confirmbox.priority', 100)
+```
+^^^
+
+^^^prompt-box
+```js
+import config from 'veui/managers/config'
+
+config.set('promptbox.priority', 100)
+```
+^^^
+
+总结起来，确定某个浮层系组件实例的层叠优先级的逻辑流程为：
+
+* 如果能够设置组件实例级别的层叠优先级，并且设置了，那么就使用这个层叠优先级值，否则进入下一步；
+* 如果能够设置组件类型级别的层叠优先级，并且设置了，那么就使用这个层叠优先级值，否则进入下一步；
+* 使用默认的层叠优先级值：`1`。
+
+## 定位
+
+VEUI 中，浮层支持两种定位方式：
+
+* 在页面范围内，以坐标值的形式进行定位；
+* 相对于某个元素，指定偏移和变换规则进行定位。
+
+以坐标方式定位时，需要自己写 CSS 进行控制（浮层模块内部只会生成浮层根元素的 `z-index` 值）。
+
+相对元素定位时，可以通过[浮层组件](../components/overlay)的 `options` 属性描述偏移和变换规则。由于目前内部采用 [Tether](http://tether.io/) 实现，因此完整的配置项可以参考 [Tether 官网](http://tether.io/#options)。同时，也支持一些常见场景的简化配置：<code>{ position: &#0096;${side}-${align}&#0096; }</code>，`side` 表示浮层根元素位于目标元素哪一边（`top`/`right`/`bottom`/`left`），`align` 表示对齐方式（`start`/`end`）。其中 `side` 是必须的，`align` 不传表示居中。推荐尽量使用简化的配置。
+
+## 样式
+
+由于浮层根元素被手动放置到 `<body>` 元素之下了，要设置浮层内容的样式，就需要给浮层根元素指定 `class`。所有浮层系组件都支持 `overlay-class` 属性，通过该属性为浮层根元素设置 `class`：
+
+```vue
+<template>
+  <veui-dialog overlay-class="my-dialog-overlay"/>
+<template>
+
+<style>
+.my-dialg-overlay {
+  /* 自定义浮层样式 */
+}
+</style>
+```
--- a/one/docs/advanced/theming.md
+++ b/one/docs/advanced/theming.md
@@ -0,0 +1,134 @@
+# 主题
+
+VEUI 的组件和主题包是完全解耦的。组件库中不含有任何样式代码，每个组件的样式都需要主题包中对应的样式文件来提供。
+
+为了方便在按需引入的同时不需要手动引入每个组件的样式代码，我们提供了 `veui-loader` 来完成通过配置自动将依赖的样式文件注入组件，详情请参考 `veui-loader` 的[相关介绍](../getting-started/veui-loader)。
+
+## 创建自定义主题包
+
+veui-loader 为 VEUI 注入依赖时，同时支持注入 script 类型及 style 类型的模块。所以主题包中可以为每个组件提供这两种类型的主题配置。
+
+### 自定义样式
+
+:::warning
+注意，主题包样式对 VEUI 组件的 DOM 结构会有依赖。
+:::
+
+为每个组件提供完整的样式，可以使用任何预处理语言。每个组件具体提供的类名及选择器可以参考 `veui-theme-dls` 中的实现。
+
+```less
+.veui-button {
+  /* ... */
+}
+```
+
+### 自定义图标
+
+VEUI 的 `Icon` 组件封装了 [Vue-Awesome](https://justineo.github.io/vue-awesome/demo/) 来输出内联 SVG 图标，无法直接在样式代码中指定，需要通过 script 模块进行注册。每个组件都定义了语义明确的图标接口，我们需要做的只是在全局配置中为组件注入相应的图标名称映射并引入对应的图标模块：
+
+```js
+import config from 'veui/managers/config'
+import '../icons/angle-up-small'
+import '../icons/angle-down-small'
+
+config.defaults({
+  icons: {
+    expand: 'angle-down-small',
+    collapse: 'angle-up-small'
+  }
+}, 'select')
+```
+
+除了 `veui-theme-dls` 自带的图标外，目前可以使用的图标包还有：
+
+* [`vue-awesome/icons`](https://justineo.github.io/vue-awesome/demo/)：Vue-Awesome 自带 [FontAwesome](https://fontawesome.com/) 图标包
+* [`vue-awesome-material-icons/icons`](https://justineo.github.io/vue-awesome-material-icons/demo/)：同样基于 Vue-Awesome 的 [Material Icons](https://material.io/tools/icons) 图标包
+
+### 预设样式及自定义配置
+
+VEUI 中各个组件的可切换的预设样式是通过为主题包提供可扩展的 `ui` 配置实现的。
+
+新增一个预设样式 `foo` 只需要在样式文件中添加 `[ui~="foo"]` 对应的样式并在使用组件时添加对应的 `ui="foo"` 声明即可完成：
+
+```less
+.veui-select {
+  /* ... */
+
+  &[ui~="foo"] {
+    color: #f00;
+  }
+}
+```
+
+```html
+<veui-select ui="foo">...</veui-select>
+```
+
+一个组件也可以同时应用多个预设样式：
+
+```html
+<veui-select ui="foo bar">...</veui-select>
+```
+
+但如果我们想将预设样式定义得更完善一些，比如 `foo` 与 `bar` 是组件的两种不可同时使用的预设样式怎么办呢？比如 `small` 和 `large` 样式都会自定义组件的尺寸，是互斥的，我们就需要通过在全局配置中为组件注入更详细的 `ui` 配置来实现。
+
+`ui` 字段下每个属性名都是需要声明的预设样式名称，其值的类型为：`{ values, boolean, inherit }`。
+
+字段详情：
+
+| 名称 | 类型 | 默认值 | 描述 |
+| -- | -- | -- | -- |
+| `values` | `Array<string>` | - | 预设 `ui` 属性的可选值。 |
+| `boolean` | `boolean` | `false` | 预设 `ui` 属性是否为布尔型。 |
+| `inherit` | `boolean` | `false` | 预设 `ui` 属性值是否会被子组件继承。 |
+
+以 `Select` 组件为例：
+
+```js
+import config from 'veui/managers/config'
+
+config.defaults({
+  ui: {
+    size: {
+      values: ['large', 'small', 'tiny', 'micro'],
+      inherit: true
+    },
+    style: {
+      values: ['alt']
+    }
+  }
+}, 'select')
+```
+
+在上面这个例子中，我们定义了两个 `ui` 属性：`size` 和 `style`。它们都是枚举类型，其中 `size` 值可被子组件继承。最终调用 `Select` 组件时，可以这样启用预设样式：
+
+```html
+<veui-select ui="alt small">...</veui-select>
+```
+
+当然，我们也可以完全不定义 `ui` 属性的详情，这时 VEUI 会将用户书写的 `ui` 属性原样输出，不会进行去重、同属性的属性值冲突检测、继承等特殊处理。
+
+:::warning
+由于 `ui` 属性最后会将值打平输出到 DOM 元素上，所以各个属性的值不能冲突。
+:::
+
+### 指定组件内部组件的预设样式
+
+有一些组件由多个其它组件组合而成，此时我们可能会需要全局指定内部特定部件的预设样式。比如在 `veui-theme-dls` 中，`Dialog` 中的取消按钮默认采用默认样式，而如果在其它主题中我们可能会想重置为 `link` 样式。此时可以使用全局配置修改组件的 `parts` 映射。
+
+```js
+import config from 'veui/managers/config'
+
+config.defaults({
+  parts: {
+    ok: 'primary',
+    cancel: 'link'
+  }
+}, 'select')
+```
+
+## 主题包列表
+
+* [veui-theme-dls](https://github.com/ecomfe/veui/tree/dev/packages/veui-theme-dls)：基于 DLS 的 VEUI 2.x 主题
+* [veui-theme-blue](https://github.com/ecomfe/veui-theme-blue)：基于 Theme Blue 的 VEUI 1.x 主题
+* [veui-theme-spectre](https://justineo.github.io/veui-theme-spectre/demo/)：基于 Spectre.css 的 VEUI 1.x 主题