@modern-js/main-doc 2.1.0 → 2.2.0

package/zh/guides/topic-detail/model/model-communicate.md

@@ -1,216 +0,0 @@
----
-sidebar_position: 7
-title: Model 通信
----
-
-Model 通信，既指不同 Model 间的通信，也指同一个 Model 内部 Effects、Actions 之间的通信。
-
-## Model 间通信
-
-Model 之间不是孤立的，是可以进行通信的。主要分为两种场景：
-
-1. 在 Model 中访问其它 Model 的 State 和 Actions。
-2. 在 Model 中监听其它 Model 变化。
-
-这里将 [快速上手](/docs/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.md)，所以 `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](/docs/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 函数。
-
-在 [副作用管理](/docs/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/zh/guides/topic-detail/model/performance.md

@@ -1,169 +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)
-:::

package/zh/guides/topic-detail/model/quick-start.md

@@ -1,110 +0,0 @@
----
-sidebar_position: 1
-title: 快速上手
----
-
-import ReduckMigration from '@site-docs/components/reduck-migration.md'
-
-<ReduckMigration />
-
-[Reduck](https://github.com/modern-js-dev/reduck) 是 Modern.js 团队开发的遵循 MVC 模式的状态管理库，底层状态存储基于 [Redux](https://redux.js.org/) 实现，同时提供更高层级的抽象，并完全兼容 Redux 生态。
-
-Reduck 的目标是以 MVC 模式组织 React 应用开发结构，将业务逻辑维护在 Model 层，业务逻辑与 UI 解耦，让开发业务逻辑更集中、更简单，同时通过更高层级的抽象，减少重复工作（样板代码）。
-
-Reduck 在 MVC 模式中，扮演 M(Model) 的角色，React UI Component 对应 V(View)，从 Reduck 中获取 Model 并修改 Model 的 React Container Component 对应 C(View Controller/Container)。
-
-Modern.js 的状态管理解决方案，是通过内置 Reduck 实现的。在 Modern.js 中使用 Reduck，不仅免去了手动集成的环节，而且所有 Reduck API 都可以从 Modern.js 的 Runtime 包中直接导入使用，具有更好的一致性体验。
-
-:::info 注
-1. Modern.js 中使用 Reduck API，需要先设置 [runtime.state](/docs/configure/app/runtime/state) 以启用状态管理插件。
-2. Reduck 也可以脱离 Modern.js 作为状态管理库[单独使用](/docs/guides/topic-detail/model/use-out-of-modernjs)。
-:::
-
-## 核心概念
-
-Reduck 中的核心概念只有 4 个： Model、State、Actions、Effects。
-
-Model: 对独立模块的逻辑和所需状态的封装，由 State、Actions、Effects 组成。
-
-State: Model 中保存的状态。
-
-Actions: 用于修改 State 的纯函数，函数必须是**同步**的。
-
-Effects: 用于修改 State 的带有副作用的函数，函数可以是**异步**的。Effects 中可以调用自身或其他 Model 的 Actions 和 Effects。
-
-Reduck 数据流如下图所示：
-
-![Reduck 数据流](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/reduck-concept.svg)
-
-## 基本用法
-
-下来我们以一个简单的 **计数器** 应用为例，演示 Reduck 的基本用法。
-
-首先，我们定义一个名为 `count` 的 Model：
-
-```js
-import { model } from '@modern-js/runtime/model';
-
-const countModel = model('count').define({
-  state: {
-    value: 1,
-  },
-});
-
-export default countModel;
-```
-
-我们使用 API `model` 创建 `countModel`，`countModel` 当前只包含存储计数器值的状态，即代码中的 `value`。
-
-我们定义一个 action，用于计算器自增加 1：
-
-```js
-import { model } from '@modern-js/runtime/model';
-
-const countModel = model('count').define({
-  state: {
-    value: 1,
-  },
-  actions: {
-    add(state) {
-      state.value += 1;
-    },
-  },
-});
-
-export default countModel;
-```
-
-在 `add` action 中，我们可以直接修改 state 的值，进行加 1 操作，而不需要把 state 作为不可变对象进行操作，这是因为 Reduck 集成了 [immer](https://github.com/immerjs/immer)，可以直接修改原 state 对象。
-
-接下来，我们演示如何在组件中使用 Model。
-
-新建一个组件 Counter，在组件内通过 `useModel` API 使用 `countModel`：
-
-```js
-import { useModel } from '@modern-js/runtime/model';
-import countModel from './models/count';
-
-function Counter() {
-  const [state, actions] = useModel(countModel);
-
-  return (
-    <div>
-      <div>counter: {state.value}</div>
-      <button onClick={() => actions.add()}>add</button>
-    </div>
-  );
-}
-```
-
-`useModel` 获取 `countModel` 的 `state` 和 `actions`，组件展示当前计算器的值，点击 `add` 按钮，计数器自增 1。
-
-:::info 注
-由于使用的案例比较简单，这里并没有严格按照 MVC 模式进行分层，组件 `Counter` 同时起到了 V 和 C 两层的作用。
-:::
-
-最终演示效果如下：
-
-![countModel](https://lf3-static.bytednsdoc.com/obj/eden-cn/eueh7vhojuh/modern/simple-count-model.gif)
-
-这样，我们就完了一个简单的计数器应用。本节完整的示例代码可以在[这里](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/counter-model)查看。

package/zh/guides/topic-detail/model/redux-integration.md

@@ -1,22 +0,0 @@
----
-sidebar_position: 11
-title: Redux 生态集成
----
-
-Reduck 基于 Redux 实现，因此可以使用 Redux [生态的库](https://redux.js.org/introduction/ecosystem)，实现功能增强。通过 [`Provider`](/docs/apis/app/runtime/model/Provider) 、[`createApp`](/docs/apis/app/runtime/model/create-app) 和 [`createStore`](/docs/apis/app/runtime/model/create-store) 等 API ，可以设置使用 Redux 的 [中间件](https://redux.js.org/understanding/thinking-in-redux/glossary#middleware) 和 [Store Enhancer](https://redux.js.org/understanding/thinking-in-redux/glossary#store-enhancer)；使用 [`createStore`](/docs/apis/app/runtime/model/create-store) 还可以完全掌控 Store 的创建过程。
-
-例如，我们希望使用中间件 [`redux-logger`](https://github.com/LogRocket/redux-logger)，示例代码如下：
-
-```ts
-ReactDOM.render(
-  <Provider config={{ middlewares: [logger] }}>
-    // 通过 Provider 的 config 参数设置 中间件
-    <App />
-  </Provider>,
-  document.getElementById('root'),
-);
-```
-
-:::caution
-Reduck 基于 Redux 底层 API 做了上层封装，屏蔽了 Redux 的一些底层概念，如 Reducer 等。Reduck 对于 Model 是动态挂载的，而 Redux 是在 Store 创建时就会挂载应用所需的全部状态。基于这些实现上的差异，有些 Redux 生态的库是无法直接在 Reduck 中使用的。
-:::

package/zh/guides/topic-detail/model/test-model.md

@@ -1,43 +0,0 @@
----
-sidebar_position: 9
-title: 测试 Model
----
-
-好的测试对代码的稳健性至关重要。下面以 [快速上手](/docs/guides/topic-detail/model/quick-start) 的 `countModel` 为例，演示在 Modern.js 中，如何对 Model 进行单元测试。
-
-使用测试功能，需要先开启该功能。在项目根目录下，执行 `pnpm run new`，进行如下选择：
-
-```bash
-? 请选择你想要的操作 启用可选功能
-? 启用可选功能 启用「单元测试 / 集成测试」功能
-```
-
-即可开启测试功能支持。
-
-新增 `count.test.ts` 文件，代码如下：
-
-```ts
-import { createStore } from '@modern-js/runtime/testing';
-import countModel from './count';
-
-describe('test model', () => {
-  it('count value should plus one after add', () => {
-    const store = createStore();
-    const [state, { add }] = store.use(countModel);
-
-    expect(state).toEqual({ value: 1 });
-
-    add();
-
-    expect(store.use(countModel)[0]).toEqual({ value: 2 });
-  });
-});
-```
-
-:::info 注
-这里使用的 [`createStore`](/docs/apis/app/runtime/model/create-store) 是从 `@modern-js/runtime/testing` 导入的，内部会使用 [`runtime.state`](/docs/configure/app/runtime/state) 的配置去创建 `store`。
-:::
-
-在测试用例里，我们新建一个 `store` 来挂载 `countModel`，通过 `store.use` 获取 `countModel` 的 State 和 Actions。然后调用 `add` Action 更新状态，并断言更新后的状态值。
-
-执行 `pnpm run test` 命令，触发测试用例的执行。

package/zh/guides/topic-detail/model/typescript-best-practice.md

@@ -1,70 +0,0 @@
----
-sidebar_position: 10
-title: TS 最佳实践
----
-
-Reduck 对 TS 提供了良好的支持，大部分使用场景下，无需任何额外工作，就可以直接获得 API 的 TS 类型提示。本节，将对其他的一些使用场景，做补充介绍。
-
-## 定义 Model 的 State 类型
-
-为 Model 的 State 声明类型信息，是在 TS 中使用 Reduck 的最佳实践。
-
-```ts title="示例"
-interface State {
-  data: string;
-}
-
-export const foo = model<State>('foo').define({
-  state: {
-    data: '',
-  },
-  computed: {
-    withSuffix: state => state.data + 'suffix',
-  },
-  actions: {
-    setData: (state, payload: string) => {
-      state.data = payload;
-    },
-  },
-});
-```
-
-当为 Model 的 State 声明类型信息后，Model 的 `computed`、`actions` 都能获取正确的类型信息。事实上，上面的示例代码中，即使我们不定义 State 类型信息，也会根据 `state` 的初始值信息自动推导出 State 的类型信息。不过，仍然建议你在定义 Model 时，声明 State 的类型信息，因为根据 `state` 的初始值信息推导出的 State 类型信息可能不完整(缺少字段或字段的类型信息缺少)，而且当使用[函数类型](/docs/apis/app/runtime/model/model_#函数类型)定义 Model 时，State 的类型信息也是无法根据 `state` 的初始值信息自动推导的。
-
-## 衍生状态的依赖类型
-
-当 Model 的衍生状态依赖其他 Model 时，需要手动指定其他 Model 的 State。
-
-```ts title="示例"
-interface State {
-  data: string;
-}
-
-export const bar = model<State>('bar').define({
-  state: {
-    data: '',
-  },
-  computed: {
-    // 为 fooState 指定类型
-    withFoo: [foo, (state, fooState: FooState) => state.data + fooState.data],
-  },
-});
-```
-
-## 获取 Model 类型信息的 Hooks
-
-Reduck 提供了一组用于获取 Model 类型信息的工具类型：
-
-- `GetModelState`： 获取 Model 的 State（包含衍生状态）类型信息。
-- `GetModelActions`：获取 Model 的 Actions（包含 Effects 函数）类型信息。
-
-```ts title="示例"
-export const foo = model<State2>('foo').define({
-  // 省略
-});
-
-// 获取 foo 的 State 类型
-let fooActions: GetModelActions<typeof foo>;
-// 获取 foo 的 Actions 类型
-let fooState: GetModelState<typeof foo>;
-```