Commit 40d7e2f3 authored by Jinjiang's avatar Jinjiang

[docs][zh] update

parent 1544a661
# 介绍 # 介绍
:::tip 版本 :::tip 版本
这份文档是为 Vue Loader v15 及以上版本撰写的。如果你正在从 v14 或更早的版本往这里迁移,请查阅[迁移指南](../migrating.md)。如果你正在使用老版本,其对应的文档[在此](https://vue-loader-v14.vuejs.org) 这份文档是为 Vue Loader v15 及以上版本撰写的。如果你正在从 v14 或更早的版本往这里迁移,请查阅[迁移指南](../migrating.md)。如果你正在使用老版本,其对应的文档[在此](https://vue-loader-v14.vuejs.org)
::: :::
...@@ -36,6 +36,6 @@ Vue Loader 还提供了很多酷炫的特性: ...@@ -36,6 +36,6 @@ Vue Loader 还提供了很多酷炫的特性:
- 允许在一个 `.vue` 文件中使用自定义块,并对其运用自定义的 loader 链; - 允许在一个 `.vue` 文件中使用自定义块,并对其运用自定义的 loader 链;
- 使用 webpack loader 将 `<style>``<template>` 中引用的资源当作模块依赖来处理; - 使用 webpack loader 将 `<style>``<template>` 中引用的资源当作模块依赖来处理;
- 为每个组件模拟出 scoped CSS; - 为每个组件模拟出 scoped CSS;
- 在开发过程中可以保持状态的热重载 - 在开发过程中使用热重载来保持状态
简而言之,webpack 和 Vue Loader 的结合为你提供了一个撰写 Vue.js 应用的、现代的、灵活的和极致强大的前端工作流 简而言之,webpack 和 Vue Loader 的结合为你提供了一个现代、灵活且极其强大的前端工作流,来帮助撰写 Vue.js 应用
# 如何起步 # 起步
## Vue CLI ## Vue CLI
如果你没有手动设置 webpack 的兴趣,我们推荐使用 [Vue CLI](https://github.com/vuejs/vue-cli) 直接创建一个项目的脚手架。通过 Vue CLI 创建的项目会预配置好绝大多数的开发需求,它们开箱即用。 如果你不想手动设置 webpack,我们推荐使用 [Vue CLI](https://github.com/vuejs/vue-cli) 直接创建一个项目的脚手架。通过 Vue CLI 创建的项目会针对多数常见的开发需求进行预先配置,做到开箱即用。
如果 Vue CLI 提供的内建的配置没有满足你的需求,或者你乐于从零开始创建你自己的 webpack 配置,那么请跟随这份指南。 如果 Vue CLI 提供的内建没有满足你的需求,或者你乐于从零开始创建你自己的 webpack 配置,那么请继续阅读这篇指南。
## 手动配置 ## 手动配置
Vue Loader 的配置和其它的 loader 不太一样。除了通过一条规则将 `vue-loader` 应用到所有扩展名为 `.vue` 的文件上之外,请确在你的 webpack 配置中添加 Vue Loader 的插件: Vue Loader 的配置和其它的 loader 不太一样。除了通过一条规则将 `vue-loader` 应用到所有扩展名为 `.vue` 的文件上之外,请确在你的 webpack 配置中添加 Vue Loader 的插件:
``` js ``` js
// webpack.config.js // webpack.config.js
...@@ -25,15 +25,15 @@ module.exports = { ...@@ -25,15 +25,15 @@ module.exports = {
] ]
}, },
plugins: [ plugins: [
// 请确引入这个插件! // 请确引入这个插件!
new VueLoaderPlugin() new VueLoaderPlugin()
] ]
} }
``` ```
**这个插件是必须的!**它的职责是将你定义过的其它规则克隆并应用到 `.vue` 文件里相应语言的块。例如,如果你有一条匹配 `/\.js$` 的规则,那么它会应用到 `.vue` 文件里的 `<script>` 块。 **这个插件是必须的!**它的职责是将你定义过的其它规则复制并应用到 `.vue` 文件里相应语言的块。例如,如果你有一条匹配 `/\.js$/` 的规则,那么它会应用到 `.vue` 文件里的 `<script>` 块。
一个更完整的 webpack 配置示例看起来像是如下的样子 一个更完整的 webpack 配置示例看起来像这样
``` js ``` js
// webpack.config.js // webpack.config.js
...@@ -66,7 +66,7 @@ module.exports = { ...@@ -66,7 +66,7 @@ module.exports = {
] ]
}, },
plugins: [ plugins: [
// 请确认引入这个插件来实现这些魔力 // 请确保引入这个插件来施展魔法
new VueLoaderPlugin() new VueLoaderPlugin()
] ]
} }
......
...@@ -20,6 +20,15 @@ createElement('img', { ...@@ -20,6 +20,15 @@ createElement('img', {
默认下列标签/特性的组合会被转换,且这些组合时可以使用 [transformAssetUrls](../options.md#transformasseturls) 选项进行配置的。 默认下列标签/特性的组合会被转换,且这些组合时可以使用 [transformAssetUrls](../options.md#transformasseturls) 选项进行配置的。
``` js
{
video: ['src', 'poster'],
source: 'src',
img: 'src',
image: 'xlink:href'
}
```
此外,如果你配置了为 `<style>` 块使用 [css-loader](https://github.com/webpack-contrib/css-loader),则你的 CSS 中的资源 URL 也会被同等处理。 此外,如果你配置了为 `<style>` 块使用 [css-loader](https://github.com/webpack-contrib/css-loader),则你的 CSS 中的资源 URL 也会被同等处理。
## 转换规则 ## 转换规则
...@@ -30,7 +39,7 @@ createElement('img', { ...@@ -30,7 +39,7 @@ createElement('img', {
- 如果路径以 `.` 开头,将会被看作相对的模块依赖,并按照你的本地文件系统上的目录结构进行解析。 - 如果路径以 `.` 开头,将会被看作相对的模块依赖,并按照你的本地文件系统上的目录结构进行解析。
- 如果路径以 `~` 开头,其后的部分将会被看作模块依赖。这意味着你可以用该特性来引用一个 node 依赖中的资源: - 如果路径以 `~` 开头,其后的部分将会被看作模块依赖。这意味着你可以用该特性来引用一个 Node 依赖中的资源:
``` html ``` html
<img src="~some-npm-package/foo.png"> <img src="~some-npm-package/foo.png">
...@@ -46,6 +55,6 @@ createElement('img', { ...@@ -46,6 +55,6 @@ createElement('img', {
转换资源 URL 的好处是: 转换资源 URL 的好处是:
1. `file-loader` 可以指定要复制和放置资源文件的位置,以及如何使用版本哈希命名以获得更好的缓存。此外,这意味着 **你可以就近管理图片文件,可以使用相对路径而不用担心部署时 URL 的问题**。使用正确的配置,webpack 将会在打包输出中自动重写文件路径为正确的URL。 1. `file-loader` 可以指定要复制和放置资源文件的位置,以及如何使用版本哈希命名以获得更好的缓存。此外,这意味着 **你可以就近管理图片文件,可以使用相对路径而不用担心部署时 URL 的问题**。使用正确的配置,webpack 将会在打包输出中自动重写文件路径为正确的 URL。
2. `url-loader` 允许你有条件地将文件转换为内联的 base-64 URL (当文件小于给定的阈值),这会减少小文件的 HTTP 请求。如果文件大于该阈值,会自动的交给 `file-loader` 处理。 2. `url-loader` 允许你有条件地将文件转换为内联的 base-64 URL (当文件小于给定的阈值),这会减少小文件的 HTTP 请求。如果文件大于该阈值,会自动的交给 `file-loader` 处理。
# CSS Modules # CSS Modules
[CSS Modules](https://github.com/css-modules/css-modules)是一个用于模块化和组合 CSS 的流行系统。`vue-loader` 提供了与 CSS 模块的一流集成,可以作为模拟 scoped CSS 的替代方案。 [CSS Modules](https://github.com/css-modules/css-modules) 是一个流行的,用于模块化和组合 CSS 的系统。`vue-loader` 提供了与 CSS Modules 的一流集成,可以作为模拟 scoped CSS 的替代方案。
## 用法 ## 用法
...@@ -86,7 +86,7 @@ export default { ...@@ -86,7 +86,7 @@ export default {
你可以查阅 [CSS Modules 规范](https://github.com/css-modules/css-modules)了解更多细节,诸如 [global exceptions](https://github.com/css-modules/css-modules#exceptions)[composition](https://github.com/css-modules/css-modules#composition) 等。 你可以查阅 [CSS Modules 规范](https://github.com/css-modules/css-modules)了解更多细节,诸如 [global exceptions](https://github.com/css-modules/css-modules#exceptions)[composition](https://github.com/css-modules/css-modules#composition) 等。
## 可选加入的用法 ## 可选用法
如果你只想在某些 Vue 组件中使用 CSS Modules,你可以使用 `oneOf` 规则并在 `resourceQuery` 字符串中检查 `module` 字符串: 如果你只想在某些 Vue 组件中使用 CSS Modules,你可以使用 `oneOf` 规则并在 `resourceQuery` 字符串中检查 `module` 字符串:
...@@ -122,7 +122,7 @@ export default { ...@@ -122,7 +122,7 @@ export default {
## 和预处理器配合使用 ## 和预处理器配合使用
CSS Modules 可以独立用于其它预处理器 CSS Modules 可以与其它预处理器一起使用
``` js ``` js
// webpack.config.js -> module.rules // webpack.config.js -> module.rules
......
...@@ -2,7 +2,7 @@ ...@@ -2,7 +2,7 @@
`.vue` 文件中,你可以自定义语言块。应用于一个自定义块的 loader 是基于这个块的 `lang` 特性、块的标签名以及你的 webpack 配置进行匹配的。 `.vue` 文件中,你可以自定义语言块。应用于一个自定义块的 loader 是基于这个块的 `lang` 特性、块的标签名以及你的 webpack 配置进行匹配的。
如果一个 `lang` 特性被指定,则这个自定义块将会作为一个带有该 `lang` 扩展名的文件进行匹配。 如果指定了一个 `lang` 特性,则这个自定义块将会作为一个带有该 `lang` 扩展名的文件进行匹配。
你也可以使用 `resourceQuery` 来为一个没有 `lang` 的自定义块匹配一条规则。例如为了匹配自定义块 `<foo>` 你也可以使用 `resourceQuery` 来为一个没有 `lang` 的自定义块匹配一条规则。例如为了匹配自定义块 `<foo>`
...@@ -43,7 +43,7 @@ module.exports = function (source, map) { ...@@ -43,7 +43,7 @@ module.exports = function (source, map) {
} }
``` ```
现在我们将会配置 webpack 来使用我们`<docs>` 自定义块撰写的自定义 loader。 现在我们将会配置 webpack 来使用为 `<docs>` 自定义块撰写的自定义 loader。
``` js ``` js
// wepback.config.js // wepback.config.js
......
# CSS 提取 # CSS 提取
:::tip 提示 :::tip 提示
请只在生产环境下使用 CSS 提取,这便于你在开发环境下进行热重载。 请只在生产环境下使用 CSS 提取,这便于你在开发环境下进行热重载。
::: :::
## webpack 4 ## webpack 4
...@@ -18,7 +18,7 @@ module.exports = { ...@@ -18,7 +18,7 @@ module.exports = {
// 其它选项... // 其它选项...
module: { module: {
rules: [ rules: [
// ...其它规则忽略 // ... 忽略其它规则
{ {
test: /\.css$/, test: /\.css$/,
use: [ use: [
...@@ -31,7 +31,7 @@ module.exports = { ...@@ -31,7 +31,7 @@ module.exports = {
] ]
}, },
plugins: [ plugins: [
// ...vue-loader 插件忽略 // ... 忽略 vue-loader 插件
new MiniCssExtractPlugin({ new MiniCssExtractPlugin({
filename: style.css filename: style.css
}) })
......
# 热重载 # 热重载
"热重载"不只是当你修改文件的时候简单重新加载页面。启用热重载后,当你修改 `.vue` 文件时,该组件的所有实例将在**不刷新页面**的情况下被替换。它甚至保持了应用程序和被替换组件的当前状态!当你调整模版或者修改样式时,这极大的提高了开发体验。 “热重载”不只是当你修改文件的时候简单重新加载页面。启用热重载后,当你修改 `.vue` 文件时,该组件的所有实例将在**不刷新页面**的情况下被替换。它甚至保持了应用程序和被替换组件的当前状态!当你调整模版或者修改样式时,这极大地提高了开发体验。
![hot-reload](http://blog.evanyou.me/images/vue-hot.gif) ![hot-reload](http://blog.evanyou.me/images/vue-hot.gif)
......
...@@ -25,7 +25,7 @@ eslint --ext js,vue MyComponent.vue ...@@ -25,7 +25,7 @@ eslint --ext js,vue MyComponent.vue
npm install -D eslint eslint-loader npm install -D eslint eslint-loader
``` ```
请确它是作为一个 pre-loader 运用的: 请确它是作为一个 pre-loader 运用的:
``` js ``` js
// webpack.config.js // webpack.config.js
......
...@@ -6,9 +6,9 @@ sidebarDepth: 2 ...@@ -6,9 +6,9 @@ sidebarDepth: 2
在 webpack 中,所有的预处理器需要匹配对应的 loader。Vue Loader 允许你使用其它 webpack loader 处理 Vue 组件的某一部分。它会根据 `lang` 特性以及你 webpack 配置中的规则自动推断出要使用的 loader。 在 webpack 中,所有的预处理器需要匹配对应的 loader。Vue Loader 允许你使用其它 webpack loader 处理 Vue 组件的某一部分。它会根据 `lang` 特性以及你 webpack 配置中的规则自动推断出要使用的 loader。
## SASS ## Sass
例如,为了通过 SASS/SCSS 编译我们的 `<style>` 标签: 例如,为了通过 Sass/SCSS 编译我们的 `<style>` 标签:
``` bash ``` bash
npm install -D sass-loader node-sass npm install -D sass-loader node-sass
...@@ -20,10 +20,10 @@ npm install -D sass-loader node-sass ...@@ -20,10 +20,10 @@ npm install -D sass-loader node-sass
module.exports = { module.exports = {
module: { module: {
rules: [ rules: [
// ...其它规则忽略 // ... 忽略其它规则
// 普通的 `.scss` 文件和 `*.vue` 文件中的 // 普通的 `.scss` 文件和 `*.vue` 文件中的
// `<style lang="scss">` 块都用它 // `<style lang="scss">` 块都用它
{ {
test: /\.scss$/, test: /\.scss$/,
use: [ use: [
...@@ -48,7 +48,7 @@ module.exports = { ...@@ -48,7 +48,7 @@ module.exports = {
这个块里的任何内容都会被 webpack 当作在一个 `*.scss` 文件中一样被处理。 这个块里的任何内容都会被 webpack 当作在一个 `*.scss` 文件中一样被处理。
### SASS vs SCSS ### Sass vs SCSS
注意 `sass-loader` 会默认处理不基于缩进的 `scss` 语法。为了使用基于缩进的 `sass` 语法,你需要向这个 loader 传递选项: 注意 `sass-loader` 会默认处理不基于缩进的 `scss` 语法。为了使用基于缩进的 `sass` 语法,你需要向这个 loader 传递选项:
...@@ -91,7 +91,7 @@ module.exports = { ...@@ -91,7 +91,7 @@ module.exports = {
} }
``` ```
## LESS ## Less
``` bash ``` bash
npm install -D less less-loader npm install -D less less-loader
...@@ -152,7 +152,7 @@ npm install -D postcss-loader ...@@ -152,7 +152,7 @@ npm install -D postcss-loader
} }
``` ```
PostCSS 的配置可以通过 `postcss.config.js``postcss-loader` 选项来完成。其更多细节请咨询 [postcss-loader 文档](https://github.com/postcss/postcss-loader) PostCSS 的配置可以通过 `postcss.config.js``postcss-loader` 选项来完成。其更多细节请查阅 [postcss-loader 文档](https://github.com/postcss/postcss-loader)
`postcss-loader` 也可以和上述其它预处理器结合使用。 `postcss-loader` 也可以和上述其它预处理器结合使用。
...@@ -182,12 +182,12 @@ npm install -D typescript ts-loader ...@@ -182,12 +182,12 @@ npm install -D typescript ts-loader
// webpack.config.js // webpack.config.js
module.exports = { module.exports = {
resolve: { resolve: {
// Add `.ts` as a resolvable extension. // 将 `.ts` 添加为一个可解析的扩展名。
extensions: ['.ts', '.js'] extensions: ['.ts', '.js']
}, },
module: { module: {
rules: [ rules: [
// ...other rules omitted // ... 忽略其它规则
{ {
test: /\.ts$/, test: /\.ts$/,
loader: 'ts-loader', loader: 'ts-loader',
......
...@@ -30,7 +30,7 @@ ...@@ -30,7 +30,7 @@
## 混用本地和全局样式 ## 混用本地和全局样式
你可以在一个组件中同时使用有 scoped 和 non-scoped 样式: 你可以在一个组件中同时使用有 scoped 和scoped 样式:
``` html ``` html
<style> <style>
......
...@@ -2,4 +2,4 @@ ...@@ -2,4 +2,4 @@
- [Vue CLI](https://github.com/vuejs/vue-cli) 提供了预配置的单元测试和 e2e 测试安装。 - [Vue CLI](https://github.com/vuejs/vue-cli) 提供了预配置的单元测试和 e2e 测试安装。
- 如果你有兴趣为 `*.vue` 文件手动设置单元测试,请[@vue/test-utils](https://vue-test-utils.vuejs.org/zh-cn/) 的文档,这份文档涵盖了对 [mocha-webpack](https://vue-test-utils.vuejs.org/zh-cn/guides/testing-SFCs-with-mocha-webpack.html)[Jest](https://vue-test-utils.vuejs.org/zh-cn/guides/testing-SFCs-with-jest.html) 的设置。 - 如果你有兴趣为 `*.vue` 文件手动设置单元测试,请[@vue/test-utils](https://vue-test-utils.vuejs.org/zh-cn/) 的文档,这份文档涵盖了对 [mocha-webpack](https://vue-test-utils.vuejs.org/zh-cn/guides/testing-SFCs-with-mocha-webpack.html)[Jest](https://vue-test-utils.vuejs.org/zh-cn/guides/testing-SFCs-with-jest.html) 的设置。
...@@ -13,7 +13,7 @@ sidebarDepth: 2 ...@@ -13,7 +13,7 @@ sidebarDepth: 2
### 现在你需要一个插件 ### 现在你需要一个插件
Vue Loader 15 现在需要伴随一个 webpack 插件才能正确使用: Vue Loader 15 现在需要配合一个 webpack 插件才能正确使用:
``` js ``` js
// webpack.config.js // webpack.config.js
...@@ -105,11 +105,11 @@ v14 或更低版本使用 [consolidate](https://github.com/tj/consolidate.js/) ...@@ -105,11 +105,11 @@ v14 或更低版本使用 [consolidate](https://github.com/tj/consolidate.js/)
现在客户端的样式注入会在最前面注入所有的样式以确保开发模式和提取模式下行为的一致性。 现在客户端的样式注入会在最前面注入所有的样式以确保开发模式和提取模式下行为的一致性。
注意它们注入的顺序仍然是不受担保的,所以你撰写的 CSS 应该避免依赖插入的顺序。 注意它们注入的顺序是不能保证的,所以你撰写的 CSS 应该避免依赖插入的顺序。
### PostCSS ### PostCSS
Vue Loader v15 不再默认应用 PostCSS 变换。想要使用 PostCSS,请像为普通 CSS 文件一样的方式配置 `postcss-loader` Vue Loader v15 不再默认应用 PostCSS 变换。想要使用 PostCSS,请像配置普通 CSS 文件那样配置 `postcss-loader`
### CSS Modules ### CSS Modules
......
...@@ -41,9 +41,9 @@ sidebar: auto ...@@ -41,9 +41,9 @@ sidebar: auto
- 类型:`Object` - 类型:`Object`
- 默认值:`{}` - 默认值:`{}`
为渲染函数的生成码配置从 ES2015+ 到 ES5 的转译选项。这里的[转译器](https://github.com/vuejs/vue-template-es2015-compiler)是一份 [Buble](https://github.com/Rich-Harris/buble) 的 fork,因此你可以在[这里](https://buble.surge.sh/guide/#using-the-javascript-api)咨询可用的选项。 为渲染函数的生成码配置从 ES2015+ 到 ES5 的转译选项。这里的[转译器](https://github.com/vuejs/vue-template-es2015-compiler)是一份 [Buble](https://github.com/Rich-Harris/buble) 的 fork,因此你可以在[这里](https://buble.surge.sh/guide/#using-the-javascript-api)查阅可用的选项。
模板渲染函数编译支持一个特殊的变换 `stripWith` (默认启用),它删除生成的渲染函数中的 `with` 用法,使它们兼容严格模式。 模板渲染函数编译支持一个特殊的变换 `stripWith` (默认启用),它删除生成的渲染函数中的 `with` 用法,使它们兼容严格模式。
## optimizeSSR ## optimizeSSR
......
...@@ -83,7 +83,7 @@ export default { ...@@ -83,7 +83,7 @@ export default {
### Src 导入 ### Src 导入
如果你喜欢分隔你的 `.vue` 文件到多个文件中,你可以通过 `src` 属性导入外部文件: 如果喜欢把 `.vue` 文件分隔到多个文件中,你可以通过 `src` 属性导入外部文件:
``` vue ``` vue
<template src="./template.html"></template> <template src="./template.html"></template>
...@@ -124,4 +124,4 @@ export default { ...@@ -124,4 +124,4 @@ export default {
## 注释 ## 注释
在语言块中使用该语言块对应的注释语法 (HTML、CSS、JavaScript、Jade 等)。顶层注释使用 HTML 注释语法:`<!-- comment contents here -->` 在语言块中使用该语言块对应的注释语法 (HTML、CSS、JavaScript、Jade 等)。顶层注释使用 HTML 注释语法:`<!-- comment contents here -->`
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment