@modern-js/main-doc 2.69.4 → 3.0.0-alpha.0

package/docs/zh/guides/topic-detail/model/_meta.json

@@ -1,14 +0,0 @@
-[
-  "quick-start",
-  "define-model",
-  "use-model",
-  "computed-state",
-  "manage-effects",
-  "auto-actions",
-  "model-communicate",
-  "performance",
-  "typescript-best-practice",
-  "redux-integration",
-  "use-out-of-modernjs",
-  "faq"
-]

package/docs/zh/guides/topic-detail/model/auto-actions.mdx

@@ -1,88 +0,0 @@
-# 自动生成 Actions
-
-在 [快速上手](/guides/topic-detail/model/quick-start) 中，我们实现最简单的计数器 Model 也需要 10 行代码。
-实际上，Modern.js 支持根据声明的 `state` 类型，自动生成常用的 Actions，从而简化模板代码量。当前支持的类型有：
-
-- 原始数据类型
-- 数组类型
-- 简单对象类型（Plain Object）
-
-## 原始数据类型
-
-```ts
-const countModel = model('count').define({ state: 1 });
-```
-
-如上我们仅用一行就完成了一个简单的 `countModel`。使用 Model 的示例代码如下：
-
-```tsx
-function Counter() {
-  const [state, actions] = useModel(countModel);
-
-  useEffect(() => {
-    // 增加 1
-    actions.setState(state + 1);
-  }, []);
-}
-```
-
-## 数组类型
-
-当 State 为数组类型时，自动生成 Actions 的示例代码如下：
-
-```ts
-const countModel = model('count').define({ state: [] });
-
-function Counter() {
-  const [state, actions] = useModel(countModel);
-
-  useEffect(() => {
-    actions.push(1);
-    actions.pop();
-    actions.shift();
-    actions.unshift(1);
-    actions.concat([1]);
-    actions.splice(0, 1, 2);
-    actions.filter(value => value > 1);
-  }, []);
-}
-```
-
-我们可以使用 JavaScript Array 对象的方法，修改 State。
-
-## 简单对象类型
-
-当 State 为简单对象类型时，自动生成 Actions 的示例代码如下：
-
-```ts
-const countModel = model('count').define({
-  state: {
-    a: 1,
-    b: [],
-    c: {},
-  },
-});
-
-function Counter() {
-  const [state, actions] = useModel(countModel);
-
-  useEffect(() => {
-    actions.setA(2);
-    actions.setB([1]);
-    actions.setC({ a: 1 });
-  }, []);
-}
-```
-
-根据 `a`、`b`、`c` 三个不同的字段分别生成 `setA`、`setB`、`setC` 三个 Actions。
-
-:::info
-当用户自定义的 Action 和 Modern.js 自动生成的 Action 名字一致时，用户自定义的 Action 优先级更高。例如，
-在 `countModel` 中已经自定义 `setA` 这个 Action，调用 `actions.setA()` 时，最终执行的是用户自定义的 `setA`。
-
-:::
-
-:::info 补充信息
-相关 API 的更多介绍，请参考[这里](/apis/app/runtime/model/auto-actions)。
-
-:::

package/docs/zh/guides/topic-detail/model/computed-state.mdx

