@modern-js/main-doc 2.1.0 → 2.2.0

package/zh/guides/topic-detail/model/use-model.mdx

@@ -0,0 +1,252 @@
+---
+sidebar_position: 3
+title: 使用 Model
+---
+# 使用 Model
+
+## 在组件内使用
+
+### 作为全局状态使用
+
+通过 `useModel` 可以获取 Model 的 State、Actions 等。当 Model 的 State 通过 Actions 进行修改后，任何其他使用了该 Model 的组件，都会自动重新渲染。
+
+在 [快速上手](/guides/topic-detail/model/quick-start) 的计数器案例中，我们已经演示了 `useModel` 的使用，不再重复。
+
+`useModel` 支持传入多个 Model，多个 Model 的 State 和 Actions 会进行合并后作为返回结果。例如：
+
+```ts
+const fooModel = model('foo').define({
+  state: {
+    value: 1,
+  },
+  actions: {
+    add(state) {
+      state += 1;
+    },
+  },
+});
+
+const barModel = model('bar').define({
+  state: {
+    title: 'bar',
+  },
+  actions: {
+    set(state, payload) {
+      state.title = payload;
+    },
+  },
+});
+
+const [state, actions] = useModel([fooModel, barModel]);
+// 或
+const [state, actions] = useModel(fooModel, barModel);
+```
+
+`state` 和 `actions` 的值分别为：
+
+```ts
+state = {
+  value: 1,
+  title: 'bar',
+};
+
+actions = {
+  add(state) {
+    state += 1;
+  },
+  set(state, payload) {
+    state.title = payload;
+  },
+};
+```
+
+`useModel` 还支持对 State 和 Actions 做 selector 操作，实现对 State 和 Actions 的筛选或重命名，例如：
+
+```ts
+const fooModel = model('foo').define({
+  state: {
+    value: 1,
+  },
+  actions: {
+    add(state) {
+      state += 1;
+    },
+  },
+});
+
+const barModel = model('bar').define({
+  state: {
+    value: 'bar',
+  },
+  actions: {
+    set(state, payload) {
+      state.value = payload;
+    },
+  },
+});
+
+const [state, actions] = useModel(
+  [fooModel, barModel],
+  (fooState, barState) => ({
+    fooValue: fooState.value,
+    barValue: barState.value,
+  }), // stateSelector
+  (fooActions, barActions) => ({ add: fooActions.add }), // actionsSelector
+);
+```
+
+我们通过 `stateSelector` ，把 `fooModel` 和 `barModel` 中重名的状态做了命名修改，通过 `actionsSelector` ，过滤掉了 `barModel` 的 Actions。
+
+如果只需要设置 `actionsSelector`，可以把 `stateSelector` 设置为 `undefined`，作为参数占位。例如：
+
+```ts
+const [state, actions] = useModel(
+  [fooModel, barModel],
+  undefined,
+  (fooActions, barActions) => ({ add: fooActions.add }), // actionsSelector
+);
+```
+
+### 作为静态状态使用
+
+通过 `useStaticModel` 获取 Model ，将 Model 中的状态作为静态状态使用。可以保证组件每次访问到的 Model 的 State 都是最新值，但是 Model 的 State 的变化，并不会引起当前组件的重新渲染。
+
+:::info 注
+`useStaticModel` 的使用方式和 `useModel` 完全一致。
+
+:::
+
+考虑下面一种场景，有一个组件 Input 负责用户输入，另外一个组件 Search 负责根据用户的输入信息，在点击查询按钮后执行查询操作，我们不希望用户输入过程中的状态变化引起 Search 重新渲染，这时候就可以使用 `useStaticModel`：
+
+```ts
+import { useStaticModel } from '@modern-js/runtime/model';
+
+function Search() {
+  // 这里注意不要解构 state
+  const [state] = useStaticModel(searchModel);
+
+  return (
+    <div>
+      <button
+        onClick={async () => {
+          const result = await mockSearch(state.input);
+          console.log(result);
+        }}
+      >
+        Search
+      </button>
+    </div>
+  );
+}
+```
+
+:::warning 注意
+不要解构 `useStaticModel` 返回的 `state`，例如改成如下写法：
+`const [{input}] = useStaticModel(searchModel);`
+将始终获取到 Input 的初始值。
+
+:::
+
+`useStaticModel` 还适合和 [react-three-fiber](https://github.com/pmndrs/react-three-fiber) 等动画库一起使用，因为在动画组件 UI 里绑定会快速变化的状态，容易引起[性能问题](https:/docs.pmnd.rs/react-three-fiber/advanced/pitfalls#never-bind-fast-state-reactive)。这种情况就可以选择使用 `useStaticModel`，它只会订阅状态，但不会引起视图组件的重新渲染。下面是一个简化示例：
+
+```ts
+function ThreeComponent() {
+  const [state, actions] = useStaticModel(modelA);
+
+  useFrame(() => {
+    state.value; // 假设初始化为 0
+    actions.setValue(1);
+    state.value; // 这里会得到1
+  });
+}
+```
+
+使用 React 的 refs 也可以实现类似效果，其实 `useStaticModel` 内部也使用到了 refs。不过直接 `useStaticModel` 有助于将状态的管理逻辑从组件中解耦，统一收敛到 Model 层。
+
+完整的示例代码可以在[这里](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/static-model)查看。
+
+### 作为局部状态使用
+
+通过 `useLocalModel` 获取 Model ，将 Model 中的状态作为局部状态使用。此时 Model State 的变化，只会引起当前组件的重新渲染，但是不会引起其他使用了该 Model 的组件重新渲染。效果和通过 React 的 `useState` 管理状态类似，但是可以将状态的管理逻辑从组件中解耦，统一收敛到 Model 层。
+
+:::info 注
+`useLocalModel` 的使用方式和 `useModel` 完全一致。
+
+:::
+
+例如，我们修改计数器应用的代码，添加一个有局部状态的计数器组件 `LocalCounter`：
+
+```ts
+import { useLocalModel } from '@modern-js/runtime/model';
+
+function LocalCounter() {
+  const [state, actions] = useLocalModel(countModel);
+
+  return (
+    <div>
+      <div>local counter: {state.value}</div>
+      <button onClick={() => actions.add()}>add</button>
+    </div>
+  );
+}
+```
+
+分别点击 `Counter` 和 `LocalCounter` 的 `add` 按钮，两者的状态互不影响：
+
+![local-model](https://lf3-static.bytednsdoc.com/obj/eden-cn/eueh7vhojuh/modern/local-model.gif)
+
+完整的示例代码可以在[这里](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/local-model)查看。
+
+## 在组件外使用
+
+在实际业务场景中，有时候我们需要在 React 组件外使用 Model，例如在工具函数中访问 State、执行 Actions 等。这个时候，我们就需要使用 Store。 Store 是一个底层概念，一般情况下用户接触不到，它负责存储和管理整个应用的状态。Reduck 的 Store 基于 [Redux 的 Store](https://redux.js.org/api/store) 实现，增加了 Reduck 特有的 API，如 `use` 。
+
+首先，在组件内调用 `useStore` 获取当前应用使用的 `store` 对象，并挂载到组件外的变量上：
+
+```ts
+let store; // 组件外部 `store` 对象的引用
+function setStore(s) {
+  store = s;
+}
+function getStore() {
+  return store;
+}
+
+function Counter() {
+  const [state] = useModel(countModel);
+  const store = useStore();
+  // 通过 useMemo 避免不必要的重复设置
+  useMemo(() => {
+    setStore(store);
+  }, [store]);
+
+  return (
+    <div>
+      <div>counter: {state.value}</div>
+    </div>
+  );
+}
+```
+
+通过 `store.use` 可以获取 Model 对象，`store.use` 的用法同 `useModel` 相同。以计数器应用为例，我们在组件树外，每 1s 对计数器值
+执行自增操作：
+
+```ts
+setInterval(() => {
+  const store = getStore();
+  const [, actions] = store.use(countModel);
+  actions.add();
+}, 1000);
+```
+
+完整的示例代码可以在[这里](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/counter-model-outof-react)查看。
+
+:::info 注
+如果是通过 [`createStore`](/apis/app/runtime/model/create-store) 手动创建的 Store 对象，无需通过 `useStore` 在组件内获取，即可直接使用。
+
+:::
+
+:::info 补充信息
+本节涉及的 API 的详细定义，请参考[这里](/apis/app/runtime/model/model_)。
+
+:::

package/zh/guides/topic-detail/model/use-out-of-modernjs.mdx

@@ -0,0 +1,50 @@
+---
+sidebar_position: 12
+title: 单独使用 Reduck
+---
+# 单独使用 Reduck
+
+在 Modern.js 以外，单独集成 Reduck 使用时，主要需要做以下修改：
+
+1. 安装 Reduck 相关包
+
+在项目中安装 Reduck 包：`@modern-js-reduck/react`。
+
+2. API 导入包名
+
+在 Modern.js 中使用时，Reduck 导出 API 的包名为：`@modern-js/runtime/model`。单独使用 Reduck 时，导出包名为：`@modern-js-reduck/react`。
+
+3. 包裹 `Provider` 组件
+
+Modern.js 自动在应用的入口组件上，包裹了用于注入 Reduck 全局 Store 的 [`Provider`](/apis/app/runtime/model/Provider) 组件。单独使用 Reduck 时，需要手动完成。
+
+示例：
+
+```tsx
+// 根组件
+const Root = () => {
+  return (
+    <Provider>
+      {/* 应用入口组件 */}
+      <App />
+    </Provider>
+  );
+};
+```
+
+4. 功能配置
+
+在 Modern.js 中使用时，可以通过 [`runtime.state`](/configure/app/runtime/state) 对 Reduck 功能进行配置。单独使用时，需要通过 [`Provider`](/apis/app/runtime/model/Provider) 的 `config` 或 `store` 参数配置。
+
+示例：
+
+```tsx
+const Root = () => {
+  return (
+    {/* 关闭 Redux DevTools */}
+    <Provider config={{ devTools: false }}>
+      <App />
+    </Provider>
+  )
+}
+```

package/zh/guides/topic-detail/monorepo/create-sub-project.mdx

@@ -0,0 +1,67 @@
+---
+sidebar_position: 2
+---
+
+# 创建子项目
+
+本章将要介绍如何在 Monorepo 工程下创建子项目。
+
+> Modern.js 支持使用 pnpm 和 Yarn 的 Monorepo，这里以使用 pnpm 为例。以下命令可以以同样方式使用 Yarn 来执行。
+
+Modern.js 针对 Monorepo 工程提供了生成器功能，它用于在 Monorepo 工程下创建不同类型的 Monorepo 子项目。在生成器中提供以下类型子项目的创建：
+
+- 「应用」类型
+- 「模块」类型
+
+要启动 Monorepo 的生成器功能，可以在 Monorepo 工程根目录下执行命令：
+
+```
+pnpm run new
+```
+
+:::info 补充信息
+使用 Yarn 的方式：`yarn new`
+
+:::
+
+执行成功后，可以看到如下内容：
+
+```
+? 请选择你想创建的工程类型 (Use arrow keys)
+❯ 应用
+  应用（测试）
+  模块
+  模块（内部）
+```
+
+:::info 注
+「应用」与「应用（测试）」都是「应用」类型的项目，区别是「应用」类型的子项目会创建在 `./apps` 目录下，而 「应用（测试）」类型的子项目会创建在 `./examples` 目录下。
+
+:::
+
+:::info 注
+「模块」与「模块（内部）」都是「模块」类型的项目，区别之一是「模块」类型的子项目会创建在 `./packages` 目录下，而「模块（内部）」类型的子项目会创建在 `./features` 目录下。
+
+对于「模块」类型的子项目允许被发布到外部（例如 npm)，而对于「模块（内部）」的子项目则可以在应用项目中直接使用其源码（该特性是「模块」项目不具备的，应用项目对于「模块（内部）」子项目做了特殊处理），因此这类子项目不需要发布到外部。
+
+:::
+
+然后根据不同的需求选择对应的类型项目选项，选择之后便开始出现对应子项目类型的问题和选项。例如选择「应用」后会出现：
+
+```
+? 请选择你想创建的工程类型 应用
+? 请填写子项目名称
+```
+
+当完成所有生成器问题之后，便开始进行项目的创建和项目依赖的下载。当创建成功之后，可以看到类似以下内容：
+
+```
+[INFO] 依赖自动安装成功
+[INFO] 创建成功！
+可在新项目的目录下运行以下命令：
+pnpm run dev          # 按开发环境的要求，运行和调试项目
+pnpm run build        # 按生产环境的要求，构建项目
+pnpm run serve        # 按生产环境的要求，运行项目
+pnpm run lint         # 检查和修复所有代码
+pnpm run new          # 继续创建更多项目要素，比如应用入口
+```

package/zh/guides/topic-detail/monorepo/publish.mdx

@@ -0,0 +1,69 @@
+---
+sidebar_position: 4
+---
+
+# 可复用模块的发布
+
+在 Monorepo 中有时会需要把多个模块项目发布到 [NPM](https://www.npmjs.com/) 上，本章将要介绍如果在 Monorepo 中对子项目进行版本更新以及发布。
+
+## 准备工作
+
+接着 [子项目联调](/guides/topic-detail/monorepo/sub-project-interface) 章节的例子，我们对 `components` 模块进行发布。
+
+## 生成变更记录
+
+在开发阶段，当某个模块的功能开完完成之后，一般需要提交代码（例如提交到 [GitHub](https://github.com/) 上）并需要记录本次修改的内容。在 Modern.js 的 Monorepo 工程中，我们可以在 monorepo 根目录执行命令：
+
+```
+pnpm run change
+```
+
+然后根据提示选择变更或者将要发布的包以及选择包升级的版本，并填写变更信息。变更信息的内容可以包含此次开发的功能、修复的问题等。
+
+那么对于上面的例子，我们选择变更的项目为 `components`，并填写此次变更的内容：
+
+```
+$ modern change
+🦋  Which packages would you like to include? · components
+🦋  Which packages should have a major bump? · No items were selected
+🦋  Which packages should have a minor bump? · components
+🦋  Please enter a summary for this change (this will be in the changelogs). Submit empty line to open external editor
+🦋  Summary · add features
+🦋  === Releasing the following packages ===
+🦋  [Minor]
+🦋    components
+🦋  ╔════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
+🦋  ║                                                      ========= NOTE ========                                                       ║
+🦋  ║All dependents of these packages that will be incompatible with the new version will be patch bumped when this changeset is applied.║
+🦋  ╚════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
+🦋  Is this your desired changeset? (Y/n) · true
+🦋  Changeset added! - you can now commit it
+🦋
+🦋  If you want to modify or expand on the changeset summary, you can find it here
+🦋  info /Users/demo/modern-js/official/monorepo-pnpm/.changeset/silent-tigers-run.md
+```
+
+该命令完成后，在 `.changeset` 中会有新的 `silent-tigers-run.md` 文件生成，其中包含了刚刚填写的信息，这些新生成的文件将用于后面发布流程中使用。**因此在提交代码的时候，需要将`.changeset` 目录下的文件一并提交**。
+
+## 版本更新
+
+在模块发布之前，还需要将模块的版本进行更新。。在 Modern.js 的 Monorepo 工程中，可以在 Monorepo 项目根目录下执行：
+
+```
+pnpm run bump
+```
+
+该命令会根据之前生成在 `.changeset` 目录下的文件自动更新对应模块的版本号和 CHANGELOG 信息，执行成功后会看到：
+
+```
+🦋  All files have been updated. Review them and commit at your leisure
+```
+
+## 发布
+
+最后执行 `pnpm run prepare --filter {./packages} && pnpm run release`，便可以发布对应的模块了。
+
+:::info 补充信息
+在上面的命令中 --filter \{./packages\} 用于筛选位于 `./packages` 目录下的子项目，可以通过 [PNPM Filtering](https://pnpm.io/filtering) 来了解更多它的使用。
+
+:::

package/zh/guides/topic-detail/monorepo/sub-project-interface.mdx

@@ -0,0 +1,179 @@
+---
+sidebar_position: 3
+---
+
+# 子项目联调
+
+本章将要介绍如何在 Monorepo 下进行子项目之间的联调使用。
+
+## 准备工作
+
+按照 [「创建子项目」](/guides/topic-detail/monorepo/create-sub-project) 章节的介绍（如果还没有看过，可以先了解一下），我们首先创建以下三个子项目：
+
+- 一个「应用」子项目
+- 一个「模块（内部）」子项目
+- 一个「模块」子项目
+
+执行 `pnpm run new`，并按照如下进行选择：
+
+**「应用」子项目：**
+
+```
+? 请选择你想创建的工程类型 应用
+? 请填写子项目名称 app
+? 请填写子项目目录名称 app
+? 请选择开发语言 TS
+```
+
+**「模块（内部）」子项目：**
+
+```
+? 请选择你想创建的工程类型 模块（内部）
+? 请填写子项目名称 internal-lib
+? 请填写子项目目录名称 internal-lib
+? 请选择开发语言 TS
+```
+
+**「模块」子项目：**
+
+```
+? 请选择你想创建的工程类型 模块
+? 请填写子项目名称 components
+? 请填写子项目目录名称 components
+? 请选择开发语言 TS
+```
+
+创建成功后，会得到以下项目：
+
+- `./apps/app`
+- `./packages/components`
+- `./features/internal-lib`
+
+然后修改一下默认的代码和新增文件：
+
+**重命名 `./pakcages/components/src/index.tsx`**
+
+```tsx
+import './index.css';
+
+export default function ({ text }: { text: string }) {
+  return (
+    <div>
+      This is UI Components Log: <p className="log">{text}</p>
+    </div>
+  );
+}
+```
+
+**新增 `./pakcages/components/src/index.css`**
+
+```css
+.log {
+  color: gray;
+}
+```
+
+**修改 `./features/internal-lib/src/index.ts`**
+
+```tsx
+export default function (text: string) {
+  return text.toUpperCase();
+}
+```
+
+**修改 `./apps/app/src/App.tsx`**
+
+```tsx
+import { Switch, Route } from '@modern-js/runtime/router';
+import formatString from 'internal-lib';
+import Comp from 'components';
+
+import './App.css';
+
+const App = () => (
+  <Switch>
+    <Route exact={true} path="/">
+      <div className="container-box">
+        <Comp text={formatString('hello world')} />
+        {/* 省略... */}
+      </div>
+    </Route>
+    <Route path="*">
+      <div>404</div>
+    </Route>
+  </Switch>
+);
+
+export default App;
+```
+
+到此为止我们创建了一个可以被发布到外部的组件项目、一个转换字符串的内部模块项目以及一个使用组件和内部模块的应用项目，如果直接运行应用项目还暂时无法正常使用。接下来将要介绍如何让它们能够互相联调使用，成功的使应用子项目 `apps/app` 正常运行。
+
+:::info 注
+启动 `apps/app` 项目之前需要先构建（`pnpm run build`） `packages/component`。
+
+:::
+
+由于 Modern.js 支持 pnpm 与 Yarn 的 Monorepo 工程，接下来会从这两个方面分别介绍。
+
+## 在使用 pnpm 的 Monorepo 中进行项目联调
+
+在 pnpm 的 Monorepo 项目中，我们通过在 `apps/app` 子项目下分别执行：
+
+```
+pnpm add components
+```
+
+以及
+
+```
+pnpm add internal-lib -D
+```
+
+:::info 注
+注意这里将 internal-lib 作为 `apps/app` 项目的开发依赖，因为在构建环境会被打包到构建产物中。
+
+:::
+
+将 `packages/components` 与 `features/internal-lib` 子项目加入到应用的依赖列表当中。
+
+执行成功后，在 `apps/app/package.json` 会发生如下变化：
+
+```json
+{
+  "dependencies": {
+++  "components": "workspace:^0.1.0"
+  },
+  "devDependencies": {
+++  "internal-lib": "workspace:^0.1.0"
+  },
+}
+```
+
+:::info 补充信息
+`workspace:^0.1.0` 是一种 PNPM 提供的 [Workspace 协议](https://pnpm.io/workspaces#workspace-protocol-workspace)。
+
+:::
+
+当依赖安装成功之后，我们还需要将 `packages/components` 进行构建，因为需要使用其构建产物。
+
+到此为止，`app/apps` 应用子项目可以正常的运行了。在修改 `features/internal-lib` 的源码，或者修改 `packages/components` 的源码并构建之后都会触发应用子项目的热更新。
+
+## 在使用 Yarn 的 Monorepo 中进行项目联调
+
+在 Yarn 的 Monorepo 项目中，默认情况下可以直接在 `apps/app` 应用项目中直接使用组件项目和内部模块项目。
+
+:::info 补充信息
+之所以可以直接在应用中使用使用组件项目和内部模块项目，是因为 Yarn 将这些子项目模块提升到了顶层的 `node_modules`内。
+
+:::
+
+但是由于组件 `components` 是非内部模块，因此建议在 `apps/app/package.json` 中进行依赖声明：
+
+```json
+{
+  "dependencies": {
+++  "components": "0.1.0"
+  },
+}
+```

package/zh/guides/troubleshooting/cli.mdx

@@ -0,0 +1,63 @@
+---
+sidebar_position: 2
+---
+
+# 命令行问题
+
+### 使用 pnpm 时无法正确传递命令行参数？
+
+pnpm v6 和 pnpm v7 版本在执行命令时使用姿势不完全一致，需要注意以下事项：
+
+pnpm v7：
+
+在使用 pnpm 调用 `package.json` 中的命令时，如果需要传递参数至 pnpm，需要将参数放到命令前。
+
+例如使用 pnpm `--filter` 参数执行 prepare 命令：
+
+```bash
+pnpm run --filter "./packages/**" prepare
+```
+
+如果需要传递参数至命令，需要将参数放到命令后。
+
+例如，在如下 `package.json` 配置中：
+
+```json
+{
+  "scripts": {
+    "command": "modern command"
+  }
+}
+```
+
+执行 command 命令时携带参数方式为：
+
+```bash
+pnpm run command --options
+```
+
+pnpm v6:
+
+在如下 `package.json` 配置中：
+
+```json
+{
+  "scripts": {
+    "command": "modern command"
+  }
+}
+```
+
+当需要执行 `modern command --option`：
+
+使用 pnpm 时，需要执行 `pnpm run command -- --option`。
+
+这是因为 pnpm 对于命令参数的处理与 Yarn 并不相同，但是与 npm 类似：在不加 `--` 字符串的时候，传递的是 pnpm 的参数；在使用 `--` 字符串的时候，传递的是执行脚本的参数。
+
+在上述例子里参数 `--option` 传递给了 `modern command`。如果执行 `pnpm run command --option`，则参数 `--option` 将传递给 pnpm。
+
+总结来说：
+
+**在使用 pnpm v7 时，如果传递参数给 pnpm，需要将参数放置到命令前**
+
+**在使用 pnpm v6 时，如果传递的参数给 pnpm，不需要加 `--`；如果传递的参数是给脚本使用，需要增加 `--` 字符串**。

package/zh/index.md

@@ -0,0 +1,4 @@
+---
+pageType: home
+---
+# index