From fbda470f8d76002845f56524ecda8281528f4e7c Mon Sep 17 00:00:00 2001 From: Jinjiang Date: Sun, 15 Aug 2021 11:32:18 +0800 Subject: [PATCH 1/4] Translated new parts of computed-watch-api and directives api --- src/api/computed-watch-api.md | 6 +++--- src/api/directives.md | 34 +++++++++++++++------------------- src/guide/web-components.md | 2 +- 3 files changed, 19 insertions(+), 23 deletions(-) diff --git a/src/api/computed-watch-api.md b/src/api/computed-watch-api.md index 353d85c51..12517eb1f 100644 --- a/src/api/computed-watch-api.md +++ b/src/api/computed-watch-api.md @@ -103,13 +103,13 @@ type StopHandle = () => void **参考**：[`watchEffect` 指南](../guide/reactivity-computed-watchers.html#watcheffect) - ## `watchPostEffect` -Alias of `watchEffect` with `flush: 'post'` option. +`watchEffect` 带有 `flush: 'post'` 选项的别名。 + ## `watchSyncEffect` -Alias of `watchEffect` with `flush: 'sync'` option. +`watchEffect` 带有 `flush: 'sync'` 选项的别名。 ## `watch` diff --git a/src/api/directives.md b/src/api/directives.md index 06f9bd23a..edbc35bff 100644 --- a/src/api/directives.md +++ b/src/api/directives.md @@ -246,9 +246,8 @@ - **修饰符**： - `.camel` - 将 kebab-case attribute 名转换为 camelCase。 - - - `.prop` - force a binding to be set as a DOM property. - - `.attr` - force a binding to be set as a DOM attribute. + - `.prop` - 将一个绑定强制设置为一个 DOM property。 + - `.attr` - 将一个绑定强制设置为一个 DOM attribute。 - **用法**： @@ -300,8 +299,7 @@ ``` - - When setting a binding on an element, Vue by default checks whether the element has the key defined as a property using an `in` operator check. If the property is defined, Vue will set the value as a DOM property instead of an attribute. This should work in most cases, but you can override this behavior by explicitly using `.prop` or `.attr` modifiers. This is sometimes necessary, especially when [working with custom elements](/guide/web-components.html#passing-dom-properties). + 当在一个元素上设置一个绑定的时候，Vue 会默认通过 `in` 操作检测该元素是否有一个被定义为 property 的 key。如果该 property 被定义了，Vue 会将这个值设置为一个 DOM property 而不是 attribute。大多数情况下，这样工作是正常的，但你也可以通过 `.prop` 或 `.attr` 修饰符显性地覆写这个行为。有的时候这是必要的，尤其是[基于自定义元素的工作](/guide/web-components.html#传递-dom-property)。 The `.prop` modifier also has a dedicated shorthand, `.`: @@ -466,21 +464,19 @@ ``` - - Since 3.2, you can also memoize part of the template with invalidation conditions using [`v-memo`](#v-memo). + 从 3.2 开始，你也可以使用 [`v-memo`](#v-memo) 记住模板的无效条件的那部分。 - **参考**： - [数据绑定语法- 插值](../guide/template-syntax.html#文本) - [v-memo](#v-memo) - ## v-memo -- **Expects:** `Array` +- **预期**：`Array` -- **Details:** +- **用法**： - Memoize a sub-tree of the template. Can be used on both elements and components. The directive expects a fixed-length array of dependency values to compare for the memoization. If every value in the array was the same as last render, then updates for the entire sub-tree will be skipped. For example: + 记住一个模板的子树。元素和组件上都可以使用。该指令接收一个固定长度的数组作为依赖值进行记忆比对。如果数组中的每个值都和上次渲染的时候相同，则整个该子树的更新会被跳过。例如： ```html
@@ -488,13 +484,13 @@
``` - When the component re-renders, if both `valueA` and `valueB` remain the same, all updates for this `
` and its children will be skipped. In fact, even the Virtual DOM VNode creation will also be skipped since the memoized copy of the sub-tree can be reused. + 当组件被重新渲染时，如果 `valueA` 和 `valueB` 都还是原来的值，则这个 `
` 及其子元素的所有更新将会被跳过。实际上，甚至连 Virtual DOM 的 VNode 创建也会被跳过，因为被记住的子树的拷贝是可复用的。 - It is important to specify the memoization array correctly, otherwise we may skip updates that should indeed be applied. `v-memo` with an empty dependency array (`v-memo="[]"`) would be functionally equivalent to `v-once`. + 正确指定记忆数组是非常重要的，否则我们可能会错过应有的更新。配合空依赖数组使用的 `v-memo` (`v-memo="[]"`) 功能上等同于 `v-once`。 - **Usage with `v-for`** + **和 `v-for` 一起使用** - `v-memo` is provided solely for micro optimizations in performance-critical scenarios and should be rarely needed. The most common case where this may prove helpful is when rendering large `v-for` lists (where `length > 1000`): + `v-memo` 仅供性能优先场景的微观优化，这种需求应该是罕见的。最常见的有帮助的情况是渲染 `v-for` 长列表 (长度大于 1000)： ```html
@@ -503,15 +499,15 @@
``` - When the component's `selected` state changes, a large amount of VNodes will be created even though most of the items remained exactly the same. The `v-memo` usage here is essentially saying "only update this item if it went from non-selected to selected, or the other way around". This allows every unaffected item to reuse its previous VNode and skip diffing entirely. Note we don't need to include `item.id` in the memo dependency array here since Vue automatically infers it from the item's `:key`. + 当组件的 `selected` 状态改变时，大量 VNode 将会被创建，哪怕大多数条目不会改变。`v-memo` 用在这里相当于在说“只在条目由未选中变为选中或反之的情况下才会被更新”。这使得每个没有被影响到的条目复用了之前的 VNode 而跳过了整个差异比对。注意我们不需要在记忆依赖数组中包含 `item.id`，因为 Vue 会从条目的 `:key` 中自动推导出来。 :::warning - When using `v-memo` with `v-for`, make sure they are used on the same element. **`v-memo` does not work inside `v-for`.** + 当和 `v-for` 一起使用 `v-memo` 时，请确保它们作用在相同的元素上。**`v-memo` 不能用在 `v-for` 内部。** ::: - `v-memo` can also be used on components to manually prevent unwanted updates in certain edge cases where the child component update check has been de-optimized. But again, it is the developer's responsibility to specify correct dependency arrays to avoid skipping necessary updates. + `v-memo` 也可以被用在组件上，以在一些子组件被去优化的极端情况下手动阻止不需要的更新。不过再次强调，开发者有责任指定正确的依赖数组以避免错过必要的更新。 -- **See also:** +- **参考**： - [v-once](#v-once) ## v-is diff --git a/src/guide/web-components.md b/src/guide/web-components.md index c690da516..680bf4cbe 100644 --- a/src/guide/web-components.md +++ b/src/guide/web-components.md @@ -55,7 +55,7 @@ module.exports = { } ``` -### Passing DOM Properties +### 传递 DOM Property Since DOM attributes can only be strings, we need to pass complex data to custom elements as DOM properties. When setting props on a custom element, Vue 3 automatically checks DOM-property presence using the `in` operator and will prefer setting the value as a DOM property if the key is present. This means that, in most cases, you won't need to think about this if the custom element follows the [recommended best practices](https://developers.google.com/web/fundamentals/web-components/best-practices#aim-to-keep-primitive-data-attributes-and-properties-in-sync,-reflecting-from-property-to-attribute,-and-vice-versa.). From f5cbc7bc8878440f02fcc753774bcb8c66720321 Mon Sep 17 00:00:00 2001 From: Jinjiang Date: Sat, 21 Aug 2021 09:44:56 +0800 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: wxsm --- src/api/computed-watch-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/api/computed-watch-api.md b/src/api/computed-watch-api.md index 12517eb1f..be24266d2 100644 --- a/src/api/computed-watch-api.md +++ b/src/api/computed-watch-api.md @@ -105,11 +105,11 @@ type StopHandle = () => void ## `watchPostEffect` -`watchEffect` 带有 `flush: 'post'` 选项的别名。 +`watchEffect` 的别名，带有 `flush: 'post'` 选项。 ## `watchSyncEffect` -`watchEffect` 带有 `flush: 'sync'` 选项的别名。 +`watchEffect` 的别名，带有 `flush: 'sync'` 选项。 ## `watch` From b8657e61155835e6d69c4ee446aa637d73f218c4 Mon Sep 17 00:00:00 2001 From: Jinjiang Date: Sat, 21 Aug 2021 23:58:32 +0800 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: GU Yiling --- src/api/directives.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/api/directives.md b/src/api/directives.md index edbc35bff..befe10655 100644 --- a/src/api/directives.md +++ b/src/api/directives.md @@ -484,13 +484,13 @@
``` - 当组件被重新渲染时，如果 `valueA` 和 `valueB` 都还是原来的值，则这个 `
` 及其子元素的所有更新将会被跳过。实际上，甚至连 Virtual DOM 的 VNode 创建也会被跳过，因为被记住的子树的拷贝是可复用的。 + 当组件被重新渲染时，如果 `valueA` 和 `valueB` 都还是原来的值，则这个 `
` 及其子元素的所有更新将会被跳过。实际上，甚至连虚拟 DOM 的 VNode 创建也会被跳过，因为被记住的子树的拷贝是可复用的。 正确指定记忆数组是非常重要的，否则我们可能会错过应有的更新。配合空依赖数组使用的 `v-memo` (`v-memo="[]"`) 功能上等同于 `v-once`。 **和 `v-for` 一起使用** - `v-memo` 仅供性能优先场景的微观优化，这种需求应该是罕见的。最常见的有帮助的情况是渲染 `v-for` 长列表 (长度大于 1000)： + `v-memo` 仅供性能敏感场景的针对性优化，会用到场景很少。渲染 `v-for` 长列表 (长度大于 1000) 可能是它最有用的场景： ```html
From 227d4754cee8f3e38e360540bf3dc23ccd8d8a4f Mon Sep 17 00:00:00 2001 From: Jinjiang Date: Sun, 29 Aug 2021 13:38:23 +0800 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: wxsm --- src/api/directives.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/api/directives.md b/src/api/directives.md index 958e9cc47..e72d78cd7 100644 --- a/src/api/directives.md +++ b/src/api/directives.md @@ -486,11 +486,11 @@ 当组件重新渲染的时候，如果 `valueA` 与 `valueB` 都维持不变，那么对这个 `
` 以及它的所有子节点的更新都将被跳过。事实上，即使是虚拟 DOM 的 VNode 创建也将被跳过，因为子树的记忆副本可以被重用。 - 正确地声明记忆数组是很重要的，否则应有更新也可能会被错过。带有空依赖数组的 `v-memo` (`v-memo="[]"`) 在功能上等效于 `v-once`。 + 正确地声明记忆数组是很重要的，否则某些事实上需要被应用的更新也可能会被跳过。带有空依赖数组的 `v-memo` (`v-memo="[]"`) 在功能上等效于 `v-once`。 **结合 `v-for` 使用** - `v-memo` 仅供性能敏感场景的针对性优化，会用到场景很少。渲染 `v-for` 长列表 (长度大于 1000) 可能是它最有用的场景： + `v-memo` 仅供性能敏感场景的针对性优化，会用到的场景应该很少。渲染 `v-for` 长列表 (长度大于 1000) 可能是它最有用的场景： ```html