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

package/zh/tutorials/first-app/c05-component/5.1-use-ui-library.md

@@ -1,68 +0,0 @@
----
-title: 使用主流组件库
----
-
-上一章节中，我们学习了如何使用 ES6+ 与 TypeScript 语法编写 Modern.js 应用。
-
-这一章节中，我们继续沿用上一章节的项目代码（注意是 TS 代码，不是 ES6+ 代码），继续完善联系人列表。
-
-为了做更好的 UI 展示和交互，我们引入主流的组件库 Ant Design 来开发，使用 List 组件来代替原始的列表。
-
-先添加依赖:
-
-```bash
-pnpm add antd
-```
-
-之前章节介绍过，Modern.js 支持在项目创建后继续为项目增加功能，我们执行 `pnpm run new`，进行如下选择，开启 Less 支持。
-
-```bash
-# 启用可选功能
-  启用 Tailwind CSS 支持
-❯ 启用 Less 支持
-  启用 Sass 支持
-  ...
-```
-
-修改 `src/App.tsx`，在顶部导入组件:
-
-```js
-import { List } from 'antd';
-```
-
-修改 App 组件的实现：
-
-```ts
-function App() {
-  return (
-    <div>
-      <List
-        dataSource={mockData}
-        renderItem={({ name, email, avatar }) => (
-          <List.Item key={name}>
-            <List.Item.Meta
-              avatar={<img alt="avatar" src={avatar} width={60} height={60} />}
-              title={name}
-              description={email}
-            />
-          </List.Item>
-        )}
-      />
-    </div>
-  );
-}
-```
-
-执行 `pnpm run dev`，查看运行结果：
-
-![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/05/result.png)
-
-可以看到 Ant Design 导出的组件，已经具备了完整的样式。
-
-:::info 注
-Modern.js 会[自动按需导入 Ant Design 组件需要的 CSS](https://github.com/ant-design/babel-plugin-import)。
-:::
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c05/hello-modern)。

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

@@ -1,92 +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/App.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` 文件：
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-touch src/modern-app-env.d.ts
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```bash
-ni src/modern-app-env.d.ts
-```
-
-</TabItem>
-</Tabs>
-
-在 `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/App.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/components/Avatar
-touch src/components/Avatar/index.tsx
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-mkdir -p src/components/Avatar
-ni src/components/Avatar/index.tsx
-```
-
-</TabItem>
-</Tabs>
-
-把 `src/App.tsx` 里的 Avatar 实现删掉，改成：
-
-```js
-import Avatar from './components/Avatar';
-```
-
-`src/components/Avatar/index.tsx` 的内容：
-
-```js
-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,148 +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 支持
-  启用 Sass 支持
-  ...
-```
-
-:::info 注
-因为我们之前已经开启了 Less 支持，所以再次添加可选功能时，不再有这个选项。
-:::
-
-在 `src/App.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/components/Item
-touch src/components/Item/index.tsx
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-mkdir -p src/components/Item
-ni src/components/Item/index.tsx
-```
-
-</TabItem>
-</Tabs>
-
-修改 `src/App.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 App() {
-  return (
-    <div className="container lg mx-auto">
-      <List
-        dataSource={mockData}
-        renderItem={info => <Item key={info.name} info={info} />}
-      />
-    </div>
-  );
-}
-
-export default App;
-```
-
-在父容器的上使用了 [Utility Class](https://tailwindcss.com/docs/container) ，快速实现了最基本的 [RWD](https://tailwindcss.com/docs/responsive-design)（最大宽度、居中）。
-
-接下来实现 `src/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/styles
-touch src/styles/utils.css
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-mkdir -p src/styles
-ni src/styles/utils.css
-```
-
-</TabItem>
-</Tabs>
-
-在 `src/App.tsx` 里导入 `utils.css`：
-
-```js
-import './styles/utils.css';
-```
-
-在 `src/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/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)。
-

package/zh/tutorials/first-app/c06-css-and-component/6.4-design-system.md

