From 5d0e263b26f2bd9861a8a2e8347c5a02a9291534 Mon Sep 17 00:00:00 2001 From: Evan You Date: Tue, 28 Jun 2022 18:42:29 +0800 Subject: [PATCH 01/53] review: home & intro --- .vitepress/theme/components/Home.vue | 8 +++---- src/guide/introduction.md | 34 ++++++++++++++-------------- 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/.vitepress/theme/components/Home.vue b/.vitepress/theme/components/Home.vue index 499e91fde..ecad00f37 100644 --- a/.vitepress/theme/components/Home.vue +++ b/.vitepress/theme/components/Home.vue @@ -19,7 +19,7 @@ onMounted(async () => {
JavaScript 框架

- 一款用于构建 Web 界面，易学易用，性能出色且功能丰富的框架。 + 易学易用，性能出色，适用场景丰富的 Web 前端框架。

@@ -62,7 +62,7 @@ onMounted(async () => {

易学易用

- 基于标准 HTML、CSS 和 JavaScript 构建，拥有直观的 API 和世界一流的文档。 + 基于标准 HTML、CSS 和 JavaScript 构建，提供容易上手的 API 和一流的文档。

@@ -72,9 +72,9 @@ onMounted(async () => {

-

功能丰富

+

灵活多变

- 拥有丰富的、可渐进式集成的生态系统，可以根据规模在仅使用一个库和使用整套框架间切换自如。 + 丰富的、可渐进式集成的生态系统，可以根据应用规模在库和框架间切换自如。

diff --git a/src/guide/introduction.md b/src/guide/introduction.md index 4e28d0c31..b058fad00 100644 --- a/src/guide/introduction.md +++ b/src/guide/introduction.md @@ -24,7 +24,7 @@ footer: false ## 什么是 Vue？ {#what-is-vue} -Vue (发音为 /vjuː/，类似 **view**) 是一款用于构建用户界面的 JavaScript 框架。它基于标准 HTML、CSS 和 JavaScript 构建，并提供了一套声明式的、组件化的编程模型，帮助你高效地开发用户界面，无论任务是简单还是复杂。 +Vue (发音为 /vjuː/，类似 **view**) 是一款用于构建用户界面的 JavaScript 框架。它基于标准 HTML、CSS 和 JavaScript 构建，并提供了一套声明式的、组件化的编程模型，帮助你高效地开发用户界面。无论是简单还是复杂的界面，Vue 都可以胜任。 下面是一个最基本的示例： @@ -61,13 +61,13 @@ const count = ref(0) -上面的示例展示了两个 Vue 的核心功能： +上面的示例展示了 Vue 的两个核心功能： -- **声明式渲染**：Vue 通过自己的模板语法扩展了标准 HTML，使得我们可以声明式地描述基于 JavaScript 状态输出的 HTML。 +- **声明式渲染**：Vue 基于标准 HTML 拓展了一套模版语法，使得我们可以声明式地描述最终输出的 HTML 和 JavaScript 状态之间的关系。 - **响应性**：Vue 会自动跟踪 JavaScript 状态变化并在改变发生时响应式地更新 DOM。 -你可能已经有了些疑问——别担心。我们会在接下来的文档中覆盖到每一个细节。现在，请继续阅读，这会让你对 Vue 所提供的功能有一个宏观的认知。 +你可能已经有了些疑问——先别急，后面的文档中我们会详细介绍每一个细节。现在，请继续看下去，确保你对 Vue 作为一个框架到底提供了什么有一个宏观的了解。 :::tip 预备知识 文档接下来的部分假设你对 HTML、CSS 和 JavaScript 已经基本熟悉。如果你对前端开发完全陌生，最好不要直接在一开始针对一个框架进行学习——最好是掌握了基础知识再回到这里。你可以通过这篇 [JavaScript 概述](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/A_re-introduction_to_JavaScript)来检验你的 JavaScript 知识水平。如果之前有其他框架的经验会很有帮助，但不是必须的。 @@ -75,20 +75,20 @@ const count = ref(0) ## 渐进式框架 {#the-progressive-framework} -Vue 是一个框架和生态，功能覆盖了大部分前端开发常见的需求。但 Web 世界又是十分多样化的，我们在 Web 上构建的东西可能在形式和规模上有很大不同。考虑到这一点，Vue 被设计成具有灵活性和可逐步集成的特点。根据你的需求场景，Vue 可以按不同的方式使用： +Vue 是一个框架，也是一个生态。其功能覆盖了大部分前端开发常见的需求。但 Web 世界又是十分多样化的，不同的开发者在 Web 上构建的东西可能在形式和规模上会有很大的不同。考虑到这一点，Vue 的设计非常注重灵活性和 “可以被逐步集成” 这个特点。根据你的需求场景，你可以用不同的方式使用 Vue： -- 增强静态的 HTML 而无需构建步骤 +- 无需构建步骤，渐进式增强静态的 HTML - 在任何页面中作为 Web Components 嵌入 - 单页应用 (SPA) - 全栈 / 服务端渲染 (SSR) - Jamstack / 静态站点生成 (SSG) -- 目标为桌面端、移动端、WebGL，甚至是命令行终端 +- 开发桌面端、移动端、WebGL，甚至是命令行终端中的界面 -如果你是初学者，可能觉得这些概念令人生畏，别担心！理解教程和指南的内容只需要具备基础的 HTML 和 JavaScript 知识。你即使不是这些方面的专家，也能够跟上。 +如果你是初学者，可能会觉得这些概念有些复杂。别担心！理解教程和指南的内容只需要具备基础的 HTML 和 JavaScript 知识。你即使不是这些方面的专家，也能够跟上。 -如果你是有经验的开发者，对于如何以最好的方式在你的项目中引入 Vue，或者是对上述的概念很好奇，我们将在[使用 Vue 的多种方式](/guide/extras/ways-of-using-vue)中讨论有关它们的更多细节。 +如果你是有经验的开发者，希望了解如何以最合适的方式在项目中引入 Vue，或者是对上述的这些概念感到好奇，我们在[使用 Vue 的多种方式](/guide/extras/ways-of-using-vue)中讨论了有关它们的更多细节。 -无论再怎么灵活，关于 Vue 是如何工作的核心知识在所有这些用例中都是通用的。即使你现在只是一个初学者，随着你的不断成长，直到未来有能力实现更雄心勃勃的目标时，这一路上获得的知识都将会一直有用。如果你已经是一个老手，你可以根据你要解决的问题来选择使用 Vue 的最佳方式，同时保留相同的生产力。这就是为什么我们将 Vue 称为“渐进式框架”：它是一个可以与你共同成长、适应你不同需求的框架。 +无论再怎么灵活，Vue 的核心知识在所有这些用例中都是通用的。即使你现在只是一个初学者，随着你的不断成长，到未来有能力实现更复杂的项目时，这一路上获得的知识依然会适用。如果你已经是一个老手，你可以根据实际场景来选择使用 Vue 的最佳方式，在各种场景下都可以保持同样的开发效率。这就是为什么我们将 Vue 称为“渐进式框架”：它是一个可以与你共同成长、适应你不同需求的框架。 ## 单文件组件 {#single-file-components} @@ -116,7 +116,7 @@ button { ``` -单文件组件是 Vue 的标志性功能。如果你的用例需要进行构建，我们推荐用它来编写 Vue 组件。你可以在后续相关章节里了解更多关于[单文件组件的用法及用途](/guide/scaling-up/sfc)。但你暂时只需要知道 Vue 会帮忙处理所有这些构建配置就好。 +单文件组件是 Vue 的标志性功能。如果你的用例需要进行构建，我们推荐用它来编写 Vue 组件。你可以在后续相关章节里了解更多关于[单文件组件的用法及用途](/guide/scaling-up/sfc)。但你暂时只需要知道 Vue 会帮忙处理所有这些构建工具的配置就好。 ## API 风格 {#api-styles} @@ -163,7 +163,7 @@ export default { ### 组合式 API {#composition-api} -通过组合式 API，我们可以使用导入的 API 函数来描述组件逻辑。在单文件组件中，组合式 API 通常会与 [` ``` diff --git a/src/examples/src/handling-input/App/composition.js b/src/examples/src/handling-input/App/composition.js index 7b986ddb7..41c2229df 100644 --- a/src/examples/src/handling-input/App/composition.js +++ b/src/examples/src/handling-input/App/composition.js @@ -5,7 +5,7 @@ export default { const message = ref('Hello World!') function reverseMessage() { - // 通过其 .value property + // 通过其 .value 属性 // 访问/修改一个 ref 的值。 message.value = message.value.split('').reverse().join('') } diff --git a/src/guide/best-practices/security.md b/src/guide/best-practices/security.md index 96a7bb394..70ce3019c 100644 --- a/src/guide/best-practices/security.md +++ b/src/guide/best-practices/security.md @@ -137,7 +137,7 @@ Vue 模板会被编译成 JavaScript，而模板内的表达式将作为渲染 ``` -为了避免用户的点击被劫持，我们建议仅在沙盒环境的 iframe 中允许用户控制 CSS。或者，当用户控制样式绑定时，我们建议使用其[对象值形式](/guide/essentials/class-and-style.html#object-syntax-2)并仅允许用户提供能够安全控制的、特定的 property，就像这样： +为了避免用户的点击被劫持，我们建议仅在沙盒环境的 iframe 中允许用户控制 CSS。或者，当用户控制样式绑定时，我们建议使用其[对象值形式](/guide/essentials/class-and-style.html#object-syntax-2)并仅允许用户提供能够安全控制的、特定的属性，就像这样： ```vue-html ` 一般都会搭配[原生 CSS 过渡](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Transitions/Using_CSS_transitions)一起使用，正如你在上面的例子中所看到的那样。这个 `transition` CSS 属性是一个简写形式，使我们可以一次定义一个过渡的各个方面，包括需要执行动画的属性、持续时间和[速度曲线](https://developer.mozilla.org/en-US/docs/Web/CSS/easing-function)。 -下面是一个更高级的例子，它使用了不同的持续时间和速度曲线来过渡多个 property： +下面是一个更高级的例子，它使用了不同的持续时间和速度曲线来过渡多个属性： ```vue-html diff --git a/src/guide/components/events.md b/src/guide/components/events.md index c7b614ed6..ae517a343 100644 --- a/src/guide/components/events.md +++ b/src/guide/components/events.md @@ -135,7 +135,7 @@ export default { } ``` -与 `setup()` 上下文中的其他 property 一样，`emit` 可以安全地被解构： +与 `setup()` 上下文对象中的其他属性一样，`emit` 可以安全地被解构： ```js export default { @@ -358,7 +358,7 @@ defineEmits(['update:modelValue']) -另一种在组件内实现 `v-model` 的方式是使用一个可写的 `computed` property，给出 getter 和 setter。`get` 方法需返回 `modelValue` property 而 `set` 方法需触发相应的事件： +另一种在组件内实现 `v-model` 的方式是使用一个可写的，同时具有 getter 和 setter 的计算属性。`get` 方法需返回 `modelValue` 属性而 `set` 方法需触发相应的事件：
diff --git a/src/guide/essentials/class-and-style.md b/src/guide/essentials/class-and-style.md index fc509ab8e..5f7a154b2 100644 --- a/src/guide/essentials/class-and-style.md +++ b/src/guide/essentials/class-and-style.md @@ -224,7 +224,7 @@ Class 的绑定也是同样的：

Hi

``` -如果你的组件有多个根元素，你将需要指定哪个根元素来接收这个 class。你可以通过组件的 `$attrs` property 来实现指定： +如果你的组件有多个根元素，你将需要指定哪个根元素来接收这个 class。你可以通过组件的 `$attrs` 属性来实现指定： ```vue-html diff --git a/src/guide/essentials/component-basics.md b/src/guide/essentials/component-basics.md index 21dc863f6..f0a0bed8d 100644 --- a/src/guide/essentials/component-basics.md +++ b/src/guide/essentials/component-basics.md @@ -305,7 +305,7 @@ const posts = ref([ 继续开发我们的 `` 组件，我们会发现有时候需要与父组件进行交互。例如，要在此处实现 A11y 的需求，将博客文章的文字能够放大，而页面的其余部分仍使用默认字号。 -在父组件中，我们可以添加一个 `postFontSize` 数据 propertyref 来实现这个效果： +在父组件中，我们可以添加一个 `postFontSize` 数据属性ref 来实现这个效果：
diff --git a/src/guide/essentials/computed.md b/src/guide/essentials/computed.md index 265942459..ceb3ec3f9 100644 --- a/src/guide/essentials/computed.md +++ b/src/guide/essentials/computed.md @@ -95,7 +95,7 @@ export default { 更改此应用的 `data` 中 `books` 数组的值后，可以看到 `publishedBooksMessage` 也会随之改变。 -在模板中使用计算属性的方式和一般的 property 并无二致。Vue 会检测到 `this.publishedBooksMessage` 依赖于 `this.author.books`，所以当 `this.author.books` 改变时，任何依赖于 `this.publishedBooksMessage` 的绑定都将同时更新。 +在模板中使用计算属性的方式和一般的属性并无二致。Vue 会检测到 `this.publishedBooksMessage` 依赖于 `this.author.books`，所以当 `this.author.books` 改变时，任何依赖于 `this.publishedBooksMessage` 的绑定都将同时更新。 也可参考：[为计算属性标记类型](/guide/typescript/options-api.html#typing-computed) diff --git a/src/guide/essentials/list.md b/src/guide/essentials/list.md index 5d118c793..6200f90ee 100644 --- a/src/guide/essentials/list.md +++ b/src/guide/essentials/list.md @@ -38,7 +38,7 @@ data() { ``` -在 `v-for` 块中可以完整地访问父作用域内的 property。`v-for` 也支持使用可选的第二个参数表示当前项的位置索引。 +在 `v-for` 块中可以完整地访问父作用域内的属性和变量。`v-for` 也支持使用可选的第二个参数表示当前项的位置索引。
@@ -272,7 +272,7 @@ Vue 默认按照“就地更新”的策略来更新通过 `v-for` 渲染的元 ``` :::tip 注意 -`key` 在这里是一个通过 `v-bind` 绑定的特殊 attribute。请不要和[在 `v-for` 中使用对象](#v-for-with-an-object)里所提到的对象 property key 相混淆。 +`key` 在这里是一个通过 `v-bind` 绑定的特殊 attribute。请不要和[在 `v-for` 中使用对象](#v-for-with-an-object)里所提到的对象属性名相混淆。 ::: [推荐](/style-guide/#keyed-v-for-essential)在任何可行的时候为 `v-for` 提供一个 `key` attribute，除非所迭代的 DOM 内容非常简单 (例如：不包含组件或有状态的 DOM 元素)，或者有意依赖默认行为来获得性能增益。 diff --git a/src/guide/essentials/reactivity-fundamentals.md b/src/guide/essentials/reactivity-fundamentals.md index e88a52704..6fe78fd69 100644 --- a/src/guide/essentials/reactivity-fundamentals.md +++ b/src/guide/essentials/reactivity-fundamentals.md @@ -12,7 +12,7 @@ outline: deep
-选用选项式 API 时，会用 `data` 选项来声明组件的响应式状态。此选项的值应为返回一个对象的函数。Vue 将在创建新组件实例的时候调用此函数，并将函数返回的对象封装到其响应式系统中。此对象的任何顶层 property 都被代理到组件实例 (即方法和生命周期钩子中的 `this`) 上。 +选用选项式 API 时，会用 `data` 选项来声明组件的响应式状态。此选项的值应为返回一个对象的函数。Vue 将在创建新组件实例的时候调用此函数，并将函数返回的对象封装到其响应式系统中。此对象的任何顶层属性都被代理到组件实例 (即方法和生命周期钩子中的 `this`) 上。 ```js{2-6} export default { @@ -35,11 +35,11 @@ export default { [在演练场中尝试一下](https://sfc.vuejs.org/#eyJBcHAudnVlIjoiPHNjcmlwdD5cbmV4cG9ydCBkZWZhdWx0IHtcbiAgZGF0YSgpIHtcbiAgICByZXR1cm4ge1xuICAgICAgY291bnQ6IDFcbiAgICB9XG4gIH0sXG5cbiAgLy8gYG1vdW50ZWRgIGlzIGEgbGlmZWN5Y2xlIGhvb2sgd2hpY2ggd2Ugd2lsbCBleHBsYWluIGxhdGVyXG4gIG1vdW50ZWQoKSB7XG4gICAgLy8gYHRoaXNgIHJlZmVycyB0byB0aGUgY29tcG9uZW50IGluc3RhbmNlLlxuICAgIGNvbnNvbGUubG9nKHRoaXMuY291bnQpIC8vID0+IDFcblxuICAgIC8vIGRhdGEgY2FuIGJlIG11dGF0ZWQgYXMgd2VsbFxuICAgIHRoaXMuY291bnQgPSAyXG4gIH1cbn1cbjwvc2NyaXB0PlxuXG48dGVtcGxhdGU+XG4gIENvdW50IGlzOiB7eyBjb3VudCB9fVxuPC90ZW1wbGF0ZT4iLCJpbXBvcnQtbWFwLmpzb24iOiJ7XG4gIFwiaW1wb3J0c1wiOiB7XG4gICAgXCJ2dWVcIjogXCJodHRwczovL3NmYy52dWVqcy5vcmcvdnVlLnJ1bnRpbWUuZXNtLWJyb3dzZXIuanNcIlxuICB9XG59In0=) -这些实例上的 property 仅在实例首次创建时被添加，因此你需要确保它们都出现在 `data` 函数返回的对象上。若所需的值还未准备好，在必要时也可以使用 `null`、`undefined` 或者其他一些值占位。 +这些实例上的属性仅在实例首次创建时被添加，因此你需要确保它们都出现在 `data` 函数返回的对象上。若所需的值还未准备好，在必要时也可以使用 `null`、`undefined` 或者其他一些值占位。 也可以不在 `data` 上定义，直接向组件实例添加新属性。但这个属性将无法触发响应式更新。 -Vue 在组件实例上暴露的内置 API 使用 `$` 作为前缀。它同时也为内部 property 保留 `_` 前缀。你应该避免在顶层 `data` 上使用任何以这些字符作前缀的 property。 +Vue 在组件实例上暴露的内置 API 使用 `$` 作为前缀。它同时也为内部属性保留 `_` 前缀。你应该避免在顶层 `data` 上使用任何以这些字符作前缀的属性。 ### 响应式代理 vs. 原始值 \* {#reactive-proxy-vs-original} @@ -75,7 +75,7 @@ import { reactive } from 'vue' const state = reactive({ count: 0 }) ``` -响应式对象其实是 [JavaScript Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)，其行为表现与一般对象相似。不同之处在于 Vue 能够跟踪对响应式对象 property 的访问与更改操作。如果你对这其中的细节感到好奇，我们在 [深入响应式系统](/guide/extras/reactivity-in-depth.html) 一章中会进行解释，但我们推荐你先读完这里的主要指南。 +响应式对象其实是 [JavaScript Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)，其行为表现与一般对象相似。不同之处在于 Vue 能够跟踪对响应式对象属性的访问与更改操作。如果你对这其中的细节感到好奇，我们在 [深入响应式系统](/guide/extras/reactivity-in-depth.html) 一章中会进行解释，但我们推荐你先读完这里的主要指南。 你也可以看看：[为响应式对象标注类型](/guide/typescript/composition-api.html#typing-reactive) @@ -200,7 +200,7 @@ export default { } ``` -和组件实例上的其他 property 一样，方法也可以在模板上被访问。在模板中它们常常被用作事件监听器： +和组件实例上的其他属性一样，方法也可以在模板上被访问。在模板中它们常常被用作事件监听器： ```vue-html @@ -302,7 +302,7 @@ function mutateDeeply() {
-### 响应式代理 vs. 原始对象 \*\* {#reactive-proxy-vs-original-1} +### 响应式代理 vs. 原始对象 \*\* {#reactive-proxy-vs-original-1} 值得注意的是，`reactive()` 返回的是一个原始对象的 [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)，它和原始对象是不相等的： @@ -343,7 +343,7 @@ console.log(proxy.nested === raw) // false 1. 仅对对象类型有效（对象、数组和 `Map`、`Set` 这样的[集合类型](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects#%E4%BD%BF%E7%94%A8%E9%94%AE%E7%9A%84%E9%9B%86%E5%90%88%E5%AF%B9%E8%B1%A1)），而对 `string`、`number` 和 `boolean` 这样的 [原始类型](https://developer.mozilla.org/zh-CN/docs/Glossary/Primitive) 无效。 -2. 因为 Vue 的响应式系统是通过 property 访问进行追踪的，因此我们必须始终保持对该响应式对象的相同引用。这意味着我们不可以随意地“替换”一个响应式对象，因为这将导致对初始引用的响应性连接丢失： +2. 因为 Vue 的响应式系统是通过属性访问进行追踪的，因此我们必须始终保持对该响应式对象的相同引用。这意味着我们不可以随意地“替换”一个响应式对象，因为这将导致对初始引用的响应性连接丢失： ```js let state = reactive({ count: 0 }) @@ -352,7 +352,7 @@ console.log(proxy.nested === raw) // false state = reactive({ count: 1 }) ``` - 同时这也意味着当我们将响应式对象的 property 赋值或解构至本地变量时，或是将该 property 传入一个函数时，我们会失去响应性： + 同时这也意味着当我们将响应式对象的属性赋值或解构至本地变量时，或是将该属性传入一个函数时，我们会失去响应性： ```js const state = reactive({ count: 0 }) @@ -383,7 +383,7 @@ import { ref } from 'vue' const count = ref(0) ``` -`ref()` 从参数中获取到值，将其包装为一个带 `.value` property 的 ref 对象： +`ref()` 从参数中获取到值，将其包装为一个带 `.value` 属性的 ref 对象： ```js const count = ref(0) @@ -397,7 +397,7 @@ console.log(count.value) // 1 你也可以看看：[为 ref 标注类型](/guide/typescript/composition-api.html#typing-ref) -和响应式对象的 property 类似，ref 的 `.value` property 也是响应式的。同时，当值为对象类型时，会用 `reactive()` 自动转换它的 `.value`。 +和响应式对象的属性类似，ref 的 `.value` 属性也是响应式的。同时，当值为对象类型时，会用 `reactive()` 自动转换它的 `.value`。 一个包含对象类型值的 ref 可以响应式地替换整个对象： @@ -429,7 +429,7 @@ const { foo, bar } = obj ### ref 在模板中的解包 \*\* {#ref-unwrapping-in-templates} -当 ref 在模板中作为顶层 property 被访问时，它们会被自动“解包”，所以不需要使用 `.value`。下面是之前的计数器例子，用 `ref()` 代替： +当 ref 在模板中作为顶层属性被访问时，它们会被自动“解包”，所以不需要使用 `.value`。下面是之前的计数器例子，用 `ref()` 代替： ```vue{13} ``` -你也可以看看[为组件 emits 标注类型](/guide/typescript/composition-api.html#typing-component-emits)这一章了解更多。 +TypeScript 用户请参考：[为组件 emits 标注类型](/guide/typescript/composition-api.html#typing-component-emits) 如果你没有在使用 ` ``` -在没有使用 ` ``` -查看这一章获取更多[组件 props 类型标注](/guide/typescript/composition-api.html#typing-component-props)的相关细节。 +更多关于基于类型的声明的细节请参考[组件 props 类型标注](/guide/typescript/composition-api.html#typing-component-props)。
@@ -121,7 +121,7 @@ defineProps<{ ### Prop 名字格式 {#prop-name-casing} -如果 prop 的名字很长，应使用 camelCase 形式，因为它们是合法的 JavaScript 标识符，可以直接在模板的表达式中使用，避免在作为属性 key 名时必须带引号。 +如果一个 prop 的名字很长，应使用 camelCase 格式，因为它们是合法的 JavaScript 标识符，可以直接在模板的表达式中使用，也可以避免在作为属性 key 名时必须加上引号。
@@ -148,23 +148,23 @@ export default { {{ greetingMessage }} ``` -从技术上来讲，你也可以在子组件传递 prop 时使用 camelCase 形式。(使用 [DOM 模板](/guide/essentials/component-basics.html#dom-template-parsing-caveats)时例外) 而实际上为了和 HTML attribute 对齐，都会将其转为 kebab-case 形式： +虽然理论上你也可以在子组件传递 props 时使用 camelCase 格式 (使用 [DOM 模板](/guide/essentials/component-basics.html#dom-template-parsing-caveats)时例外)，但实际上为了和 HTML attribute 对齐，我们通常会将其写为 kebab-case 格式： ```vue-html ``` -一般情况下都会使用 [PascalCase 作为组件标签名](/guide/components/registration.html#component-name-casing)，因为这提高了模板的可读性，能很好地区分出 Vue 组件和原生 HTML 元素。然而这对于传递 prop 来说收效并不高，因此我们选择对其进行转换。 +对于组件名我们推荐使用 [PascalCase](/guide/components/registration.html#component-name-casing)，因为这提高了模板的可读性，能帮助我们区分 Vue 组件和原生 HTML 元素。然而对于传递 props 来说，使用 camelCase 并没有太多优势，因此我们推荐更贴近 HTML 的书写风格。 ### 静态 vs. 动态 Prop {#static-vs-dynamic-props} -至此，你已经见过了很多像这样的静态值形式的 prop： +至此，你已经见过了很多像这样的静态值形式的 props： ```vue-html ``` -相应地还有使用 `v-bind` 或缩写 `:` 所动态绑定的 prop 值： +相应地，还有使用 `v-bind` 或缩写 `:` 来进行动态绑定的 props： ```vue-html @@ -176,12 +176,12 @@ export default { ### 传递不同的值类型 {#passing-different-value-types} -在上述的两个例子中，我们只传入了字符串值，但实际上**任何**类型的值都可以作为一个 prop。 +在上述的两个例子中，我们只传入了字符串值，但实际上**任何**类型的值都可以作为 props 的值被传递。 #### Number {#number} ```vue-html - + @@ -192,7 +192,7 @@ export default { #### Boolean {#boolean} ```vue-html - + @@ -206,7 +206,7 @@ export default { #### Array {#array} ```vue-html - + @@ -217,7 +217,7 @@ export default { #### Object {#object} ```vue-html - + @@ -275,7 +275,7 @@ const post = { ## 单向数据流 {#one-way-data-flow} -所有的 prop 都遵循着**单向绑定**原则，prop 因父组件的更新而变化，自然地将新的状态向下流往子组件，而不会逆向传递。这避免了子组件意外修改了父组件的状态，不然应用的数据流就会变得难以理解了。 +所有的 props 都遵循着**单向绑定**原则，props 因父组件的更新而变化，自然地将新的状态向下流往子组件，而不会逆向传递。这避免了子组件意外修改父组件的状态的情况，不然应用的数据流将很容易变得混乱而难以理解。 另外，每次父组件更新后，所有的子组件中的 props 都会被更新到最新值，这意味着你**不应该**在子组件中去更改一个 prop。若你这么做了，Vue 会在控制台上向你抛出警告： @@ -303,9 +303,9 @@ export default {
-想要更改 prop 通常都符合以下两种场景： +导致你想要更改一个 prop 的需求通常来源于以下两种场景： -1. **prop 被用于传入初始值；而子组件想在之后将其作为一个局部数据属性**。在这种情况下，最好是新定义一个局部数据属性，从 prop 上获取初始值即可： +1. **prop 被用于传入初始值；而子组件想在之后将其作为一个局部数据属性**。在这种情况下，最好是新定义一个局部数据属性，从 props 上获取初始值即可：
@@ -335,7 +335,7 @@ export default {
-2. **prop 以原始的形式传入，但还需作转换**。在这种情况中，最好是基于该 prop 值定义一个计算属性： +2. **需要对传入的 prop 值做进一步的转换**。在这种情况中，最好是基于该 prop 值定义一个计算属性：
@@ -363,17 +363,17 @@ export default {
-### 更改对象 / 数组类型的 prop {#mutating-object-array-props} +### 更改对象 / 数组类型的 props {#mutating-object-array-props} -当对象或数组作为 prop 被传入时，虽然子组件无法更改 prop 绑定，但仍然**可以**更改对象或数组内部的值。这是因为 JavaScript 的对象和数组是按引用传递，而对 Vue 来说，阻止这样的改变不但非常昂贵，也不合理。 +当对象或数组作为 props 被传入时，虽然子组件无法更改 props 绑定，但仍然**可以**更改对象或数组内部的值。这是因为 JavaScript 的对象和数组是按引用传递，而对 Vue 来说，禁止这样的改动虽然可能，但有很大的性能损耗，比较得不偿失。 -这种更改的主要缺陷是它允许了子组件以某种不明显的方式影响了父组件的状态，可能会使数据流在将来变得更难以推理。按照最佳实践来讲，你应该避免这样的更改，除非父子组件在设计上耦合得非常紧密。在大多数的用例场景中，子组件都应该[抛出一个事件](/guide/components/events.html)来通知父组件做出改变。 +这种更改的主要缺陷是它允许了子组件以某种不明显的方式影响父组件的状态，可能会使数据流在将来变得更难以理解。在最佳实践中，你应该尽可能避免这样的更改，除非父子组件在设计上本来就需要紧密耦合。在大多数场景下，子组件应该[抛出一个事件](/guide/components/events.html)来通知父组件做出改变。 ## Prop 校验 {#prop-validation} -组件可以更细致地指定对其 prop 的需求，比如你上面看到的类型限制，如果并没有指定要求，Vue 会在浏览器的 JavaScript 控制台中抛出警告来提醒你。这在开发为其他人提供的组件时非常有用。 +Vue 组件可以更细致地声明对传入的 props 的校验要求。比如我们上面已经看到过的类型声明，如果传入的值不满足类型要求，Vue 会在浏览器控制台中抛出警告来提醒使用者。这在开发给其他开发者使用的组件时非常有用。 -要描述对 prop 的校验，你可以向 `defineProps()` 宏`props` 选项提供一个带有 prop 校验的对象，而不是一个字符串数组，例如： +要声明对 props 的校验，你可以向 `defineProps()` 宏`props` 选项提供一个带有 props 校验选项的对象，例如：
@@ -483,7 +483,7 @@ export default { - 所有 prop 默认都是可选的，除非声明了 `required: true`。 - 除 `Boolean` 外的未传递的可选 prop 将会有一个默认值 `undefined`。 - + - `Boolean` 类型的未传递 prop 将被转换为 `false`。你应该为它设置一个 `default` 值来确保行为符合预期。 - 如果声明了 `default` 值，那么在 prop 的值被解析为 `undefined` 时，无论 prop 是未被传递还是显式指明的 `undefined`，都会改为 `default` 值。 @@ -492,7 +492,7 @@ export default {
-如果使用了[基于类型的 prop 声明](/api/sfc-script-setup.html#typescript-only-features)，Vue 会尽最大努力在运行时按照 prop 的类型标注进行编译。举个例子，`defineProps<{ msg: string }>` 会被编译为 `{ msg: { type: String, required: true }}`。 +如果使用了[基于类型的 prop 声明](/api/sfc-script-setup.html#typescript-only-features) ，Vue 会尽最大努力在运行时按照 prop 的类型标注进行编译。举例来说，`defineProps<{ msg: string }>` 会被编译为 `{ msg: { type: String, required: true }}`。
@@ -505,7 +505,7 @@ export default { ### 运行时类型检查 {#runtime-type-checks} -`type` 可以是下列这些原生构造器： +校验选项中的 `type` 可以是下列这些原生构造函数： - `String` - `Number` @@ -516,7 +516,7 @@ export default { - `Function` - `Symbol` -另外，`type` 也可以是自定义的类或构造函数，可以通过 `instanceof` 来检查、断言。例如下面这个类： +另外，`type` 也可以是自定义的类或构造函数，Vue 将会通过 `instanceof` 来检查类型是否匹配。例如下面这个类： ```js class Person { @@ -550,7 +550,7 @@ export default {
-这会校验 `author` prop 的值是否是由 `new Person` 创建的。 +Vue 会通过 `instanceof Person` 来校验 `author` prop 的值是否是 `Person` 类的一个实例。 ## Boolean 类型转换 {#boolean-casting} @@ -587,7 +587,7 @@ export default { ``` -当需要一个 prop 在声明时允许多种类型时，应该像这样： +当一个 prop 被声明为允许多种类型时，例如：
From 739e60758cf1a71aa0354c5a2d813ed706742729 Mon Sep 17 00:00:00 2001 From: Evan You Date: Mon, 1 Aug 2022 18:33:17 +0800 Subject: [PATCH 18/53] review: component events --- src/guide/components/events.md | 60 ++++++++++++++++------------------ src/guide/components/props.md | 4 +-- 2 files changed, 31 insertions(+), 33 deletions(-) diff --git a/src/guide/components/events.md b/src/guide/components/events.md index ae517a343..f5bd172aa 100644 --- a/src/guide/components/events.md +++ b/src/guide/components/events.md @@ -1,6 +1,6 @@ # 组件事件 {#component-events} -> 阅读此章节时，我们假设你已经读过[组件基础](/guide/essentials/component-basics)，若你对组件还完全不了解，请先阅读它。 +> 此章节假设你已经看过了[组件基础](/guide/essentials/component-basics)。若你还不了解组件是什么，请先阅读该章节。
@@ -43,15 +43,15 @@ export default { ``` -像组件与 prop 一样，事件的名字也提供了自动的转换。请注意，我们触发了一个以 camelCase 形式命名的事件，但在父组件中可以使用 kebab-case 形式来监听。与 [prop 大小写格式](/guide/components/props.html#prop-name-casing)一样，在模板中我们也推荐使用 kebab-case 形式来编写监听器。 +像组件与 prop 一样，事件的名字也提供了自动的格式转换。注意这里我们触发了一个以 camelCase 形式命名的事件，但在父组件中可以使用 kebab-case 形式来监听。与 [prop 大小写格式](/guide/components/props.html#prop-name-casing)一样，在模板中我们也推荐使用 kebab-case 形式来编写监听器。 :::tip -和原生 DOM 事件不太一样，组件触发的事件**不会冒泡**。你只能监听直接子组件触发的事件。 +和原生 DOM 事件不一样，组件触发的事件**没有冒泡机制**。你只能监听直接子组件触发的事件。平级组件或是跨越多层嵌套的组件间通信，应使用一个外部的事件总线，或是使用一个[全局状态管理方案](/guide/scaling-up/state-management.html)。 ::: ## 事件参数 {#event-arguments} -有时候我们会需要在触发事件时附带一个特定的值。举个例子，我们想要 `` 组件来管理文本会缩放得多大。在这个场景下，我们可以给 `$emit` 提供一个值作为额外的参数： +有时候我们会需要在触发事件时附带一个特定的值。举例来说，我们想要 `` 组件来管理文本会缩放得多大。在这个场景下，我们可以给 `$emit` 提供一个额外的参数： ```vue-html ``` -然后我们在父组件中监听事件，我们可以先简单写一个内联的箭头函数作为监听器，此时可以访问到事件附带的参数： +然后我们在父组件中监听事件，我们可以先简单写一个内联的箭头函数作为监听器，此函数会接收到事件附带的参数： ```vue-html ``` -或者用一个方法来作为事件处理函数： +或者，也可以用一个组件方法来作为事件处理函数： ```vue-html ``` -然后，可以从方法的第一个参数上取到这个值： +该方法也会接收到事件所传递的参数：
@@ -122,7 +122,7 @@ function buttonClick() { ``` -该 `defineEmits()` 宏**不能**在子函数中使用，他必须直接放置在 ` ``` -如果你正在搭配 ` ``` -更多细节：[如何为组件所抛出事件标注类型](/guide/typescript/composition-api.html#typing-component-emits) +TypeScript 用户请参考：[如何为组件所抛出事件标注类型](/guide/typescript/composition-api.html#typing-component-emits)
@@ -199,11 +199,11 @@ export default { } ``` -你也可以看看这一章了解[如何为组件所抛出的事件标注类型](/guide/typescript/options-api.html#typing-component-emits)。 +TypeScript 用户请参考：[如何为组件所抛出的事件标注类型](/guide/typescript/options-api.html#typing-component-emits)。
-尽管是可选的，我们还是推荐你定义所有要触发的事件，以此更好地在代码中描述和呈现组件的作用。这也使得 Vue 能更好地将事件和[透传 attribute](/guide/components/attrs.html#v-on-listener-inheritance) 作出区分。 +尽管事件声明是可选的，我们还是推荐你完整地声明所有要触发的事件，以此在代码中作为文档记录组件的用法。同时，事件声明能让 Vue 更好地将事件和[透传 attribute](/guide/components/attrs.html#v-on-listener-inheritance) 作出区分，从而避免一些由第三方代码触发的自定义 DOM 事件所导致的边界情况。 :::tip 如果一个原生事件的名字 (例如 `click`) 被定义在 `emits` 选项中，则监听器只会监听组件触发的 `click` 事件而不会再响应原生的 `click` 事件。 @@ -211,7 +211,7 @@ export default { ## 事件校验 {#events-validation} -和对 prop 添加类型校验的方式类似，所有触发的事件也可以使用对象形式来描述。 +和对 props 添加类型校验的方式类似，所有触发的事件也可以使用对象形式来描述。 要为事件添加校验，那么事件可以被赋值为一个函数，接受的参数就是抛出事件时传入 `this.$emit``emit` 的内容，返回一个布尔值来表明事件是否合法。 @@ -271,13 +271,13 @@ export default { ## 配合 `v-model` 使用 {#usage-with-v-model} -自定义事件可以用来创建对应 `v-model` 的自定义输入： +自定义事件可以用于开发支持 `v-model` 的自定义表单组件。回忆一下 `v-model` 的用法： ```vue-html ``` -和下面这段代码是等价的： +上面的代码其实等价于下面这段（编译器会对 `v-model` 进行展开）： ```vue-html ``` -当使用在一个组件上时，`v-model` 是这样做的： +而当使用在一个组件上时，`v-model` 会被展开为如下的形式： ```vue-html ``` -为了使组件能像这样工作，内部的 `` 组件必须： +要让这个例子实际工作起来，`` 组件内部需要做两件事： -- 绑定 `value` attribute 到 `modelValue` prop -- 输入新的值时在 `input` 元素上触发 `update:modelValue` 事件 +1. 将内部原生 `input` 元素的 `value` attribute 绑定到 `modelValue` prop +2. 输入新的值时在 `input` 元素上触发 `update:modelValue` 事件 这里是相应的代码： @@ -358,7 +358,7 @@ defineEmits(['update:modelValue'])
-另一种在组件内实现 `v-model` 的方式是使用一个可写的，同时具有 getter 和 setter 的计算属性。`get` 方法需返回 `modelValue` 属性而 `set` 方法需触发相应的事件： +另一种在组件内实现 `v-model` 的方式是使用一个可写的，同时具有 getter 和 setter 的计算属性。`get` 方法需返回 `modelValue` prop，而 `set` 方法需触发相应的事件：
@@ -416,13 +416,13 @@ const value = computed({ ### `v-model` 的参数 {#v-model-arguments} -默认情况下，`v-model` 在组件上都是使用 `modelValue` 作为 prop，以 `update:modelValue` 作为对应的事件。我们可以通过给 `v-model` 指定一个参数来更改这些名字： +默认情况下，`v-model` 在组件上都是使用 `modelValue` 作为 prop，并以 `update:modelValue` 作为对应的事件。我们可以通过给 `v-model` 指定一个参数来更改这些名字： ```vue-html ``` -在这个例子中，子组件应该有一个 `title` prop，并通过触发 `update:title` 事件更新父组件值： +在这个例子中，子组件应声明一个 `title` prop，并通过触发 `update:title` 事件更新父组件值：
@@ -471,9 +471,7 @@ export default { ### 多个 `v-model` 绑定 {#multiple-v-model-bindings} -通过我们刚才在 [`v-model` 参数](#v-model-arguments)小节中学到的，利用一个特定的 prop 和一个特定事件，可以在一个组件上创建多个 `v-model` 双向绑定： - -每一个 `v-model` 都会同步不同的 prop，而不需要在组件上写更多额外的选项： +利用刚才在 [`v-model` 参数](#v-model-arguments)小节中学到的技巧，我们可以在一个组件上创建多个 `v-model` 双向绑定，每一个 `v-model` 都会同步不同的 prop： ```vue-html ``` -要给组件的 `v-model` 添加修饰符，都可以通过 `modelModifiers` prop 在组件内访问到。在下面的例子中，我们会创建一个包含 `modelModifiers` prop 的组件，它的默认值是一个空对象： +组件的 `v-model` 上所添加的修饰符，可以通过 `modelModifiers` prop 在组件内访问到。在下面的组件中，我们声明了 `modelModifiers` 这个 prop，它的默认值是一个空对象：
@@ -609,7 +607,7 @@ export default { 注意这里组件的 `modelModifiers` prop 包含了 `capitalize` 且其值为 `true`，因为它在模板中的 `v-model` 绑定上被使用了。 -此时和 prop 相关的已经准备完毕，我们可以开始检索 `modelModifiers` 对象的 key 并写一个处理函数来改变抛出事件附带的值。在下面的代码里我们就是在每次 `` 元素抛出 `input` 事件时执行大写首字母： +有了 `modelModifiers` 这个 prop，我们就可以在原生事件侦听函数中检查它的值，然后决定触发的自定义事件中要向父组件传递什么值。在下面的代码里，我们就是在每次 `` 元素触发 `input` 事件时将值的首字母大写：
@@ -672,13 +670,13 @@ export default {
-对于又有参数又有修饰符的 `v-model` 绑定，生成的 prop 名将是 `arg + "Modifiers"`。举个例子： +对于又有参数又有修饰符的 `v-model` 绑定，生成的 prop 名将是 `arg + "Modifiers"`。举例来说： ```vue-html ``` -则相应的声明应该是： +相应的声明应该是：
diff --git a/src/guide/components/props.md b/src/guide/components/props.md index c60aa37d5..61a79f408 100644 --- a/src/guide/components/props.md +++ b/src/guide/components/props.md @@ -121,7 +121,7 @@ defineProps<{ ### Prop 名字格式 {#prop-name-casing} -如果一个 prop 的名字很长，应使用 camelCase 格式，因为它们是合法的 JavaScript 标识符，可以直接在模板的表达式中使用，也可以避免在作为属性 key 名时必须加上引号。 +如果一个 prop 的名字很长，应使用 camelCase 形式，因为它们是合法的 JavaScript 标识符，可以直接在模板的表达式中使用，也可以避免在作为属性 key 名时必须加上引号。
@@ -148,7 +148,7 @@ export default { {{ greetingMessage }} ``` -虽然理论上你也可以在子组件传递 props 时使用 camelCase 格式 (使用 [DOM 模板](/guide/essentials/component-basics.html#dom-template-parsing-caveats)时例外)，但实际上为了和 HTML attribute 对齐，我们通常会将其写为 kebab-case 格式： +虽然理论上你也可以在子组件传递 props 时使用 camelCase 形式 (使用 [DOM 模板](/guide/essentials/component-basics.html#dom-template-parsing-caveats)时例外)，但实际上为了和 HTML attribute 对齐，我们通常会将其写为 kebab-case 形式： ```vue-html From c30e5c21ad0d4829257a3eeb540e158e33400f7c Mon Sep 17 00:00:00 2001 From: Evan You Date: Mon, 1 Aug 2022 22:38:07 +0800 Subject: [PATCH 19/53] review: fallthrough attributes --- src/guide/components/attrs.md | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/src/guide/components/attrs.md b/src/guide/components/attrs.md index 53f6cbec5..042ba546a 100644 --- a/src/guide/components/attrs.md +++ b/src/guide/components/attrs.md @@ -4,20 +4,20 @@ outline: deep # 透传 Attribute {#fallthrough-attributes} -> 阅读此章节时，我们假设你已经读过[组件基础](/guide/essentials/component-basics)，若你对组件还完全不了解，请先阅读它。 +> 此章节假设你已经看过了[组件基础](/guide/essentials/component-basics)。若你还不了解组件是什么，请先阅读该章节。 ## Attribute 继承 {#attribute-inheritance} -“透传 attribute”是传递给组件的 attribute 或者 `v-on` 事件监听器，但并没有显式地声明在所接收组件的 [props](./props) 或 [emits](./events.html#defining-custom-events) 上。最常见的例子就是 `class`、`style` 和 `id`。 +“透传 attribute”指的是传递给一个组件，却没有被该组件声明为 [props](./props) 或 [emits](./events.html#defining-custom-events) 的 attribute 或者 `v-on` 事件监听器。最常见的例子就是 `class`、`style` 和 `id`。 -当一个组件以单个元素为根作渲染时，透传的 attribute 会自动添加到根元素的 attribute 中。举个例子，下面这个 `` 组件有这样的模板： +当一个组件以单个元素为根作渲染时，透传的 attribute 会自动被添加到根元素上。举例来说，假如我们有一个 `` 组件，它的模板长这样： ```vue-html ``` -一个父组件使用了这个组件： +一个父组件使用了这个组件，并且传入了 `class`： ```vue-html @@ -29,16 +29,18 @@ outline: deep ``` +这里，`` 并没有将 `class` 声明为一个它所接受的 prop，所以 `class` 被视作透传 attribute，自动透传到了 `` 的根元素上。 + ### 对 `class` 和 `style` 的合并 {#class-and-style-merging} -如果一个子组件的根元素已经有了 `class` 或 `style` attribute，它会和从父组件上继承的值合并。将之前的 `` 组件的模板改成这样： +如果一个子组件的根元素已经有了 `class` 或 `style` attribute，它会和从父组件上继承的值合并。如果我们将之前的 `` 组件的模板改成这样： ```vue-html ``` -最后渲染出的 DOM 结果是： +则最后渲染出的 DOM 结果会变成： ```html @@ -52,18 +54,18 @@ outline: deep ``` -监听器 `click` 会被添加到 `` 的根元素，即那个原生的 `
-最常见的需要禁用 attribute 继承的场景就是 attribute 需要应用在根节点以外的其他元素上。通过设置 `inheritAttrs` 选项为 `false`，你可以完全控制透传进来的 attribute 如何应用。 +最常见的需要禁用 attribute 继承的场景就是 attribute 需要应用在根节点以外的其他元素上。通过设置 `inheritAttrs` 选项为 `false`，你可以完全控制透传进来的 attribute 被如何使用。 这些透传进来的 attribute 可以在模板的表达式中直接用 `$attrs` 访问到。 @@ -102,7 +104,7 @@ export default { Fallthrough attribute: {{ $attrs }} ``` -这个 `$attrs` 对象包含了除组件的 `props` 和 `emits` 属性外的所有其他 attribute，例如 `class`，`style`，`v-on` 监听器等等。 +这个 `$attrs` 对象包含了除组件所声明的 `props` 和 `emits` 之外的所有其他 attribute，例如 `class`，`style`，`v-on` 监听器等等。 有几点需要注意： @@ -126,7 +128,7 @@ export default {
``` -请记住[没有参数的 `v-bind`](/guide/essentials/template-syntax.html#dynamically-binding-multiple-attributes) 会将一个对象的所有属性都作为 attribute 应用到目标元素上。 +小提示：[没有参数的 `v-bind`](/guide/essentials/template-syntax.html#dynamically-binding-multiple-attributes) 会将一个对象的所有属性都作为 attribute 应用到目标元素上。 ## 多根节点的 Attribute 继承 {#attribute-inheritance-on-multiple-root-nodes} From bc0a4fdb75a1024ca49c13c93710c9fe777d2638 Mon Sep 17 00:00:00 2001 From: Evan You Date: Mon, 1 Aug 2022 22:41:10 +0800 Subject: [PATCH 20/53] =?UTF-8?q?=E4=B8=BE=E4=B8=AA=E4=BE=8B=E5=AD=90=20->?= =?UTF-8?q?=20=E4=B8=BE=E4=BE=8B=E6=9D=A5=E8=AF=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/api/built-in-directives.md | 2 +- src/api/built-in-special-attributes.md | 2 +- src/api/built-in-special-elements.md | 4 ++-- src/api/options-composition.md | 2 +- src/api/options-misc.md | 2 +- src/api/sfc-spec.md | 2 +- src/guide/best-practices/performance.md | 6 +++--- src/guide/best-practices/security.md | 2 +- src/guide/built-ins/teleport.md | 2 +- src/guide/built-ins/transition.md | 2 +- src/guide/components/events.md | 2 +- src/guide/components/slots.md | 22 +++++++++++----------- src/guide/essentials/class-and-style.md | 6 +++--- src/guide/essentials/component-basics.md | 2 +- src/guide/essentials/computed.md | 2 +- src/guide/essentials/event-handling.md | 6 +++--- src/guide/essentials/list.md | 2 +- src/guide/essentials/template-syntax.md | 2 +- src/guide/essentials/watchers.md | 4 ++-- src/guide/extras/rendering-mechanism.md | 4 ++-- src/guide/reusability/composables.md | 4 ++-- src/guide/reusability/custom-directives.md | 4 ++-- src/guide/reusability/plugins.md | 2 +- src/guide/scaling-up/ssr.md | 2 +- src/guide/typescript/composition-api.md | 2 +- src/guide/typescript/options-api.md | 2 +- 26 files changed, 47 insertions(+), 47 deletions(-) diff --git a/src/api/built-in-directives.md b/src/api/built-in-directives.md index e1cdb8edd..c9d54e89a 100644 --- a/src/api/built-in-directives.md +++ b/src/api/built-in-directives.md @@ -469,7 +469,7 @@ - **详细信息** - 缓存一个模板的子树。元素和组件都可以使用。为了实现缓存，该指令期待传入一个定长地依赖值数组进行比较。如果数组里的每个值都与最后一次的渲染相同，那么整个子树的更新将被跳过。举个例子： + 缓存一个模板的子树。元素和组件都可以使用。为了实现缓存，该指令期待传入一个定长地依赖值数组进行比较。如果数组里的每个值都与最后一次的渲染相同，那么整个子树的更新将被跳过。举例来说： ```vue-html
diff --git a/src/api/built-in-special-attributes.md b/src/api/built-in-special-attributes.md index e45ec0922..5f64ff64d 100644 --- a/src/api/built-in-special-attributes.md +++ b/src/api/built-in-special-attributes.md @@ -25,7 +25,7 @@ - 在适当的时候触发组件的生命周期钩子 - 触发过渡 - 举个例子： + 举例来说： ```vue-html diff --git a/src/api/built-in-special-elements.md b/src/api/built-in-special-elements.md index cb0296c86..798e0fc84 100644 --- a/src/api/built-in-special-elements.md +++ b/src/api/built-in-special-elements.md @@ -67,7 +67,7 @@ ``` - [内置组件](./built-in-components.html)都可以传递给 `is`，但是如果想通过名称传递则必须先对其进行注册。举个例子： + [内置组件](./built-in-components.html)都可以传递给 `is`，但是如果想通过名称传递则必须先对其进行注册。举例来说： ```vue diff --git a/src/api/options-composition.md b/src/api/options-composition.md index 7eb25eec7..5a99ccdff 100644 --- a/src/api/options-composition.md +++ b/src/api/options-composition.md @@ -183,7 +183,7 @@ - **详细信息** - `mixins` 选项接受一个 mixin 对象数组。这些 mixin 对象可以像普通的实例对象一样包含实例选项，它们将使用一定的选项合并逻辑与最终的选项进行合并。举个例子，如果你的 mixin 包含了一个 `created` 钩子，而组件自身也有一个，那么这两个函数都会被调用。 + `mixins` 选项接受一个 mixin 对象数组。这些 mixin 对象可以像普通的实例对象一样包含实例选项，它们将使用一定的选项合并逻辑与最终的选项进行合并。举例来说，如果你的 mixin 包含了一个 `created` 钩子，而组件自身也有一个，那么这两个函数都会被调用。 Mixin 钩子的调用顺序与提供它们的选项顺序相同，且会在组件自身的钩子前被调用。 diff --git a/src/api/options-misc.md b/src/api/options-misc.md index 0a248daa1..587c0a0bc 100644 --- a/src/api/options-misc.md +++ b/src/api/options-misc.md @@ -20,7 +20,7 @@ - 在 Vue 开发者工具中的组件树显示时 - 在组件抛出的警告追踪栈信息中显示时 - 当你在使用单文件组件时，组件已经会根据其文件名推导出其名称。举个例子，一个名为 `MyComponent.vue` 的文件会推导出显示名称为“MyComponent”。 + 当你在使用单文件组件时，组件已经会根据其文件名推导出其名称。举例来说，一个名为 `MyComponent.vue` 的文件会推导出显示名称为“MyComponent”。 另一种场景是当一个组件通过 [`app.component`](/api/application.html#app-component) 被全局注册时，这个全局 ID 就自动被设为了其名称。 diff --git a/src/api/sfc-spec.md b/src/api/sfc-spec.md index a4a095ae9..7248f140e 100644 --- a/src/api/sfc-spec.md +++ b/src/api/sfc-spec.md @@ -62,7 +62,7 @@ export default { ### 自定义块 {#custom-blocks} -在一个 `*.vue` 文件中可以为任何项目特定需求使用额外的自定义块。举个例子，一个用作写文档的 `` 块。这里是一些自定义块的真实用例： +在一个 `*.vue` 文件中可以为任何项目特定需求使用额外的自定义块。举例来说，一个用作写文档的 `` 块。这里是一些自定义块的真实用例： - [Gridsome：``](https://gridsome.org/docs/querying-data/) - [vite-plugin-vue-gql：``](https://github.com/wheatjs/vite-plugin-vue-gql) diff --git a/src/guide/best-practices/performance.md b/src/guide/best-practices/performance.md index f0247108e..f88302dc2 100644 --- a/src/guide/best-practices/performance.md +++ b/src/guide/best-practices/performance.md @@ -12,7 +12,7 @@ Vue 的设计对于大多数常见的使用情况来说都是性能优秀的， - **页面加载性能**：应用展示出内容与首次访问时变为可交互的速度。这通常是使用网络的重要指标来衡量，如最大的[最大内容绘制 (LCP)](https://web.dev/lcp/) 和[首次输入延迟](https://web.dev/fid/)。 -- **更新性能**：应用响应用户输入更新的速度。举个例子，当用户在一个搜索框中输入时列表的更新速度，或者用户在一个单页面应用 (SPA) 中点击链接跳转页面时的切换速度。 +- **更新性能**：应用响应用户输入更新的速度。举例来说，当用户在一个搜索框中输入时列表的更新速度，或者用户在一个单页面应用 (SPA) 中点击链接跳转页面时的切换速度。 虽然最理想的情况是将两者都最大化，但是不同的前端架构往往会影响到在这些方面是否能达到更理想的性能。此外，你所构建的应用程序的类型极大地影响了你在性能方面应该优先考虑的问题。因此，确保最佳性能的第一步是为你的应用类型挑选合适的架构： @@ -45,13 +45,13 @@ Vue 的设计对于大多数常见的使用情况来说都是性能优秀的， - 尽可能地采用构建步骤 - - 如果使用的是相对现代的打包工具，许多 Vue 的 API 都是可以被 [tree-shake](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) 的。举个例子，如果你根本没有使用到内置的 `` 组件，它将不会被打包进入最终的产物里。Tree-shaking 也可以移除你源代码中其他未使用到的模块。 + - 如果使用的是相对现代的打包工具，许多 Vue 的 API 都是可以被 [tree-shake](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) 的。举例来说，如果你根本没有使用到内置的 `` 组件，它将不会被打包进入最终的产物里。Tree-shaking 也可以移除你源代码中其他未使用到的模块。 - 当使用了构建步骤时，模板会被预编译，因此我们无须在浏览器中载入 Vue 编译器。这在同样最小化加上 gzip 优化下会相对缩小 **14kb** 并避免运行时的编译开销。 - 在引入新的依赖项时要小心包体积膨胀！在现实的应用中，包体积膨胀通常因为无意识地引入了过重的依赖导致的。 - - 如果使用了构建步骤，应当尽量选择提供 ES 模块格式的依赖，它们对 tree-shaking 更友好。举个例子，选择 `lodash-es` 比 `lodash` 更好。 + - 如果使用了构建步骤，应当尽量选择提供 ES 模块格式的依赖，它们对 tree-shaking 更友好。举例来说，选择 `lodash-es` 比 `lodash` 更好。 - 查看依赖的体积，并评估与其所提供的功能之间的性价比。如果依赖对 tree-shaking 友好，实际增加的体积大小将取决于你从它之中导入的 API。像 [bundlejs.com](https://bundlejs.com/) 这样的工具可以用来做快速的检查，但是根据实际的构建设置来评估总是最准确的。 diff --git a/src/guide/best-practices/security.md b/src/guide/best-practices/security.md index 70ce3019c..aae3c4f88 100644 --- a/src/guide/best-practices/security.md +++ b/src/guide/best-practices/security.md @@ -8,7 +8,7 @@ ## 首要规则：不要使用无法信赖的模板 {#rule-no-1-never-use-non-trusted-templates} -使用 Vue 时最基本的安全规则就是**不要将无法信赖的内容作为你的组件模板**。使用无法信赖的模板相当于允许任意的 JavaScript 在你的应用中执行。更糟糕的是，如果在服务端渲染时执行了这些代码，可能会导致服务器被攻击。举个例子： +使用 Vue 时最基本的安全规则就是**不要将无法信赖的内容作为你的组件模板**。使用无法信赖的模板相当于允许任意的 JavaScript 在你的应用中执行。更糟糕的是，如果在服务端渲染时执行了这些代码，可能会导致服务器被攻击。举例来说： ```js Vue.createApp({ diff --git a/src/guide/built-ins/teleport.md b/src/guide/built-ins/teleport.md index 4421eed19..b18beb836 100644 --- a/src/guide/built-ins/teleport.md +++ b/src/guide/built-ins/teleport.md @@ -160,7 +160,7 @@ let open = $ref(false) ## 禁用传送门 {#disabling-teleport} -在某些场景中，你们可能需要视情况禁用 ``。举个例子，我们想要在桌面端将一个组件当做浮层来渲染，但在移动端则当作行内组件。可以对 `` 动态地传入一个 `disabled` prop 来处理这两种不同情况。 +在某些场景中，你们可能需要视情况禁用 ``。举例来说，我们想要在桌面端将一个组件当做浮层来渲染，但在移动端则当作行内组件。可以对 `` 动态地传入一个 `disabled` prop 来处理这两种不同情况。 ```vue-html diff --git a/src/guide/built-ins/transition.md b/src/guide/built-ins/transition.md index e11f8cb6b..68b0d9430 100644 --- a/src/guide/built-ins/transition.md +++ b/src/guide/built-ins/transition.md @@ -252,7 +252,7 @@ Vue 提供了两个内置组件，可以帮助你制作基于状态变化的过 Vue 需要附加事件监听器，以便知道过渡何时结束。可以是 `transitionend` 或 `animationend`，这取决于你所应用的 CSS 规则。如果你仅仅使用二者的其中之一，Vue 可以自动探测到正确的类型。 -然而在某些场景中，你或许想要在同一个元素上同时使用它们两个。举个例子，Vue 触发了一个 CSS 动画，同时鼠标悬停触发另一个 CSS 过渡。此时你需要显式地传入 `type` prop 来声明，告诉 Vue 需要关心哪种类型，传入的值是 `animation` 或 `transition`： +然而在某些场景中，你或许想要在同一个元素上同时使用它们两个。举例来说，Vue 触发了一个 CSS 动画，同时鼠标悬停触发另一个 CSS 过渡。此时你需要显式地传入 `type` prop 来声明，告诉 Vue 需要关心哪种类型，传入的值是 `animation` 或 `transition`： ```vue-html ... diff --git a/src/guide/components/events.md b/src/guide/components/events.md index f5bd172aa..d80e2c575 100644 --- a/src/guide/components/events.md +++ b/src/guide/components/events.md @@ -95,7 +95,7 @@ function increaseCount(n) {
:::tip -所有传入 `$emit()` 的额外参数都会被直接传向监听器。举个例子，`$emit('foo', 1, 2, 3)` 触发后，监听器函数将会收到这三个参数值。 +所有传入 `$emit()` 的额外参数都会被直接传向监听器。举例来说，`$emit('foo', 1, 2, 3)` 触发后，监听器函数将会收到这三个参数值。 ::: ## 声明触发的事件 {#declaring-emitted-events} diff --git a/src/guide/components/slots.md b/src/guide/components/slots.md index 4124a615f..74d520bf2 100644 --- a/src/guide/components/slots.md +++ b/src/guide/components/slots.md @@ -1,14 +1,14 @@ # 插槽 {#slots} -> 阅读此章节时，我们假设你已经读过[组件基础](/guide/essentials/component-basics)，若你对组件还完全不了解，请先阅读它。 +> 此章节假设你已经看过了[组件基础](/guide/essentials/component-basics)。若你还不了解组件是什么，请先阅读该章节。 -## 插槽内容与插口 {#slot-content-and-outlet} +## 插槽内容与出口 {#slot-content-and-outlet} -我们已经学习过组件能够接收任意类型的 JavaScript 值作为 props，但组件要如何接收模板内容呢？在某些场景中，我们可能想要为子组件传递一些模板片段，让子组件在它们的组件中渲染这些片段。 +在之前的章节中，我们已经了解到组件能够接收任意类型的 JavaScript 值作为 props，但组件要如何接收模板内容呢？在某些场景中，我们可能想要为子组件传递一些模板片段，让子组件在它们的组件中渲染这些片段。 -举个例子，这里有一个 `` 组件，可以像这样使用： +举例来说，这里有一个 `` 组件，可以像这样使用： ```vue-html{2} @@ -20,11 +20,11 @@ ```vue-html{2} ``` -`` 元素是一个**插槽的插口**，标示了父元素提供的**插槽内容**将在哪里被渲染。 +`` 元素是一个**插槽的出口**，标示了父元素提供的**插槽内容**将在哪里被渲染。 ![插槽图示](./images/slots.png) @@ -93,7 +93,7 @@ Vue 组件的插槽机制是受[原生 Web Component `` 元素](https://de ## 渲染作用域 {#render-scope} -插槽内容可以访问到父组件的数据作用域，因为插槽内容本身是在父组件模板中定义的。举个例子： +插槽内容可以访问到父组件的数据作用域，因为插槽内容本身是在父组件模板中定义的。举例来说： ```vue-html {{ message }} @@ -163,7 +163,7 @@ Vue 组件的插槽机制是受[原生 Web Component `` 元素](https://de ## 具名插槽 {#named-slots} -有时在一个组件中包含多个插槽的插口是很有用的。举个例子，在一个 `` 组件中，有如下这样的模板： +有时在一个组件中包含多个插槽的出口是很有用的。举例来说，在一个 `` 组件中，有如下这样的模板： ```vue-html
@@ -195,9 +195,9 @@ Vue 组件的插槽机制是受[原生 Web Component `` 元素](https://de
``` -没有提供 `name` 的 `` 插口会隐式地命名为“default”。 +没有提供 `name` 的 `` 出口会隐式地命名为“default”。 -在父组件中使用 `` 时，我们需要一种方式将多个插槽内容传入到各自目标插槽的插口。此时就需要用到**具名插槽**了： +在父组件中使用 `` 时，我们需要一种方式将多个插槽内容传入到各自目标插槽的出口。此时就需要用到**具名插槽**了： 要为具名插槽传入内容，我们需要使用一个含 `v-slot` 指令的 `