@modern-js/main-doc 2.69.4 → 3.0.0-alpha.0

package/docs/zh/tutorials/first-app/c04-routes.mdx

@@ -1,172 +0,0 @@
----
-title: 添加客户端路由
----
-# 添加客户端路由
-
-import { Tabs, Tab as TabItem } from "@theme";
-
-上一章节中，我们学习了如何为创建 UI 组件，并添加样式。
-
-这一章节中，我们将会学习如何添加**客户端路由**。
-
-之前我们已经为联系人列表增加了 Archive 按钮，接下来我们添加一个客户端路由 `/archives`，访问这个路由时，只显示已存档的联系人，而原有的 `/` 继续显示所有联系人。
-
-新建 `src/routes/archives/page.tsx` 文件：
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-mkdir -p src/routes/archives
-touch src/routes/archives/page.tsx
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-mkdir -p src/routes/archives
-ni src/routes/archives/page.tsx
-```
-
-</TabItem>
-</Tabs>
-
-添加如下代码：
-
-```tsx title="src/archives/page.tsx"
-import { List } from 'antd';
-import { Helmet } from '@modern-js/runtime/head';
-import Item from '../../components/Item';
-
-const getAvatar = (users: Array<{ name: string; email: string }>) =>
-  users.map(user => ({
-    ...user,
-    avatar: `https://api.dicebear.com/7.x/pixel-art/svg?seed=${user.name}`,
-  }));
-
-const getMockArchivedData = () =>
-  getAvatar([
-    { name: 'Thomas', email: 'w.kccip@bllmfbgv.dm' },
-    { name: 'Chow', email: 'f.lfqljnlk@ywoefljhc.af' },
-  ]);
-function Index() {
-  return (
-    <div className="container lg mx-auto">
-      <Helmet>
-        <title>Archives</title>
-      </Helmet>
-      <List
-        dataSource={getMockArchivedData()}
-        renderItem={info => <Item key={info.name} info={info} />}
-      />
-    </div>
-  );
-}
-
-export default Index;
-```
-
-这里使用了 [React Helmet](https://github.com/nfl/react-helmet) 的 `Helmet` 组件，在 `src/routes/page.tsx` 中也添加 Helmet 组件：
-
-```tsx
-import { Helmet } from '@modern-js/runtime/head';
-
-function Index() {
-  return (
-    <div className="container lg mx-auto">
-      <Helmet>
-        <title>All</title>
-      </Helmet>
-      ...
-    </div>
-  );
-}
-```
-
-:::info
-Modern.js 默认集成了 react-helmet，也可以结合 SSR 使用，满足 SEO 需求。
-
-:::
-
-因为现在有多个页面，都需要用到前面的 Utility Class，因此我们需要把样式文件移动到 `src/routes/layout.tsx`：
-
-```tsx
-import 'tailwindcss/base.css';
-import 'tailwindcss/components.css';
-import 'tailwindcss/utilities.css';
-import '../styles/utils.css';
-```
-
-执行 `pnpm run dev`，访问 `http://localhost:8080`，可以看到完整的联系人，页面的标题是 All：
-
-![display1](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c04-archives.png)
-
-访问 `http://localhost:8080/archives`，只会看到已存档的联系人，页面的标题是 Archives：
-
-![display](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c04-all.png)
-
-查看页面 HTML 源码，可以看到两个页面的内容是一样，是在客户端针对不同 URL 渲染不同内容。
-
-**接下来我们增加一个简单的导航栏，让用户能在两个列表之间切换**。
-
-打开 `src/routes/layout.tsx`，在顶部导入 Radio 组件：
-
-```tsx
-import { Radio } from 'antd';
-```
-
-然后将 UI 最顶部进行修改，增加一组单选框
-
-```tsx
-export default function Layout() {
-  // [!code highlight:8]
-  return (
-    <div>
-      <div className="h-16 p-2 flex items-center justify-center">
-        <Radio.Group onChange={handleSetList} value={currentList}>
-          <Radio value="/">All</Radio>
-          <Radio value="/archives">Archives</Radio>
-        </Radio.Group>
-      </div>
-      <Outlet />
-    </div>
-  );
-}
-```
-
-然后我们来实现 `currentList` 和 `handleSetList`。
-
-引入三个 React Hook：`useState` 和 `useNavigate` 和 `useParams`，以及 Ant Design 的事件类型定义：
-
-```js
-import { useState } from 'react';
-import { Radio, RadioChangeEvent } from 'antd';
-import { Outlet, useLocation, useNavigate } from '@modern-js/runtime/router';
-```
-
-最后在 Layout 组件里增加局部状态和相关逻辑：
-
-```tsx
-export default function Layout() {
-  // [!code highlight:8]
-  const navigate = useNavigate();
-  const location = useLocation();
-  const [currentList, setList] = useState(location.pathname || '/');
-  const handleSetList = (e: RadioChangeEvent) => {
-    const { value } = e.target;
-    setList(value);
-    navigate(value);
-  };
-  return (
-  ...
-}
-```
-
-到这里就已经完成了页面导航栏实现，执行 `pnpm run dev` 查看效果：
-
-![display2](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c04-switch.png)
-
-点击导航栏中 Archives，可以看到单选框的选中状态和 URL 都会变化，页面没有刷新，只发生了 CSR。
-
-通过 URL 访问两个页面，可以看到 HTML 内容是不同的，这是因为在 SSR 阶段页面就执行了客户端路由的逻辑，HTML 里已经包含了最终的渲染结果。

