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

package/zh/tutorials/first-app/c04-es6-plus-and-ts/4.2-use-typescript.md

@@ -1,135 +0,0 @@
----
-title: 使用 TypeScript 语法
----
-
-Modern.js 同样对 TypeScript 提供了一等公民、开箱即用的支持。
-
-这一小节，我们将当前为 ES6+ 语法的 Demo 修改为 TypeScript 语法。
-
-在项目根目录下执行：
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-mv src/routes/layout.jsx src/routes/layout.tsx
-mv src/routes/page.jsx src/routes/page.tsx
-mv modern.config.js modern.config.ts
-touch src/modern-app-env.d.ts
-
-pnpm add typescript @types/react @types/react-dom @types/node -D
-
-touch tsconfig.json
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```bash
-mv src/routes/layout.jsx src/routes/layout.tsx
-mv src/routes/page.jsx src/routes/page.tsx
-mv modern.config.js modern.config.ts
-ni src/modern-app-env.d.ts
-
-pnpm add typescript @types/react @types/react-dom @types/node -D
-
-ni tsconfig.json
-```
-
-</TabItem>
-</Tabs>
-
-:::info 注
-接下来所有章节的项目，都会使用 TS 来进行开发。
-:::
-
-`tsconfig.json` 内容如下：
-
-```json
-{
-  "extends": "@modern-js/tsconfig/base",
-  "compilerOptions": {
-    "declaration": false,
-    "jsx": "preserve",
-    "baseUrl": "./",
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  },
-  "include": ["src", "shared", "config"]
-}
-```
-
-`modern.config.ts` 内容修改如下：
-
-```ts
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  runtime: {
-    router: true,
-    state: true,
-  },
-});
-```
-
-`modern-app-env.d.ts` 内容如下
-
-```ts
-/// <reference types='@modern-js/app-tools/types' />
-```
-
-打开 `src/routes/page.tsx`，把代码改成以下内容：
-
-```ts
-const getAvatar = (users: Array<{ name: string; email: string }>) =>
-  users.map(user => ({
-    ...user,
-    avatar: `https://avatars.dicebear.com/v2/identicon/${user.name}.svg`,
-  }));
-
-const getMockData = () =>
-  getAvatar([
-    { name: 'Thomas', email: 'w.kccip@bllmfbgv.dm' },
-    { name: 'Chow', email: 'f.lfqljnlk@ywoefljhc.af' },
-    { name: 'Bradley', email: 'd.wfovsqyo@gpkcjwjgb.fr' },
-    { name: 'Davis', email: '"t.kqkoj@utlkwnpwk.nu' },
-  ]);
-
-function Index() {
-  return (
-    <ul>
-      {getMockData().map(({ name, avatar, email }) => (
-        <li key={name}>
-          <img src={avatar} width={60} height={60} /> ---
-          <span>{name}</span> ---
-          <span>{email}</span>
-        </li>
-      ))}
-    </ul>
-  );
-}
-
-export default Index;
-```
-
-可以看到，跟 ES6+ 的代码相比有以下不同：
-
-1. 由于 TS 还不支持 [Pipeline Operator](https://babeljs.io/docs/en/babel-plugin-proposal-pipeline-operator) 语法，需要把 mockData 的生成过程改成普通的函数调用语法。
-2. 需要声明 `getAvatar` 参数的类型。
-
-在 VS Code 里，把鼠标悬停在 `mockData` 上，可以看到它的类型已经被自动推导出来。如果把 `key={name}` 改成 `key={name * 2}`，可以看到 TS 的报错。
-
-运行 `pnpm run dev`，可以看到一样的运行结果。
-
-:::info 注
-更简单、开箱即用的方式，是在创建项目的时候，**开发语言**选择 TS，会自动生成上述样板代码，源代码文件也会自动默认采用 .ts 和 .tsx。
-:::
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c04/hello-modern-2)。
-

package/zh/tutorials/first-app/c04-es6-plus-and-ts/4.3-compatibility.md

@@ -1,67 +0,0 @@
----
-title: 客户端兼容性
----
-
-前两个小节我们学习了如何使用 ES6+ 与 TypeScript 语法来编写应用。
-
-这一小节，我们来学习如何在 Modern.js 中解决客户端兼容性的问题。
-
-在实际项目中，往往会因为需要兼容老版本浏览器，而无法利用现代浏览器的最新特性与最佳实践。
-
-Modern.js 提供了开箱即用的解决客户端兼容性的能力，支持自动 Polyfill、Browserslist 配置、差异化分发。
-
-我们首先使用微生成器开启该功能：
-
-```bash
-? 请选择你想要的操作：启用可选功能
-? 启用可选功能：启用「基于 UA 的 Polyfill」功能
-```
-
-接着我们修改 `modern.config.ts`，添加以下配置：
-
-```typescript title="modern.config.ts"
-export default defineConfig({
-  output: {
-    polyfill: 'ua',
-  },
-});
-```
-
-以上配置将会开启「 自动 Polyfill 」，Modern.js 会根据浏览器对规范的支持程度，返回不同内容的 polyfill，我们不需要再担心低版本浏览器对新版本浏览器的拖累。
-
-执行 `pnpm run dev`，可以看到浏览器中请求了当前服务上 `/__polyfill__` 这一资源，但是当前请求到的资源是空的：
-
-![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/result1.png)
-
-我们切换到 Chrome Mobile 模式，选择设备为 iPhone 5/SE，重新刷新页面，可以看到请求到了有内容的资源：
-
-![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/result2.png)
-
-:::info 注
-如果遇到无法识别的浏览器，Modern.js 将会返回全量的 polyfill。
-:::
-
-接下里我们继续修改 `modern.config.ts`：
-
-```typescript title="modern.config.ts"
-export default defineConfig({
-  output: {
-    enableModernMode: true,
-    polyfill: 'ua',
-  },
-});
-```
-
-以上配置将会开启「 差异化分发 」，在原生支持模块功能的浏览器中，Modern.js 优先使用带有 ESM 模块语法静态资源的 HTML，浏览器能够最优化的加载模块，带来更好的页面性能。
-
-执行 `pnpm run build && pnpm run start`，打开页面，可以看到已经加载了带有 `-es6` 后缀的资源文件：
-
-![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/result3.png)
-
-:::info 注
-更多相关内容可以查看 [**客户端兼容性**](/docs/guides/advanced-features/compatibility)。
-:::
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c04/hello-modern-3)。

package/zh/tutorials/first-app/c04-es6-plus-and-ts/_category_.json

@@ -1,3 +0,0 @@
-{
-  "label": "4: 写 JS 代码"
-}

package/zh/tutorials/first-app/c05-component/5.2-use-standalone-component.md

@@ -1,72 +0,0 @@
----
-title: 使用独立开源组件
----
-
-上一小节我们使用 Ant Design 组件库中的组件来实现列表。
-
-这一小节我们用独立开源组件来实现联系人的操作按钮。
-
-以按钮库 [Ladda](https://lab.hakim.se/ladda/) 的 [React 实现](https://www.npmjs.com/package/react-ladda) 为例，先添加依赖：
-
-```bash
-pnpm add react-ladda ladda
-```
-
-在 `src/routes/page.tsx` 里导入组件，同时手动导入需要的 CSS：
-
-```ts
-import LaddaButton, { S, SLIDE_UP } from 'react-ladda';
-import 'ladda/dist/ladda.min.css';
-```
-
-修改 `List.Item` 组件的调用代码，添加 actions：
-
-```ts
-<List.Item
-  key={name}
-  actions={[
-    <LaddaButton
-      key={email}
-      loading={false}
-      data-size={S}
-      data-style={SLIDE_UP}
-      data-spinner-size={20}
-      data-spinner-color="#ddd"
-      data-spinner-lines={8}>
-      Call
-    </LaddaButton>
-  ]}>
-  <List.Item.Meta
-    avatar={<img alt="avatar" src={avatar} width={60} height={60} />}
-    title={name}
-    description={email}
-  />
-</List.Item>
-```
-
-`react-ladda` 组件库没有提供 types 文件，我们添加一个 `.d.ts` 文件：
-
-在 `modern-app-env.d.ts` 中添加模块定义：
-
-```ts
-declare module 'react-ladda' {
-  const LaddaButton: any;
-  export default LaddaButton;
-  export const S: any;
-  export const SLIDE_UP: any;
-}
-```
-
-执行 `pnpm run dev`，查看运行结果：
-
-![result1](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/05/result1.png)
-
-:::info 注
-CSS 文件会自动经过 Modern.js 内置的 [PostCSS](/docs/guides/basic-features/css/postcss) 的处理，能够满足大多数项目的样式开发需求。
-
-Modern.js 也支持导入 SCSS、Less 文件。此外，有的组件使用 CSS in JS，不需要额外导入样式文件，下一节会有相关介绍。
-:::
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c05/hello-modern-2)。

package/zh/tutorials/first-app/c05-component/_category_.json

@@ -1,3 +0,0 @@
-{
-  "label": "5: 使用 UI 组件"
-}

package/zh/tutorials/first-app/c06-css-and-component/6.1-css-in-js.md

@@ -1,110 +0,0 @@
----
-title: 用 CSS in JS 写组件
----
-
-上一章节中，我们学习了如何使用 UI 组件库、标准三方库中的组件。
-
-这一章节中，我们将学习如何实现 UI 组件。
-
-首先我们希望自己控制联系人头像的展示，实现这种设计稿：
-
-![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/design1.png)
-
-假设没有现成的组件可以实现，那就需要自己写些 CSS 了，传统上，我们有如下选择：
-
-1. 直接在元素的 style 属性上写样式，缺点是：不方便维护，UI 视觉上的细节也会跟 UI 结构上的细节和业务逻辑混在一起。
-2. 在 CSS 代码里用选择器找到这个头像元素，写样式，避免了 1 的缺点，但新的缺点是：不方便在其他有头像出现的地方复用，集中维护，做到 [DRY](https://en.wikipedia.org/wiki/Don't_repeat_yourself)。
-3. 在 CSS 代码里写一个 classname，封装这个样式，避免了 2 的缺点，但新的缺点是：需要考虑命名问题，避免在全局命名空间下重名，可能要用到 [BEM](http://getbem.com/) 之类的规范。
-4. 用 CSS Modules 技术，让 CSS 文件和其中的 classname 变得【 模块化 】，避免了 3 的缺点。
-
-Modern.js 开箱即用的支持 CSS Modules，但我们更推荐优先采用 CSS Modules 的继承者、在【 模块化 】上更进一步的 [styled-components](https://styled-components.com/)，来实现类似的需求。
-
-Modern.js 同样开箱即用的支持 styled-components，既不需要安装依赖，也不需要做任何配置。
-
-在 `src/routes/page.tsx` 里修改顶部的代码：
-
-```js
-import styled from '@modern-js/runtime/styled';
-```
-
-添加以下代码：
-
-```js
-const Avatar = styled.img`
-  width: 50px;
-  height: 50px;
-  border: 4px solid #0ef;
-  border-radius: 50%;
-`;
-```
-
-修改 `List.Item.Meta` 的代码：
-
-```tsx
-<List.Item.Meta
-  avatar={<Avatar src={avatar} />}
-  title={name}
-  description={email}
-/>
-```
-
-执行 `pnpm run dev`，可以看到预期的运行结果：
-
-![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result1.png)
-
-接下来我们做一点重构，为了增强可读性，让代码更容易维护，可以把 Avatar 组件拆分出去
-
-在终端执行以下命令：
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-mkdir -p src/routes/components/Avatar
-touch src/routes/components/Avatar/index.tsx
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-mkdir -p src/routes/components/Avatar
-ni src/routes/components/Avatar/index.tsx
-```
-
-</TabItem>
-</Tabs>
-
-把 `src/routes/page.tsx` 里的 Avatar 实现删掉，改成：
-
-```ts
-import Avatar from './components/Avatar';
-```
-
-`src/routes/components/Avatar/index.tsx` 的内容：
-
-```ts
-import styled from '@modern-js/runtime/styled';
-
-const Avatar = styled.img`
-  width: 50px;
-  height: 50px;
-  border: 4px solid #0ef;
-  border-radius: 50%;
-`;
-
-export default Avatar;
-```
-
-执行 `pnpm run dev`，运行结果应该是一样的。
-
-:::info 注
-采用目录形式（Avatar/index.tsx）而不是单文件形式（Avatar.tsx）的原因是，之后可以方便在目录内部增加子文件，包括专用的资源（图片等）、专用子组件、CSS 文件等，在这个**黑盒**内部可以随意重构，只考虑**最小局部**。
-:::
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c06/hello-modern)。

