Skip to content

Commit f9260cf

Browse files
Jinjiangyyx990803
Jinjiang
authored and
yyx990803
committed
docs(zh): update (vuejs#2016) [ci skip]
1 parent e21c49a commit f9260cf

18 files changed

+427
-55
lines changed

‎docs/.vuepress/config.js

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ module.exports = {
77
},
88
'/zh/': {
99
lang: 'zh-CN',
10-
title: 'Vue CLI',
10+
title: 'Vue CLI 3',
1111
description: '🛠️ Vue.js 开发的标准工具'
1212
},
1313
},
@@ -118,12 +118,12 @@ module.exports = {
118118
link: '/zh/config/'
119119
},
120120
{
121-
text: '开发指南',
121+
text: '插件开发指南',
122122
items: [
123-
{ text: 'Plugin Dev Guide', link: '/zh/dev-guide/plugin-dev.md' },
124-
{ text: 'UI Plugin Info', link: '/zh/dev-guide/ui-info.md' },
125-
{ text: 'UI Plugin API', link: '/zh/dev-guide/ui-api.md' },
126-
{ text: 'UI Localization', link: '/zh/dev-guide/ui-localization.md' }
123+
{ text: '插件开发指南', link: '/zh/dev-guide/plugin-dev.md' },
124+
{ text: 'UI 插件信息', link: '/zh/dev-guide/ui-info.md' },
125+
{ text: 'UI 插件 API', link: '/zh/dev-guide/ui-api.md' },
126+
{ text: 'UI 本地化', link: '/zh/dev-guide/ui-localization.md' }
127127
]
128128
},
129129
{
@@ -147,20 +147,21 @@ module.exports = {
147147
sidebar: {
148148
'/zh/guide/': [
149149
'/zh/guide/',
150+
'/zh/guide/installation',
150151
{
151-
title: 'CLI',
152+
title: '基础',
152153
collapsable: false,
153154
children: [
154-
'/zh/guide/creating-a-project',
155155
'/zh/guide/prototyping',
156-
'/zh/guide/plugins-and-presets'
156+
'/zh/guide/creating-a-project',
157+
'/zh/guide/plugins-and-presets',
158+
'/zh/guide/cli-service'
157159
]
158160
},
159161
{
160162
title: '开发',
161163
collapsable: false,
162164
children: [
163-
'/zh/guide/cli-service',
164165
'/zh/guide/browser-compatibility',
165166
'/zh/guide/html-and-static-assets',
166167
'/zh/guide/css',
@@ -173,9 +174,15 @@ module.exports = {
173174
],
174175
'/zh/dev-guide/': [
175176
'/zh/dev-guide/plugin-dev.md',
176-
'/zh/dev-guide/ui-info.md',
177-
'/zh/dev-guide/ui-api.md',
178-
'/zh/dev-guide/ui-localization.md'
177+
{
178+
title: 'UI 开发',
179+
collapsable: false,
180+
children: [
181+
'/zh/dev-guide/ui-info.md',
182+
'/zh/dev-guide/ui-api.md',
183+
'/zh/dev-guide/ui-localization.md'
184+
]
185+
}
179186
]
180187
}
181188
}

‎docs/zh/README.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ features:
1010
details: 它的插件系统可以让社区根据常见需求构建和共享可复用的解决方案。
1111
- title: 无需 Eject
1212
details: Vue CLI 完全是可配置的，无需 eject。这样你的项目就可以长期保持更新了。
13-
- title: 基于 CLI 的图形化界面
13+
- title: CLI 之上的图形化界面
1414
details: 通过配套的图形化界面创建、开发和管理你的项目。
1515
- title: 即刻创建原型
1616
details: 用单个 Vue 文件即刻实践新的灵感。
@@ -21,10 +21,18 @@ footer: MIT Licensed | Copyright © 2018-present Evan You
2121

2222
## 起步
2323

24+
安装：
25+
2426
``` bash
2527
npm install -g @vue/cli
2628
# OR
2729
yarn global add @vue/cli
30+
```
31+
32+
创建一个项目：
2833

34+
``` bash
2935
vue create my-project
36+
# OR
37+
vue ui
3038
```

‎docs/zh/config/README.md

Lines changed: 45 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ sidebar: auto
88

99
有些针对 `@vue/cli` 的全局配置，例如你惯用的包管理器和你本地保存的 preset，都保存在 home 目录下一个名叫 `.vuerc` 的 JSON 文件。你可以用编辑器直接编辑这个文件来更改已保存的选项。
1010

11+
你也可以使用 `vue config` 命令来审查或修改全局的 CLI 配置。
12+
1113
## 目标浏览器
1214

1315
请查阅指南中的[浏览器兼容性](../guide/browser-compatibility.md#browserslist)章节。
@@ -44,7 +46,7 @@ module.exports = {
4446
}
4547
```
4648

47-
这个值也可以被设置为空字符串 (`''`) 这样所有的资源都会被链接为相对路径，这样打出来的包可以用在类似 Cordova hybrid 应用的文件系统中。需要注意的生成的 CSS 文件要始终放在输出路径的根部，以确保 CSS 中的 URL 正常工作。
49+
这个值也可以被设置为空字符串 (`''`) 这样所有的资源都会被链接为相对路径，这样打出来的包可以用在类似 Cordova hybrid 应用的文件系统中。**注意：生成的 CSS 文件要始终放在输出路径的根部，以确保 CSS 中的 URL 正常工作。**
4850

4951
::: tip 提示
5052
请始终使用 `baseUrl` 而不要修改 webpack 的 `output.publicPath`。
@@ -66,7 +68,25 @@ module.exports = {
6668
- Type: `string`
6769
- Default: `''`
6870

69-
放置生成的静态资源 (js、css、img、fonts) 的目录。
71+
放置生成的静态资源 (js、css、img、fonts) 的 (相对于 `outputDir` 的) 目录。
72+
73+
::: tip 提示
74+
从生成的资源覆写 filename 或 chunkFilename 时，`assetsDir` 会被忽略。
75+
:::
76+
77+
### indexPath
78+
79+
- Type: `string`
80+
- Default: `'index.html'`
81+
82+
指定生成的 `index.html` 的输出路径 (相对于 `outputDir`)。也可以是一个绝对路径。
83+
84+
### filenameHashing
85+
86+
- Type: `boolean`
87+
- Default: `true`
88+
89+
默认情况下，生成的静态资源在它们的文件名中包含了 hash 以便更好的控制缓存。然而，这也要求 index 的 HTML 是被 Vue CLI 自动生成的。如果你无法使用 Vue CLI 生成的 index HTML，你可以通过将这个选项设为 `false` 来关闭文件名哈希。
7090

7191
### pages
7292

@@ -75,7 +95,7 @@ module.exports = {
7595

7696
在 multi-page 模式下构建应用。每个“page”应该有一个对应的 JavaScript 入口文件。其值应该是一个对象，对象的 key 是入口的名字，value 是：
7797

78-
- 一个指定了 `entry`, `template` 和 `filename` 的对象；
98+
- 一个指定了 `entry`, `template`, `filename`, `title` 和 `chunks` 的对象 (除了 `entry` 之外都是可选的)；
7999
- 或一个指定其 `entry` 的字符串。
80100

81101
``` js
@@ -87,7 +107,13 @@ module.exports = {
87107
// 模板来源
88108
template: 'public/index.html',
89109
// 在 dist/index.html 的输出
90-
filename: 'index.html'
110+
filename: 'index.html',
111+
// 当使用 title 选项时，
112+
// template 中的 title 标签需要是 <title><%= htmlWebpackPlugin.options.title %></title>
113+
title: 'Index Page',
114+
// 在这个页面中包含的块，默认情况下会包含
115+
// 提取出来的通用 chunk 和 vendor chunk。
116+
chunks: ['chunk-vendors', 'chunk-common', 'index']
91117
},
92118
// 当使用只有入口的字符串格式时，
93119
// 模板会被推导为 `public/subpage.html`
@@ -104,11 +130,13 @@ module.exports = {
104130

105131
### lintOnSave
106132

107-
- Type: `boolean`
133+
- Type: `boolean` | `error`
108134
- Default: `true`
109135

110136
是否在开发环境下通过 [eslint-loader](https://github.com/webpack-contrib/eslint-loader) 在每次保存时 lint 代码。这个值会在 [`@vue/cli-plugin-eslint`](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-eslint) 被安装之后生效。
111137

138+
设置为 `true` 时，eslint-loader 在 webpack 的编译过程中只会触发警告，以避免中断开发流程。如果你希望换做触发错误 (例如在为生成环境构建时)，可以这样设置：`lintOnSave: 'error'`。
139+
112140
### runtimeCompiler
113141

114142
- Type: `boolean`
@@ -132,6 +160,13 @@ module.exports = {
132160

133161
如果你不需要生产环境的 source map，可以将其设置为 `false` 以加速生产环境构建。
134162

163+
### corsUseCredentials
164+
165+
- Type: `boolean`
166+
- Default: `false`
167+
168+
在现代模式下，生成的 HTML 会包含 `<script type="module">`，这需要[始终开启 CORS 才能被载入](https://jakearchibald.com/2017/es-modules-in-browsers/#always-cors)。默认情况下，它被处理为 `crossorigin="anonymous"`，将这个选项设置为 `true` 后则会换用 `crossorigin="use-credentials"`。
169+
135170
### configureWebpack
136171

137172
- Type: `Object | Function`
@@ -161,15 +196,17 @@ module.exports = {
161196

162197
### css.extract
163198

164-
- Type: `boolean`
165-
- Default: `true` (in production mode)
199+
- Type: `boolean | Object`
200+
- Default: 生产环境下是 `true`，开发环境下是 `false`
166201

167202
是否将组件中的 CSS 提取至一个独立的 CSS 文件中 (而不是动态注入到 JavaScript 中的 inline 代码)。
168203

169-
同样当构建 Web Components 组件时它会默认被禁用 (样式是 inline 的并注入到了 shadowRoot 中)。
204+
同样当构建 Web Components 组件时它总是会被禁用 (样式是 inline 的并注入到了 shadowRoot 中)。
170205

171206
当作为一个库构建时，你也可以将其设置为 `false` 免得用户自己导入 CSS。
172207

208+
提取 CSS 在开发环境模式下是默认不开启的，因为它和 CSS 热重载不兼容。然而，你仍然可以将这个值显性地设置为 `true` 在所有情况下都强制提取。
209+
173210
### css.sourceMap
174211

175212
- Type: `boolean`

‎docs/zh/dev-guide/plugin-dev.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -234,6 +234,33 @@ export default {
234234
<%# END_REPLACE %>
235235
```
236236

237+
#### 文件名都极端情况
238+
239+
如果你想要渲染一个以点开头的模板文件 (例如 `.env`)，则需要遵循一个特殊的命名约定，因为以点开头的文件会在插件发布到 npm 的时候被忽略：
240+
241+
```
242+
# 以点开头的模板需要使用下划线取代那个点：
243+
244+
/generator/template/_env
245+
246+
# 调用 api.render('./template') 会在项目目录中渲染成为：
247+
248+
.env
249+
```
250+
251+
同时这也意味着当你想渲染以下划线开头的文件时，同样需要遵循一个特殊的命名约定：
252+
253+
```
254+
# 这种模板需要使用两个下划线来取代单个下划线：
255+
256+
/generator/template/__variables.scss
257+
258+
# 调用 api.render('./template') 会在项目目录中渲染成为：
259+
260+
_variables.scss
261+
```
262+
263+
237264
### 提示符
238265

239266
#### 内建插件的提示符

‎docs/zh/dev-guide/ui-api.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# UI API
1+
# UI 插件 API
22

33
这个 cli-ui 暴露一个 API，允许增强项目的配置和任务，也可以分享数据和在进程间进行通信。
44

‎docs/zh/dev-guide/ui-localization.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,14 +34,18 @@ API 的用法示例：
3434
```js
3535
api.describeConfig({
3636
// vue-i18n 路径
37-
description: 'my-plugin.config.foo'
37+
description: 'com.my-name.my-plugin.config.foo'
3838
})
3939
```
4040

41+
::: danger 危险
42+
请确定为 id 设置正确的命名空间，因为它需要跨所有插件保持唯一。我们推荐使用[反向域名记号 (reverse domain name notation)](https://en.wikipedia.org/wiki/Reverse_domain_name_notation)。
43+
:::
44+
4145
在组件中使用的示例：
4246

4347
```html
44-
<VueButton>{{ $t('my-plugin.actions.bar') }}</VueButton>
48+
<VueButton>{{ $t('com.my-name.my-plugin.actions.bar') }}</VueButton>
4549
```
4650

4751
如果你愿意的话，可以使用 `ClientAddonApi` 在一个客户端 addon 加载地区文件：

‎docs/zh/guide/README.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,12 @@ sidebarDepth: 0
44

55
# 介绍
66

7+
<Bit/>
8+
9+
::: warning 警告
10+
这份文档是对应 `@vue/cli` **3.x** 版本的。老版本的 `vue-cli` 文档请移步[这里](https://github.com/vuejs/vue-cli/tree/v2#vue-cli--)。
11+
:::
12+
713
Vue CLI 是一个基于 Vue.js 进行快速开发的完整系统，提供：
814

915
- 通过 `@vue/cli` 搭建交互式的项目脚手架。
@@ -14,6 +20,7 @@ Vue CLI 是一个基于 Vue.js 进行快速开发的完整系统，提供：
1420
- 可以通过项目内的配置文件进行配置；
1521
- 可以通过插件进行扩展。
1622
- 一个丰富的官方插件集合，集成了前端生态中最好的工具。
23+
- 一套完全图形化的创建和管理 Vue.js 项目的用户界面。
1724

1825
Vue CLI 致力于将 Vue 生态中的工具基础标准化。它确保了各种构建工具能够基于智能的默认配置即可平稳衔接，这样你可以专注在撰写应用上，而不必花好几天去纠结配置的问题。与此同时，它也为每个工具提供了调整配置的灵活性，无需 eject。
1926

‎docs/zh/guide/browser-compatibility.md

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,13 @@
22

33
## browserslist
44

5-
你会发现 `package.json` 文件里有一个 `browserlist` 字段，指定里项目的目标浏览器的范围。这个值会被 [@babel/preset-env][babel-preset-env] 和 [Autoprefixer][autoprefixer] 用来确定需要转译的 JavaScript 特性和需要添加的 CSS 浏览器前缀。
5+
你会发现有 `package.json` 文件里的 `browserlist` 字段 (或一个单独的 `.browserslistrc` 文件)，指定了项目的目标浏览器的范围。这个值会被 [@babel/preset-env][babel-preset-env] 和 [Autoprefixer][autoprefixer] 用来确定需要转译的 JavaScript 特性和需要添加的 CSS 浏览器前缀。
66

77
现在查阅[这里][browserslist]了解如何指定浏览器范围。
88

99
## Polyfill
1010

11-
一个默认的 Vue CLI 项目会使用 [@vue/babel-preset-app][babel-preset-env]，它通过 `@babel/preset-env` 和 `browserslist` 配置来决定项目需要的 polyfill。
11+
一个默认的 Vue CLI 项目会使用 [@vue/babel-preset-app][babel-preset-app]，它通过 `@babel/preset-env` 和 `browserslist` 配置来决定项目需要的 polyfill。
1212

1313
默认情况下，它会把 [`useBuiltIns: 'usage'`](https://new.babeljs.io/docs/en/next/babel-preset-env.html#usebuiltins-usage) 传递给 `@babel/preset-env`，这样它会根据源代码中出现的语言特性自动检测需要的 polyfill。这确保了最终包里 polyfill 数量的最小化。然而，这也意味着**如果其中一个依赖需要特殊的 polyfill，默认情况下 Babel 无法将其检测出来。**
1414

@@ -62,6 +62,17 @@ Vue CLI 会产生两个应用的版本：一个现代版的包，面向支持 [E
6262

6363
对于一个 Hello World 应用来说，现代版的包已经小了 16%。在生产环境下，现代版的包通常都会表现出显著的解析速度和运算速度，从而改善应用的加载性能。
6464

65+
::: tip 提示
66+
`<script type="module">` [需要配合始终开启的 CORS 进行加载](https://jakearchibald.com/2017/es-modules-in-browsers/#always-cors)。这意味着你的服务器必须返回诸如 `Access-Control-Allow-Origin: *` 的有效的 CORS 头。如果你想要通过认证来获取脚本，可使用 [corsUseCredentials](../config/#corsusecredentials) 选项。
67+
68+
同时，现代浏览器使用一段内联脚本来避免 Safari 10 重复加载脚本包，所以如果你在使用一套严格的 CSP，你需要这样显性地允许内联脚本：
69+
70+
```
71+
Content-Security-Policy: script-src 'self' 'sha256-4RS22DYeB7U14dra4KcQYxmwt5HkOInieXK1NUMBmQI='
72+
```
73+
:::
74+
6575
[autoprefixer]: https://github.com/postcss/autoprefixer
6676
[babel-preset-env]: https://new.babeljs.io/docs/en/next/babel-preset-env.html
77+
[babel-preset-app]: https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/babel-preset-app
6778
[browserslist]: https://github.com/ai/browserslist

‎docs/zh/guide/build-targets.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -70,13 +70,15 @@ Web Components 模式不支持 IE11 及更低版本。[更多细节](https://git
7070
在 Web Components 模式中，Vue 是*外置的*。这意味着包中不会有 Vue，即便你在代码中导入了 Vue。这里的包会假设在页面中已经有一个可用的全局变量 `Vue`。
7171
:::
7272

73-
你可以通过下面的命令将一个单独的入口构建为一个库：
73+
你可以通过下面的命令将一个单独的入口构建为一个 Web Components 组件：
7474

7575
```
7676
vue-cli-service build --target wc --name my-element [entry]
7777
```
7878

79-
这将会产生一个单独的 JavaScript 文件 (及其压缩后的版本) 将所有的东西都内联起来。当这个脚本被引入网页时，会注册自定义组件 `<my-element>`，其使用 `@vue/web-component-wrapper` 包裹了目标的 Vue 组件。这个包裹器会自动代理属性、特性、事件和插槽。请查阅 [`@vue/web-component-wrapper` 的文档](https://github.com/vuejs/vue-docs-zh-cn/blob/master/vue-web-component-wrapper/README.md)了解更多细节。
79+
注意这里的入口应该是一个 `*.vue` 文件。Vue CLI 将会把这个组件自动包裹并注册为 Web Components 组件，无需在 `main.js` 里做这件事。你也完全可以在开发时以一个 demo app 使用 `main.js`。
80+
81+
该构建将会产生一个单独的 JavaScript 文件 (及其压缩后的版本) 将所有的东西都内联起来。当这个脚本被引入网页时，会注册自定义组件 `<my-element>`，其使用 `@vue/web-component-wrapper` 包裹了目标的 Vue 组件。这个包裹器会自动代理属性、特性、事件和插槽。请查阅 [`@vue/web-component-wrapper` 的文档](https://github.com/vuejs/vue-docs-zh-cn/blob/master/vue-web-component-wrapper/README.md)了解更多细节。
8082

8183
**注意这个包依赖了在页面上全局可用的 `Vue`。**
8284

‎docs/zh/guide/cli-service.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,18 @@ yarn serve
2929
npx vue-cli-service serve
3030
```
3131

32+
::: tip 提示
33+
你可以通过 `vue ui` 命令使用 GUI 运行更多的特性脚本。
34+
:::
35+
36+
这里有一个 GUI 的 Webpack Analyzer：
37+
38+
![UI Webpack Analyzer](/ui-analyzer.png)
39+
3240
## vue-cli-service serve
3341

3442
```
35-
用法：vue-cli-service serve [options]
43+
用法：vue-cli-service serve [options] [entry]
3644
3745
选项：
3846

0 commit comments

Comments
 (0)