@modern-js/main-doc 2.7.0 → 2.9.0

package/en/guides/topic-detail/model/manage-effects.mdx

@@ -1,260 +0,0 @@
----
-sidebar_position: 5
-title: 副作用管理
----
-# 副作用管理
-
-Model 中的 Action 必须是一个纯函数，执行过程中不会产生任何副作用。但在真实的业务中，我们会遇到很多副作用场景，如：请求 HTTP 接口获取状态数据，或者在更新状态的同时修改 localStorage、发送事件等。在 Reduck 中，是通过 Model 的 Effects 函数管理副作用的。
-
-## 副作用对 State 修改
-
-副作用修改 State，最常见的场景就是请求 HTTP 接口，更新状态数据。
-
-我们以一个简单的 `todoModel` 为例。其有一个 `load` 的副作用函数，请求远端的 TODO 列表，请求成功之后更新 `state.items` 字段。
-
-```ts
-const todoModel = model('todo').define({
-  state: {
-    items: [],
-    loading: false,
-    error: null,
-  },
-  actions: {
-    load: {
-      pending(state) {
-        state.loading = true;
-      },
-      fulfilled(state, items) {
-        state.items = items;
-        state.loading = false;
-      },
-      rejected(state, error) {
-        state.error = error;
-        state.loading = false;
-      },
-    },
-  },
-  effects: {
-    // Promise 副作用
-    async load() {
-      return new Promise(resolve => {
-        setTimeout(() => resolve(['Learn Modern.js']), 2000);
-      });
-    },
-  },
-});
-```
-
-副作用函数统一定义在 `effects` 字段下。这里我们写了一个 `load` 函数，它返回一个 Promise，Promise 执行成功后，返回 TODO 列表 `["Lerna Modern.js"]`。
-
-副作用函数需要和 actions 配合使用，才能完成状态的修改。因此，我们在 `actions` 中定义了一个 `load`（命名需要和 `effects` 下的副作用函数的名字保持一致）对象，包含 `pending`、`fulfilled`、`rejected` 3 个 action，分别是对副作用函数 `load` 返回的 `Promise` 的三种状态（ pending、fulfilled、rejected ）的处理：
-
-- `pending`：接收当前状态 `state` 作为参数，新的状态中 `loading` 设为 `true`。
-- `fulfilled`：接收当前状态 `state` 和 Promise fulfilled 状态的值 `items` 为参数，新的状态中 `items` 等于参数 `items`、`loading` 设为 `false`。
-- `rejected`：接收当前状态 `state` 和 Promise rejected 状态的错误 `error` 为参数，新的状态中 `error` 等于参数 `error`、`loading` 设为 `false`。
-
-组件中如何调用 effects 函数呢？ effects 函数会被合并到 actions 对象上，因此可以通过 actions 对象调用 effects 函数，如下所示：
-
-```ts
-function Todo() {
-  const [state, actions] = useModel(todoModel);
-
-  useEffect(() => {
-    // 调用 effects 函数
-    actions.load();
-  }, []);
-
-  if (state.loading) {
-    return <div>loading....</div>;
-  }
-
-  return (
-    <div>
-      <div>
-        {state.items.map((item, index) => (
-          <div key={index}>{item}</div>
-        ))}
-      </div>
-    </div>
-  );
-}
-```
-
-上面的示例中， `pending`、`fulfilled`、`rejected` 3 个 action，对于用于获取数据的 HTTP 请求场景下，一般都是需要的。Reduck 提供了一个工具函数 `handleEffect`，用于简化这种场景下的 action 创建。
-
-`handleEffect` 约定这种副作用场景下， Model 的 State 结构包含 `result`、`error`、`pending` 3 个字段，初始值为：
-
-```ts
-{
-  result: null,
-  error: null,
-  pending: false，
-}
-```
-
-调用 `handleEffect` 会返回如下数据结构:
-
-```ts
-{
-  pending() { // ... },
-  fulfilled() { // ... },
-  rejected() { // ... }
-}
-```
-
-这个数据结构和我们在 `actions` 下的 `load` 对象的数据结构是相同的。`handleEffect` 返回的对象，其实就是对应了 Effects 函数需要的 3 个 action。
-
-利用 `handleEffect`，改写 `todoModel`：
-
-```ts
-const todoModel = model('todo').define({
-  state: {
-    items: [],
-    loading: false,
-    error: null,
-  },
-  actions: {
-    load: handleEffect({ result: 'items' }),
-  },
-  effects: {
-    // Promise 副作用
-    async load() {
-      return new Promise(resolve => {
-        setTimeout(() => resolve(['Learn Modern.js']), 2000);
-      });
-    },
-  },
-});
-```
-
-`handleEffect` 接收的参数对象，将 `result` 设置为 `item`。因为 `todoModel` 的 state，使用 `items` 作为 key 保存 todo 列表数据，而不是使用 `handleEffect` 默认的 `result` 作为 key，所以这里需要进行配置。
-
-明显可见，通过 `handleEffect` 实现的 `todoModel` 比之前的实现有了很大精简。
-
-如果不希望 pending、fulfilled、rejected 3 种状态都被 `handleEffect` 自动处理，例如 fulfilled 需要手动处理较复杂的数据类型，但是 pending、rejected 依旧想进行自动化处理，可以参考如下写法：
-
-```ts
-  actions: {
-    load: {
-      ...handleEffect(),
-      fulfilled(state, payload) {
-        // 手动处理
-      },
-    },
-  },
-```
-
-:::info 补充信息
-`handleEffect` [API](/apis/app/runtime/model/handle-effect)。
-
-:::
-
-Effects 函数中，也支持手动调用 Actions，例如：
-
-```ts
-const todoModel = model('todo').define((context, utils) => ({
-  state: {
-    items: [],
-    loading: false,
-    error: null,
-  },
-  actions: {
-    pending(state) {
-      state.loading = true;
-    },
-    fulfilled(state, items) {
-      state.items = items;
-      state.loading = false;
-    },
-  },
-  effects: {
-    async load() {
-      // 通过 utils.use 获取当前 Model 对象的 actions
-      const [, actions] = utils.use(todoModel);
-      // 手动调用 action
-      actions.pending();
-
-      return new Promise(resolve => {
-        setTimeout(() => {
-          const items = ['Learn Modern.js'];
-          // 手动调用 action
-          actions.fulfilled(items);
-          resolve(items);
-        }, 2000);
-      });
-    },
-  },
-}));
-```
-
-:::info
-可以使用 `use` 函数加载其它 Model（包括 Model 自身），实现 [Model 间通信](/guides/topic-detail/model/model-communicate)。
-
-:::
-
-## 副作用不影响 state
-
-有些场景下，我们只需要读取 State，执行相关副作用逻辑，副作用不会修改 State。
-
-例如，存储某些 State 到 `localStorage`：
-
-```ts
-const fooModel = model('foo').define((context, utils) => ({
-  state: {
-    value: 'foo',
-  },
-  effects: {
-    setLocalStorage(key) {
-      const [state] = utils.use(fooModel);
-      localStorage.set(key, state.value);
-      return 'success';
-    },
-  },
-}));
-```
-
-或者是向服务端发送数据：
-
-```ts
-const fooModel = model('foo').define({
-  state: {
-    value: 'foo',
-  },
-  effects: {
-    async sendData(data) {
-      const res = await fetch('url', {
-        method: 'POST',
-        body: data,
-      });
-      return res.json();
-    },
-  },
-});
-```
-
-## 副作用函数返回值
-
-有时候，我们希望能根据副作用函数的执行结果，直接执行后续逻辑。这时候，就需要使用 Effects 函数的返回。
-
-例如，当点击发送按钮，发送数据成功后，立即关闭当前的弹窗；如果失败，显示错误信息。我们可以通过如下代码实现：
-
-```ts
-// 代码仅做示意，不能执行
-// 组件内部 发送按钮 的响应函数
-const handleClick = async () => {
-  // sendData 返回代表状态的字符串
-  const result = await actions.sendData('some data');
-  if (result === 'success') {
-    // 关闭弹窗
-    closeModal();
-  } else {
-    // 显示错误
-    showError(result);
-  }
-};
-```
-
-:::info 补充信息
-[示例代码](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/effects)
-
-:::

