@modern-js/main-doc 0.0.0-next-20221116121040

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

@@ -0,0 +1,274 @@
+---
+title: ​完整使用 Model
+---
+
+上一章节中，我们初步引入**客户端应用架构**，从【 视图组件 】中拆分出【 业务模型（Model）】，`AllContacts` 中不再包含 UI 无关的业务逻辑实现细节，只需要使用 Model，就能实现同样的功能。
+
+这一章节中，我们要进一步利用 Model 中实现的业务逻辑，让 `AllContacts` 和  `ArchivedContacts` 都从 BFF 获取数据，实现 Archive 按钮，点击按钮能把联系人归档，只显示在 Archives 列表里，不显示在 All 列表里。
+
+先改造 `Item` 组件，增加 Archive 按钮的交互实现：
+
+```tsx title="src/contacts/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;
+```
+
+`ArchivedContacts` 和 `AllContacts` 需要共用同一套状态（联系人列表数据、联系人是否被归档），并且由于 Archives 列表和 All 列表都可能是第一屏页面（从不同 URL 访问），这两个组件都需要包含加载初始数据的逻辑（如果客户端没有联系人列表数据，就请求 BFF），所以这类两个组件公用的实现逻辑应该合并到一起：
+
+我们删除原有的两个组件，创建一个新的 `Contacts` 组件：
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+rm -r src/contacts/components/*Contacts
+mkdir -p src/contacts/components/Contacts/
+touch src/contacts/components/Contacts/index.tsx
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+rm -r src/contacts/components/*Contacts
+mkdir -p src/contacts/components/Contacts/
+ni src/contacts/components/Contacts/index.tsx
+```
+
+</TabItem>
+</Tabs>
+
+修改`components/Contacts/index.tsx` ，内容如下：
+
+```tsx title="src/contacts/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;
+```
+
+:::info 注
+由于 computed 功能还未提供，这里先在组件里将传入的数据做预处理。
+:::
+
+最后改造 `App.tsx`，利用 Contacts 实现 Archives 列表和 All 列表：
+
+```tsx title="src/contacts/App.tsx"
+import { useState } from 'react';
+import { Radio, RadioChangeEvent } from 'antd';
+import { Route, useHistory } from '@modern-js/runtime/router';
+import { Helmet } from '@modern-js/runtime/head';
+import 'tailwindcss/base.css';
+import 'tailwindcss/components.css';
+import 'tailwindcss/utilities.css';
+import './styles/utils.css';
+import Contacts from './components/Contacts';
+
+function App() {
+  const history = useHistory();
+  const [currentList, setList] = useState(history.location.pathname || '/');
+  const handleSetList = (e: RadioChangeEvent) => {
+    const { value } = e.target;
+    setList(value);
+    history.push(value);
+  };
+
+  return (
+    <div className="container lg mx-auto">
+      <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>
+      <Route path="/" exact={true}>
+        <Helmet>
+          <title>All</title>
+        </Helmet>
+        <Contacts source="items" />
+      </Route>
+      <Route path="/archives" exact={true}>
+        <Helmet>
+          <title>Archives</title>
+        </Helmet>
+        <Contacts source="archived" />
+      </Route>
+    </div>
+  );
+}
+
+export default App;
+```
+
+执行 `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` 组件，是两个各自独立的组件：
+
+```tsx title="src/contacts/App.tsx"
+<Route path="/" exact={true}>
+  <Helmet>
+    <title>All</title>
+  </Helmet>
+  <Contacts source="items" />
+</Route>
+<Route path="/archives" exact={true}>
+  <Helmet>
+    <title>Archives</title>
+  </Helmet>
+  <Contacts source="archived" />
+</Route>
+```
+
+所以它们有各自独立的内部 state，互相不共享状态，渲染 `Archives` 列表的时候，`items` 仍然是初始状态。
+
+要解决这个问题，一种方式把 `useLocalModel` 的逻辑提升到父组件里，把状态分别传给两个 `Contacts` 组件。更清晰、完善的方式，是启用全局唯一的「 应用状态 」，两个 `Contacts` 组件「 连接 」应用状态。
+
+在 Modern.js 里实现应用状态管理很简单，只需要把 `useLocalModel` 换成 `useModel`。
+
+修改 `components/Contacts/index.tsx` 的内容：
+
+
+```tsx title="src/contacts/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

@@ -0,0 +1,106 @@
+---
+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/containers/
+mv src/contacts/components/Contacts/index.tsx src/contacts/containers/Contacts.tsx
+rm -r src/contacts/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';
+```
+
+修改 `App.tsx` 的代码：
+
+```tsx
+import Contacts from './containers/Contacts';
+```
+
+重构完成，现在的项目结构是：
+
+```md
+.
+├── .vscode/
+├── api/
+│   ├── .eslintrc.json
+│   └── contacts.ts
+├── src/
+│   ├── contacts/
+│   │   ├── components/
+│   │   │   ├── Avatar/
+│   │   │   │   ├── index.stories.tsx
+│   │   │   │   └── index.tsx
+│   │   │   └── Item/
+│   │   │       ├── index.test.tsx
+│   │   │       └── index.tsx
+│   │   ├── containers/
+│   │   │   └── Contacts.tsx
+│   │   ├── models/
+│   │   │   ├── contacts.test.ts
+│   │   │   └── contacts.ts
+│   │   ├── styles/
+│   │   │   └── utils.css
+│   │   ├── App.css
+│   │   └── App.tsx
+│   ├── landing-page/
+│   │   └── pages/
+│   │       ├── comments/
+│   │       │   └── [commentTitle]/
+│   │       │       └── index.tsx
+│   │       ├── _app.tsx
+│   │       ├── docs.tsx
+│   │       └── index.tsx
+│   ├── .eslintrc.json
+│   └── modern-app-env.d.ts
+├── .editorconfig
+├── .gitignore
+├── .npmrc
+├── .nvmrc
+├── README.md
+├── package.json
+├── pnpm-lock.yaml
+└── 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

@@ -0,0 +1,61 @@
+---
+title: ​使用 Loader
+---
+
+到目前为止，我们都是用 `useEffect` 来请求 BFF，加载联系人列表数据。
+
+在启用 SSR 的情况下，`useEffect` 在服务器端是不会执行的，所以 SSR 过程中不会加载数据，这种 SSR 只能渲染很有限的 UI，是低价值的。
+
+可以在当前项目中开启 [SSR](/docs/configure/app/server/ssr)，看下这种效果。
+
+```json
+"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

@@ -0,0 +1,56 @@
+---
+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/containers/contacts.test.tsx
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+ni src/contacts/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

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

package/zh/tutorials/first-app/overview.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 0
+---
+
+# 概览
+
+import OverviewNav from '@site/src/components/OverviewNav';
+import sidebarData from '@site/plugins/overview-loader!@site/plugins/overview-data.json'
+import Link from '@docusaurus/Link';
+
+<OverviewNav cards={sidebarData.docsSidebars.tutorialsSidebar[1].items}/>

package/zh/tutorials/foundations/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "基础",
+  "position": 1,
+  "collapsed": false
+}

package/zh/tutorials/foundations/basic.md

@@ -0,0 +1,8 @@
+---
+title: JavaScript & React
+sidebar_position: 2
+---
+
+:::note Todo
+敬请期待
+:::

package/zh/tutorials/foundations/introduction.md

@@ -0,0 +1,41 @@
+---
+title: Modern.js 介绍
+sidebar_position: 1
+---
+
+欢迎来到 Modern.js 教程！
+
+阅读本栏目后，你将初步理解 Modern.js，并使用 Modern.js 创建第一个应用。
+
+:::note 关注
+加入我们的飞书群，咨询相关问题，了解最新动态。
+:::
+
+## Modern.js 是什么
+
+**Modern.js** 是基于 React 的渐进式现代 Web 开发框架。
+
+框架内置多种开箱即用的开发工具，拥有极致的构建性能，支持零配置的渲染范式切换，一体化的 API 调用。并从三种工程方案出发（应用工程方案、模块工程方案，Monorepo 工程方案），支持全链路的前端研发。
+
+Modern.js 是字节跳动的底层前端研发框架，已经直接或间接的服务上千个应用，包括中后台、PC Web、H5 等多种应用场景。框架覆盖完整的生命周期，拥有完善的插件体系，提供高度定制能力。支持通过生成器插件自定义业务线专属的工程方案，定制各种功能扩展和业务需求，帮助开发者更快速的搭建应用。
+
+## 为什么使用 Modern.js
+
+Modern.js 能为开发者提供极致的**开发体验（Development Experience）**，让应用拥有更好的**用户体验（User Experience）**。
+
+在开发 React 应用过程中，开发者通常需要去为某些功能去设计实现方案，或是使用其他的库、框架来解决这些问题。Modern.js 支持 React 应用所需要的所有配置和工具，并内置**额外的功能和优化**。开发者可以使用 React 构建应用的 UI，然后逐步采用 Modern.js 的功能来解决常见的应用需求，如路由、数据获取、状态管理等。
+
+它主要包含以下特点：
+
+- 🪜 **渐进式**：使用最精简的模板创建项目，通过生成器逐步开启插件功能，定制解决方案。
+- 🏠 **一体化**：开发与生产环境 Web Server 唯一，CSR 和 SSR 同构开发，函数即接口的 API 服务调用。
+- 📦 **开箱即用**：默认 TS 支持，内置构建、ESLint、调试工具，全功能可测试。
+- 🌏 **周边生态**：自研状态管理、微前端、模块打包、Monorepo 方案等周边需求。
+- 🕸 **多种路由模式**：包含自控路由、基于文件约定的路由（嵌套路由）、配置式路由等。
+- 🚀 **独立构建核心**：支持多种打包工具，深度优化构建产物。
+
+## 下一步
+
+如果你是前端初学者，可能会觉得这些概念有些复杂。我们提供了一些 [JavaScript 和 React](/docs/tutorials/foundations/basic) 的学习资料，你可以先对它们做些了解。
+
+如果你是有经验的开发者，希望了解如何使用 Modern.js，你可以尝试[创建第一个应用](/docs/tutorials/first-app/overview)，或是阅读[指南](/docs/guides/overview)。