Formily Reactive2.3.7

English

简体中文

English

简体中文

Appearance

observable ​

Mainly used to create observable objects with different responsive behaviors, and can be used as an annotation to define to mark responsive attributes

Core Idea ​

observable is the foundation of the reactive model. By creating a subscribable object, @formily/reactive can collect dependencies when a property is read and notify subscribers when a property is written. Internally it is mainly implemented with ES Proxy, so data operations on objects can be intercepted completely.

Besides using the observable APIs directly, you can also build domain models with define and model. Under the hood, they are still combining observable, computed, and action/batch capabilities.

observable/observable.deep ​

Description ​

Create deep hijacking responsive objects

Signature ​

ts
interface observable<T extends object> {
  (target: T): T
}

interface deep<T extends object> {
  (target: T): T
}

Example ​

Deep mode tracks nested properties, so mutating aa.bb and replacing aa will both trigger autorun.

autorun runs
1
current value
123
last tracked value
123
Raw Snapshot 
{
  "aa": {
    "bb": 123
  }
}
Last Tracked Snapshot 
{
  "aa": {
    "bb": 123
  }
}
Run Log
  • autorun #1: aa.bb = 123

Example Code ​

ts
import { autorun, observable } from '@formily/reactive'

const obs = observable({
  aa: {
    bb: 123,
  },
})

autorun(() => {
  console.log(obs.aa.bb)
})

obs.aa.bb = 321

observable.shallow ​

Description ​

Create shallow hijacking responsive objects, that is, only respond to the first-level attribute operations of the target object

Signature ​

ts
interface shallow<T extends object> {
  (target: T): T
}

Example ​

Shallow mode only tracks first-level properties. Mutating aa.bb changes the raw value, but it does not rerun autorun; replacing aa does.

autorun runs
1
current value
111
last tracked value
111
Raw Snapshot 
{
  "aa": {
    "bb": 111
  }
}
Last Tracked Snapshot 
{
  "aa": {
    "bb": 111
  }
}
Run Log
  • autorun #1: aa.bb = 111

Example Code ​

ts
import { autorun, observable } from '@formily/reactive'

const obs = observable.shallow({
  aa: {
    bb: 111,
  },
})

autorun(() => {
  console.log(obs.aa.bb)
})

obs.aa.bb = 222 // will not respond
obs.aa = { bb: 333 } // can respond

observable.computed ​

Description ​

Create a calculation buffer

Core Idea ​

computed can be understood as a cached reaction. As long as the observable data it depends on does not change, it keeps reusing the previous calculation result. It only recalculates when its dependencies change.

That also means a computed function should stay pure whenever possible. Its dependencies should be observable data or external constants. If it depends on ordinary external variables, changing those variables will not trigger a recalculation.

Signature ​

ts
interface computed {
  <T extends () => any>(target: T): { value: ReturnType<T> }
  <T extends { get?: () => any, set?: (value: any) => void }>(target: T): {
    value: ReturnType<T['get']>
  }
}

Example ​

The getter recalculates when its dependencies change. If aa and bb stay the same, reading computed.value repeatedly will hit the cache.

current sum
33
getter runs
1
autorun runs
1
Raw Snapshot 
{
  "aa": 11,
  "bb": 22
}
Cache Hint 
If the dependencies do not change, repeated reads reuse the cached value.
Run Log
  • autorun #1: sum = 33

Example Code ​

ts
import { autorun, observable } from '@formily/reactive'

const obs = observable({
  aa: 11,
  bb: 22,
})

const computed = observable.computed(() => obs.aa + obs.bb)

autorun(() => {
  console.log(computed.value)
})

obs.aa = 33

observable.ref ​

Description ​

Create reference hijacking responsive objects

Signature ​

ts
interface ref<T extends object> {
  (target: T): { value: T }
}

Example ​

observable.ref is useful for primitive values or whole-object references. Mutate value directly to trigger updates.

autorun runs
1
current value
1
last tracked value
1
Run Log
  • autorun #1: ref.value = 1

Example Code ​

ts
import { autorun, observable } from '@formily/reactive'

const ref = observable.ref(1)

autorun(() => {
  console.log(ref.value)
})

ref.value = 2

observable.box ​

Description ​

Similar to ref, except that the data is read and written through the get/set method

Signature ​

ts
interface box<T extends object> {
  (target: T): { get: () => T, set: (value: T) => void }
}

Example ​

observable.box behaves like ref, except reads and writes go through get and set.

autorun runs
1
current value
1
last tracked value
1
Run Log
  • autorun #1: box.get() = 1

Example Code ​

ts
import { autorun, observable } from '@formily/reactive'

const box = observable.box(1)

autorun(() => {
  console.log(box.get())
})

box.set(2)