@@ -1,83 +0,0 @@
----
-title: ​管理 Design System
----
-
-在前两个小节中，我们了解了 Utility Class 以及使用了 Modern.js 已经集成的 Utility Class 工具库 [Tailwind CSS](https://tailwindcss.com/)，
-默认提供的设计系统生成的样式可以满足实际开发中的部分需求。
-
-然而实际开发中，我们可能需要修改默认的设计系统规范。为此，Modern.js 提供了
-[`source.designSystem`](/docs/configure/app/source/design-system) 配置来管理项目的设计系统。
-
-## 覆盖默认配置
-
-要覆盖默认的设计系统配置，请在 `modern.config.ts` 的 `source.designSystem` 中添加要覆盖的键。
-
-```typescript title="modern.config.ts"
-export default defineConfig({
-  source: {
-    designSystem: {
-      opacity: {
-        0: '0',
-        20: '0.2',
-        40: '0.4',
-        60: '0.6',
-        80: '0.8',
-        100: '1',
-      },
-    },
-  },
-});
-```
-
-这将完全替换默认键配置，因此在上面的示例中，不会生成默认的 opacity utilities。
-
-所有未覆盖的键都将从默认主题继承，因此在上面的示例中，将保留颜色，间距，边框圆角，背景位置等内容的默认主题配置。
-
-## 扩展默认配置
-
-如果您想保留主题选项的默认值，但又要添加新值，请在 `designSystem.extend` 下添加扩展的内容。
-
-例如，如果我们想添加一个额外的断点但保留现有的断点，则可以扩展 `screens` 属性：
-
-```typescript title="modern.config.ts"
-export default defineConfig({
-  source: {
-    designSystem: {
-      opacity: {
-        0: '0',
-        20: '0.2',
-        40: '0.4',
-        60: '0.6',
-        80: '0.8',
-        100: '1',
-      },
-      extend: {
-        screens: {
-          '2xl': '1440px',
-        },
-      },
-    },
-  },
-});
-```
-
-修改 `src/Item/index.tsx` 的 button 组件代码
-
-```js
-<button
-  type="button"
-  disabled={archived}
-  className={`bg-blue-500 text-white font-bold
-    py-2 px-4 rounded-full hover:bg-blue-700 2xl:bg-red-500`}
->
-  Archive
-</button>
-```
-
-执行 `pnpm run dev` 后，增加页面宽度超过 1440px 可以看到 button 颜色变化：
-
-![design2](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result4.png)
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c06/hello-modern-4)。

package/zh/tutorials/first-app/c06-css-and-component/6.5-storybook.md

@@ -1,77 +0,0 @@
----
-title: ​用 Storybook 调试组件
----
-
-前几个小节中，我们已经开发了一个简单的 UI 组件。组件开发完后，一般我们需要对它进行调试。
-
-除了可以直接在项目中进行调试以外，我们还可以使用 [**Storybook**](https://storybook.js.org/) 进行调试。
-
-Modern.js 提供了开箱即用的 Storybook 能力，可以识别应用工程下的 Story 文件。
-
-我们执行 `pnpm run new`，启用该模式：
-
-```bash
-# 启用可选功能
-  ...
-  启用「单元测试 / 集成测试」功能
-❯ 启用「Visual Testing (Storybook)」模式
-```
-
-安装成功后，我们需要为我们的组件添加 Story 文件。
-
-:::info 补充信息
-Story 文件是指 `*.stories.[t|j]sx?` 格式的文件。
-:::
-
-这里我们为 `Avatar` 组件 添加 `src/components/Avatar/index.stories.tsx` Story 文件。
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-touch src/components/Avatar/index.stories.tsx
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-ni src/components/Avatar/index.stories.tsx
-```
-
-</TabItem>
-</Tabs>
-
-内容如下：
-
-``` javascript
-import Avatar from '.';
-
-export const DanielTaylorAvatar = () => (
-  <Avatar src="https://avatars.dicebear.com/v2/identicon/Daniel Taylor.svg" />
-);
-
-export default {
-  title: 'Avatar Demo',
-};
-```
-
-然后我们启动 Storybook 调试：
-
-``` bash
-pnpm run dev story
-```
-
-然后我们可以看到如下界面：
-
-![storybook demo](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/mwa-storybook-demo.png)
-
-如果需要配置 Storybook，则需要在 [`config/storybook/**`](/docs/apis/app/hooks/config/storybook) 目录下进行配置。
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c06/hello-modern-5)。
-