MobX API 参考

标有 {🚀} 的函数被认为是高级函数，通常不需要。您可以下载我们方便的速查表，它在一个页面上解释了所有重要的 API。

核心 API

这些是最重要的 MobX API。

理解 observable、computed、reaction 和 action 就足以在您的应用程序中掌握和使用 MobX！

创建可观察对象

使事物可观察。

`makeObservable`

用法：makeObservable(target, annotations?, options?) (更多信息)

属性、整个对象、数组、Map 和 Set 都可以设置为可观察的。

`makeAutoObservable`

用法：makeAutoObservable(target, overrides?, options?) (更多信息)

自动使属性、对象、数组、Map 和 Set 可观察。

`extendObservable`

{🚀} 用法：extendObservable(target, properties, overrides?, options?)

可用于在 target 对象上引入新属性并立即使其可观察。基本上是 Object.assign(target, properties); makeAutoObservable(target, overrides, options); 的简写。但是，不会触碰 target 上的现有属性。

老式的构造函数可以很好地利用 extendObservable

function Person(firstName, lastName) {
    extendObservable(this, { firstName, lastName })
}

const person = new Person("Michel", "Weststrate")

可以在实例化后使用 extendObservable 向现有对象添加可观察字段，但要注意，以这种方式添加可观察属性本身并不是一个可以观察到的事实。

`observable`

用法：observable(source, overrides?, options?)、observable (注解) 或 @observable accessor (字段装饰器)。 (更多信息)

克隆一个对象并使其可观察。源可以是普通对象、数组、Map 或 Set。默认情况下，observable 会递归应用。如果遇到的值之一是对象或数组，则该值也会通过 observable 传递。

`observable.object`

{🚀} 用法：observable.object(source, overrides?, options?) (更多信息)

observable(source, overrides?, options?) 的别名。创建所提供对象的克隆并使其所有属性可观察。

`observable.array`

{🚀} 用法：observable.array(initialValues?, options?)

根据提供的 initialValues 创建一个新的可观察数组。要将可观察数组转换回普通数组，请使用 .slice() 方法，或查看 toJS 以递归转换它们。除了所有语言内置的数组函数外，可观察数组还提供以下好东西

clear() 从数组中删除所有当前条目。
replace(newItems) 用新的条目替换数组中的所有现有条目。
remove(value) 通过值从数组中移除单个项目，如果找到并移除了该项目，则返回 true。

如果数组中的值不应自动转换为可观察值，请使用 { deep: false } 选项使数组成为浅层可观察值。

`observable.map`

{🚀} 用法：observable.map(initialMap?, options?)

基于提供的 initialMap 创建一个新的可观察 ES6 Map。如果您不仅想对特定条目的更改做出反应，还想对它们的添加和删除做出反应，那么它们非常有用。如果您没有启用 Proxies，则创建可观察 Map 是创建动态键控集合的推荐方法。

除了所有语言内置的 Map 函数之外，可观察 Map 还提供以下便利：

toJSON() 返回此 Map 的浅层普通对象表示形式（使用 toJS 进行深拷贝）。
merge(values) 将提供 values（普通对象、条目数组或字符串键控的 ES6 Map）中的所有条目复制到此 Map 中。
replace(values) 使用提供的 values 替换此 Map 的全部内容。

如果 Map 中的值不应自动转换为可观察值，请使用 { deep: false } 选项使 Map 成为浅层可观察值。

`observable.set`

{🚀} 用法：observable.set(initialSet?, options?)

基于提供的 initialSet 创建一个新的可观察 ES6 Set。当您想要创建一个动态集（其中需要观察值的添加和删除，但值在整个集合中只能出现一次）时，请使用它。

如果 Set 中的值不应自动转换为可观察值，请使用 { deep: false } 选项使 Set 成为浅层可观察值。

与 Map 键不同，Set 值不会被单独跟踪。

`observable.ref`

用法：observable.ref （注解） (更多信息)

与 observable 注解类似，但只会跟踪重新赋值。分配的值本身不会自动变为可观察值。例如，如果您打算在可观察字段中存储不可变数据，请使用此选项。

`observable.shallow`

用法：observable.shallow （注解） (更多信息)

与 observable.ref 注解类似，但用于集合。分配的任何集合都将变为可观察的，但集合本身的内容不会变为可观察的。

`observable.struct`

{🚀} 用法：observable.struct （注解） (更多信息)

与 observable 注解类似，不同之处在于将忽略与当前值结构相同的任何赋值。

`observable.deep`

{🚀} 用法：observable.deep （注解） (更多信息)

observable 注解的别名。

`observable.box`

{🚀} 用法：observable.box(value, options?)

JavaScript 中的所有原始值都是不可变的，因此根据定义是不可观察的。通常情况下，这很好，因为 MobX 可以只使包含该值的_属性_可观察。在极少数情况下，拥有一个不属于任何对象的_可观察_原始值会很方便。对于这种情况，可以创建一个可观察的_盒子_来管理这样的_原始值_。

observable.box(value) 接受任何值并将其存储在盒子中。可以通过 .get() 访问当前值，并使用 .set(newValue) 更新它。

