@modern-js/main-doc 2.0.0-canary.0 → 2.0.0

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/model/use-model.md

@@ -0,0 +1,244 @@
+---
+sidebar_position: 3
+title: 使用 Model
+---
+
+## 在组件内使用
+### 作为全局状态使用
+
+通过 `useModel` 可以获取 Model 的 State、Actions 等。当 Model 的 State 通过 Actions 进行修改后，任何其他使用了该 Model 的组件，都会自动重新渲染。
+
+在 [快速上手](/docs/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`](/docs/apis/app/runtime/model/create-store) 手动创建的 Store 对象，无需通过 `useStore` 在组件内获取，即可直接使用。
+:::
+
+:::info 补充信息
+本节涉及的 API 的详细定义，请参考[这里](/docs/apis/app/runtime/model/model_)。
+:::

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/model/use-out-of-modernjs.md

@@ -0,0 +1,51 @@
+---
+sidebar_position: 12
+title: 单独使用 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`](/docs/apis/app/runtime/model/Provider) 组件。单独使用 Reduck 时，需要手动完成。
+
+示例：
+```tsx
+// 根组件
+const Root = () => {
+  return (
+    <Provider>
+      {/* 应用入口组件 */}
+      <App />
+    </Provider>
+  )
+}
+```
+
+
+4. 功能配置
+
+在 Modern.js 中使用时，可以通过 [`runtime.state`](/docs/configure/app/runtime/state) 对 Reduck 功能进行配置。单独使用时，需要通过 [`Provider`](/docs/apis/app/runtime/model/Provider) 的 `config` 或 `store` 参数配置。
+
+
+示例：
+```tsx
+const Root = () => {
+  return (
+    {/* 关闭 Redux DevTools */}
+    <Provider config={{ devTools: false }}>
+      <App />
+    </Provider>
+  )
+}
+```

package/en/docusaurus-plugin-content-docs/current/tutorials/first-app/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "First App",
+  "position": 2,
+  "collapsed": false
+}

package/en/docusaurus-plugin-content-docs/current/tutorials/first-app/c01-start.md

@@ -0,0 +1,99 @@
+---
+title: 创建项目
+---
+
+从这一章节开始，我们将进入实战教程部分。在实战教程中，我们将会从环境准备开始，从简单到复杂，一步一步搭建一个真实的项目。
+
+## 环境准备
+
+import Prerequisites from '@site-docs/components/prerequisites.md'
+
+<Prerequisites />
+
+## 初始化项目
+
+我们创建新的目录，通过命令行工具初始化项目：
+
+```bash
+mkdir myapp && cd myapp
+npx @modern-js/create
+```
+
+import InitApp from '@site-docs/components/init-app.md'
+
+<InitApp />
+
+## 调试项目
+
+import DebugApp from '@site-docs/components/debug-app.md'
+
+<DebugApp />
+
+## 修改代码
+
+我们将原本的示例代码删除，替换成一个简单的联系人列表：
+
+```tsx title="src/routes/page.tsx"
+const getAvatar = (users: Array<{ name: string; email: string }>) =>
+  users.map(user => ({
+    ...user,
+    avatar: `https://avatars.dicebear.com/v2/identicon/${user.name}.svg`,
+  }));
+
+const mockData = getAvatar([
+  { name: 'Thomas', email: 'w.kccip@bllmfbgv.dm' },
+  { name: 'Chow', email: 'f.lfqljnlk@ywoefljhc.af' },
+  { name: 'Bradley', email: 'd.wfovsqyo@gpkcjwjgb.fr' },
+  { name: 'Davis', email: '"t.kqkoj@utlkwnpwk.nu' },
+]);
+
+function App() {
+  return (
+    <ul>
+      {mockData.map(({ name, avatar, email }) => (
+        <li key={name}>
+          <img src={avatar} width={60} height={60} /> ---
+          <span>{name}</span> ---
+          <span>{email}</span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+export default App;
+```
+
+删除多余的 css 文件，保持目录没有多余的文件：
+
+```bash
+rm src/routes/index.css
+```
+
+因为框架默认支持 [HMR](https://webpack.js.org/concepts/hot-module-replacement/)，可以看到 `http://localhost:8080/` 里的内容会自动更新为：
+
+![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvt/ljhwZthlaukjlkulzlp/screenshot-20221214-141909.png)
+
+此刻的页面还没有样式。下一章节将展开这部分的内容。
+
+## 开启 SSR
+
+接下来，我们修改项目中的 `modern.config.ts`，开启 SSR 能力：
+
+```ts
+import AppToolsPlugin, { defineConfig } from '@modern-js/app-tools';
+
+// https://modernjs.dev/docs/apis/app/config
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+  },
+  server: {
+    ssr: true,
+  },
+  plugins: [AppToolsPlugin()],
+});
+```
+
+重新执行 `pnpm run dev`，可以发现项目已经在服务端完成了页面渲染。

package/en/docusaurus-plugin-content-docs/current/tutorials/first-app/c02-component.md

@@ -0,0 +1,56 @@
+---
+title: 编写 UI 组件
+---
+
+上一章节中，我们学习了如何初始化项目，并使用配置修改 Modern.js 的默认行为。
+
+这一章节中，我们继续沿用上一章节的项目代码，继续完善联系人列表。
+
+为了做更好的 UI 展示和交互，我们引入组件库 [Antd](https://ant.design/index-cn) 来开发，使用 `<List>` 组件来代替原始的列表。先添加依赖：
+
+```bash
+pnpm add antd
+```
+
+修改 `src/routes/page.tsx`，在顶部导入组件：
+
+```ts
+import { List } from 'antd';
+```
+
+修改 `<App>` 组件的实现：
+
+```tsx
+function App() {
+  return (
+    <div>
+      <List
+        dataSource={mockData}
+        renderItem={({ name, email, avatar }) => (
+          <List.Item key={name}>
+            <List.Item.Meta
+              avatar={<img alt="avatar" src={avatar} width={60} height={60} />}
+              title={name}
+              description={email}
+            />
+          </List.Item>
+        )}
+      />
+    </div>
+  );
+}
+```
+
+执行 `pnpm run dev`，查看运行结果：
+
+![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c02-antd-result.png)
+
+可以看到 Ant Design 导出的组件，已经具备了完整的样式。
+
+:::info 注
+Modern.js 会[自动按需导入 Ant Design 组件需要的 CSS](https://github.com/ant-design/babel-plugin-import)。
+:::
+
+:::note
+我们也可以使用其他组件库来实现同样的功能，例如 [Arco Design](https://arco.design/)。
+:::