@modern-js/main-doc 2.0.3-alpha.0 → 2.2.0

package/zh/tutorials/first-app/c06-model.mdx

@@ -0,0 +1,275 @@
+---
+title: 添加业务模型（状态管理）
+---
+
+# 添加业务模型（状态管理）
+
+上一章节中，我们把硬编码的 `mockData` 改成从 Data Loader 中加载。
+
+这一章节中，我们会进一步实现项目的功能，例如实现 **Archive** 按钮的功能，把联系人归档。
+
+因此会开始编写一些跟 UI 完全无关的业务逻辑，如果继续写在组件代码中，会产生越来越多的面条式代码。为此，我们引入了一种叫做 **业务模型（Model）** 的代码模块，将这些业务逻辑和 UI 解耦。
+
+:::info 注意
+使用状态管理相关 API，需要先启用配置项 [runtime.state](/docs/configure/app/runtime/state)：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  runtime: {
+    state: true,
+  },
+});
+```
+
+:::
+
+## 实现 Model
+
+创建一个完整的 Model 首先需要定义**状态（state）**，包括状态中数据的名称和初始值。
+
+我们使用 Model 来管理联系人列表的数据，因此定义如下数据状态：
+
+```js
+const state = {
+  items: [],
+};
+```
+
+使用 TS 语法，可以定义更完整的类型信息，比如 items 里每个对象都应该有 `name`、`email` 字段。为了实现归档功能，还需要创建 `archived` 字段保存这个联系人是否已被归档的状态。
+
+我们还需要一个字段用来访问所有已归档的联系人，可以定义 **computed** 类型的字段，对已有的数据做转换：
+
+```js
+const computed = {
+  archived: ({ items }) => {
+    return items.filter(item => item.archived);
+  },
+};
+```
+
+`computed` 类型字段的定义方式是函数，但使用时可以像普通字段一样通过 state 访问。
+
+:::info
+Modern.js 集成了 [Immer](https://immerjs.github.io/immer/)，能够像操作 JS 中常规的可变数据一样，去写这种状态转移的逻辑。
+
+:::
+
+实现 Archive 按钮时，我们需要一个 `archive` 函数，负责修改指定联系人的 `archived` 字段，我们把这种函数都叫作 **action**：
+
+```js
+const actions = {
+  archive(draft, payload) {
+    const target = draft.items.find(item => item.email === payload);
+    if (target) {
+      target.archived = true;
+    }
+  },
+};
+```
+
+action 函数是一种**纯函数**，确定的输入得到确定的输出（转移后的状态），不应该有任何副作用。
+
+函数的第一个参数是 Immer 提供的 Draft State，第二个参数是 action 被调用时传入的参数（后面会介绍怎么调用）。
+
+我们尝试完整实现它们：
+
+```js
+const state = {
+  items: [],
+  pending: false,
+  error: null,
+};
+
+const computed = {
+  archived: ({ items }) => {
+    return items.filter(item => item.archived);
+  },
+};
+
+const actions = {
+  archive(draft, payload) {
+    const target = draft.items.find(item => item.email === payload);
+    if (target) {
+      target.archived = true;
+    }
+  },
+};
+```
+
+接下来我们把上面的代码连起来，放在同一个 Model 文件里。首先执行以下命令，创建新的文件目录：
+
+```bash
+mkdir -p src/models/
+touch src/models/contacts.ts
+```
+
+添加 `src/models/contacts.ts` 的内容：
+
+```tsx
+import { model } from '@modern-js/runtime/model';
+
+type State = {
+  items: {
+    avatar: string;
+    name: string;
+    email: string;
+    archived?: boolean;
+  }[];
+  pending: boolean;
+  error: null | Error;
+};
+
+export default model<State>('contacts').define({
+  state: {
+    items: [],
+    pending: false,
+    error: null,
+  },
+  computed: {
+    archived: ({ items }: State) => items.filter(item => item.archived),
+  },
+  actions: {
+    archive(draft, payload) {
+      const target = draft.items.find(item => item.email === payload)!;
+      if (target) {
+        target.archived = true;
+      }
+    },
+  },
+});
+```
+
+我们把一个包含 state，action 等要素的 plain object 称作 **Model Spec**，Modern.js 提供了 [Model API](/apis/app/runtime/model/model_)，可以根据 Model Spec 生成 **Model**。
+
+## 使用 Model
+
+现在我们直接使用这个 Model，把项目的逻辑补充起来。
+
+首先修改 `src/components/Item/index.tsx`，添加 **Archive 按钮**的 UI 和交互，内容如下：
+
+```tsx
+import Avatar from '../Avatar';
+
+type InfoProps = {
+  avatar: string;
+  name: string;
+  email: string;
+  archived?: boolean;
+};
+
+const Item = ({
+  info,
+  onArchive,
+}: {
+  info: InfoProps;
+  onArchive?: () => void;
+}) => {
+  const { avatar, name, email, archived } = info;
+  return (
+    <div className="flex p-4 items-center border-gray-200 border-b">
+      <Avatar src={avatar} />
+      <div className="ml-4 custom-text-gray flex-1 flex justify-between">
+        <div className="flex-1">
+          <p>{name}</p>
+          <p>{email}</p>
+        </div>
+        <button
+          type="button"
+          disabled={archived}
+          onClick={onArchive}
+          className={`text-white font-bold py-2 px-4 rounded-full ${
+            archived
+              ? 'bg-gray-400 cursor-default'
+              : 'bg-blue-500 hover:bg-blue-700'
+          }`}
+        >
+          {archived ? 'Archived' : 'Archive'}
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export default Item;
+```
+
+接下来，我们修改 `src/routes/page.tsx`，为 `<Item>` 组件传递更多参数：
+
+```tsx
+import { Helmet } from '@modern-js/runtime/head';
+import { useModel } from '@modern-js/runtime/model';
+import { useLoaderData } from '@modern-js/runtime/router';
+import { List } from 'antd';
+import { name, internet } from 'faker';
+import Item from '../components/Item';
+import contacts from '../models/contacts';
+
+type LoaderData = {
+  code: number;
+  data: {
+    name: string;
+    avatar: string;
+    email: string;
+  }[];
+};
+
+export const loader = async (): Promise<LoaderData> => {
+  const data = new Array(20).fill(0).map(() => {
+    const firstName = name.firstName();
+    return {
+      name: firstName,
+      avatar: `https://avatars.dicebear.com/api/identicon/${firstName}.svg`,
+      email: internet.email(),
+      archived: false,
+    };
+  });
+
+  return {
+    code: 200,
+    data,
+  };
+};
+
+function Index() {
+  const { data } = useLoaderData() as LoaderData;
+  const [{ items }, { archive, setItems }] = useModel(contacts);
+  if (items.length === 0) {
+    setItems(data);
+  }
+
+  return (
+    <div className="container lg mx-auto">
+      <Helmet>
+        <title>All</title>
+      </Helmet>
+      <List
+        dataSource={items}
+        renderItem={info => (
+          <Item
+            key={info.name}
+            info={info}
+            onArchive={() => {
+              archive(info.email);
+            }}
+          />
+        )}
+      />
+    </div>
+  );
+}
+
+export default Index;
+```
+
+`useModel` 是 Modern.js 提供的 hooks API。可以在组件中提供 Model 中定义的 state，或通过 actions 调用 Model 中定义的 side effect 与 action，从而改变 Model 的 state。
+
+Model 是业务逻辑，是计算过程，本身不创建也不持有状态。只有在被组件用 hooks API 使用后，才在指定的地方创建状态。
+
+执行 `pnpm run dev`，点击 **Archive 按钮**，可以看到页面 UI 发生了变化。
+
+:::note
+上述例子中，`useLoaderData` 其实在每次切换路由时都会执行。因为我们在 Data Loader 里使用了 fake 数据，每次返回的数据是不同的。但我们优先使用了 Model 中的数据，因此切换路由时数据没有发生改变。
+
+:::

package/zh/tutorials/first-app/c07-container.mdx

@@ -0,0 +1,282 @@
+---
+title: 添加容器组件
+---
+# 添加容器组件
+
+import { Tabs, Tab as TabItem } from "@theme";
+
+上一章节中，我们初步引入**业务模型**，从 UI 组件中拆分出这部分逻辑。`page.tsx` 中不再包含 UI 无关的业务逻辑实现细节，只需要使用 Model，就能实现同样的功能。
+
+这一章节中，我们要进一步利用 Model 中实现的业务逻辑，让 `page.tsx` 和 `archived/page.tsx` 获取同一份数据。并实现 Archive 按钮，点击按钮能把联系人归档，只显示在 Archives 列表里，不显示在 All 列表里。
+
+## 使用完整 Model
+
+因为两个页面需要共用同一套状态（联系人列表数据、联系人是否被归档），都需要包含加载初始数据的逻辑，因此我们需要在更上一层完成数据获取。
+
+Modern.js 支持在 `layout.tsx` 通过 Data Loader 获取数据，我们先数据获取这部分代码移动到 `src/routes/layout.tsx` 中：
+
+```tsx
+import { name, internet } from 'faker';
+import {
+  Outlet,
+  useLoaderData,
+  useLocation,
+  useNavigate,
+} from '@modern-js/runtime/router';
+import { useState } from 'react';
+import { Radio, RadioChangeEvent } from 'antd';
+import { useModel } from '@modern-js/runtime/model';
+import contacts from '../models/contacts';
+import 'tailwindcss/base.css';
+import 'tailwindcss/components.css';
+import 'tailwindcss/utilities.css';
+import '../styles/utils.css';
+
+type LoaderData = {
+  code: number;
+  data: {
+    name: string;
+    avatar: string;
+    email: string;
+  }[];
+};
+
+export const loader = async (): Promise<LoaderData> => {
+  const data = new Array(20).fill(0).map(() => {
+    const firstName = name.firstName();
+    return {
+      name: firstName,
+      avatar: `https://avatars.dicebear.com/api/identicon/${firstName}.svg`,
+      email: internet.email(),
+    };
+  });
+
+  return {
+    code: 200,
+    data,
+  };
+};
+
+export default function Layout() {
+  const { data } = useLoaderData() as LoaderData;
+  const [{ items }, { setItems }] = useModel(contacts);
+  if (items.length === 0) {
+    setItems(data);
+  }
+
+  const navigate = useNavigate();
+  ...
+}
+```
+
+在 `src/routes/page.tsx` 中，直接使用 Model，获取数据：
+
+```tsx
+import { Helmet } from '@modern-js/runtime/head';
+import { useModel } from '@modern-js/runtime/model';
+import { List } from 'antd';
+import Item from '../components/Item';
+import contacts from '../models/contacts';
+
+function Index() {
+  const [{ items }, { archive }] = useModel(contacts);
+
+  return (
+    <div className="container lg mx-auto">
+      <Helmet>
+        <title>All</title>
+      </Helmet>
+      <List
+        dataSource={items}
+        renderItem={info => (
+          <Item
+            key={info.name}
+            info={info}
+            onArchive={() => {
+              archive(info.email);
+            }}
+          />
+        )}
+      />
+    </div>
+  );
+}
+
+export default Index;
+```
+
+同样在 `archived/page.tsx` 中，删除原本的 `mockData` 逻辑，使用 Model 中 computed 的 `archived` 值作为数据源：
+
+```tsx
+import { Helmet } from '@modern-js/runtime/head';
+import { useModel } from '@modern-js/runtime/model';
+import { List } from 'antd';
+import Item from '../../components/Item';
+import contacts from '../../models/contacts';
+
+function Index() {
+  const [{ archived }, { archive }] = useModel(contacts);
+
+  return (
+    <div className="container lg mx-auto">
+      <Helmet>
+        <title>Archives</title>
+      </Helmet>
+      <List
+        dataSource={archived}
+        renderItem={info => (
+          <Item
+            key={info.name}
+            info={info}
+            onArchive={() => {
+              archive(info.email);
+            }}
+          />
+        )}
+      />
+    </div>
+  );
+}
+
+export default Index;
+```
+
+执行 `pnpm run dev`，访问 `http://localhost:8080/`，点击 Archive 按钮后，可以看到按钮置灰：
+
+![display](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c07-contacts-all.png)
+
+接下来点击顶部导航，切换到 Archives 列表，可以发现刚才 **Archive** 的联系人已经出现在列表当中：
+
+![display](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c07-contacts-archives.png)
+
+## 抽离容器组件
+
+前面章节中，我们把项目中的业务逻辑拆分成了两个 layer，一个是**视图组件**，另一个是**业务模块**。前者负责 UI 展示、交互等，后者负责实现 UI 无关的业务逻辑，专门管理状态。
+
+像 `src/routes/page.tsx` 和 `src/routes/archives/page.tsx` 这样使用了 `useModel` API 的组件，负责把 View 和 Model 这两个 layer 连接起来，类似传统 MVC 架构中 Controller 的角色，在 Modern.js 里我们沿用习惯，把它们称作**容器组件（Container）**。
+
+容器组件推荐放在专门的 `containers/` 目录里，我们执行以下命令，创建新的文件：
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+mkdir -p src/containers
+touch src/containers/Contacts.tsx
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+mkdir -p src/containers
+ni src/containers/Contacts.tsx
+```
+
+</TabItem>
+</Tabs>
+
+我们将原本两个 `page.tsx` 中公共的部分抽离出来，`src/containers/Contacts.tsx` 的代码如下：
+
+```tsx
+import { Helmet } from '@modern-js/runtime/head';
+import { useModel } from '@modern-js/runtime/model';
+import { List } from 'antd';
+import Item from '../components/Item';
+import { Helmet } from '@modern-js/runtime/head';
+import { useModel } from '@modern-js/runtime/model';
+import { List } from 'antd';
+import Item from '../components/Item';
+import contacts from '../models/contacts';
+
+function Contacts({
+  title,
+  source,
+}: {
+  title: string;
+  source: 'items' | 'archived';
+}) {
+  const [state, { archive }] = useModel(contacts);
+
+  return (
+    <div className="container lg mx-auto">
+      <Helmet>
+        <title>{title}</title>
+      </Helmet>
+      <List
+        dataSource={state[source]}
+        renderItem={info => (
+          <Item
+            key={info.name}
+            info={info}
+            onArchive={() => {
+              archive(info.email);
+            }}
+          />
+        )}
+      />
+    </div>
+  );
+}
+
+export default Contacts;
+```
+
+修改 `src/routes/page.tsx` 和 `src/routes/archives/page.tsx` 的代码：
+
+```tsx title="src/routes/page.tsx"
+import Contacts from '../containers/Contacts';
+
+function Index() {
+  return <Contacts title="All" source="items" />;
+}
+
+export default Index;
+```
+
+```tsx title="src/routes/archives/page.tsx"
+import Contacts from '../../containers/Contacts';
+
+function Index() {
+  return <Contacts title="Archives" source="archived" />;
+}
+
+export default Index;
+```
+
+重构完成，现在的项目结构是：
+
+```bash
+.
+├── README.md
+├── dist
+├── modern.config.ts
+├── node_modules
+├── package.json
+├── pnpm-lock.yaml
+├── src
+│   ├── components
+│   │   ├── Avatar
+│   │   │   └── index.tsx
+│   │   └── Item
+│   │       └── index.tsx
+│   ├── containers
+│   │   └── Contacts.tsx
+│   ├── models
+│   │   └── contacts.ts
+│   ├── modern-app-env.d.ts
+│   ├── routes
+│   │   ├── archives
+│   │   │   └── page.tsx
+│   │   ├── layout.tsx
+│   │   └── page.tsx
+│   └── styles
+│       └── utils.css
+└── tsconfig.json
+```
+
+`components/` 里的**视图组件**，都是目录形式，如 `Avatar/index.tsx`。而 `containers/` 里的**容器组件**，都是单文件形式，如 `contacts.tsx`。**这是我们推荐的一种最佳实践**。
+
+在 ​ [添加 UI 组件（Component）](./c02-component.md) 章节提到过，视图组件用目录形式，是因为视图组件负责实现 UI 展示和交互细节，可以演变的复杂。用目录形式，可以方便增加子文件，包括专用的资源（图片等）、专用子组件、CSS 文件等。在这个目录内部可以随意重构，只考虑最小局部。
+
+而容器组件只负责连接，是一个胶水层，复杂的业务逻辑和实现细节都交给 View 层和 Model 层去实现。容器组件自己应该保持简单清晰，不应该包含复杂实现细节，所以不应该有内部结构。采用单文件形式不但更简洁，也能起到约束作用，提醒开发者不要把容器组件写复杂。

package/zh/tutorials/first-app/c08-entries.mdx

@@ -0,0 +1,136 @@
+---
+title: 添加应用入口
+---
+# 添加应用入口
+
+上一个章节中，我们基本完成了联系人列表应用的开发，介绍了 Modern.js 中部分功能的用法，以及推荐的最佳实践。
+
+这一章节中，我们将介绍如何为应用添加新的入口。
+
+## 新建入口
+
+一个完整的项目可能需要多个入口，Modern.js 支持自动创建新入口，前面的章节中提到过，`pnpm run new` 可以启用可选功能。
+
+我们也可以通过它来创建新的工程元素，在项目根目录下执行 `pnpm run new`：
+
+```bash
+? 请选择你想要的操作 创建工程元素
+? 创建工程元素 新建「应用入口」
+? 请填写入口名称 (entry) landing-page
+```
+
+创建完成，项目会变成这样：
+
+```bash
+.
+├── README.md
+├── modern.config.ts
+├── node_modules
+├── package.json
+├── pnpm-lock.yaml
+├── src
+│   ├── modern-app-env.d.ts
+│   ├── landing-page
+│   │   └── routes
+│   │       ├── index.css
+│   │       ├── layout.tsx
+│   │       └── page.tsx
+│   └── myapp
+│       ├── components
+│       │   ├── Avatar
+│       │   │   └── index.tsx
+│       │   └── Item
+│       │       └── index.tsx
+│       ├── containers
+│       │   └── Contacts.tsx
+│       ├── models
+│       │   └── contacts.ts
+│       ├── routes
+│       │   ├── archives
+│       │   │   └── page.tsx
+│       │   ├── layout.tsx
+│       │   └── page.tsx
+│       └── styles
+│           └── utils.css
+└── tsconfig.json
+```
+
+可以看到联系人列表应用的文件，都被自动重构到 `src/myapp/` 里。
+
+同时新建了一个 `src/landing-page/`，里面同样有 `routes/*`（`pnpm run new` 命令只做了这些事，所以你也可以很容易的手动创建新入口或修改入口）
+
+执行 `pnpm run dev`，显示：
+
+![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c08-entries-myapp.png)
+
+访问 `http://localhost:8080/`，可以像之前一样看到应用程序。
+
+访问 `http://localhost:8080/landing-page`，可以看到刚创建的新入口 `landing-page` 的页面（Modern.js 自动生成的默认页面）。
+
+Modern.js 框架的设计原则之一是【[约定优于配置（Convention over Configuration）](https://en.wikipedia.org/wiki/Convention_over_configuration)】，多数情况下可以按约定直接写代码，不需要做任何配置，这里 `src/` 中的目录结构就是一种约定：
+
+`src/myapp/` 和 `src/landing-page/` 被自动识别为两个应用入口：myapp 和 landing-page。
+
+其中 `src/myapp/` 的目录名跟项目名（`package.json` 里的 `name`）一致，会被认为是项目**主入口**，项目 URL 的根路径（开发环境里默认是 `http://localhost:8080/`）会自动指向主入口。
+
+其他入口的 URL，是在根路径后追加入口名，比如 `http://localhost:8080/landing-page`。
+
+接下来，我们把 `src/myapp/` 重命名为 `src/contacts/`：
+
+```bash
+mv src/myapp src/contacts
+```
+
+再次执行 `pnpm run dev`，结果变成：
+
+![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c08-entries-contacts.png)
+
+现在不再有主入口，联系人列表现在是一个普通入口，需要用 `http://localhost:8080/contacts` 访问。
+
+## 按入口修改配置
+
+我们可以在 Modern.js 配置文件里，自己写代码来控制项目的配置。
+
+现在，修改 `modern.config.ts` 里面添加内容：
+
+```ts
+import appTools, { defineConfig } from '@modern-js/app-tools';
+import tailwindcssPlugin from '@modern-js/plugin-tailwindcss';
+
+// https://modernjs.dev/docs/apis/app/config
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+  },
+  server: {
+    ssr: true,
+    ssrByEntries: {
+      'landing-page': false,
+    },
+  },
+  plugins: [appTools(), tailwindcssPlugin()],
+});
+```
+
+执行 `pnpm run dev`，再用浏览器打开 `view-source:http://localhost:8080/landing-page`，可以看到 `landing-page` 网页内容是通过 js 动态加载的，且此页面的 SSR 功能被关闭。
+
+如果注释掉 `ssrByEntries` 和它的值，landing-page 的 SSR 功能就恢复开启了。
+
+还有一些时候，需要一些更复杂的逻辑来做设置，比如需要 JS 变量、表达式、导入模块等，例如在只在开发环境里开启 SSR：
+
+```js
+export default defineConfig({
+  server: {
+    ssrByEntries: {
+      'landing-page': process.env.NODE_ENV !== 'production',
+    },
+  },
+};
+```
+
+到底为止，我们的联系人列表应用的雏形就基本完成了 👏👏👏。
+
+## 下一步
+
+接下来你可以通过了解[指南](/guides/get-started/quick-start)、[配置](/configure/app/usage) 等更多教程，进一步完善你的应用。