package/zh/tutorials/first-app/c06-css-and-component/6.2-utility-class.md

@@ -1,143 +0,0 @@
----
-title: ​​用 Utility Class 写组件
----
-
-上一小节我们学习了如何使用 style-components 实现 `Avatar` 组件。
-
-但当前的 UI 仍然不能让人满意，缺乏专业感，例如列表项内部的布局有点粗糙，很多地方没对齐。
-
-本小节中，我们自己来实现一个更好的 `Item` 组件，实现这样的设计稿：
-
-![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/design2.png)
-
-这次要实现的 UI 更复杂，有内部结构，但另一方面，并没有 `Avatar` 组件的**很粗的亮蓝色边框**这样很特殊的 UI，都是很常规的水平垂直布局、居中、字体样式等。
-
-这种情况下，其实根本没必要写 CSS，有更高效的、跟 styled-components 互补的实现方式：Utility Class。
-
-Modern.js 集成了主流、轻量、通用的 Utility Class 工具库 [Tailwind CSS](https://tailwindcss.com/)。
-
-执行 `pnpm run new`，进行如下选择，开启 Tailwind CSS：
-
-```bash
-# 启用可选功能
-❯ 启用 Tailwind CSS 支持
-  ...
-```
-
-在 `src/routes/page.tsx` 顶部引入 Tailwind CSS 的 css 文件，就可以开始快速实现专业的 UI：
-
-```js
-import 'tailwindcss/base.css';
-import 'tailwindcss/components.css';
-import 'tailwindcss/utilities.css';
-```
-
-先创建 Item 组件：
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-mkdir -p src/routes/components/Item
-touch src/routes/components/Item/index.tsx
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-mkdir -p src/routes/components/Item
-ni src/routes/components/Item/index.tsx
-```
-
-</TabItem>
-</Tabs>
-
-修改 `src/routes/page.tsx`，把 `List` 的 `render` 实现交给 `Item` 组件：
-
-```js
-import { List } from 'antd';
-import 'tailwindcss/base.css';
-import 'tailwindcss/components.css';
-import 'tailwindcss/utilities.css';
-import Item from './components/Item';
-
-const getAvatar = (users: Array<{ name: string; email: string }>) =>
-  users.map(user => ({
-    ...user,
-    avatar: `https://avatars.dicebear.com/v2/identicon/${user.name}.svg`,
-  }));
-
-const mockData = getAvatar([
-  { name: 'Thomas', email: 'w.kccip@bllmfbgv.dm' },
-  { name: 'Chow', email: 'f.lfqljnlk@ywoefljhc.af' },
-  { name: 'Bradley', email: 'd.wfovsqyo@gpkcjwjgb.fr' },
-  { name: 'Davis', email: '"t.kqkoj@utlkwnpwk.nu' },
-]);
-
-function Index() {
-  return (
-    <div className="container lg mx-auto">
-      <List
-        dataSource={mockData}
-        renderItem={info => <Item key={info.name} info={info} />}
-      />
-    </div>
-  );
-}
-
-export default Index;
-```
-
-在父容器的上使用了 [Utility Class](https://tailwindcss.com/docs/container) ，快速实现了最基本的 [RWD](https://tailwindcss.com/docs/responsive-design)（最大宽度、居中）。
-
-接下来实现 `src/routes/components/Item/index.tsx`：
-
-```tsx
-import Avatar from '../Avatar';
-
-type InfoProps = {
-  avatar: string;
-  name: string;
-  email: string;
-  archived?: boolean;
-};
-
-const Item = ({ info }: { info: InfoProps }) => {
-  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 flex-1 flex justify-between">
-        <div className="flex-1">
-          <p>{name}</p>
-          <p>{email}</p>
-        </div>
-        <button
-          type="button"
-          disabled={archived}
-          className={`bg-blue-500  text-white font-bold
-            py-2 px-4 rounded-full hover:bg-blue-700`}>
-          Archive
-        </button>
-      </div>
-    </div>
-  );
-};
-
-export default Item;
-```
-
-执行 `pnpm run dev`，可以看到预期的运行结果：
-
-![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result2.png)
-
-这一小节中，我们只使用了少量 Utility Class，比如 [Flex](https://tailwindcss.com/docs/display/)、[Padding](https://tailwindcss.com/docs/padding/)、[Margin](https://tailwindcss.com/docs/margin/)、[Text](https://tailwindcss.com/docs/text-color/)、[Font](https://tailwindcss.com/docs/font-weight/)、[Border](https://tailwindcss.com/docs/border-width)，不写一行 CSS 就实现了有【 设计系统（Design System）】的、符合设计稿的专业 UI。
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c06/hello-modern-2)。
-

package/zh/tutorials/first-app/c06-css-and-component/6.3-postcss.md

@@ -1,84 +0,0 @@
----
-title: ​​添加新的 Utility Class
----
-
-上一小节，我们学习了如何使用通用的 Utility Class 工具库.
-
-我们不但可以自己写组件，也可以自己实现新的 Utility Class，方便在代码间复用。
-
-Utility Class 本身也是一种**面向组件**的技术（将不同 class 用在一个组件上，等价于给这个组件设置了一些来自基类的属性），但 Utility Class 的 classname 是全局的（因为要用在任意组件/元素上），很适合用独立 CSS 文件来实现。
-
-创建一个新的 CSS 文件：
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-mkdir -p src/routes/styles
-touch src/routes/styles/utils.css
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-mkdir -p src/routes/styles
-ni src/routes/styles/utils.css
-```
-
-</TabItem>
-</Tabs>
-
-在 `src/routes/page.tsx` 里导入 `utils.css`：
-
-```js
-import './styles/utils.css';
-```
-
-在 `src/routes/styles/utils.css` 里实现一个叫作 `custom-text-gray` 的 Utility Class。
-
-```css
-:root {
-  --custom-text-color:rgb(113, 128, 150);
-}
-
-.custom-text-gray {
-  color: var(--custom-text-color);
-}
-```
-
-:::info 注
-Modern.js 集成了 [PostCSS](/docs/guides/basic-features/css/postcss)，支持现代 CSS 语法特性，比如 [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*)。
-:::
-
-在 `src/routes/components/Item/index.tsx` 里使用，把：
-
-```js
-<div className="ml-4 flex-1 flex justify-between">
-```
-
-改成：
-
-```js
-<div className="ml-4 custom-text-gray flex-1 flex justify-between">
-```
-
-执行 `pnpm run dev`，可以看到字体颜色改变了：
-
-![design2](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result3.png)
-
-:::info 注
-此处只是为了演示 Utility Class 用法。真实项目中，在有 Tailwind CSS 的情况下，这种 Utility Class 没什么价值，应该通过配置 Design System 的 [**theme**](https://tailwindcss.com/docs/customizing-colors) 来增加字体颜色。
-
-`utils.css` 也可以写成 `utils.scss` 或 `utils.less`，Modern.js 对 SCSS 和 Less 同样提供开箱即用的支持。
-
-不过在 PostCSS 的支持下，现代 CSS 应该足以满足这些开发需求，性能相较于预处理器也更好，建议优先用 .css 文件。
-:::
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c06/hello-modern-3)。
-