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

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

@@ -1,281 +0,0 @@
----
-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` 中：
-
-```ts title="src/routes/layout.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(),
-    };
-  });
-
-  return {
-    code: 200,
-    data,
-  };
-};
-```
-
-```tsx title="src/routes/layout.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';
-import type { LoaderData } from './layout.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 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.mdx) 章节提到过，视图组件用目录形式，是因为视图组件负责实现 UI 展示和交互细节，可以演变的复杂。用目录形式，可以方便增加子文件，包括专用的资源（图片等）、专用子组件、CSS 文件等。在这个目录内部可以随意重构，只考虑最小局部。
-
-而容器组件只负责连接，是一个胶水层，复杂的业务逻辑和实现细节都交给 View 层和 Model 层去实现。容器组件自己应该保持简单清晰，不应该包含复杂实现细节，所以不应该有内部结构。采用单文件形式不但更简洁，也能起到约束作用，提醒开发者不要把容器组件写复杂。

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

@@ -1,135 +0,0 @@
----
-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 title="modern.config.ts"
-import { appTools, defineConfig } from '@modern-js/app-tools';
-import { tailwindcssPlugin } from '@modern-js/plugin-tailwindcss';
-
-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) 等更多教程，进一步完善你的应用。