@modern-js/main-doc 2.1.0 → 2.2.0

package/zh/apis/app/runtime/model/auto-actions.mdx

@@ -0,0 +1,122 @@
+---
+sidebar_position: 6
+title: Auto actions
+---
+# Auto actions
+
+import ReduckTip from "@site-docs/components/reduck-tip"
+
+<ReduckTip />
+
+Reduck 可以根据 State 的类型，自动生成相应的 Actions，为修改 State 提供便利。
+
+:::tip 提示
+可通过 [`runtime.state.autoActions`](/configure/app/runtime/state#autoactions) 关闭 auto actions 功能。
+
+:::
+
+## 示例
+
+### 基础数据类型
+
+State 类型为 `string`、`number`、`boolean`、`null` 时，生成 `setState` Action。
+
+```tsx title="示例"
+const fooModel = model('foo').define({
+  state: 1,
+});
+
+function App() {
+  const [state, actions] = useModel(fooModel);
+
+  return (
+    <div>
+      <div>State: {state}</div>
+      <button
+        type="button"
+        onClick={() => {
+          // 调用自动生成的 setState Action
+          actions.setState(state + 1);
+        }}
+      >
+        add
+      </button>
+    </div>
+  );
+}
+```
+
+### 数组 Array
+
+State 类型为 Array 时，生成下列 Actions：
+
+- `push`：将一个或多个元素添加到数组的末尾。
+- `pop`：从数组中删除最后一个元素。
+- `shift`：从数组中删除第一个元素。
+- `unshift`：将一个或多个元素添加到数组的开头。
+  - 语法：`arr.unshift(element1, ..., elementN)`
+  - `elementN`：要添加到数组开头的元素或多个元素。
+- `filter`：过滤元素。
+{/* 语义与原生方法不同，待修改 API  */}
+- `concat`：拼接数组。
+{/* 语义与原生方法不同，待修改 API  */}
+- `splice`：通过删除或替换现有元素或者原地添加新的元素来修改数组，并以数组形式返回修改后的数组（注意和原生 `splice` 返回值不同）。
+  - 语法：`splice(start[, deleteCount[, item1[, item2[, ...]]]])`
+  - `start`：指定修改的开始位置（从 0 计数）。
+  - `deleteCount`：可选，整数，表示要移除的数组元素的个数。
+  - `item, item2, ...`：可选，要添加进数组的元素，从 start 位置开始。如果不指定，则 `splice` 将只删除数组元素。
+
+```tsx title="示例"
+const fooModel = model('foo').define({
+  state: [1, 2, 3],
+});
+
+function App() {
+  const [state, actions] = useModel(fooModel);
+
+  useEffect(() => {
+    actions.push(4);
+    actions.pop();
+    actions.shift(0);
+    actions.unshift();
+    actions.filter(val => val <= 2);
+    actions.splice(0, 1, 1, 2);
+  }, []);
+
+  return (
+    <div>
+      <div>State: {state}</div>
+    </div>
+  );
+}
+```
+
+### 简单对象 PlainObject
+
+State 类型为 PlainObject 时，根据 State 包含的属性名，生成 `set${key}`（小驼峰命名）Actions。
+
+```tsx title="示例"
+const fooModel = model('foo').define({
+  state: {
+    a: 1,
+    b: { value: 1 },
+    c: 'c',
+  },
+});
+
+function App() {
+  const [state, actions] = useModel(fooModel);
+
+  useEffect(() => {
+    actions.setA(2);
+    actions.setB({ value: 2 });
+    actions.setC('d');
+  }, []);
+
+  return (
+    <div>
+      <div>State: {state}</div>
+    </div>
+  );
+}
+```

package/zh/apis/app/runtime/model/connect.mdx

@@ -0,0 +1,143 @@
+---
+sidebar_position: 5
+title: connect
+---
+# connect
+
+import ReduckTip from "@site-docs/components/reduck-tip"
+
+<ReduckTip />
+
+:::tip 提示
+Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [**connect**](https://github.com/modern-js-dev/reduck/blob/main/packages/react/src/connect.ts)。
+
+:::
+
+`connect` 功能上同 `useModel` 一致，是对应的 HOC 风格的 API。建议优先使用 Hook 风格的 `useModel`。
+
+## 类型
+
+```ts
+type SelectStateToProps = (
+  ...modelStates: State[],
+  ownProps?: any,
+) => PlainObject;
+type SelectActionsToProps = (
+  ...modelActions: Actions[],
+  ownProps?: any,
+) => PlainObject;
+
+function connect(models: Model, options?: ConnectOptions);
+function connect(
+  models: [...Model[], SelectStateToProps?, SelectActionsToProps?],
+  options?: ConnectOptions,
+);
+```
+
+## 参数
+
+- `models`：传入的 1 个或多个 Model，当 `models` 为数组类型参数时，最后两项元素可以是用于筛选 State 的函数（ `SelectStateToProps` 类型）和用于筛选 Actions 的函数（ `SelectActionsToProps` 类型）。
+  - `SelectStateToProps`： `modelStates` 是传入的 Model 对象的 State 组成的数组，`ownProps` 是当前组件接收外部传递的 `props`，`SelectStateToProps` 返回的数据会传递到组件的 `props` 上。当 `models` 中没有传入 `SelectStateToProps` 参数时，所有 Model 的 State 进行合并后传递到组件的 `props` 上。
+  - `SelectActionsToProps`： `modelActions` 是传入的 Model 对象的 Actions 组成的数组，`ownProps` 是当前组件接收外部传递的 `props`，`SelectActionsToProps` 返回的数据也会传递到组件的 `props` 上。当 `models` 中没有传入 `SelectActionsToProps` 参数时，所有 Model 的 Actions 进行合并后传递到组件的 `props` 上。
+
+- `options`：可选参数，用于辅助配置。目前支持设置 `forwardRef`，用于控制是否转发组件的 `ref`，默认值为 `false`，表示不转发 `ref`。设置为 `{forwardRef: true}`，表示转发 `ref`。
+
+## 返回值
+
+返回一个高阶组件：接收一个传入的组件，返回一个在 `props` 上注入了额外 State 和 Actions 的组件。
+
+## 示例
+
+### 简单用法
+
+```ts
+const modelA = model('modelA').define({
+  state: {
+    a: 1,
+  },
+  actions: {
+    incA(state) {
+      return {
+        ...state,
+        a: state.a + 1,
+      };
+    },
+  },
+});
+
+const modelB = model('modelB').define({
+  state: {
+    b: 10,
+  },
+  actions: {
+    incB(state) {
+      return {
+        ...state,
+        b: state.b + 1,
+      };
+    },
+  },
+});
+
+function Test(props) {
+  props.incA(); // 调用 modelA 的 action
+  props.incB(); // 调用 modelB 的 action
+
+  props.a; // 获取 modelA 的 state: a
+  props.b; // 获取 modelB 的 state: b
+}
+
+export default connect([modelA, modelB])(Test);
+```
+
+### 筛选 State 和 Actions
+
+```ts
+function Test(props) {
+  props.incAll();
+  props.c;
+}
+
+const stateSelector = (stateA, stateB) => ({
+  ...stateA,
+  ...stateB,
+  c: stateA.a + stateA.b,
+});
+const actionsSelector = (actionsA, actionsB) => ({
+  ...actionsA,
+  ...actionsB,
+  incAll: () => {
+    actionsA.incA();
+    actionsB.incB();
+  },
+});
+
+export default connect([modelA, modelB, stateSelector, actionsSelector])(Test);
+```
+
+### 转发组件的 ref
+
+```ts
+import { useRef, forwardRef } from 'react';
+
+function Test(props, ref) {
+  const { a, b } = props;
+
+  return (
+    <div ref={ref}>
+      <span>{a}</span>
+      <span>{b}</span>
+    </div>
+  );
+}
+
+const TestWrapper = connect([modelA, modelB], { forwardRef: true })(
+  forwardRef(Test),
+);
+
+function App() {
+  const testRef = useRef();
+
+  return <TestWrapper ref={testRef} />;
+}
+```

package/zh/apis/app/runtime/model/create-app.mdx

@@ -0,0 +1,75 @@
+---
+sidebar_position: 11
+title: createApp
+---
+# createApp
+
+import ReduckTip from "@site-docs/components/reduck-tip"
+
+<ReduckTip />
+
+Reduck 内部默认会使用 `createApp` 创建一个全局应用，如果整个应用只需要共享一个 Store，那么是不需要使用 `createApp` 的。只有当需要在应用局部创建共享 Store 时，才需要使用 `createApp`。
+
+:::caution 注意
+注意 `@modern-js/runtime/model` 中导出的 `createApp` 用于管理状态，而 `@modern-js/runtime` 导出的 `createApp` 用于管理整个应用的运行时环境，两者功能不同。
+
+:::
+
+## 函数签名
+
+```ts
+interface AppConfig extends StoreConfig {
+  devTools?: boolean | DevToolsOptions;
+  autoActions?: boolean;
+}
+
+function createApp(config: AppConfig): object;
+```
+
+### 参数
+
+- config：`Record<string, any>`
+  - StoreConfig：同 [`createStore`](./create-store.md) 的参数。
+  - devTools：默认值为 true。是否开启 Redux DevTools，当为对象类型时，支持配置 Redux DevTools 的 [Options](https://github.com/reduxjs/redux-devtools/blob/main/extension/docs/API/Arguments.md)。
+  - autoActions：默认值为 true。是否[自动生成 Actions](./auto-actions.md)。
+
+### 返回值
+
+Reduck App，有以下属性组成：
+
+- Provider：为应用局部的组件树注入共享 Store 的组件。用法同 [`Provider`](./Provider.md)。
+- useModel：获取应用局部 Store 挂载的 Model 对象。用法同 [`useModel`](./use-model.md)。
+- useStaticModel：获取应用局部 Store 挂载的 Model 对象。用法同 [`useStaticModel`](./use-static-model.md)。
+- useLocalModel：获取应用局部 Store 挂载的 Model 对象。用法同 [`useLocalModel`](./use-local-model.md)。
+- useStore：获取应用局部使用的 Store 对象。用法同 [`useStore`](./use-store.md)。
+
+## 示例
+
+通过 `createApp` 可以创建局部状态，将不同 Reduck 应用间的状态隔离。
+
+```tsx
+const { Provider: LocalFooProvider, useModel: useLocalFooModel } = createApp();
+const { Provider: LocalBarProvider, useModel: useLocalBarModel } = createApp();
+
+function Foo() {
+  const [fooState] = useLocalFooModel(fooModel);
+  const [barState] = useLocalBarModel(fooModel);
+
+  return (
+    <div>
+      <div>Foo: {fooState}</div>
+      <div>Bar: {barState}</div>
+    </div>
+  );
+}
+
+function Container() {
+  return (
+    <LocalFooProvider>
+      <LocalBarProvider>
+        <Foo />
+      </LocalBarProvider>
+    </LocalFooProvider>
+  );
+}
+```

package/zh/apis/app/runtime/model/create-store.mdx

@@ -0,0 +1,61 @@
+---
+sidebar_position: 10
+title: createStore
+---
+# createStore
+
+import ReduckTip from "@site-docs/components/reduck-tip"
+
+<ReduckTip />
+
+`createStore` 用于创建一个 Store 对象。Reduck 的 Store 基于 Redux 的 [Store](https://redux.js.org/api/store) 实现，用于存储应用的状态，同时提供一组用于管理状态和 Model 的方法。
+
+一般情况下，不需要使用这个 API，只有需要完全掌控 Store 的创建时，才会使用这个 API。例如，自定义一个 Store，传入 [`Provider`](./Provider.md) 组件使用。
+
+## 函数签名
+
+```ts
+interface StoreConfig {
+  initialState?: Record<string, any>;
+  middlewares?: Middleware[];
+  models?: Model[];
+  plugins?: Plugin[];
+  enhancers?: StoreEnhancer[];
+}
+
+interface ReduckStore extends ReduxStore {
+  use: typeof useModel;
+  unmount: (model: Model) => void;
+}
+
+function createStore(config: StoreConfig): ReduckStore;
+```
+
+### 参数
+
+- config?：store 配置选项
+  - initialState?: 设置全局 Store 的初始状态。
+  - models?: 设置提前（Store 创建后）挂载到 Store 的 Model。（正常使用无需提前挂载）
+  - middlewares?: 设置 Redux [中间件](https://redux.js.org/understanding/thinking-in-redux/glossary#middleware)。
+  - enhancers?: 设置 Redux 的 [Store enhancer](https://redux.js.org/understanding/thinking-in-redux/glossary#store-enhancer) 。
+  - plugins?: 设置 Reduck 插件。**_试验性配置，不推荐使用_**。
+
+### 返回值
+
+Reduck Store 对象：
+
+- use：动态挂载和获取 Model 对象。用法与 [`useModel`](./use-model.md) 相同，但可以在 React 组件外使用。
+- unmount：卸载 Model 对象，Model 的 State 会从 Store 中清除。
+- ReduxStore：Redux Store 对象具有的方法，[详见](https://redux.js.org/tutorials/fundamentals/part-4-store#redux-store)。
+
+## 示例
+
+```tsx
+const store = createStore();
+
+function load() {
+  const [, actions] = store.use(fooModel);
+
+  actions.load();
+}
+```

package/zh/apis/app/runtime/model/handle-effect.mdx

@@ -0,0 +1,107 @@
+---
+sidebar_position: 7
+title: handleEffect
+---
+# handleEffect
+
+import ReduckTip from "@site-docs/components/reduck-tip"
+
+<ReduckTip />
+
+一个异步函数类型的 Effect，通常有三种需要处理的状态: 请求中、请求成功、请求处理失败。这些状态处理的方式，就是编写对应的 Action 函数(pending、fulfilled、rejected)。
+
+借助 `handleEffect` API，我们可以生成默认的 Action 函数来处理异步请求各个阶段的不同结果。`handleEffect` 生成的 Action 返回的 State 的结构如下：
+
+```ts
+interface State {
+  result: any; // 存储 fulfilled 状态的返回结果
+  pending: boolean; // 请求是否结束
+  error: string; // 请求失败的结果
+}
+```
+
+## 函数签名
+
+```ts
+interface EffectActions {
+  pending: Action;
+  fulfilled: Action;
+  rejected: Action;
+}
+
+interface Config {
+  ns?: string;
+  result?: string | false;
+  error?: string | false;
+  pending?: string | false;
+  combineMode?: 'merge' | 'replace';
+  omitResultNamespace?: boolean;
+}
+
+function handleEffect(config: Config): EffectActions;
+```
+
+### 参数
+
+- ns：默认返回的 State 结构扁平地挂载到 Model 的 State 上，通过设置该参数可以将返回的 State 挂载到 `ns` 值命名的字段下。例如，`ns` 设置为 `data`，返回的 State 结构为：
+
+```ts
+interface State {
+  data: {
+    pending: boolean;
+    result: any;
+    error: string;
+  };
+}
+```
+
+- result：默认值为 `"result"`。该参数对应存储异步请求 fulfilled 状态结果的字段名称。例如，设置 `result` 为 `"items"`，返回的 State 结构为：
+
+```ts
+interface State {
+  items: any; // 默认的 result -> items
+  pending: boolean;
+  error: string;
+}
+```
+
+`result` 为 `false`，返回的 State 结构中不存在 `result`：
+
+```ts
+interface State {
+  pending: boolean;
+  error: string;
+}
+```
+
+- pending：默认值为 `"pending"`。改变返回 State 中的 `pending` 字段名。用法同上。
+
+- error： 默认值为 `"error"`。改变返回 State 中的 `error` 字段名。用法同上。
+
+- combineMode：默认值为 `"merge"`。获取 fulfilled 状态的返回数据后，对 `result` 的处理方式：merge（合并）和 replace（替换）。这里能自动处理的数据类型也仅限为简单的对象或者数组类型。
+
+  - merge：前一次的数据与当前的数据合并。数据为数组类型，内部操作类似于 `[].concat(lastData, currentData)`；数据为对象类型，内部操作类似于 `{...lastData, ...curData}`。
+  - replace：当前的数据直接替换之前的数据。
+
+- omitResultNamespace：默认值为 `"false"`。当异步请求的结果为对象类型，希望把该结果直接挂载到 Model 的 State 上，而不是挂载到 `"result"` 上，可以设置为 true。例如：
+
+```ts
+// 一个异步请求得到的数据为一个对象：{user: 'xx', email: 'xx'}，
+// 配置 handleEffect({ omitResultNamespace: true })
+// 则得到的 State 结构如下：
+{
+  user: 'xx',
+  email: 'xx',
+  pending: false,
+  error: null,
+}
+```
+
+### 返回值
+
+分别处理 pending、fulfilled、rejected 三种状态的 Action 组成的对象。
+
+:::info 更多参考
+[副作用管理](/guides/topic-detail/model/manage-effects)
+
+:::

package/zh/apis/app/runtime/model/model_.mdx

@@ -0,0 +1,199 @@
+---
+sidebar_position: 1
+title: model
+---
+# model
+
+import ReduckTip from "@site-docs/components/reduck-tip"
+
+<ReduckTip />
+
+:::tip 提示
+Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [**model**](https://github.com/modern-js-dev/reduck/blob/main/packages/store/src/model/model.ts)。
+
+:::
+
+## model
+
+用于创建管理应用状态的 Model。
+
+`function model(name: string): { define: function }`
+
+- name：`string`，创建的 Model 的唯一标识。
+
+```ts title="示例"
+model('foo');
+```
+
+## define
+
+用于定义 Model 的详细结构，支持传入一个对象类型或函数类型的参数。
+
+### 对象类型
+
+`function define(modelDesc: ModelDesc): Model;`
+
+- modelDesc: `ModelDesc`，对 Model 结构的定义，包含 `state`、`computed`、`actions`、`effects` 等属性。
+
+```tsx title="示例"
+const fooModel = model('foo').define({
+  state: 'foo',
+  computed: {
+    cFoo: state => `c${state}`,
+  },
+  actions: {
+    setState: (state, value) => {
+      return value;
+    },
+  },
+  effects: {
+    loadState: async () => {
+      // 从服务端获取 state
+    },
+  },
+});
+```
+
+### 函数类型
+
+`function define((context: Context, utils: Utils) => ModelDesc): Model;`
+
+- context: Context，Reduck 上下文对象，可以获取底层的 `store` 对象。`store` 除支持 Redux Store 的所有 [API](https://redux.js.org/api/store) 以外，还挂载了用于消费 Model 的 `use` 的方法，和用于卸载 Model 的 `unmount` 方法。
+- utils: Utils，定义 Model 时，常用的工具函数：`use`、`onMount`。`use` 作用同 `store` 对象上的 `use`，`onMount` 是 Model 挂载后的钩子函数。
+
+{/* TODO: @anchao 调整类型  */}
+```ts
+interface Utils {
+  use: UseModel;
+  onMount: OnMountHook;
+}
+
+interface Context {
+  store: ReduxStore & {
+    use: UseModel;
+    unmount: (model: Model) => void;
+  };
+}
+```
+
+如通过 `use`，可以获取 Model 自身及其它 Model 的 `state`，`actions`。
+
+```tsx title="示例"
+const fooModel = model('foo').define(() => {
+  return {
+    state: 'foo',
+    actions: {
+      setState: (state, value) => {
+        return value;
+      },
+    },
+  };
+});
+
+const barModel = model('bar').define((_, { use }) => {
+  return {
+    state: 'bar',
+    effects: {
+      syncFoo() {
+        const [state, actions] = use(fooModel);
+        actions.setState(state);
+      },
+    },
+  };
+});
+```
+
+### 参数
+
+#### ModelDesc.state
+
+定义 Model 的状态。技术上，支持任意类型的 **State**，但是实践中建议使用可进行 JSON 序列化的类型。
+
+```ts
+interface ModelDesc {
+  state: any;
+}
+```
+
+#### ModelDesc.actions
+
+定义 Model 的 Actions。Actions 的函数类型为：
+
+```ts
+interface ModelDesc {
+  actions: {
+    [actionKey: string]: (state: State, payload: any) => State | void;
+  };
+}
+```
+
+Reduck 内部集成了 [immer](https://github.com/immerjs/immer)，可以直接原始的 `state`，当 Action 没有显式返回值时，Reduck 内部会返回修改过的新的 State 对象。
+
+#### ModelDesc.computed
+
+定义 Model 的衍生状态。衍生状态的定义支持两种类型：
+
+1. 只依赖 Model 自身的状态
+
+```ts
+interface ModelDesc {
+  computed: {
+    [computedKey: string]: (state: State) => any;
+  };
+}
+```
+
+2. 依赖其他 Model 的状态
+
+```ts
+interface ModelDesc {
+  computed: {
+    [computedKey: string]: [
+      ...models: Model[],
+      (state: State, ...args: ModelState[]) => any,
+    ];
+  };
+}
+```
+
+```ts title="示例"
+const fooModel = model('foo').define({
+  state: 'foo',
+});
+
+const barModel = model('bar').define({
+  state: 'bar',
+  computed: {
+    combineFoo: [fooModel, (state, fooState) => state + fooState],
+  },
+});
+```
+
+#### ModelDesc.effects
+
+定义 Model 的 Effects。Effects 中定义的函数类型为：
+
+```ts
+interface ModelDesc {
+  effects: {
+    [effectKey: string]: (...args: any[]) => any;
+  };
+}
+```
+
+```ts title="示例"
+const fooModel = model('foo').define((context, { use }) => ({
+  state: 'foo',
+  effects: {
+    persist() {
+      const [state] = use(fooModel);
+      localStorage.setItem('state', state);
+    },
+  },
+}));
+```
+
+:::info 更多参考
+[创建 Model](/guides/topic-detail/model/define-model)
+
+:::