@modern-js/main-doc 2.0.0-beta.3 → 2.0.0-beta.4

package/zh/tutorials/first-app/c11-container/11.1-use-model-with-app-state.md

@@ -1,240 +0,0 @@
----
-title: ​完整使用 Model
----
-
-上一章节中，我们初步引入**客户端应用架构**，从【 视图组件 】中拆分出【 业务模型（Model）】，`page.tsx` 中不再包含 UI 无关的业务逻辑实现细节，只需要使用 Model，就能实现同样的功能。
-
-这一章节中，我们要进一步利用 Model 中实现的业务逻辑，让 `archived/page.ts` 也从 BFF 获取数据，实现 Archive 按钮，点击按钮能把联系人归档，只显示在 Archives 列表里，不显示在 All 列表里。
-
-先改造 `Item` 组件，增加 Archive 按钮的交互实现：
-
-```tsx title="src/contacts/routes/components/Item/index.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;
-```
-
-两个页面需要共用同一套状态（联系人列表数据、联系人是否被归档），并且由于 Archives 列表和 All 列表都可能是第一屏页面（从不同 URL 访问），这两个组件都需要包含加载初始数据的逻辑（如果客户端没有联系人列表数据，就请求 BFF），所以这类两个组件公用的实现逻辑应该合并到一起：
-
-我们创建一个新的 `Contacts` 组件：
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-mkdir -p src/contacts/routes/components/Contacts/
-touch src/contacts/routes/components/Contacts/index.tsx
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-mkdir -p src/contacts/routes/components/Contacts/
-ni src/contacts/routes/components/Contacts/index.tsx
-```
-
-</TabItem>
-</Tabs>
-
-修改`components/Contacts/index.tsx` ，内容如下：
-
-```tsx title="src/contacts/routes/components/Contacts/index.tsx"
-import { useEffect } from 'react';
-import { useLocalModel } from '@modern-js/runtime/model';
-import { List } from 'antd';
-import contacts from '../../models/contacts';
-import Item from '../Item';
-
-const Contacts = ({ source }: { source: 'archived' | 'items' }) => {
-  const [state, actions] = useLocalModel(contacts);
-  const { items, error, pending } = state;
-  useEffect(() => {
-    if (!items.length && !error && !pending) {
-      actions.load();
-    }
-  });
-
-  const data = state.items.filter(item =>
-    source === 'archived' ? item.archived : true,
-  );
-
-  return (
-    (items.length && (
-      <List
-        dataSource={data}
-        renderItem={info => (
-          <Item
-            key={info.email}
-            info={info}
-            onArchive={() => {
-              actions.archive(info.email);
-            }}
-          />
-        )}
-      />
-    )) || (
-      <div className="p-4 items-center border-gray-200 border-b border-t custom-text-gray">
-        Pending...
-      </div>
-    )
-  );
-};
-
-export default Contacts;
-```
-
-最后改造 `page.tsx` 和 `archived/page.ts`，利用 Contacts 实现 Archives 列表和 All 列表：
-
-```tsx title="src/contacts/page.tsx"
-import Contacts from './components/Contacts';
-import 'ladda/dist/ladda.min.css';
-import 'tailwindcss/base.css';
-import 'tailwindcss/components.css';
-import 'tailwindcss/utilities.css';
-import './styles/utils.css';
-
-function Index() {
-  return (
-    <div className="container lg mx-auto">
-      <Contacts source="items" />
-    </div>
-  );
-}
-
-export default Index;
-```
-
-```tsx title="src/contacts/archived/page.tsx"
-import Contacts from './components/Contacts';
-
-function Index() {
-  return (
-    <div className="container lg mx-auto">
-      <Contacts source="archived" />
-    </div>
-  );
-}
-
-export default Index;
-```
-
-执行 `pnpm run dev`，访问 `http://localhost:8080/contacts/`，点击 Archive 按钮后，可以看到按钮置灰：
-
-![display](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/11/display.png)
-
-接下来点击顶部导航，切换到 Archives 列表，我们预期的时候能看到列表里显示刚才归档的联系人，但实际上列表是空的：
-
-![display7](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/11/display7.png)
-
-出现这个问题的原因是，我们继续沿用了上一节的 `useLocalModel` API 来使用 Model，状态被保存到了组件内部的 state 里，而 `All` 列表和 `Archives` 列表中分别调用的 `Contacts` 组件，是两个各自独立的组件.
-
-所以它们有各自独立的内部 state，互相不共享状态，渲染 `Archives` 列表的时候，`items` 仍然是初始状态。
-
-要解决这个问题，一种方式把 `useLocalModel` 的逻辑提升到父组件里，把状态分别传给两个 `Contacts` 组件。更清晰、完善的方式，是启用全局唯一的「 应用状态 」，两个 `Contacts` 组件「 连接 」应用状态。
-
-在 Modern.js 里实现应用状态管理很简单，只需要把 `useLocalModel` 换成 `useModel`。
-
-修改 `components/Contacts/index.tsx` 的内容：
-
-
-```tsx title="src/contacts/routes/components/Contacts/index.tsx"
-import { useEffect } from 'react';
-import { useModel } from '@modern-js/runtime/model';
-import { List } from 'antd';
-import contacts from '../../models/contacts';
-import Item from '../Item';
-
-const Contacts = ({ source }: { source: 'archived' | 'items' }) => {
-  const [state, actions] = useModel(contacts);
-  const { items, error, pending } = state;
-  useEffect(() => {
-    if (!items.length && !error && !pending) {
-      actions.load();
-    }
-  });
-
-  const data = state.items.filter(item =>
-    source === 'archived' ? item.archived : true,
-  );
-
-  return (
-    (items.length && (
-      <List
-        dataSource={data}
-        renderItem={info => (
-          <Item
-            key={info.email}
-            info={info}
-            onArchive={() => {
-              actions.archive(info.email);
-            }}
-          />
-        )}
-      />
-    )) || (
-      <div className="p-4 items-center border-gray-200 border-b border-t custom-text-gray">
-        Pending...
-      </div>
-    )
-  );
-};
-
-export default Contacts;
-```
-
-重新执行 `pnpm run dev`，重复刚才的操作，可以看到 Archives 列表能正常显示了：
-
-![display1](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/11/display1.png)
-
-:::info 注
-useModel API 还可以设置 Selector，只连接这个 Model 定义的状态中的局部。
-:::
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c11/hello-modern)。
-

