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/getting-started/babel-plugin-veui.md
+++ b/one/docs/getting-started/babel-plugin-veui.md
@@ -0,0 +1,78 @@
+# babel-plugin-veui
+
+:::tip
+VEUI 目前在 npm 上直接以源码方式进行发布，在使用时必须提前转译（其中的优缺点和取舍可以参考 [Henry Zhu](https://www.patreon.com/henryzhu) 在 Babel 的官方博客上发布的[这篇文章](https://babeljs.io/blog/2018/06/26/on-consuming-and-publishing-es2015+-packages)）。VEUI 的源代码依赖 Lodash 和 Vue JSX 相关的 Babel 插件才能正确转译。此外，VEUI 还提供了自己的 Babel 插件，以帮助应用书写更简单的 `import` 语句的同时最小化代码的体积。
+:::
+
+## 按需引入组件
+
+这个 Babel 插件可以让我们直接书写更简单的 `import` 语句而无需担心会将 VEUI 整体引入到项目中。
+
+该插件的主要功能就是将如下语句：
+
+```js
+import { Button, Input } from 'veui'
+```
+
+自动转成：
+
+```js
+import Button from 'veui/components/Button'
+import Input from 'veui/components/Input'
+```
+
+这样最终我们打包的代码就只会包含真正用到的组件了。功能类似 Lodash 的 [babel-plugin-lodash](https://github.com/lodash/babel-plugin-lodash) 插件。
+
+## 自动添加前缀
+
+为了避免与原生元素名冲突，我们在注册组件时需要以如下的方式为其添加前缀：
+
+```js
+export default {
+  components: {
+    'veui-button': Button,
+    'veui-input': Input
+  }
+  // ...
+}
+```
+
+由于这种方式显得有些冗长，所以 `babel-plugin-veui` 支持了如下写法：
+
+```js
+import { VeuiButton, VeuiInput } from 'veui'
+
+export default {
+  components: {
+    VeuiButton,
+    VeuiInput
+  }
+  // ...
+}
+```
+
+当引入的组件名带 `Veui` 前缀时可以自动对应到相应的模块。这样就可以直接在模板中按如下方式引用了：
+
+```html
+<veui-button>提交</veui-button>
+```
+
+除了 `veui-` 前缀外，babel-plugin-veui 还支持直接使用 `v-` 前缀：
+
+```js
+import { VButton, VInput } from 'veui'
+
+export default {
+  components: {
+    VButton,
+    VInput
+  }
+  // ...
+}
+```
+
+然后这样使用：
+
+```html
+<v-button>提交</v-button>
+```
--- a/one/docs/getting-started/focus-visible.md
+++ b/one/docs/getting-started/focus-visible.md
@@ -0,0 +1,33 @@
+# `:focus-visible`
+
+通常我们会为交互元素定义 `:focus` 状态下的样式，以增强键盘可访问性。但在使用鼠标进行点击时，多数浏览器会使 `<button>` 等元素处于 `:focus` 状态。在多个按钮并列时，这容易使人产生「按钮被选中」的错觉。[CSS Selectors Level 4 草案中的 `:focus-visible` 伪类选择器](https://drafts.csswg.org/selectors-4/#the-focusvisible-pseudo)为我们提供了选择更精确的聚焦状态的能力。
+
+Chrome 浏览器在默认状态下对 `<button>` 元素就有类似的处理。
+
+> [`:focus-visible` 详细说明](https://github.com/WICG/focus-visible/blob/master/explainer.md)
+
+## 使用
+
+VEUI 的默认主题包 `veui-theme-dls` 依赖 `:focus-visible` 的 polyfill 才能提供最好的交互效果。使用时，需要自行在项目中进行引入：
+
+```js
+import 'focus-visible'
+```
+
+严格来说 focus-visible 不能算一个真正的“polyfill”，因为在样式中我们无法直接使用 `:focus-visible` 这个伪类，而需要针对 `.focus-visible` 这个类编写样式。编写自定义样式时也需要注意这一点。
+
+### 兼容性
+
+当需要支持 IE9 时，由于 WICG 的 polyfill 不会自行引入其它 polyfill，故还需要引入 `classList` 的兼容脚本（需自行安装）：
+
+```shell
+$ npm i --save classlist-polyfill
+```
+
+```js
+import 'classlist-polyfill'
+```
+
+## 示例
+
+[[ demo src="/demo/focus-visible.vue" ]]
--- a/one/docs/getting-started/index.md
+++ b/one/docs/getting-started/index.md
@@ -0,0 +1,103 @@
+# 起步
+
+:::tip
+为了使 VEUI 在你的项目中运行，请按下述步骤完成**所有**安装及配置。
+:::
+
+## 安装
+
+使用 Vue CLI 创建项目以后，在项目根目录下运行：
+
+```sh
+npm i --save veui veui-theme-dls
+npm i --save-dev less less-loader veui-loader babel-plugin-veui babel-plugin-lodash
+```
+
+## 配置
+
+### Babel 插件
+
+将项目根目录中生成的 `babel.config.js` 修改为：
+
+```js
+module.exports = {
+  presets: [
+    '@vue/app'
+  ],
+  plugins: [
+    'veui',
+    'lodash'
+  ]
+}
+```
+
+关于 `babel-plugin-veui` 的更详细信息请移步[这里](/getting-started/babel-plugin-veui)。
+
+### webpack Loader
+
+综上，我们需要在项目根目录下的 `vue.config.js` 中进行如下配置
+
+```js
+module.exports = {
+  css: {
+    loaderOptions: {
+      less: {
+        javascriptEnabled: true
+      }
+    }
+  },
+  transpileDependencies: [
+    'veui',
+    'vue-awesome',
+    'resize-detector'
+  ],
+  chainWebpack: config => {
+    config.module
+      .rule('veui')
+      .test(/\.vue$/)
+      .pre()
+      .use('veui-loader')
+      .loader('veui-loader')
+      .tap(() => {
+        return {
+          modules: [
+            {
+              package: 'veui-theme-dls',
+              fileName: '{module}.less'
+            },
+            {
+              package: 'veui-theme-dls',
+              fileName: '{module}.js',
+              transform: false
+            }
+          ]
+        }
+      })
+  }
+}
+```
+
+想了解配置 `veui-loader` 的更多细节，请移步[这里](/getting-started/veui-loader)。
+
+++为什么要配置这些选项？
+
+VEUI 采取了样式主题与组件代码分离的开发、发布方式。组件代码对样式代码没有显式的依赖，故以源码方式引入时，需要使用 `veui-loader` 配置关联的主题包。
+
+如需使用默认的样式包 `veui-theme-dls`，我们还需要确保在 webpack 配置中引入 `veui-loader`。同时由于 Less 3+ 不再默认开启内联 JavaScript 解析，而 `veui-theme-dls` 依赖了这一功能，所以我们需要手动开启配置项。
+
+另外，由于我们采用将 VEUI 及其依赖与项目一起打包的策略，需要手动指定相关的依赖包进行转译。
+++
+
+
+### 全局样式
+
+在使用 `veui-theme-dls` 时，需要先全局引入基础样式以及，包括样式的 normalize 及一些基本元素的样式。
+
+除此之外还需自行引入 `:focus-visible` polyfill 以更好地处理焦点交互样式（[为什么？](./getting-started/focus-visible)）。
+
+从 JavaScript 引入：
+
+```js
+import 'veui-theme-dls/common.less'
+import 'focus-visible'
+```
--- a/one/docs/getting-started/style-variants.md
+++ b/one/docs/getting-started/style-variants.md
@@ -0,0 +1,35 @@
+# 预设样式
+
+VEUI 组件通过 `ui` 属性为组件提供预设样式。不同主题包可以为每个组件提供不同的 `ui` 值进行扩展，用户也可以自定义 `ui` 值及其样式来给 VEUI 组件扩展预设样式。
+
+### `ui` 属性
+
+`ui` 属性是一个空格分隔的字符串，类似 HTML 原生的 `class` 属性。其中每一项都代表组件的一种预设样式，像下面的例子中，`primary` 和 `large` 都定义了 `<veui-button>` 组件的某个预设样式：
+
+```html
+<veui-button ui="primary large">OK</veui-button>
+```
+
+:::tip
+我们知道，许多组件库通常通过一些组件的枚举属性（prop）来提供预定义的样式，常见的比如 `shape`/`size`/`type` 等。
+
+但根据我们设计的初衷，VEUI 应该尽量不绑定到特定的设计语言上（虽然组件生成的结构要完全和设计语言解耦是不太可能的）。如果采用预定义枚举属性的方式时需要新增一套主题，但在这套主题中某些有额外可选的样式没有在 VEUI 的组件上预留出枚举属性，就只能使用 `class` 来实现无感知地添加样式钩子了。
+
+这时又会遇到 `class` 命名、前缀等一系列问题，所以我们干脆提供一个自定义属性 `ui` 并且输出到组件的 DOM 元素上，来实现语义更清晰、与组件逻辑解耦的预设样式。
+:::
+
+### 使用 DLS 主题
+
+使用 [`veui-loader`](./veui-loader) 的相应配置，即可在 VEUI 中加载 `veui-theme-dls` 主题包。主题包为很多组件提供了不同维度的可选预设样式，可以参考每个组件对 `ui` 属性的说明来查阅组件支持的预设样式。
+
+### 自定预设样式
+
+新增自定义的 `ui` 项无需通过组件接口进行注册，只需要在样式文件中针对 `[ui~="..."]` 选择器添加相应样式即可。
+
+比如：要为 `Button` 组件新增一个 `secondary` 的样式，只需为 `.veui-button[ui~="secondary"]` 编写样式就可以实现。
+
+[[ demo src="/demo/ui.vue" ]]
+
+### 自定义主题包
+
+关于自定义主题包的开发，可以参考[高级 › 主题](../advanced/theming)来了解更多 VEUI 对主题包的约定接口以及更多自定义 `ui` 属性的高级方法。
--- a/one/docs/getting-started/veui-loader.md
+++ b/one/docs/getting-started/veui-loader.md
@@ -0,0 +1,64 @@
+# veui-loader
+
+这个 webpack loader 帮助我们自动在构建时按组件自动自动注入主题、语言包等依赖的模块。
+
+你可以在 loader 选项中，给每个 VEUI 组件配置对应需要加载的样式、JS 模块。
+
+```js
+modules: [
+  {
+    package: 'veui-theme-dls',
+    fileName: '{module}.less'
+  },
+  {
+    package: 'veui-theme-dls',
+    fileName: '{module}.js',
+    transform: false
+  }
+]
+```
+
+上面的配置表明我们为每个组件额外引入两个模块。比如对于 `Button.vue`，会额外引入 `veui-theme-dls/components/button.less` 和 `veui-theme-dls/components/Button.js` 这两个模块的代码。
+
+## 为何不用 Babel 插件？
+
+我们知道，在 Ant Design 和 Element 等组件库中，都是用 Babel 插件（[babel-plugin-import](https://github.com/ant-design/babel-plugin-import)/[babel-plugin-component](https://github.com/ElementUI/babel-plugin-component)）来完成主题样式的依赖注入，但是 VEUI 使用 webpack loader 的原因有两点：
+
+1. 由于 Babel 对 webpack 的 resolve 逻辑并不感知，所以无法准确判断某个路径经过 webpack 解析后对应的模块是否真实存在，需要对主题包的路径有强约束。而 `veui-loader` 会自动检查每个路径在 webpack 解析完毕后对应的模块是否存在，不会发生引入不存在的模块产生错误的情况。
+2. Vue 在 SSR 自动抽取 critical CSS 时，无法将 JS 代码中引入的样式注入组件，而 `veui-loader` 通过预处理 `.vue` 单文件组件的方式进行依赖注入，可以解决这个问题。
+
+## 选项
+
+* `modules`
+
+  类型：`Array<{package, path, fileName, transform}>`
+
+  包含每个组件需要额外加载的对应模块信息，是一个数组，每个数组项都表示对于每个组件文件要额外引入的模块。
+
+  每个模块项字段如下：
+
+  | 字段 | 类型 | 默认值 | 描述 |
+  | -- | -- | -- | -- |
+  | `package` | `string` | - | 需要额外加载模块所属包的名字。一般来说会是主题包的包名，如 `'veui-theme-dls'`。 |
+  | `path` | `string` | `'components'` | 需要加载的模块在对应包内的目录名。 |
+  | `fileName` | `string` | `'{module}.css'` | 组件对应模块的文件名模板，必须包含占位符 `{module}`。 |
+  | `transform` | `string|boolean` | `'kebab-case'` | 组件名的转换规则。转换完毕后将替换 `fileName` 中的 `{module}` 占位符。如果值为 `false` 则不进行转换。可选的转换规则有 `'kebab-case'`、`'camleCase'` 与 `'PascalCase'` 三种。 |
+
+* `locale`
+
+  类型：`boolean|string=|Array<string>=`
+
+  需要注入的语言包标识。当传入 `Array` 类型值时，将自动引入多个语言包。默认值为 `zh-Hans`。目前支持的值有 `zh-Hans` 与 `en-US`。
+
+  如果不需要自动加载语言包，可以传入 `false` 以显式禁止，此时用户需要手动注册语言包。
+
+
+* `global`
+
+  类型：`Array<string>=`
+
+  需要在所有组件中引入的模块。数组项为需要引入的模块的完整路径。
+
+  :::warning
+  请注意，请不要通过 `global` 选项注入样式代码，这将会使样式代码在每个组件中重复输出。
+  :::