@@ -1,147 +0,0 @@
-# 衍生状态
-
-一些场景中，组件需要对 Model 中的 State 进行进一步计算，才能在组件中使用，这部分逻辑可以直接写在组件内部，也可以通过 Model 的衍生状态实现。
-衍生状态定义在 Model 中的 `computed` 字段下。根据依赖的 Model 的不同、返回类型的不同，衍生状态的定义方法可以分为以下 3 种。
-
-## 只依赖自身的 State
-
-衍生状态只依赖当前 Model 的 State，State 会作为第一个参数，传入衍生状态的定义函数中。
-
-例如， todo 应用的 State 有 `items` 和 `filter`，`filter` 用于过滤当前页面显示的 todo 项，所以我们定义了一个 `visibleTodos` 的衍生状态可以直接在组件中使用。示例代码如下：
-
-```ts
-/**
- *  假设 todo item 结构如下：
-{
-    id: string;          // id
-    text: string;        // todo 事项
-    completed: boolean;  // 完成状态：0 代表未完成，1 代表完成
-}
-**/
-
-const todoModel = model('todo').define({
-  state: {
-    items: [],
-    filter: 'ALL', // ALL: 显示全部；COMPLETED：显示完成的事项；ACTIVE：显示未完成的事项
-  },
-  computed: {
-    visibleTodos: state => {
-      switch (state.filter) {
-        case 'ALL':
-          return state.items;
-        case 'COMPLETED':
-          return todos.filter(t => t.completed);
-        case 'ACTIVE':
-          return todos.filter(t => !t.completed);
-        default:
-          return [];
-      }
-    },
-  },
-});
-```
-
-衍生状态最终会和 Model 的 State 进行合并，因此，可以通过 Model 的 State 对象访问到衍生状态，例如，`visibleTodos` 在组件内的使用方式如下：
-
-```ts
-function Todo() {
-  const [state, actions] = useModel(todoModel);
-
-  return (
-    <div>
-      <div>
-        {state.visibleTodos.map(item => (
-          <div key={item.id}>{item.text}</div>
-        ))}
-      </div>
-    </div>
-  );
-}
-```
-
-## 依赖其他 Model 的 State
-
-除了依赖当前 Model 的 State，衍生状态还依赖其他 Model 的 State，这时候衍生状态的定义格式为：
-
-```ts
-[stateKey]: [...depModels, (selfState, ...depModels) => computedState]
-```
-
-下面的示例，演示了 `barModel` 的衍生状态 `combinedValue` 是如何依赖 `fooModel` 的 State 的。
-
-```ts
-const fooModel = model('foo').define({
-  state: {
-    value: 'foo',
-  },
-});
-
-const barModel = model('bar').define({
-  state: {
-    value: 'foo',
-  },
-  computed: {
-    combinedValue: [
-      fooModel,
-      (state, fooState) => state.value + fooState.value,
-    ],
-  },
-});
-```
-
-## 函数类型的衍生状态
-
-衍生状态还可以返回一个函数。这时候衍生状态的定义格式为：
-
-```ts
-[stateKey]: (state) => (...args) => computedState    // 只依赖自身的 state
-[stateKey]: [...depModels, (selfState, ...depModels) => (...args) => computedState]  // 依赖其他 Model 的 state
-```
-
-假设，todo 应用的 state 不存储 `filter` 状态，而是直接在组件中使用，那么 `visibleTodos` 可以是一个函数类型的值，这个函数在组件中使用的时候，接收 `filter` 参数。如下所示：
-
-```ts
-const todoModel = model('todo').define({
-  state: {
-    items: [],
-  },
-  computed: {
-    visibleTodos: state => filter => {
-      switch (filter) {
-        case 'ALL':
-          return state.items;
-        case 'COMPLETED':
-          return todos.filter(t => t.completed);
-        case 'ACTIVE':
-          return todos.filter(t => !t.completed);
-        default:
-          return [];
-      }
-    },
-  },
-});
-
-function Todo(props) {
-  // filter 状态通过 props 传入
-  const { filter } = props;
-  const [state, actions] = useModel(todoModel);
-
-  // 计算得到最终要显示的 todos
-  const todos = state.visibleTodos(filter);
-
-  return (
-    <div>
-      <div>
-        {todos.map(item => (
-          <div key={item.id}>{item.text}</div>
-        ))}
-      </div>
-    </div>
-  );
-}
-```
-
-:::info 更多参考
-[使用 Model](/guides/topic-detail/model/computed-state)
-
-:::

package/docs/zh/guides/topic-detail/model/define-model.mdx