package/zh/tutorials/first-app/c11-container/11.2-add-container.md

@@ -1,109 +0,0 @@
----
-title: 容器组件（Container）
----
-
-前两个章节中，我们把项目中的业务逻辑拆分成了两个 layer，一个是【 视图组件 】，另一个是 【 业务模块 】。
-
-【 视图组件 】 负责 UI 展示、交互等；【 业务模块 】负责实现 UI 无关的业务逻辑，专门管理状态，既可以是组件状态（局部，不唯一），也可以是应用状态（全局，唯一）。
-
-像 `components/Contacts/index.tsx` 这样使用了 `useModel` API 的组件，其实已经在**客户端应用架构**中扮演一种新的角色，负责把 View 和 Model 这两个 layer 连接起来，类似传统 MVC 架构中 Controller 的角色，也类似一种 ViewController。
-
-因为这种组件属于一种新的功能模块，在 Modern.js 里我们沿用习惯，把它们称作【 容器组件（Container）】。
-
-容器组件推荐放在专门的 `containers/` 目录里，我们执行以下命令：
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-mkdir -p src/contacts/routes/containers/
-mv src/contacts/routes/components/Contacts/index.tsx src/contacts/routes/containers/Contacts.tsx
-rm -r src/contacts/routes/components/Contacts/
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-mkdir -p src/contacts/containers/
-mv src/contacts/components/Contacts/index.tsx src/contacts/containers/Contacts.tsx
-rm -r src/contacts/components/Contacts/
-```
-
-</TabItem>
-</Tabs>
-
-修改 `containers/Contacts.tsx` 的代码：
-
-```tsx
-import Item from '../components/Item';
-import contacts from '../models/contacts';
-```
-
-修改 `page.tsx` 和 `archives/page.tsx` 的代码：
-
-```tsx
-import Contacts from './containers/Contacts';
-```
-
-重构完成，现在的项目结构是：
-
-```md
-.
-├── .eslintrc.js
-├── .gitignore
-├── .husky
-├── .npmrc
-├── .nvmrc
-├── .prettierrc
-├── .vscode
-├── README.md
-├── api
-│   └── contacts.ts
-├── modern.config.ts
-├── package.json
-├── pnpm-lock.yaml
-├── src
-│   ├── .eslintrc.js
-│   ├── contacts
-│   │   └── routes
-│   │       ├── archives
-│   │       │   └── page.tsx
-│   │       ├── components
-│   │       │   ├── Avatar
-│   │       │   │   ├── index.stories.tsx
-│   │       │   │   └── index.tsx
-│   │       │   └── Item
-│   │       │       ├── index.test.tsx
-│   │       │       └── index.tsx
-│   │       ├── containers
-│   │       │   └── Contacts.tsx
-│   │       ├── index.css
-│   │       ├── layout.tsx
-│   │       ├── models
-│   │       │   ├── contacts.test.ts
-│   │       │   └── contacts.ts
-│   │       ├── page.tsx
-│   │       └── styles
-│   │           └── utils.css
-│   ├── landing-page
-│   │   └── routes
-│   │       ├── index.css
-│   │       ├── layout.tsx
-│   │       └── page.tsx
-│   └── modern-app-env.d.ts
-└── tsconfig.json
-```
-
-`components/` 里的【 视图组件 】，都是目录形式，如 `Avatar/index.tsx`。而 `containers/` 里的【 容器组件 】，都是单文件形式，如 `contacts.tsx`。**这是我们推荐的一种最佳实践**。
-
-在​ [添加 UI 组件（Component）](../c06-css-and-component/6.1-css-in-js.md) 章节提到过，【 视图组件 】用目录形式，是因为【 视图组件 】负责实现 UI 展示和交互细节，可以演变的复杂，用目录形式，可以方便增加子文件，包括专用的资源（图片等）、专用子组件、CSS 文件等，在这个目录内部可以随意重构，只考虑最小局部。
-
-而【 容器组件 】只负责连接，是一个胶水层，复杂的业务逻辑和实现细节都交给 View 层和 Model 层去实现，【 容器组件 】自己应该保持简单清晰，不应该包含复杂实现细节，所以不应该有内部结构，采用单文件形式不但更简洁，也能起到约束作用，提醒开发者不要把容器组件写复杂。
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c11/hello-modern-2)。

package/zh/tutorials/first-app/c11-container/11.3-use-loader.md

@@ -1,63 +0,0 @@
----
-title: ​使用 Loader
----
-
-到目前为止，我们都是用 `useEffect` 来请求 BFF，加载联系人列表数据。
-
-在启用 SSR 的情况下，`useEffect` 在服务器端是不会执行的，所以 SSR 过程中不会加载数据，这种 SSR 只能渲染很有限的 UI，是低价值的。
-
-可以在当前项目中开启 [SSR](/docs/configure/app/server/ssr)，看下这种效果。
-
-```js
-export default defineConfig({
-  server: {
-    ssr: true,
-  },
-});
-```
-
-执行 `pnpm run dev`，在 devtools 的 network 面板里查看 HTML 请求的 Preview 面板，可以看到 SSR 的渲染结果只有导航栏和 Pending... 字符，并没有联系人数据：
-
-![display5](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/11/display5.png)
-
-前面提到过，应用工程里的 SSR 实现是 Serverless SSR，不仅在部署、运维环节，在开发环节对 Server 也是无感的，项目里不需要专门写服务器的实现。
-
-上述加载初始数据的业务逻辑，也不应该像传统模式一样，在客户端代码和服务器端代码中分别实现。
-
-Modern.js 提供一个叫 `useLoader` 的 hooks API，在这种场景下替代 `useEffect`，能自动在 SSR 环节做**预加载**，先获取足够的数据，再运行 app 代码渲染 HTML。
-
-同时，在 CSR 环节中，自动检查当前 loader 需要的数据，如果在 SSR 环节中已经预加载，在客户端就不再重复执行 loader，直接用现成数据；反之就在客户端执行 loader（相当于一种 fallback）。
-
-`useLoader` 的使用很简单，把当前项目中 `Contacts` 组件中的 `useEffect` 代码替换成：
-
-```js
-useLoader(
-  async () => {
-    if (!items.length && !error && !pending) {
-      return actions.load();
-    }
-    return Promise.resolve();
-  },
-  {
-    params: 'contacts',
-  },
-);
-```
-
-`useLoader` API 要求返回一个 promise，用于判断这个 loader 是否完成。第二个参数是当前 Loader 的唯一标识。
-
-同时，在文件顶部的导入 `useLoader`：
-
-```js
-import { useLoader } from '@modern-js/runtime';
-```
-
-重新执行 `pnpm run dev`，查看 `view-source:http://localhost:8080/contacts/`，或在 devtools 的 Network 面板里查看 HTML 请求的「 Preview 」，可以看到 SSR 渲染出来的 HTML 已经包含完整的 UI：
-
-![display6](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/11/display6.png)
-
-查看 `http://localhost:8080/contacts/`，可以看到首屏是没有 pending 过程的。
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c11/hello-modern-3)。

