@modern-js/main-doc 0.0.0-next-20221116121040

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

@@ -0,0 +1,28 @@
+---
+sidebar_position: 4
+title: useLocalModel
+---
+
+import ReduckTip from '@site/docs/components/reduck-tip.md'
+
+<ReduckTip />
+
+用于把 Model 中的 State 作为局部状态使用，效果类似 React 的 `useState`。`useStaticModel` 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

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

package/zh/apis/app/runtime/model/use-static-model.md

@@ -0,0 +1,47 @@
+---
+sidebar_position: 3
+title: useStaticModel
+---
+
+import ReduckTip from '@site/docs/components/reduck-tip.md'
+
+<ReduckTip />
+
+如果想在组件里以 React Hook 的形式消费某个 Model，并能随时获取到当前最新的状态，但又不希望 Model 状态更新的时候，引起组件的重新渲染，可以使用 `useStaticModel`。`useStaticModel` API 形式上与 `useModel` 完全一致。具体使用请参考 [`useModel`](./use-model.md)。
+
+为了保证总是能获取到最新状态，注意不要对返回的 `state` 解构。
+
+```tsx
+function App() {
+  // ❌ 不能解构 state，但可以解构 actions。
+  const [{ username }, { logout }] = useStaticModel(userModel);
+
+  // ✅ 这才是正确使用姿势。
+  const [state, { logout }] = useStaticModel(userModel);
+
+  useEffect(() => {
+    state.username;
+  }, []);
+}
+```
+
+#### 示例
+
+如下 `App` 组件消费了 `userModel` 的状态，但没有直接在 JSX 里使用。如果 `userModel` 状态的改变会引起组件重新渲染，这是没有必要的，这种情况可以使用 `useStaticModel` 进行优化。
+
+```tsx
+function App() {
+  const [state] = useStaticModel(userModel);
+
+  useEffect(() => {
+    // 统计 UV 数据
+    send('pageview', { user: state.user });
+  }, [state]);
+
+  return <div>Hello</div>;
+}
+```
+
+:::info 更多参考
+[使用 Model](/docs/guides/topic-detail/model/use-model)
+:::

package/zh/apis/app/runtime/model/use-store.md

@@ -0,0 +1,48 @@
+---
+sidebar_position: 9
+title: useStore
+---
+
+import ReduckTip from '@site/docs/components/reduck-tip.md'
+
+<ReduckTip />
+
+`useStore` 用于获取当前组件树共享的 Store。常用于在组件外访问 Model 的场景。注意，`useStore` 是一个 React Hook，只能在组件内使用。
+
+
+## 类型
+
+```ts
+function useStore(): ReduckStore;
+```
+
+## 返回值
+
+- ReduckStore：Reduck Store，类型参考 [createStore](./create-store.md) 返回值。
+
+## 示例
+
+```ts
+// 保证 getStore 在组件树挂载完成后执行
+setTimeout(() => {
+  const store = getStore();
+  const [, actions] = store.use(countModel);
+  setInterval(() => {
+    actions.add();
+  }, 1000);
+}, 1000);
+
+function Counter() {
+  const [state] = useModel(countModel);
+
+  return (
+    <div>
+      <div>counter: {state.value}</div>
+    </div>
+  );
+}
+```
+
+:::info 更多参考
+[使用 Model](/docs/guides/topic-detail/model/use-model)
+:::

package/zh/apis/app/runtime/plugin/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "插件 API",
+  "position": 12
+}

package/zh/apis/app/runtime/plugin/abstract.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 1
+---
+
+# 概览
+
+Modern.js 的基础的插件系统中主要分为三个部分：Hook 模型（Pipeline、Workflow、Waterfall）、 Hook 模型的管理器（Manager），上下文共享机制。
+
+其中的 Hook 模型是用于管理运行一系列相同模型（形状）函数的管理工具，目前提供了三个大类，7个小类：
+
+- Pipeline
+  - Sync
+  - Async
+- Waterfall
+  - Sync
+  - Async
+- Workflow
+  - Sync
+  - Async
+  - Parallel(Async)
+
+它们之间的区别是他们所管理的函数的运行模式的不同。不同的地方会在下面具体分析介绍。
+
+Hook 模型的管理器（Manager），顾名思义就是用来管理上面提到的那些 Hook 模型，添加至同一个 Manager 可以使用同一个 Runner 对象（包含所有 Hook 的执行函数）来运行，也共享同一个上下文环境。而 Modern.js 的基础插件系统中的插件就是针对 Manager 来说的，是一个拥有属性、插件 Hook 函数的对象。
+
+基于上面的工具（Hook 模型 + Manager），在 Modern.js 中主要构建了三套插件模型：CLI、Runtime、Server。其中 CLI 是 Modern.js 中主要的运行流程控制模型，Modern.js 中的各种工程方案（应用工程方案、模块工程方案、Monorepo 工程方案）都是主要通过这一套模型运行的。而 Runtime 则主要负责的是 React 路由组件和元素的处理（Component 和 Element）和渲染（包括服务器端渲染和客户端渲染）。而 Server 则是针对 Server 运行时的这个阶段的生命周期运行和特殊信息收集。其中 Runtime 和 Server 的运行都是在 CLI 中触发的。