@@ -1,63 +0,0 @@
-# 创建 Model
-
-上一节的计数器应用中，我们简单演示了如何创建一个 Model。本节我们将详细介绍 Model 的创建方法。
-
-通过 `model` API 创建 Model，例如，`model('foo')` 表示要创建一个名为 `foo` 的 Model，通过调用 `model('foo')` 返回的 `define` 函数，定义 Model 包含的 State、Actions 等：
-
-```js
-import { model, useModel } from '@modern-js/runtime/model';
-
-const fooModel = model('foo').define({
-  state: {
-    value: 'foo',
-  },
-  actions: {
-    setValue: (state, payload){
-      state.value = payload
-    }
-  }
-});
-```
-
-:::info
-
-- Model 中的 Action 中不能包含有副作用的逻辑，如请求 HTTP 接口，访问 localStorage 等。
-- `setValue` 内部直接修改了入参 State，看起来是违反了纯函数的定义，实际上 Reduck 内部使用 [immer](https://github.com/immerjs/immer) 来修改不可变对象，保证了这种写法不会影响对象的不可变性，所以 `setValue` 仍然是一个纯函数。当然，你也可以直接在 Action 中返回一个新对象，不过这样的写法会更加复杂一些。
-
-:::
-
-`define` 接收的参数，只是对 Model 原始结构的描述：内部定义的 State、Actions 等。`define` 返回值 `fooModel` 才是真正创建得到的 Model 对象。例如，虽然 `setValue`，有 2 个参数，但是当真正调用 `setValue` 这个 Action 时，我们只需要传入 `payload` 一个参数，因为我们调用的是 `fooModel` 上的 Action 方法，而不是 Model 原始结构上描述的 Action 方法。详细参考[使用 Model](/guides/topic-detail/model/use-model)。
-
-`define` 除了接收对象类型的参数，还可以接收函数类型的参数。例如：
-
-```js
-import { model, useModel } from '@modern-js/runtime/model';
-
-const fooModel = model('foo').define((context, utils) => {
-  return {
-    state: {
-      value: 'foo',
-    },
-    actions: {
-      setValue: (state, payload){
-        state.value = payload
-      }
-    }
-  }
-});
-```
-
-通过函数定义 Model 时，函数内部会自动传入 `context`、`utils` 2 个参数，`context` 是 Reduck 的上下文对象，可以获取到 `store` 对象，`utils` 提供了一组工具函数，方便实现 Model 通信等复杂功能需求。
-
-Model 支持复制。例如：
-
-```ts
-const barModel = fooModel('bar');
-```
-
-barModel 是基于 fooModel 创建出一个的新的 Model 对象，类比面向对象编程语言中的概念，barModel 和 fooModel 是基于同一个类（Class）创建出的 2 个实例对象。当两个模块的状态管理逻辑相同，例如一个页面中的两个 tab 模块，使用的数据的结构和逻辑相同，区别只是从不同的接口获取数据，那么可以通过 Model 复制的方式，创建 2 个不同的 Model 对象。
-
-:::info 补充信息
-本节涉及的 API 的详细定义，请参考[这里](/apis/app/runtime/model/model_)。
-
-:::

package/docs/zh/guides/topic-detail/model/faq.mdx

@@ -1,36 +0,0 @@
-# 常见问题
-
-## 浏览器兼容性
-
-Reduck 的编译构建产物默认使用 ES6 语法，如果你需要支持更低版本的浏览器，请将 `@modern-js-reduck` 命名空间下的所有包加入到应用的编译过程。
-
-:::info 补充信息
-Reduck 使用的 [`@babel/preset-env`](https://babeljs.io/docs/en/babel-preset-env) 的详细[配置](https://github.com/web-infra-dev/reduck/blob/main/common/config.js#L10~L17)。
-
-:::
-
-## 微前端子应用 Model 访问主应用 Model
-
-微前端子应用 Model 访问主应用 Model 时，如果该 **Model** 在主应用尚未挂载，会自动挂载到子应用上。
-
-示例：
-
-```ts
-import { useModel } from '@modern-js/runtime/model';
-import parentModel from '@MasterApp/models/todoModel';
-
-function SubModelApp() {
-  const [state, actions] = useModel(parentModel);
-
-  return <div>...</div>;
-}
-```
-
-![微前端通信流程图](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/mf-communicate.svg)
-
-为了避免意外降级挂载，建议将主应用所需要共享的 Model 预先挂载：
-
-```ts
-// App 是主应用的入口组件，sharedModel1、sharedModel2 是需要共享的 Model。
-App.models = [sharedModel1, sharedModel2];
-```

package/docs/zh/guides/topic-detail/model/manage-effects.mdx

@@ -1,256 +0,0 @@
-# 副作用管理
-
-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/web-infra-dev/modern-js-examples/tree/main/examples/runtime-api/effects)
-
-:::