package/zh/tutorials/first-app/c11-container/11.4-testing.md

@@ -1,56 +0,0 @@
----
-title: ​测试容器组件
----
-
-跟[测试组件​​​](../c06-css-and-component/6.6-testing.md)中一样，不需要做任何配置，可以直接给Model 写测试用例。
-
-以 `containers/Contacts.tsx` 为例，我们创建对应的 `.test` 文件：
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-touch src/contacts/routes/containers/contacts.test.tsx
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-ni src/contacts/routes/containers/contacts.test.tsx
-```
-
-</TabItem>
-</Tabs>
-
-在测试用例中可以使用 Modern.js 提供的 API 进行渲染，并通过 API 返回的工具函数进行断言。
-
-测试用例文件的示例：
-
-```ts
-import { renderApp, waitFor } from '@modern-js/runtime/testing';
-import ContactContainer from './Contacts';
-
-describe('test contracts model', () => {
-  it('actions works well', async () => {
-    const { getByText } = renderApp(<ContactContainer source="items" />);
-
-    await waitFor(() => {
-      expect(getByText('Pending...')).toBeInTheDocument();
-    });
-  });
-});
-```
-
-:::info 注
-更多相关内容可以查看 [Test API](/docs/apis/app/runtime/testing/renderApp)。
-:::
-
-执行 `pnpm run test`，可以看到测试报告。
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c11/hello-modern-4)。

package/zh/tutorials/first-app/c11-container/_category_.json

@@ -1,3 +0,0 @@
-{
-  "label": "11: 添加容器组件"
-}