taolin/docs_vue2
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

feat: publicize doc implemetation

Browse Source
This commit is contained in:
Justineo
2020-08-13 11:47:56 +08:00
parent 55b9b044f2
commit 1e5fcff6ad
372 changed files with 50636 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
one/docs/en-US/getting-started/babel-plugin-veui.md Normal file
View File

@@ -0,0 +1,78 @@
# babel-plugin-veui
:::tip
Currently VEUI is published on npm in the form of source code and has to be transpiled before use. (Read more about the trade-off of publishing source code in [this post](https://babeljs.io/blog/2018/06/26/on-consuming-and-publishing-es2015+-packages) published by [Henry Zhu](https://www.patreon.com/henryzhu) on Babel's blog.) Babel plugins for Lodash and Vue JSX are required to transpile VEUI and VEUI provides its own Babel plugin to offer minimized code size while simply `import`ing components.
:::
## Cherrypicking components
This Babel plugin allows you to write simple `import` statements without importing VEUI as a whole.
With this plugin, the following statement:
```js
import { Button, Input } from 'veui'
```
will be automatically transformed into:
```js
import Button from 'veui/components/Button'
import Input from 'veui/components/Input'
```
So only the components that are actually imported will appear in the final bundle. It works similarly with Lodash's [babel-plugin-lodash](https://github.com/lodash/babel-plugin-lodash).
## Automatic prefixing
To avoid conflict with native HTML elements, it's recommended to prefix components when they are registered as follows:
```js
export default {
components: {
'veui-button': Button,
'veui-input': Input
}
// ...
}
```
It's kind of verbose so `babel-plugin-veui` helps to support the following usage:
```js
import { VeuiButton, VeuiInput } from 'veui'
export default {
components: {
VeuiButton,
VeuiInput
}
// ...
}
```
When the imported component is prefixed with `Veui` the plugin will find the corresponding component without the prefix. Now it's possible to use components inside templates as follows:
```html
<veui-button>Submit</veui-button>
```
Apart from the prefix `veui-`, `babel-plugin-veui` also supports using `v-` as a prefix:
```js
import { VButton, VInput } from 'veui'
export default {
components: {
VButton,
VInput
}
// ...
}
```
And use as follows:
```html
<v-button>Submit</v-button>
```

33
one/docs/en-US/getting-started/focus-visible.md Normal file
View File

@@ -0,0 +1,33 @@
# `:focus-visible`
Usually we provide `:focus` styles for interactive elements to enhance (keyboard) accessibility. But when we click around with mouses, most browsers will activate `:focus` state of elements like `<button>`. This will easily cause misunderstanding that the button is “selected” especially when different types of buttons are placed together. [The draft of CSS Selector Level 4 provided a `:focus-visible` pseudo class selector](https://drafts.csswg.org/selectors-4/#the-focusvisible-pseudo) to help us targeting focused elements more accurately.
Actually Chrome is handling native `<button>`s in a similar way by default.
> [Details on `:focus-visible`](https://github.com/WICG/focus-visible/blob/master/explainer.md)
## Usage
VEUI's default style package `veui-theme-dls` uses a polyfill library for `:focus-visible` to provide optimized interactive experience. You need to import it yourself in your application code:
```js
import 'focus-visible'
```
Technically focus-visible isn't really a “polyfill” because we have to use the `.focus-visible` selector instead of directly using `:focus-visible`. This should also be noted when customizing styles.
### Browser compatibility
As the polyfill provided by WICG won't automatically import other polyfills, you need to import polyfill for `classList` when you need to support IE9 (requires to be installed by yourself as well).
```shell
$ npm i --save classlist-polyfill
```
```js
import 'classlist-polyfill'
```
## Demo
[[ demo src="/demo/focus-visible.vue" ]]

101
one/docs/en-US/getting-started/index.md Normal file
View File

@@ -0,0 +1,101 @@
# Getting started
:::tip
To make VEUI works in your project, please install and configure according to **all** of the following steps.
:::
## Installation
After scaffolding the project with Vue CLI, run the following under the its root directory:
```sh
npm i --save veui veui-theme-dls
npm i --save-dev less less-loader veui-loader babel-plugin-veui babel-plugin-lodash
```
## Configuration
### Babel plugin
You need to configure the auto-generated `babel.config.js` as follows:
```js
module.exports = {
presets: [
'@vue/app'
],
plugins: [
'veui',
'lodash'
]
}
```
Read more about `babel-plugin-veui` [here](/getting-started/babel-plugin-veui).
### webpack Loader
In general, you need to configure `vue.config.js` in the root directory as follows:
```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
}
]
}
})
}
}
```
To learn more details of configuring `veui-loader`, read its documentation [here](/getting-started/veui-loader).
+++Why all these configs?
VEUI's style code is separate from its components. The component code doesn't explicitly depend on style code so `veui-loader` is needed to specify and inject style package into the components.
If you want to use `veui-theme-dls`, the default style package, you need import and configure `veui-loader` for webpack. As Less 3+ no longer enable JavaScript evaluation by default, which `veui-theme-dls` relies on, you need to manually enable this option.
We intend to transpile and build VEUI and its dependencies along with the application code itself so you need to add the related packages into the transpilation process.
+++
### Global stylesheet
When using `veui-theme-dls`, you need to import the base stylesheet, which includes style normalization.
You also need to import `:focus-visible` polyfill for better focus style to work properly ([Why?](./getting-started/focus-visible)).
Import from JavaScript:
```js
import 'veui-theme-dls/common.less'
import 'focus-visible'
```

35
one/docs/en-US/getting-started/style-variants.md Normal file
View File

@@ -0,0 +1,35 @@
# Style variants
VEUI provide style variants via the `ui` prop. Theme packages can provide different `ui` value for each component and users can also use custom `ui` values to create extended style variants.
### The `ui` prop
The `ui` prop takes a string consists of a list of whitespace-separated tokens, similar to HTML's native `class` attribute. Each token stands for a style variant of a component. In the following example, `primary` and `large` are both style variants of component `<veui-button>`:
```html
<veui-button ui="primary large">OK</veui-button>
```
:::tip
As we know, most component libraries provide style variants via enum props like `shape`/`size`/`type`/... .
While our design goal is that VEUI should not be bound to a specific design language tightly (though it's hard to completely decouple component structure/behavior and design languages). If we use enum props, once we need to create a completely new theme package but some of the new style variants cannot be described with the preserved enum props, we'll have to use something like `class` to attach style hooks to implement these style variants.
Using `class` will lead to problems of naming conventions, prefixes, etc. So we decided to directly output a custom attribute `ui` to component's DOM nodes for more semantic style variants and minimize the coupling with component logic.
:::
### Use the DLS theme
You can enable `veui-theme-dls` by setting the corresponding options for [`veui-loader`](./veui-loader). The theme package provides style variants for most components. You can refer to documentation for the `ui` prop in each component to learn about the supported style variants.
### Custom style variants
You don't need to register via component API to define custom `ui` tokens. Just adding style declarations for the corresponding `[ui~="..."]` selector would be sufficient.
eg. If you want a new `secondary` variant for `Button` component, just add styles to `.veui-button[ui~"secondary"]`:
[[ demo src="/demo/ui.vue" ]]
### Custom theme package
If you want to create a custom theme package, please read more about VEUI's theming API more the advanced ways of customizing `ui` prop at [Advanced › Theming](../advanced/theming).

64
one/docs/en-US/getting-started/veui-loader.md Normal file
View File

@@ -0,0 +1,64 @@
# veui-loader
This webpack loader is used to inject theme/locale modules for used components only at build time.
You can specify style/script module you want to inject into each VEUI component in loader options:
```js
modules: [
{
package: 'veui-theme-dls',
fileName: '{module}.less'
},
{
package: 'veui-theme-dls',
fileName: '{module}.js',
transform: false
}
]
```
Options above result in importing two extra modules for each component. eg. For `Button.vue`, `veui-theme-dls/components/button.less` and `veui-theme-dls/components/Button.js` will be injected.
## Why not use a Babel plugin?
As we know, in popular component libraries like Ant Design and Element, theme packages are injected with Babel plugins ([babel-plugin-import](https://github.com/ant-design/babel-plugin-import)/[babel-plugin-component](https://github.com/ElementUI/babel-plugin-component)). VEUI is using webpack loader for the following reasons:
1. webpack's resolving logic is transparent to Babel so we cannot accurately guarantee the module exists at the path resolved by webpack, so it's hard to specify arbitrary location of the theme package. veui-loader, on the other hand, can accurately check the existence of each generated path after resolved by webpack.
2. Vue Loader cannot handle styles imported from script blocks while extracting component-level critical CSS, while `veui-loader` solved the issue by preprocessing `.vue` files and inject style blocks instead of injecting import statements into script block.
## Options
* `modules`
Type: `Array<{package, path, fileName, transform}>`
The configuration of all extra modules to be injected into each component.
Properties of each module:
| Property | Type | Default | Description |
| -- | -- | -- | -- |
| `package` | `string` | - | The name of the injected package. It's generally the name of the theme package, like `'veui-theme-dls'`. |
| `path` | `string` | `'components'` | The path of the directory containing the injected module. |
| `fileName` | `string` | `'{module}.css'` | The file name template corresponds to the component name. Must include the placeholder `{module}`. |
| `transform` | `string|boolean` | `'kebab-case'` | Transformation applied for component names. The `{module}` part within `fileName` will be replaced with the transformed name. Provide `false` to prevent transformation. All possible values are `'kebab-case'`, `'camleCase'` and `'PascalCase'`. |
* `locale`
Type: `boolean|string=|Array<string>=`
The ID of the locale modules to be injected. Array values indicate to inject multiple locale packages. Defaults to `zh-Hans`. Current available values are `zh-Hans` and `en-US`.
Provide `false` to explicitly prevent automatically injecting locale package. You need to import locale packages manually.
* `global`
Type: `Array<string>=`
The array of module paths to be injected int every component.
:::warning
Do not inject style modules via the `global` option. This will repeatedly output the same style code for every component.
:::