package/en/guides/topic-detail/model/model-communicate.mdx

@@ -1,220 +0,0 @@
----
-sidebar_position: 7
-title: Model 通信
----
-# Model 通信
-
-Model 通信，既指不同 Model 间的通信，也指同一个 Model 内部 Effects、Actions 之间的通信。
-
-## Model 间通信
-
-Model 之间不是孤立的，是可以进行通信的。主要分为两种场景：
-
-1. 在 Model 中访问其它 Model 的 State 和 Actions。
-2. 在 Model 中监听其它 Model 变化。
-
-这里将 [快速上手](/guides/topic-detail/model/quick-start) 一节的简单计数器应用改造成一个可设置步频的计数器应用。可以通过设置步频，从而影响每次计数器增加的幅度。
-
-我们抽象出两个 Model，分别为 `stepModel`（步频）、`counterModel`（计数器）：
-
-```ts
-import { model } from '@modern-js/runtime/model';
-
-const stepModel = model('step').define({
-  state: 1,
-});
-
-const counterModel = model('count').define((context, { use, onMount }) => {
-  const [, , subscribeStep] = use(stepModel);
-
-  onMount(() => {
-    return subscribeStep(() => {
-      console.log(
-        `Subscribe in counterModel: stepModel change to ${use(stepModel)[0]}`,
-      );
-    });
-  });
-
-  return {
-    state: {
-      value: 1,
-    },
-    actions: {
-      add(state) {
-        const step = use(stepModel)[0];
-        state.value += step;
-      },
-    },
-  };
-});
-
-export { stepModel, counterModel };
-```
-
-`stepModel` 只声明一个 `state`，初始值为 1。
-
-`counterModel` 通过 `use` 函数加载 `stepModel`，拿到返回的 `subscribeStep` 函数，用来监听 `stepModel` 状态的变更。 `onMount` 是 Model 挂载完成后的钩子函数，`counterModel` 挂载完成后开始订阅 `stepModel` 状态的变更，打印出 `stepModel` 的最新值。
-
-`counterModel` 通过 `use` 函数访问 `stepModel`，在 `add` 里可以获取到当前 `stepModel` 的值（步频），以此值来做自增。
-
-:::caution 注意
-当需要访问其他 Model 的 State 时，必须要在当前 Actions 或 Effects 函数（本例中对应 `add` 函数 ）真正执行的阶段调用 `use`，以保证获取的 State 是最新值。因此，我们虽然在 `define` 的回调函数中也调用了 `use(stepModel)`，但是我们并没有解构 `stepModel` 的 `state` 值，因为 `define` 的回调函数是在 Model 的挂载阶段执行的，这个时候获取到的 `stepModel` 的 `state` 可能和 `add` 执行时获取到的值是不同的。
-
-:::
-
-修改 **App.tsx**
-
-```tsx
-import { useModel } from '@modern-js/runtime/model';
-import { counterModel, stepModel } from './models/count';
-
-function Counter() {
-  const [state, actions] = useModel(counterModel);
-  const [step, stepActions] = useModel(stepModel);
-
-  return (
-    <div>
-      <div>step: {step}</div>
-      <button onClick={() => stepActions.setState(step + 1)}>add step</button>
-      <div>counter: {state.value}</div>
-      <button onClick={() => actions.add()}>add counter</button>
-    </div>
-  );
-}
-
-export default function App() {
-  return <Counter />;
-}
-```
-
-:::info 补充信息
-Modern.js 默认开启 [自动生成 actions](./auto-actions.mdx)，所以 `stepModel` 中虽然没有手动定义 Actions，但可以使用自动生成的 `setState`。
-
-:::
-
-- 点击 **add step** 增加步频。
-- 点击 **add counter** 触发计数器增加。
-
-最终效果如下：
-
-![communicate-models](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/models-communicate.gif)
-
-:::info 补充信息
-- 本节完整的[示例代码](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/models-communication)。
-- 相关 API 的更多介绍，请参考：[model](/apis/app/runtime/model/model_#函数类型)。
-
-:::
-
-前面 `counterModel` 的例子，我们是在 Actions 的函数内部调用 `use` 获取其他 Model 对象的。如果只需要调用其它 Model 的 Actions，因为 Actions 都是函数，不存在值过期问题，所以也可以在 `define` 的回调函数中调用 `use` 获取 Model 的 Actions。例如：
-
-```ts
-const barModel = model('bar').define({
-  // 省略
-});
-
-const fooModel = model('foo').define((context, utils) => {
-  // 获取 barModel 的 actions
-  const [, actions] = utils.use(barModel);
-  return {
-    // 省略 state、actions
-    effects: {
-      async loadA() {
-        // 省略副作用逻辑
-        // 调用 barModel 的 action
-        barModel.actionA();
-      },
-      async loadB() {
-        // 省略副作用逻辑
-        // 调用 barModel 的 action
-        barModel.actionB();
-      },
-    },
-  };
-});
-```
-
-这样，我们不需要在 `loadA`、`loadB` 中重复获取 `barModel` 对象，简化了代码逻辑。
-
-## Model 内通信
-
-Model 内通信，也主要分为两种场景：
-
-1. Effects 函数调用自身 Model 的 Actions 函数、或其他 Effects 函数。
-2. Actions 函数调用自身 Model 的 其他 Actions 函数。
-
-在 [副作用管理](/guides/topic-detail/model/manage-effects) 一节，我们演示过 Effects 函数如何调用 Actions 函数。
-
-这里我们再来举一个例子：
-
-```ts
-const fooModel = model('foo').define((context, { use, onMount }) => ({
-  state: {
-    a: '',
-    b: '',
-  },
-  actions: {
-    setA(state, payload) {
-      state.a = payload;
-    },
-    setB(state, payload) {
-      state.a = payload;
-    },
-  },
-  effects: {
-    async loadA() {
-      // 通过 use 获取当前 Model 的 actions
-      const [, actions] = use(fooModel);
-      const res = await mockFetchA();
-      actions.setA(res);
-    },
-    async loadB() {
-      // 通过 use 获取当前 Model 的 actions
-      const [, actions] = use(fooModel);
-      const res = await mockFetchB();
-      actions.setB(res);
-    },
-  },
-}));
-```
-
-这个例子中，`fooModel` 的两个 Effects 函数，需要调用自身的 Actions 函数。这里我们在每个 Effects 函数中，都调用了一次 `use`，为什么不能像 Model 间通信的例子中，在 `define` 的回调函数中，统一调用 `use` 获取 Model 自身的 Actions 呢？这是因为调用 `use` 获取 Model 时，会先检查这个 Model 是否已经挂载，如果还没有挂载，会先执行挂载逻辑，而 `define` 的回调函数又是在 Model 的挂载阶段执行的，这样一来，在挂载阶段调用 `use` 获取 Model 自身，会出现死循环（代码实际执行过程会抛出错误）。所以，**一定不能在 `define` 的回调函数中，调用 `use` 获取 Model 自身对象。**
-
-不过，我们可以利用 `onMount` 这个钩子函数，在 Model 挂载完成后，再通过 `use` 获取 Model 自身对象：
-
-```ts
-const fooModel = model('foo').define((context, { use, onMount }) => {
-  let actions;
-
-  onMount(() => {
-    // fooModel 挂载完成后，通过 use 获取当前 Model 的 actions
-    [, actions] = use(fooModel);
-  });
-
-  return {
-    state: {
-      a: '',
-      b: '',
-    },
-    actions: {
-      setA(state, payload) {
-        state.a = payload;
-      },
-      setB(state, payload) {
-        state.a = payload;
-      },
-    },
-    effects: {
-      async loadA() {
-        const res = await mockFetchA();
-        actions.setA(res);
-      },
-      async loadB() {
-        const res = await mockFetchB();
-        actions.setB(res);
-      },
-    },
-  };
-});
-```
-
-这样，我们也可以实现代码的简化。

package/en/guides/topic-detail/model/performance.mdx

@@ -1,171 +0,0 @@
----
-sidebar_position: 8
-title: 性能优化
----
-# 性能优化
-
-Reduck 内部已经做了大量性能优化工作，一般情况下不需要考虑性能问题。不过当对性能比较敏感、或者遇到了性能问题，可以考虑从以下 3 个方面，进行更有针对性的性能优化。
-
-## Model 拆分
-
-当 `useModel` 返回 Model 对象的完整 State 时，State 任意部分的变化都会导致调用了 `useModel` 的组件重新渲染。
-
-例如：
-
-```ts
-const fooModel = model('foo').define({
-  state: {
-    a: '',
-    b: '',
-  },
-  actions: {
-    setA(state, payload) {
-      state.a = payload;
-    },
-    setB(state, payload) {
-      state.b = payload;
-    },
-  },
-});
-
-function ComponentA() {
-  const [state] = useModel(fooModel);
-
-  return <div>{state.a}</div>;
-}
-```
-
-组件 `ComponentA` 虽然只需要使用 `a` 状态，但当 `b` 状态发送变化时， `ComponentA` 仍然会重新渲染。这种情况，我们可以考虑把 `fooModel` 拆分，`a`、`b` 分别由不同的 Model 负责管理：
-
-```ts
-const fooModel = model('foo').define({
-  state: {
-    a: '',
-  },
-  actions: {
-    setA(state, payload) {
-      state.a = payload;
-    },
-  },
-});
-
-const barModel = model('bar').define({
-  state: {
-    b: '',
-  },
-  actions: {
-    setB(state, payload) {
-      state.b = payload;
-    },
-  },
-});
-```
-
-## 状态筛选
-
-`useModel` 支持传入 selector 函数，对返回给组件的 State 和 Actions 做筛选。我们可以通过 selector 函数，确保返回给组件的 State 是组件直接需要使用的，从而保证组件不会因为其他无关状态的变化而重新渲染。
-
-对于上面同样的例子，我们采用 selector 函数进行性能优化，代码如下：
-
-```ts
-const fooModel = model('foo').define({
-  state: {
-    a: '',
-    b: '',
-  },
-  actions: {
-    setA(state, payload) {
-      state.a = payload;
-    },
-    setB(state, payload) {
-      state.b = payload;
-    },
-  },
-});
-
-function ComponentA() {
-  // 通过传入 selector 函数，只返回 a 状态给组件
-  const [stateA] = useModel(fooModel, state => state.a);
-
-  return <div>{stateA}</div>;
-}
-```
-
-## 衍生状态缓存
-
-当 Model 存在 `computed` 时，每次调用`useModel` 都会执行 `computed` 函数。
-
-考虑如下代码：
-
-```ts
-const barModel = model('bar').define({
-  state: {
-    value: 'bar',
-  },
-  computed: {
-    combineA: [
-      fooModel, // fooModel 定义同上
-      (state, fooState) => {
-        return state + fooState.a;
-      },
-    ],
-  },
-  actions: {
-    setValue(state, payload) {
-      state.value = payload;
-    },
-  },
-});
-
-function ComponentB() {
-  const [state, actions] = useModel(fooModel);
-  const [{ combineA }] = useModel(barModel);
-  // 省略
-}
-```
-
-`barModel` 的衍生状态 `combineA` 依赖 `barModel` 自身状态 和 `fooModel` 的状态 `a`，但是即使是 `fooModel` 的状态 `b` 发生了变化，组件重新渲染时， `combineA` （更准确的说法是 `combineA` 的最后一个函数类型的元素 ）依然会被调用执行。
-
-一般情况下，`computed` 函数中的逻辑都是非常轻量的，但当 `computed` 函数逻辑比较复杂时，我们可以考虑对计算逻辑做缓存。例如，我们使用 [reselect](https://github.com/reduxjs/reselect) 对 `barModel` 的 `combineA` 做缓存：
-
-```ts
-import 'createSelector' from 'reselect';
-
-// 创建缓存函数
-const selectCombineA = createSelector(
-  (state) => state.bar.value,
-  (state) => state.foo.a,
-  (barState, fooState) => {
-    return barState + fooState;
-  }
-);
-
-const barModel = model("bar").define({
-  state: {
-    value: "bar",
-  },
-  computed: {
-    combineA: [
-      fooModel,
-      (state, fooState) => {
-        return selectCombineA({
-          foo: fooState,
-          bar: state,
-        });
-      },
-    ],
-  },
-  actions: {
-    setValue(state, payload) {
-      state.value = payload;
-    },
-  },
-});
-```
-
-我们创建缓存函数 `createSelector`，仅当 `barModel` 的状态发生改变或 `fooModel` 的 `a` 状态发生改变时，才会重新计算 `combineA` 的值。
-
-:::info 补充信息
-本节完整的[示例代码](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/performance-optimization)
-
-:::