npm - @modern-js/main-doc - Versions diffs - 2.1.0 → 2.3.0 - Mend

@modern-js/main-doc 2.1.0 → 2.3.0

Files changed (1299) hide show

package/zh/apis/app/runtime/model/connect.md DELETED Viewed

@@ -1,141 +0,0 @@
----
-sidebar_position: 5
-title: connect
----
-import ReduckTip from '@site-docs/components/reduck-tip.md'
-<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.md DELETED Viewed

@@ -1,73 +0,0 @@
----
-sidebar_position: 11
-title: createApp
----
-import ReduckTip from '@site-docs/components/reduck-tip.md'
-<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.md DELETED Viewed

@@ -1,60 +0,0 @@
----
-sidebar_position: 10
-title: createStore
----
-import ReduckTip from '@site-docs/components/reduck-tip.md'
-<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.md DELETED Viewed

@@ -1,105 +0,0 @@
----
-sidebar_position: 7
-title: handleEffect
----
-import ReduckTip from '@site-docs/components/reduck-tip.md'
-<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 更多参考
-[副作用管理](/docs/guides/topic-detail/model/manage-effects)
-:::

package/zh/apis/app/runtime/model/model_.md DELETED Viewed

@@ -1,196 +0,0 @@
----
-sidebar_position: 1
-title: model
----
-import ReduckTip from '@site-docs/components/reduck-tip.md'
-<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](/docs/guides/topic-detail/model/define-model)
-:::

package/zh/apis/app/runtime/model/use-local-model.md DELETED Viewed

@@ -1,27 +0,0 @@
----
-sidebar_position: 4
-title: useLocalModel
----
-import ReduckTip from '@site-docs/components/reduck-tip.md'
-<ReduckTip />
-用于把 Model 中的 State 作为局部状态使用，效果类似 React 的 `useState`。`useLocalModel` API 形式上与 `useModel` 完全一致。具体使用请参考 [`useModel`](./use-model.md)。
-#### 示例
-```tsx
-function Container() {
-  const [state, actions] = useLocalModel(modelA);
-  const [state1, actions1] = useLocalModel(modelA);
-  // ...
-}
-```
-上面通过 `useLocalModel` 加载了两次 `modelA`，因为 `useLocalModel` 消费的是局部状态，所以 `state` 和 `state1` 也是完全隔离的。
-:::info 更多参考
-[使用 Model](/docs/guides/topic-detail/model/use-model)
-:::

package/zh/apis/app/runtime/model/use-model.md DELETED Viewed

@@ -1,86 +0,0 @@
----
-sidebar_position: 2
-title: useModel
----
-import ReduckTip from '@site-docs/components/reduck-tip.md'
-<ReduckTip />
-:::tip 提示
-Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [model](https://github.com/modern-js-dev/reduck/blob/main/packages/store/src/model/useModel.ts)。
-:::
-## 函数签名
-```ts
-function useModel(
-  models: Models[],
-  stateSelector?: StateSelector,
-  actionSelector?: ActionSelector,
-): [state, actions, subscribe];
-function useModel(
-  ...models: Models[],
-  stateSelector?: (...args: State[]) => any,
-  actionSelector?: (...args: Actions[]) => any,
-): [state, actions, subscribe];
-```
-### 参数
-- models：Model 对象数组，可以作为一个数组类型的参数传入，也可以所有 Model 逐个作为参数传入。
-- stateSelector：可选参数，用于筛选 State 计算。前 n 个参数为 n 个 Model 对应的 State，返回的数据作为 `useModel` 返回值数组的第一个元素。
-- actionSelector：可选参数，用于筛选 Actions 计算。前 n 个参数为 n 个 Model 对应的 Actions，返回的数据作为 `useModel` 返回值数组的第二个元素。
-### 返回值
-返回一个数组，每一项元素分别为：
-- state：`stateSelector` 的返回值。如果未传 `stateSelector`，会把传入的所有 Model 的 State (包含衍生状态)合并后返回。如果不同 Model 的 State 中存在同名属性，后面的 State 会覆盖前面的 State。当 `state` 发生变化时，调用 `useModel` 的组件会重新渲染。
-- actions：第二个元素为 `actionSelector` 的返回值。如果未传 `actionSelector`，会把传入的所有 Model 的 Actions (包含 Effects) 合并后返回。如果不同 Model 的 Actions 中存在同名属性，后面的 Actions 会覆盖前面的 Actions。
-- subscribe：订阅 State 变化的函数。当传入的任意 Model 的 State 发生改变时，该函数会被调用。
-## 示例
-### 基本用法
-```tsx
-import todoModel from 'models/todo';
-import filterModel from 'models/filter';
-function Test(props) {
-  const [state, actions] = useModel([todoModel, filterModel]);
-  actions.add(); // 调用 todoModel add action
-  actions.setVisibleStatus(); // 调用 filterModel filterModel action
-  state.items; // 获取 todoModel state items
-  state.visibleStatus; // 获取 filterModel state visibleStatus
-}
-```
-### selector 用法
-```js
-function Test(props) {
-  const [state, actions] = useModel(
-    [todoModel, filterModel],
-    (todoState, filterState) => ({
-      items: todoState.items,
-      visibleStatus: `${props.prefix}-${filterState.visibleStatus}`,
-    }),
-    (todoActions, filterActions) => ({
-      ...todoActions,
-      ...filterActions,
-    }),
-  );
-  actions.add(); // 调用 todoModel add action
-  actions.setVisibleStatus(); // 调用 filterModel filterModel action
-  state.items; // 获取 todoModel state items
-  state.visibleStatus; // 获取 filterModel state visibleStatus
-}
-```
-:::info 更多参考
-[使用 Model](/docs/guides/topic-detail/model/use-model)
-:::