Skip to content

Commit ce3f418

Browse files
JinjiangJinjiang
committed
translation: start the zh version from legacy repo (docs-next-zh-cn)
1 parent e99a954 commit ce3f418

36 files changed

+3755
-0
lines changed

‎src/zh/array-refs.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
title: v-for 中的 Ref 数组
3+
badges:
4+
- breaking
5+
---
6+
7+
# {{ $frontmatter.title }} <MigrationBadges :badges="$frontmatter.badges" />
8+
9+
在 Vue 2 中，在 `v-for` 中使用的 `ref` attribute 会用 ref 数组填充相应的 `$refs` property。当存在嵌套的 `v-for` 时，这种行为会变得不明确且效率低下。
10+
11+
在 Vue 3 中，此类用法将不再自动创建 `$ref` 数组。要从单个绑定获取多个 ref，请将 `ref` 绑定到一个更灵活的函数上 (这是一个新特性)：
12+
13+
```html
14+
<div v-for="item in list" :ref="setItemRef"></div>
15+
```
16+
17+
结合选项式 API:
18+
19+
```js
20+
export default {
21+
data() {
22+
return {
23+
itemRefs: []
24+
}
25+
},
26+
methods: {
27+
setItemRef(el) {
28+
if (el) {
29+
this.itemRefs.push(el)
30+
}
31+
}
32+
},
33+
beforeUpdate() {
34+
this.itemRefs = []
35+
},
36+
updated() {
37+
console.log(this.itemRefs)
38+
}
39+
}
40+
```
41+
42+
结合组合式 API:
43+
44+
```js
45+
import { onBeforeUpdate, onUpdated } from 'vue'
46+
47+
export default {
48+
setup() {
49+
let itemRefs = []
50+
const setItemRef = el => {
51+
if (el) {
52+
itemRefs.push(el)
53+
}
54+
}
55+
onBeforeUpdate(() => {
56+
itemRefs = []
57+
})
58+
onUpdated(() => {
59+
console.log(itemRefs)
60+
})
61+
return {
62+
setItemRef
63+
}
64+
}
65+
}
66+
```
67+
68+
注意：
69+
70+
- `itemRefs` 不必是数组：它也可以是一个对象，其 ref 可以通过迭代的 key 被设置。
71+
72+
- 如有需要，`itemRefs` 也可以是响应式的，且可以被侦听。
73+
74+
## 迁移策略
75+
76+
[迁移构建开关：](migration-build.html#兼容性配置)
77+
78+
- `V_FOR_REF`
79+
- `COMPILER_V_FOR_REF`

‎src/zh/async-components.md

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
badges:
3+
- new
4+
---
5+
6+
# 异步组件 <MigrationBadges :badges="$frontmatter.badges" />
7+
8+
## 概览
9+
10+
以下是对变化的总体概述：
11+
12+
- 新的 `defineAsyncComponent` 助手方法，用于显式地定义异步组件
13+
- `component` 选项被重命名为 `loader`
14+
- Loader 函数本身不再接收 `resolve` 和 `reject` 参数，且必须返回一个 Promise
15+
16+
如需更深入的解释，请继续阅读！
17+
18+
## 介绍
19+
20+
以前，异步组件是通过将组件定义为返回 Promise 的函数来创建的，例如：
21+
22+
```js
23+
const asyncModal = () => import('./Modal.vue')
24+
```
25+
26+
或者，对于带有选项的更高阶的组件语法：
27+
28+
```js
29+
const asyncModal = {
30+
component: () => import('./Modal.vue'),
31+
delay: 200,
32+
timeout: 3000,
33+
error: ErrorComponent,
34+
loading: LoadingComponent
35+
}
36+
```
37+
38+
## 3.x 语法
39+
40+
现在，在 Vue 3 中，由于函数式组件被定义为纯函数，因此异步组件需要通过将其包裹在新的 `defineAsyncComponent` 助手方法中来显式地定义：
41+
42+
```js
43+
import { defineAsyncComponent } from 'vue'
44+
import ErrorComponent from './components/ErrorComponent.vue'
45+
import LoadingComponent from './components/LoadingComponent.vue'
46+
47+
// 不带选项的异步组件
48+
const asyncModal = defineAsyncComponent(() => import('./Modal.vue'))
49+
50+
// 带选项的异步组件
51+
const asyncModalWithOptions = defineAsyncComponent({
52+
loader: () => import('./Modal.vue'),
53+
delay: 200,
54+
timeout: 3000,
55+
errorComponent: ErrorComponent,
56+
loadingComponent: LoadingComponent
57+
})
58+
```
59+
60+
::: tip 注意
61+
Vue Router 支持一个类似的机制来异步加载路由组件，也就是俗称的*懒加载*。尽管类似，但是这个功能和 Vue 所支持的异步组件是不同的。当用 Vue Router 配置路由组件时，你**不**应该使用 `defineAsyncComponent`。你可以在 Vue Router 文档的[懒加载路由](https://next.router.vuejs.org/guide/advanced/lazy-loading.html)章节阅读更多相关内容。
62+
:::
63+
64+
对 2.x 所做的另一个更改是，`component` 选项现在被重命名为 `loader`，以明确组件定义不能直接被提供。
65+
66+
```js{4}
67+
import { defineAsyncComponent } from 'vue'
68+
69+
const asyncModalWithOptions = defineAsyncComponent({
70+
loader: () => import('./Modal.vue'),
71+
delay: 200,
72+
timeout: 3000,
73+
errorComponent: ErrorComponent,
74+
loadingComponent: LoadingComponent
75+
})
76+
```
77+
78+
此外，与 2.x 不同，loader 函数不再接收 `resolve` 和 `reject` 参数，且必须始终返回 Promise。
79+
80+
```js
81+
// 2.x 版本
82+
const oldAsyncComponent = (resolve, reject) => {
83+
/* ... */
84+
}
85+
86+
// 3.x 版本
87+
const asyncComponent = defineAsyncComponent(
88+
() =>
89+
new Promise((resolve, reject) => {
90+
/* ... */
91+
})
92+
)
93+
```
94+
95+
有关异步组件用法的详细信息，请参阅：
96+
97+
- [指南：动态 & 异步组件](/guide/component-dynamic-async.html#在动态组件上使用-keep-alive)
98+
- [迁移构建开关：`COMPONENT_ASYNC`](migration-build.html#兼容性配置)

‎src/zh/attribute-coercion.md

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
badges:
3+
- breaking
4+
---
5+
6+
# attribute 强制行为 <MigrationBadges :badges="$frontmatter.badges" />
7+
8+
:::info 信息
9+
这是一个底层的内部 API 更改，绝大多数开发人员不会受到影响。
10+
:::
11+
12+
## 概览
13+
14+
以下是对变化的总体概述：
15+
16+
- 移除枚举 attribute 的内部概念，并将这些 attribute 视为普通的非布尔 attribute
17+
- **非兼容**：如果值为布尔值 `false`，则不再移除 attribute。取而代之的是，它将被设置为 attr="false"。若要移除 attribute，应该使用 `null` 或者 `undefined`。
18+
19+
如需更深入的解释，请继续阅读！
20+
21+
## 2.x 语法
22+
23+
在 2.x，我们有以下策略来强制 `v-bind` 的值：
24+
25+
- 对于某些 attribute/元素对，Vue 始终使用相应的 IDL attribute (property)：[比如 `<input>`，`<select>`，`<progress>` 中的 `value`，等等](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/util/attrs.js#L11-L18)。
26+
27+
- 对于“[布尔 attribute](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/util/attrs.js#L33-L40)”和 [xlinks](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/util/attrs.js#L44-L46)，如果它们是 `falsy` ([`undefined`，`null` 或 `false`](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/util/attrs.js#L52-L54)) 的，Vue 会移除它们，否则会加上。(见[这里](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/runtime/modules/attrs.js#L66-L77)和[这里](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/runtime/modules/attrs.js#L81-L85))。
28+
29+
- 对于“[枚举 attribute](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/util/attrs.js#L20)” (目前来说包括 `contenteditable`、`draggable` 和 `spellcheck`)，Vue 会尝试将它们[强制](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/util/attrs.js#L24-L31)转换为字符串 (目前对 `contenteditable` 做了特殊处理，以修复 [vuejs/vue#9397](https://github.com/vuejs/vue/issues/9397))。
30+
31+
- 对于其他 attribute，我们将移除 `falsy` 的值 (`undefined`，`null`，或 `false`)，其他值按原样设置 (见[这里](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/runtime/modules/attrs.js#L92-L113))。
32+
33+
下表描述了 Vue 如何强制转换“枚举 attribute”，以及与普通非布尔 attribute 的不同之处：
34+
35+
| 绑定表达式 | `foo` <sup>正常</sup> | `draggable` <sup>枚举</sup> |
36+
| ------------------- | ----------------------- | --------------------------------- |
37+
| `:attr="null"` | - | `draggable="false"` |
38+
| `:attr="undefined"` | - | - |
39+
| `:attr="true"` | `foo="true"` | `draggable="true"` |
40+
| `:attr="false"` | - | `draggable="false"` |
41+
| `:attr="0"` | `foo="0"` | `draggable="true"` |
42+
| `attr=""` | `foo=""` | `draggable="true"` |
43+
| `attr="foo"` | `foo="foo"` | `draggable="true"` |
44+
| `attr` | `foo=""` | `draggable="true"` |
45+
46+
47+
从上表可以看出，当前实现将 `true` 强制转换为了 `'true'`，但如果 attribute 为 `false`，则将其移除。这也导致了不一致性，并要求用户在非常常见的用例中手动将布尔值强制转换为字符串，例如
48+
`aria-*` attribute，例如 `aria-selected`、`aria-hidden` 等等。
49+
50+
## 3.x 语法
51+
52+
我们打算放弃“枚举型 attribute”的内部概念，并将它们视为普通的非布尔型 HTML attribute。
53+
54+
- 这就解决了普通非布尔型 attribute 和“枚举型 attribute”之间的不一致性问题
55+
- 这个改动还使得对于诸如 `contenteditable` 这样的 attribute，我们可以使用 `'true'` 和 `'false'` 以外的值，甚至是未来新增的关键字。
56+
57+
对于非布尔型 attribute，如果其值为 `false`，Vue 将不再移除它们，而是将其强制转换为 `'false'`。
58+
59+
- 这就解决了 `true` 和 `false` 之间的不一致性，并更易于输出 `aria-*` attribute
60+
61+
下表描述了新的行为：
62+
63+
| 绑定表达式 | `foo` <sup>正常</sup> | `draggable` <sup>枚举</sup> |
64+
| ------------------- | -------------------------- | --------------------------------- |
65+
| `:attr="null"` | - | - <sup>*</sup> |
66+
| `:attr="undefined"` | - | - |
67+
| `:attr="true"` | `foo="true"` | `draggable="true"` |
68+
| `:attr="false"` | `foo="false"` <sup>*</sup> | `draggable="false"` |
69+
| `:attr="0"` | `foo="0"` | `draggable="0"` <sup>*</sup> |
70+
| `attr=""` | `foo=""` | `draggable=""` <sup>*</sup> |
71+
| `attr="foo"` | `foo="foo"` | `draggable="foo"` <sup>*</sup> |
72+
| `attr` | `foo=""` | `draggable=""` <sup>*</sup> |
73+
74+
<small>*：已改变</small>
75+
76+
布尔型 attribute 的强制转换保持不变。
77+
78+
## 迁移策略
79+
80+
### 枚举 attribute
81+
82+
枚举 attribute 如果不存在，可能会和 `attr="false"` 会产生不同的 IDL attribute 值 (将反映实际状态)，描述如下：
83+
84+
| 不存在的枚举 attr | IDL attr & 值 |
85+
| ---------------------- | ------------------------------------ |
86+
| `contenteditable` | `contentEditable` &rarr; `'inherit'` |
87+
| `draggable` | `draggable` &rarr; `false` |
88+
| `spellcheck` | `spellcheck` &rarr; `true` |
89+
90+
对于“枚举 attribute”，由于我们不再把 `null` 转换为 `'false'`，在 3.x 中，对于 `contenteditable` 和 `spellcheck`，开发者需要将原来解析为 `null` 的 `v-bind` 表达式变更为 `false` 或 `'false'` 才能保持和 2.x 中的行为一致。
91+
92+
在 2.x 中，枚举 attribute 的无效值将被强制转换为 `'true'`。这通常是不符合预期的，所以该行为不太可能被大规模依赖。在 3.x 中，应显式指定 `true` 或 `'true'`。
93+
94+
### 将 `false` 强制转换为 `'false'` 而不是移除 attribute
95+
96+
在 3.x 中，应该使用 `null` 或 `undefined` 以显式移除 attribute。
97+
98+
### 2.x 和 3.x 行为的比较
99+
100+
<table>
101+
<thead>
102+
<tr>
103+
<th>Attributes</th>
104+
<th><code>v-bind</code> 的值 <sup>2.x</sup></th>
105+
<th><code>v-bind</code> 的值 <sup>3.x</sup></th>
106+
<th>HTML 输出</th>
107+
</tr>
108+
</thead>
109+
<tbody>
110+
<tr>
111+
<td rowspan="3">2.x “枚举 attribute”<br><small>即 <code>contenteditable</code>、<code>draggable</code> 与 <code>spellcheck</code>。</small></td>
112+
<td><code>undefined</code></td>
113+
<td><code>undefined</code>, <code>null</code></td>
114+
<td><i>被移除</i></td>
115+
</tr>
116+
<tr>
117+
<td>
118+
<code>true</code>, <code>'true'</code>, <code>''</code>, <code>1</code>,
119+
<code>'foo'</code>
120+
</td>
121+
<td><code>true</code>, <code>'true'</code></td>
122+
<td><code>"true"</code></td>
123+
</tr>
124+
<tr>
125+
<td><code>null</code>, <code>false</code>, <code>'false'</code></td>
126+
<td><code>false</code>, <code>'false'</code></td>
127+
<td><code>"false"</code></td>
128+
</tr>
129+
<tr>
130+
<td rowspan="2">其他非布尔 attribute<br><small>如 <code>aria-checked</code>、<code>tabindex</code>、<code>alt</code> 等等。</small></td>
131+
<td><code>undefined</code>, <code>null</code>, <code>false</code></td>
132+
<td><code>undefined</code>, <code>null</code></td>
133+
<td><i>被移除</i></td>
134+
</tr>
135+
<tr>
136+
<td><code>'false'</code></td>
137+
<td><code>false</code>, <code>'false'</code></td>
138+
<td><code>"false"</code></td>
139+
</tr>
140+
</tbody>
141+
</table>
142+
143+
[迁移构建开关：](migration-build.html#兼容性配置)
144+
145+
- `ATTR_FALSE_VALUE`
146+
- `ATTR_ENUMERATED_COERCION`

‎src/zh/attrs-includes-class-style.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
title: $attrs 包含 class & style
3+
badges:
4+
- breaking
5+
---
6+
7+
# `$attrs` 包含 `class` & `style` <MigrationBadges :badges="$frontmatter.badges" />
8+
9+
## 概览
10+
11+
`$attrs` 现在包含了*所有*传递给组件的 attribute，包括 `class` 和 `style`。
12+
13+
## 2.x 行为
14+
15+
Vue 2 的虚拟 DOM 实现对 `class` 和 `style` attribute 有一些特殊处理。因此，与其它所有 attribute 不一样，它们*没有*被包含在 `$attrs` 中。
16+
17+
上述行为在使用 `inheritAttrs: false` 时会产生副作用：
18+
19+
- `$attrs` 中的 attribute 将不再被自动添加到根元素中，而是由开发者决定在哪添加。
20+
- 但是 `class` 和 `style` 不属于 `$attrs`，它们仍然会被应用到组件的根元素中：
21+
22+
```vue
23+
<template>
24+
<label>
25+
<input type="text" v-bind="$attrs" />
26+
</label>
27+
</template>
28+
<script>
29+
export default {
30+
inheritAttrs: false
31+
}
32+
</script>
33+
```
34+
35+
像这样使用时：
36+
37+
```html
38+
<my-component id="my-id" class="my-class"></my-component>
39+
```
40+
41+
……将生成以下 HTML：
42+
43+
```html
44+
<label class="my-class">
45+
<input type="text" id="my-id" />
46+
</label>
47+
```
48+
49+
## 3.x 行为
50+
51+
`$attrs` 包含了*所有的* attribute，这使得把它们全部应用到另一个元素上变得更加容易了。现在上面的示例将生成以下 HTML：
52+
53+
```html
54+
<label>
55+
<input type="text" id="my-id" class="my-class" />
56+
</label>
57+
```
58+
59+
## 迁移策略
60+
61+
在使用了 `inheritAttrs: false` 的组件中，请确保样式仍然符合预期。如果你之前依赖了 `class` 和 `style` 的特殊行为，那么一些视觉效果可能会遭到破坏，因为这些 attribute 现在可能被应用到了另一个元素中。
62+
63+
[迁移构建开关：`INSTANCE_ATTRS_CLASS_STYLE`](migration-build.html#兼容性配置)
64+
65+
## 参考
66+
67+
- [相关的 RFC](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0031-attr-fallthrough.md)
68+
- [迁移指南 - 移除 `$listeners`](./listeners-removed.md)
69+
- [迁移指南 - 新增 Emits 选项](./emits-option.md)
70+
- [迁移指南 - 移除 `.native` 修饰符](./v-on-native-modifier-removed.md)
71+
- [迁移指南 - 渲染函数 API 的更改](./render-function-api.md)

0 commit comments

Comments
 (0)