Skip to content
This repository was archived by the owner on Aug 8, 2022. It is now read-only.

Commit fce645d

Browse files
wxsmsJustineo
andauthored
docs: update attribute-coercion.md (#679)
Co-authored-by: GU Yiling <justice360@gmail.com>
1 parent 64e1d8a commit fce645d

File tree

1 file changed

+32
-33
lines changed

1 file changed

+32
-33
lines changed

src/guide/migration/attribute-coercion.md

Lines changed: 32 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -6,31 +6,31 @@ badges:
66
# attribute 强制行为 <MigrationBadges :badges="$frontmatter.badges" />
77

88
:::info 信息
9-
这是一个低等级的内部 API 更改,不会影响大多数开发人员
9+
这是一个底层的内部 API 更改,绝大多数开发人员不会受到影响
1010
:::
1111

1212
## 概览
1313

14-
下面是对这些变化的高层次总结
14+
以下是对变化的总体概述
1515

16-
- 删除枚举 attribute 的内部概念,并将这些 attribute 视为普通的非布尔 attribute
17-
- **重大改变**:如果值为布尔值,则不再删除 attribute `false`。相反,它被设置为 attr=false”。移除 attribute,应该使用 `null` 或者 `undefined`
16+
- 移除枚举 attribute 的内部概念,并将这些 attribute 视为普通的非布尔 attribute
17+
- **非兼容**:如果值为布尔值 `false`,则不再移除 attribute。取而代之的是,它将被设置为 attr="false"。若要移除 attribute,应该使用 `null` 或者 `undefined`
1818

1919
如需更深入的解释,请继续阅读!
2020

2121
## 2.x 语法
2222

2323
在 2.x,我们有以下策略来强制 `v-bind` 的值:
2424

25-
- 对于某些 attribute/元素对,Vue 始终使用相应的 IDL attribute(property):[比如拥有 `value``<input>``<select>``<progress>`,等等](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/util/attrs.js#L11-L18)
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)
2626

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` 的,Vue 会移除它们 ([`undefined``null` or `false`](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/util/attrs.js#L52-L54)) ,否则会加上它们 (见[这里](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))。
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))。
2828

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))。
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))。
3030

31-
- 对于其他 attribute,我们移除了 `falsy` (`undefined``null`or `false`) 并按原样设置其他值 (见[这里](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/runtime/modules/attrs.js#L92-L113))。
31+
- 对于其他 attribute,我们将移除 `falsy` 的值 (`undefined``null` `false`),其他值按原样设置 (见[这里](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/runtime/modules/attrs.js#L92-L113))。
3232

33-
下表描述了 Vue 如何使用普通非布尔 attribute 强制“枚举 attribute”:
33+
下表描述了 Vue 如何强制转换“枚举 attribute”,以及与普通非布尔 attribute 的不同之处
3434

3535
| 绑定表达式 | `foo` <sup>正常</sup> | `draggable` <sup>枚举</sup> |
3636
| ------------------- | ----------------------- | --------------------------------- |
@@ -43,23 +43,22 @@ badges:
4343
| `attr="foo"` | `foo="foo"` | `draggable="true"` |
4444
| `attr` | `foo=""` | `draggable="true"` |
4545

46-
<small>/:移除</small>
4746

48-
从上表可以看出,当前实现 `true` 强制为 `'true'` 但如果 attribute 为 `false`则移除该 attribute。这也导致了不一致性,并要求用户在非常常见的用例中手动强制布尔值为字符串,例如
49-
`aria-*` attribute,例如 `aria-selected``aria-hidden`等等。
47+
从上表可以看出,当前实现将 `true` 强制转换为了 `'true'`但如果 attribute 为 `false`则将其移除。这也导致了不一致性,并要求用户在非常常见的用例中手动将布尔值强制转换为字符串,例如
48+
`aria-*` attribute,例如 `aria-selected``aria-hidden` 等等。
5049

5150
## 3.x 语法
5251

5352
我们打算放弃“枚举型 attribute”的内部概念,并将它们视为普通的非布尔型 HTML attribute。
5453

55-
- 这就解决了普通非布尔型 attribute 和“枚举型 attribute”之间的不一致性
56-
- 它还可以使用 `'true'``'false'` 以外的值,甚至可以使用 `contenteditable` 等 attribute 的关键字
54+
- 这就解决了普通非布尔型 attribute 和“枚举型 attribute”之间的不一致性问题
55+
- 这个改动还使得对于诸如 `contenteditable` 这样的 attribute,我们可以使用 `'true'``'false'` 以外的值,甚至是未来新增的关键字。
5756

58-
对于非布尔型 attribute,如果 attribute 值为 `false`,Vue 将停止删除它们,相反强制它们的值为 `'false'`
57+
对于非布尔型 attribute,如果其值为 `false`,Vue 将不再移除它们,而是将其强制转换为 `'false'`
5958

60-
- 这就解决了 `true``false` 之间的不一致性,并使输出 `aria-*` attributes 更容易
59+
- 这就解决了 `true``false` 之间的不一致性,并更易于输出 `aria-*` attribute
6160

62-
下表描述了新行为
61+
下表描述了新的行为
6362

6463
| 绑定表达式 | `foo` <sup>正常</sup> | `draggable` <sup>枚举</sup> |
6564
| ------------------- | -------------------------- | --------------------------------- |
@@ -72,47 +71,47 @@ badges:
7271
| `attr="foo"` | `foo="foo"` | `draggable="foo"` <sup>*</sup> |
7372
| `attr` | `foo=""` | `draggable=""` <sup>*</sup> |
7473

75-
<small>*变更</small>
74+
<small>*已改变</small>
7675

77-
布尔 attributes 的强制保持不变
76+
布尔型 attribute 的强制转换保持不变
7877

7978
## 迁移策略
8079

8180
### 枚举 attribute
8281

83-
缺少值的枚举 attribute `attr="false"` 可能会产生不同的 IDL attribute 值 (将反映实际状态),描述如下:
82+
枚举 attribute 如果不存在,可能会和 `attr="false"` 会产生不同的 IDL attribute 值 (将反映实际状态),描述如下:
8483

85-
| 缺少枚举attr | IDL attr & 值 |
84+
| 不存在的枚举 attr | IDL attr & 值 |
8685
| ---------------------- | ------------------------------------ |
8786
| `contenteditable` | `contentEditable` &rarr; `'inherit'` |
8887
| `draggable` | `draggable` &rarr; `false` |
8988
| `spellcheck` | `spellcheck` &rarr; `true` |
9089

91-
为了保持原有的行为,我们将强制使布尔型 Attribute 的 `false` 转换为 `'false'`,在 3.x Vue 中,开发人员需要将 `v-bind` 表达式解析为 `false``'false'`,表示 `contenteditable``spellcheck`
90+
对于“枚举 attribute”,由于我们不再把 `null` 转换为 `'false'`,在 3.x 中,对于 `contenteditable``spellcheck`,开发者需要将原来解析为 `null``v-bind` 表达式变更为 `false``'false'` 才能保持和 2.x 中的行为一致
9291

93-
在 2.x 中,枚举 attribute 的无效值被强制为 `'true'`这通常是无意的,不太可能大规模依赖。在 3.x 中,应显式指定 `true``'true'`
92+
在 2.x 中,枚举 attribute 的无效值将被强制转换为 `'true'`这通常是不符合预期的,所以该行为不太可能被大规模依赖。在 3.x 中,应显式指定 `true``'true'`
9493

95-
### `false` 强制转换为 `'false'` 而不是删除 attribute
94+
### `false` 强制转换为 `'false'` 而不是移除 attribute
9695

97-
在 3.x`null``undefined` 应用于显式删除 attribute。
96+
在 3.x 中,应该使用 `null``undefined` 以显式移除 attribute。
9897

9998
### 2.x 和 3.x 行为的比较
10099

101100
<table>
102101
<thead>
103102
<tr>
104103
<th>Attributes</th>
105-
<th><code>v-bind</code> value <sup>2.x</sup></th>
106-
<th><code>v-bind</code> value <sup>3.x</sup></th>
104+
<th><code>v-bind</code> 的值 <sup>2.x</sup></th>
105+
<th><code>v-bind</code> 的值 <sup>3.x</sup></th>
107106
<th>HTML 输出</th>
108107
</tr>
109108
</thead>
110109
<tbody>
111110
<tr>
112-
<td rowspan="3">2.x “枚举attribute”<br><small>i.e. <code>contenteditable</code>, <code>draggable</code> and <code>spellcheck</code>.</small></td>
113-
<td><code>undefined</code>, <code>false</code></td>
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>
114113
<td><code>undefined</code>, <code>null</code></td>
115-
<td><i>removed</i></td>
114+
<td><i>被移除</i></td>
116115
</tr>
117116
<tr>
118117
<td>
@@ -123,15 +122,15 @@ badges:
123122
<td><code>"true"</code></td>
124123
</tr>
125124
<tr>
126-
<td><code>null</code>, <code>'false'</code></td>
125+
<td><code>null</code>, <code>false</code>, <code>'false'</code></td>
127126
<td><code>false</code>, <code>'false'</code></td>
128127
<td><code>"false"</code></td>
129128
</tr>
130129
<tr>
131-
<td rowspan="2">其他非布尔attribute<br><small>eg. <code>aria-checked</code>, <code>tabindex</code>, <code>alt</code>, etc.</small></td>
130+
<td rowspan="2">其他非布尔 attribute<br><small> <code>aria-checked</code><code>tabindex</code><code>alt</code> 等等。</small></td>
132131
<td><code>undefined</code>, <code>null</code>, <code>false</code></td>
133132
<td><code>undefined</code>, <code>null</code></td>
134-
<td><i>removed</i></td>
133+
<td><i>被移除</i></td>
135134
</tr>
136135
<tr>
137136
<td><code>'false'</code></td>

0 commit comments

Comments
 (0)