package/docs/zh/tutorials/first-app/c05-loader.mdx

@@ -1,89 +0,0 @@
----
-title: 添加 Loader
----
-# 添加 Loader
-
-上一章节中，我们学习了如何添加客户端路由。
-
-这一章节中，我们将会学习如何为**路由组件添加 Loader**。
-
-到目前为止，我们都是通过硬编码的方式，为组件提供数据。如果要从远端获取数据，通常情况下会使用 `useEffect` 来做。但在启用 SSR 的情况下，`useEffect` 是不会在服务端执行的，所以这种 SSR 只能渲染很有限的 UI。
-
-Modern.js 为提供了 Data Loader 的能力，支持同构的在组件中获取数据，让 SSR 的价值最大化。
-
-下面我们演示如何为路由组件添加 Data Loader，并模拟远端数据获取。我们使用 faker 来 mock 需要的数据，首先安装依赖：
-
-```bash
-pnpm add faker@5
-pnpm add @types/faker@5 -D
-```
-
-创建 `src/routes/page.data.ts`：
-
-```tsx
-import { name, internet } from 'faker';
-
-export 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://api.dicebear.com/7.x/pixel-art/svg?seed=${firstName}`,
-      email: internet.email(),
-    };
-  });
-
-  return {
-    code: 200,
-    data,
-  };
-};
-```
-
-:::note
-Data Loader 并非只为 SSR 工作。在 CSR 项目中，Data Loader 也可以避免数据获取依赖 UI 渲染，解决请求瀑布流的问题。未来，Modern.js 也会为这一特性添加更多能力，例如预获取、数据缓存等。
-
-:::
-
-Modern.js 也提供了一个叫 `useLoaderData` 的 hooks API，我们修改 `src/routes/page.tsx` 导出的组件：
-
-```tsx
-// [!code highlight:2]
-import { useLoaderData } from '@modern-js/runtime/router';
-import type { LoaderData } from './page.data';
-
-function Index() {
-  // [!code highlight:1]
-  const { data } = useLoaderData() as LoaderData;
-
-  return (
-    <div className="container lg mx-auto">
-      <Helmet>
-        <title>All</title>
-      </Helmet>
-      // [!code highlight:1]
-      <List
-        dataSource={data}
-        renderItem={info => <Item key={info.name} info={info} />}
-      />
-    </div>
-  );
-}
-
-export default Index;
-```
-
-{/* Todo 重新截图，SSR 内容  */}
-
-重新执行 `pnpm run dev`，查看 `view-source:http://localhost:8080/`，或在 devtools 的 Network 面板里查看 HTML 请求的「 Preview 」，可以看到 SSR 渲染出来的 HTML 已经包含完整的 UI：
-
-![display6](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/11/display6.png)

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

@@ -1,274 +0,0 @@
-
-# 添加状态管理
-
-上一章节中，我们把硬编码的 `mockData` 改成从 Data Loader 中加载。
-
-这一章节中，我们会进一步实现项目的功能，例如实现 **Archive** 按钮的功能，把联系人归档。
-
-因此会开始编写一些跟 UI 完全无关的业务逻辑，如果继续写在组件代码中，会产生越来越多的面条式代码。为此，我们引入了一种叫做 **业务模型（Model）** 的代码模块，将这些业务逻辑和 UI 解耦。
-
-:::info 注意
-使用状态管理相关 API，需要先启用配置项 [runtime.state](/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` 和 `src/routes/page.data.ts`，为 `<Item>` 组件传递更多参数：
-
-```ts title="src/routes/page.data.ts"
-export 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://api.dicebear.com/7.x/pixel-art/svg?seed=${firstName}`,
-      email: internet.email(),
-      archived: false,
-    };
-  });
-
-  return {
-    code: 200,
-    data,
-  };
-};
-```
-
-```tsx title="src/routes/page.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';
-
-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 中的数据，因此切换路由时数据没有发生改变。
-
-:::