@modern-js/main-doc 2.7.0 → 2.9.0

package/en/guides/topic-detail/model/quick-start.mdx

@@ -1,113 +0,0 @@
----
-sidebar_position: 1
-title: 快速上手
----
-# 快速上手
-
-import ReduckMigration from "@site-docs/components/reduck-migration"
-
-<ReduckMigration />
-
-[Reduck](https://github.com/modern-js-dev/reduck) 是 Modern.js 团队开发的遵循 MVC 模式的状态管理库，底层状态存储基于 [Redux](https://redux.js.org/) 实现，同时提供更高层级的抽象，并完全兼容 Redux 生态。
-
-Reduck 的目标是以 MVC 模式组织 React 应用开发结构，将业务逻辑维护在 Model 层，业务逻辑与 UI 解耦，让开发业务逻辑更集中、更简单，同时通过更高层级的抽象，减少重复工作（样板代码）。
-
-Reduck 在 MVC 模式中，扮演 M(Model) 的角色，React UI Component 对应 V(View)，从 Reduck 中获取 Model 并修改 Model 的 React Container Component 对应 C(View Controller/Container)。
-
-Modern.js 的状态管理解决方案，是通过内置 Reduck 实现的。在 Modern.js 中使用 Reduck，不仅免去了手动集成的环节，而且所有 Reduck API 都可以从 Modern.js 的 Runtime 包中直接导入使用，具有更好的一致性体验。
-
-:::info
-1. Modern.js 中使用 Reduck API，需要先设置 [runtime.state](/configure/app/runtime/state) 以启用状态管理插件。
-2. Reduck 也可以脱离 Modern.js 作为状态管理库[单独使用](/guides/topic-detail/model/use-out-of-modernjs)。
-
-:::
-
-## 核心概念
-
-Reduck 中的核心概念只有 4 个： Model、State、Actions、Effects。
-
-Model: 对独立模块的逻辑和所需状态的封装，由 State、Actions、Effects 组成。
-
-State: Model 中保存的状态。
-
-Actions: 用于修改 State 的纯函数，函数必须是**同步**的。
-
-Effects: 用于修改 State 的带有副作用的函数，函数可以是**异步**的。Effects 中可以调用自身或其他 Model 的 Actions 和 Effects。
-
-Reduck 数据流如下图所示：
-
-![Reduck 数据流](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/reduck-concept.svg)
-
-## 基本用法
-
-下来我们以一个简单的 **计数器** 应用为例，演示 Reduck 的基本用法。
-
-首先，我们定义一个名为 `count` 的 Model：
-
-```js
-import { model } from '@modern-js/runtime/model';
-
-const countModel = model('count').define({
-  state: {
-    value: 1,
-  },
-});
-
-export default countModel;
-```
-
-我们使用 API `model` 创建 `countModel`，`countModel` 当前只包含存储计数器值的状态，即代码中的 `value`。
-
-我们定义一个 action，用于计算器自增加 1：
-
-```js
-import { model } from '@modern-js/runtime/model';
-
-const countModel = model('count').define({
-  state: {
-    value: 1,
-  },
-  actions: {
-    add(state) {
-      state.value += 1;
-    },
-  },
-});
-
-export default countModel;
-```
-
-在 `add` action 中，我们可以直接修改 state 的值，进行加 1 操作，而不需要把 state 作为不可变对象进行操作，这是因为 Reduck 集成了 [immer](https://github.com/immerjs/immer)，可以直接修改原 state 对象。
-
-接下来，我们演示如何在组件中使用 Model。
-
-新建一个组件 Counter，在组件内通过 `useModel` API 使用 `countModel`：
-
-```js
-import { useModel } from '@modern-js/runtime/model';
-import countModel from './models/count';
-
-function Counter() {
-  const [state, actions] = useModel(countModel);
-
-  return (
-    <div>
-      <div>counter: {state.value}</div>
-      <button onClick={() => actions.add()}>add</button>
-    </div>
-  );
-}
-```
-
-`useModel` 获取 `countModel` 的 `state` 和 `actions`，组件展示当前计算器的值，点击 `add` 按钮，计数器自增 1。
-
-:::info
-由于使用的案例比较简单，这里并没有严格按照 MVC 模式进行分层，组件 `Counter` 同时起到了 V 和 C 两层的作用。
-
-:::
-
-最终演示效果如下：
-
-![countModel](https://lf3-static.bytednsdoc.com/obj/eden-cn/eueh7vhojuh/modern/simple-count-model.gif)
-
-这样，我们就完了一个简单的计数器应用。本节完整的示例代码可以在[这里](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/counter-model)查看。

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

@@ -1,252 +0,0 @@
----
-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/en/guides/troubleshooting/cli.mdx

@@ -1,63 +0,0 @@
----
-sidebar_position: 2
----
-
-# CLI FAQ
-
-### Can't pass command line arguments correctly when using pnpm?
-
-The pnpm v6 and pnpm v7 versions do not use the same posture when executing commands. The following should be noted:
-
-pnpm v7：
-
-When using pnpm to invoke a command in `package.json`, if you need to pass arguments to pnpm, you need to put the arguments before the command.
-
-For example, execute the prepare command with the pnpm '--filter' parameter:
-
-```bash
-pnpm run --filter "./packages/**" prepare
-```
-
-If you need to pass parameters to a command, you need to put the parameters after the command.
-
-For example, in the following `package.json` configuration:
-
-```json
-{
-  "scripts": {
-    "command": "modern command"
-  }
-}
-```
-
-The way to carry parameters when executing the command command is:
-
-```bash
-pnpm run command --options
-```
-
-pnpm v6:
-
-In the following `package.json` configuration:
-
-```json
-{
-  "scripts": {
-    "command": "modern command"
-  }
-}
-```
-
-If you need to execute `modern command --option`,
-
-When using pnpm, you need to execute the `pnpm run command -- --option`.
-
-This is because pnpm does not handle command parameters the same as Yarn, but is similar to npm: when not adding a `--` character string, the parameters of pnpm are passed; when using a `--` character string, the parameters of the execution script are passed.
-
-In the above example the parameter `--option` is passed to `modern command`. If `pnpm run command --option` is executed, the parameter `--option` will be passed to pnpm.
-
-Summary:
-
-** When using pnpm v7, if you pass arguments to pnpm, you need to put the arguments before the command **
-
-** When using pnpm v6, if the parameter passed to pnpm, you do not need to add `--`; if the parameter passed is for script use, you need to add `--` character string **.