import { observable, autorun } from "mobx"

const cityName = observable.box("Vienna")

autorun(() => {
    console.log(cityName.get())
})
// Prints: 'Vienna'

cityName.set("Amsterdam")
// Prints: 'Amsterdam'

如果盒子中的值不应自动转换为可观察值，请使用 { deep: false } 选项使盒子成为浅层可观察值。

动作

动作是指任何修改状态的代码。

`action`

用法: action(fn), action (注解) 或 @action (方法 / 字段装饰器) (更多信息)

用于意图修改状态的函数。

`runInAction`

{🚀} 用法: runInAction(fn) (更多信息)

创建一个立即调用的单次动作。

`flow`

用法: flow(fn), flow (注解) 或 @flow (生成器方法装饰器) (更多信息)

MobX 对 async / await 的友好替代品，支持取消。

`flowResult`

用法: flowResult(flowFunctionResult) (更多信息)

仅适用于 TypeScript 用户。将生成器的输出转换为 Promise 的实用程序。这只是对 flow 执行的 Promise 包装进行类型上的更正。在运行时，它直接返回输入的值。

计算值

计算值可以用来从其他可观察值中派生信息。

`computed`

用法: computed(fn, options?), computed(options?) (注解) 或 @computed (getter 装饰器) (更多信息)

创建一个从其他可观察值派生的可观察值，但除非其中一个基础可观察值发生变化，否则不会重新计算。

React 集成

来自 mobx-react / mobx-react-lite 包。

`observer`

用法: observer(component) (更多信息)

一个高阶组件，可用于在可观察值更改时重新渲染函数式或基于类的 React 组件。

`Observer`

用法: <Observer>{() => rendering}</Observer> (更多信息)

渲染给定的渲染函数，并在渲染函数中使用的某个可观察值发生变化时自动重新渲染。

`useLocalObservable`

用法: useLocalObservable(() => source, annotations?) (更多信息)

使用 makeObservable 创建一个新的可观察对象，并在组件的整个生命周期内将其保留在组件中。

反应

反应的目标是模拟自动发生的副作用。

`autorun`

用法：autorun(() => effect, options?) (更多信息)

每次它观察到的任何内容发生变化时，都会重新运行一个函数。

`reaction`

用法：reaction(() => data, data => effect, options?) (更多信息)

当任何选定的数据发生变化时，重新运行副作用。

`when`

用法：when(() => condition, () => effect, options?) 或 await when(() => condition, options?) (更多信息)

当可观察条件变为真时，执行一次副作用。

实用工具

使用可观察对象或计算值时，这些实用工具可能会更加方便。更简单的实用工具也可以在 mobx-utils 包中找到。

`onReactionError`

{🚀} 用法：onReactionError(handler: (error: any, derivation) => void)

附加一个全局错误监听器，它会在每次从*反应*中抛出错误时被调用。这可以用于监控或测试目的。

`intercept`

{🚀} 用法：intercept(propertyName|array|object|Set|Map, listener) (更多信息)

在将更改应用于可观察 API 之前拦截它们。返回一个停止拦截的处置函数。

`observe`

{🚀} 用法：observe(propertyName|array|object|Set|Map, listener) (更多信息)

可用于观察单个可观察值的低级 API。返回一个停止拦截的处置函数。

`onBecomeObserved`

{🚀} 用法：onBecomeObserved(observable, property?, listener: () => void) (更多信息)

当某些内容被观察到时的钩子。

`onBecomeUnobserved`

{🚀} 用法：onBecomeUnobserved(observable, property?, listener: () => void) (更多信息)

当某些内容停止被观察时的钩子。

`toJS`

用法：toJS(value) (更多信息)

将可观察对象递归转换为 JavaScript *对象*。支持可观察数组、对象、映射和基元。

它不会递归到不可观察对象，即使它们包含可观察对象，它们也会保持原样。计算和其他不可枚举的属性将被完全忽略，并且不会被返回。

对于更复杂的（反）序列化场景，建议为类提供（计算的）toJSON 方法，或使用像 serializr 这样的序列化库。

const obj = mobx.observable({
    x: 1
})

const clone = mobx.toJS(obj)

console.log(mobx.isObservableObject(obj)) // true
console.log(mobx.isObservableObject(clone)) // false

配置

微调您的 MobX 实例。

`configure`

用法：在活动的 MobX 实例上设置全局行为设置。（更多信息）使用它来更改 MobX 作为一个整体的行为方式。

集合实用程序 {🚀}

它们可以使用相同的通用 API 操作可观察数组、对象和映射。这在没有 Proxy 支持的环境中很有用，但在其他情况下通常不需要。

`values`

{🚀} 用法: values(array|object|Set|Map) (更多信息)

以数组形式返回集合中的所有值。

`keys`

{🚀} 用法: keys(array|object|Set|Map) (更多信息)

以数组形式返回集合中的所有键/索引。

`entries`

{🚀} 用法: entries(array|object|Set|Map) (更多信息)

以数组形式返回集合中每个条目的 [key, value] 对。

`set`

