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

Basic reactivity proofread #404

Merged
merged 3 commits into from
Mar 7, 2021
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions src/api/basic-reactivity.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 响应性基础 API

> 本节例子中代码使用的[单文件组件](../guide/single-file-component.html)语法
> 本节例子中代码使用[单文件组件](../guide/single-file-component.html)语法

## `reactive`

Expand All @@ -10,7 +10,7 @@
const obj = reactive({ count: 0 })
```

响应式转换是“深层”的——它影响所有嵌套 property。在基于 [ES2015 Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) 的实现中,返回的 proxy 是**不**等于原始对象的。建议只使用响应式 proxy,避免依赖原始对象。
响应式转换是“深层”的——它影响所有嵌套 property。在基于 [ES2015 Proxy](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Proxy) 的实现中,返回的 proxy 是**不**等于原始对象的。建议只使用响应式 proxy,避免依赖原始对象。

**类型声明:**

Expand All @@ -20,19 +20,19 @@ function reactive<T extends object>(target: T): UnwrapNestedRefs<T>

## `readonly`

获取一个对象 (响应式或纯对象) 或 [ref](./refs-api.html#ref) 并返回原始 proxy 的只读 proxy。只读 proxy 是深层的:访问的任何嵌套 property 也是只读的。
接受一个对象 (响应式或纯对象) 或 [ref](./refs-api.html#ref) 并返回原始对象的只读 proxy。只读 proxy 是深层的:任何被访问的嵌套 property 也是只读的。
Jinjiang marked this conversation as resolved.
Show resolved Hide resolved

```js
const original = reactive({ count: 0 })

const copy = readonly(original)

watchEffect(() => {
// 适用于响应性追踪
// 用于响应性追踪
console.log(copy.count)
})

// 变更original 会触发侦听器依赖副本
// 变更 original 会触发依赖于副本的侦听器
original.count++

// 变更副本将失败并导致警告
Expand All @@ -45,7 +45,7 @@ copy.count++ // 警告!

## `isReactive`

检查对象是否是 [`reactive`](#reactive)创建的响应式 proxy。
检查对象是否是由 [`reactive`](#reactive) 创建的响应式 proxy。
Jinjiang marked this conversation as resolved.
Show resolved Hide resolved

```js
import { reactive, isReactive } from 'vue'
Expand All @@ -59,7 +59,7 @@ export default {
}
```

如果 proxy 是 [`readonly`](#readonly) 创建的,但还包装了由 [`reactive`](#reactive) 创建的另一个 proxy,它也会返回 `true`。
如果 proxy 是 [`readonly`](#readonly) 创建的,但包装了由 [`reactive`](#reactive) 创建的另一个 proxy,它也会返回 `true`。
Jinjiang marked this conversation as resolved.
Show resolved Hide resolved

```js{7-15}
import { reactive, isReactive, readonly } from 'vue'
Expand All @@ -83,11 +83,11 @@ export default {

## `isReadonly`

检查对象是否是由[`readonly`](#readonly)创建的只读 proxy。
检查对象是否是由 [`readonly`](#readonly) 创建的只读 proxy。
Jinjiang marked this conversation as resolved.
Show resolved Hide resolved

## `toRaw`

返回 [`reactive`](#reactive) 或 [`readonly`](#readonly) proxy 的原始对象。这是一个转义口,可用于临时读取而不会引起 proxy 访问/跟踪开销,也可用于写入而不会触发更改。不建议保留对原始对象的持久引用。请谨慎使用。
返回 [`reactive`](#reactive) 或 [`readonly`](#readonly) proxy 的原始对象。这是一个“逃生舱”,可用于临时读取数据而无需承担 proxy 访问/跟踪开销,也可用于写入数据而避免触发更改。**不**建议保留对原始对象的持久引用。请谨慎使用。
Jinjiang marked this conversation as resolved.
Show resolved Hide resolved

```js
const foo = {}
Expand All @@ -109,35 +109,35 @@ const bar = reactive({ foo })
console.log(isReactive(bar.foo)) // false
```

:::warning
:::warning 重要

下方的 `markRaw` shallowXXX API 使你可以有选择地选择退出默认的深度响应式/只读转换,并将原始的,非 proxy 的对象嵌入状态图中。它们可以在各种情况下使用
`markRaw` 和下方的 shallowXXX API 使你可以有选择地退出默认的深度响应式/只读转换模式,并将原始的,未被代理的对象嵌入状态图中。它们可以根据情况灵活运用

- 有些值不应被设置为响应式的,例如复杂的第三方类实例或 Vue 组件对象。
- 有些值不应该是响应式的,例如复杂的第三方类实例或 Vue 组件对象。
- 当渲染具有不可变数据源的大列表时,跳过 proxy 转换可以提高性能。

它们被认为是高阶的,因为原始选择退出仅在根级别,因此,如果将嵌套的、未标记的原始对象设置为响应式对象,然后再次访问它,则可以得到 proxy 版本。这可能会导致**本源危害**——即执行依赖于对象本身但同时使用同一对象的原始版本和 proxy 版本的操作
这些例子是进阶的运用,因为原始选择退出仅在根级别,因此,如果将嵌套在内的、未标记的原始对象添加进响应式对象,然后再次访问该响应式对象,就会得到原始对象被代理后的版本。这可能会导致**同一性风险**——即执行一个依赖于对象本身的操作,但同时使用同一对象的原始版本和被代理后的版本

```js
const foo = markRaw({
nested: {}
})

const bar = reactive({
// 虽然 `foo` 被标记为原始,foo.nested 不是。
// 虽然 `foo` 被标记为原始,foo.nested 不是。
nested: foo.nested
})

console.log(foo.nested === bar.nested) // false
```

本源危害通常很少见。然而,为了在安全地避免本源危害的同时正确地使用这些 API,需要对响应性系统的工作原理有一个坚实的理解
同一性风险通常很少见。然而,为了正确地使用这些 API,同时安全地避免同一性风险,就需要对响应性系统的工作原理有一个充分的理解

:::

## `shallowReactive`

创建一个响应式 proxy,跟踪其自身 property 的响应性,但不执行嵌套对象的深度响应式转换 (暴露原始值)。
创建一个响应式 proxy,它跟踪其自身 property 的响应性,但不执行嵌套对象的深层响应式转换 (暴露原始值)。
Jinjiang marked this conversation as resolved.
Show resolved Hide resolved

```js
const state = shallowReactive({
Expand All @@ -147,7 +147,7 @@ const state = shallowReactive({
}
})

// 改变状态本身的性质是响应式的
// 改变 state 本身的性质是响应式的
state.foo++
// ...但是不转换嵌套对象
isReactive(state.nested) // false
Expand All @@ -166,7 +166,7 @@ const state = shallowReadonly({
}
})

// 改变状态本身的property将失败
// 改变 state 本身的 property 将失败
state.foo++
// ...但适用于嵌套对象
isReadonly(state.nested) // false
Expand Down