{🚀} 用法: set(array|object|Map, key, value) (更多信息)

更新集合。

`remove`

{🚀} 用法: remove(array|object|Map, key) (更多信息)

从集合中删除条目。

`has`

{🚀} 用法: has(array|object|Map, key) (更多信息)

检查集合中是否存在成员。

`get`

{🚀} 用法: get(array|object|Map, key) (更多信息)

使用键从集合中获取值。

自省实用程序 {🚀}

如果您想检查 MobX 的内部状态，或者想在 MobX 之上构建酷炫的工具，这些实用程序可能会派上用场。

`isObservable`

{🚀} 用法: isObservable(array|object|Set|Map)

对象/集合是否由 MobX 设置为可观察的？

`isObservableProp`

{🚀} 用法: isObservableProp(object, propertyName)

该属性是否是可观察的？

`isObservableArray`

{🚀} 用法: isObservableArray(array)

该值是否是一个可观察数组？

`isObservableObject`

{🚀} 用法: isObservableObject(object)

该值是否是一个可观察对象？

`isObservableSet`

{🚀} 用法: isObservableSet(set)

该值是否是一个可观察集合？

`isObservableMap`

{🚀} 用法: isObservableMap(map)

该值是否是一个可观察映射？

`isBoxedObservable`

{🚀} 用法: isBoxedObservable(value)

该值是否是一个使用 observable.box 创建的可观察盒子？

`isAction`

{🚀} 用法: isAction(func)

该函数是否被标记为 action？

`isComputed`

{🚀} 用法: isComputed(boxedComputed)

这是使用 computed(() => expr) 创建的盒装计算值吗？

`isComputedProp`

{🚀} 用法: isComputedProp(object, propertyName)

这是计算属性吗？

`trace`

{🚀} 用法: trace(), trace(true) (进入调试器) 或 trace(object, propertyName, enterDebugger?) (更多信息)

应该在 observer、reaction 或 computed 值内部使用。记录值失效的时间，如果使用 true 调用，则设置调试器断点。

`spy`

{🚀} 用法: spy(eventListener) (更多信息)

注册一个全局 spy 监听器，它监听 MobX 中发生的所有事件。

`getDebugName`

{🚀} 用法: getDebugName(reaction|array|Set|Map) 或 getDebugName(object|Map, propertyName) (更多信息)

返回可观察对象或 reaction 的（生成的）友好调试名称。

`getDependencyTree`

{🚀} 用法: getDependencyTree(object, computedPropertyName) (更多信息)

返回一个树结构，其中包含给定反应/计算当前依赖的所有可观察值。

`getObserverTree`

{🚀} 用法: getObserverTree(array|Set|Map) 或 getObserverTree(object|Map, propertyName) (更多信息)

返回一个树结构，其中包含正在观察给定可观察值的所有反应/计算。

扩展 MobX {🚀}

在极少数情况下，您需要扩展 MobX 本身。

`createAtom`

{🚀} 用法: createAtom(name, onBecomeObserved?, onBecomeUnobserved?) (更多信息)

创建您自己的可观察数据结构并将其连接到 MobX。由所有可观察数据类型在内部使用。Atom 公开了两种 * 报告 * 方法，以便在以下情况下通知 MobX

reportObserved()：原子已被观察到，应该被认为是当前派生关系树的一部分。
reportChanged()：原子已更改，依赖于它的所有派生关系都应该失效。

`getAtom`

{🚀} 用法: getAtom(thing, property?) (更多信息)

返回支持原子。

`transaction`

{🚀} 用法: transaction(worker: () => any)

事务是一个低级 API。建议使用 action 或 runInAction 代替。

用于批量执行一系列更新，直到事务结束才会运行任何反应。与 untracked 类似，它由 action 自动应用，因此通常使用操作比直接使用 transaction 更有意义。

它接受一个单一的、无参数的 worker 函数作为参数，并返回由它返回的任何值。请注意，transaction 以完全同步的方式运行，并且可以嵌套。只有在完成最外层的 transaction 之后，才会运行挂起的反应。

import { observable, transaction, autorun } from "mobx"

const numbers = observable([])

autorun(() => console.log(numbers.length, "numbers!"))
// Prints: '0 numbers!'

transaction(() => {
    transaction(() => {
        numbers.push(1)
        numbers.push(2)
    })
    numbers.push(3)
})
// Prints: '3 numbers!'

`untracked`

{🚀} 用法: untracked(worker: () => any)

Untracked 是一个低级 API。建议使用 reaction、action 或 runInAction 代替。

运行一段代码而不建立观察者。与 transaction 类似，untracked 由 action 自动应用，因此通常使用操作比直接使用 untracked 更有意义。

const person = observable({
    firstName: "Michel",
    lastName: "Weststrate"
})

autorun(() => {
    console.log(
        person.lastName,
        ",",
        // This untracked block will return the person's
        // firstName without establishing a dependency.
        untracked(() => person.firstName)
    )
})
// Prints: 'Weststrate, Michel'

person.firstName = "G.K."
// Doesn't print!

person.lastName = "Chesterton"
// Prints: 'Chesterton, G.K.'