mirror of
https://gitee.com/ant-design/ant-design.git
synced 2024-11-30 02:59:04 +08:00
docs: fix minor errors and improve readability (#45565)
* docs: improve readability in use-with-umi.zh-CN.md Signed-off-by: Tao Zhou <taozhou@umich.edu> * docs: improve readability in introduce.zh-CN.md Signed-off-by: Tao Zhou <taozhou@umich.edu> * docs: improve readability in getting-started.zh-CN.md Signed-off-by: Tao Zhou <taozhou@umich.edu> * docs: fix typos in customize-theme.zh-CN.md Signed-off-by: Tao Zhou <taozhou@umich.edu> * docs: improve readability in compatible-style.zh-CN.md Signed-off-by: Tao Zhou <taozhou@umich.edu> * docs: improve readability in contributing.zh-CN.md Signed-off-by: Tao Zhou <taozhou@umich.edu> --------- Signed-off-by: Tao Zhou <taozhou@umich.edu>
This commit is contained in:
Tao Zhou
GitHub
parent
8c45c73222
commit
a559a90049
@ -13,7 +13,7 @@ Ant Design 支持最近 2 个版本的现代浏览器。如果你需要兼容旧
|
||||
|
||||
## `:where` 选择器
|
||||
|
||||
Ant Design 的 CSS-in-JS 默认通过 `:where` 选择器降低 CSS Selector 优先级，以减少用户升级时额外调整自定义样式成本，不过 `:where` 语法的[兼容性](https://developer.mozilla.org/en-US/docs/Web/CSS/:where#browser_compatibility)在低版本浏览器比较差。在某些场景下你如果需要支持的旧版浏览器（或者如 TailwindCSS 优先级冲突），你可以使用 `@ant-design/cssinjs` 取消默认的降权操作（请注意版本保持与 antd 一致）：
|
||||
Ant Design 的 CSS-in-JS 默认通过 `:where` 选择器降低 CSS Selector 优先级，以减少用户升级时额外调整自定义样式的成本，不过 `:where` 语法的[兼容性](https://developer.mozilla.org/en-US/docs/Web/CSS/:where#browser_compatibility)在低版本浏览器比较差。在某些场景下你如果需要支持旧版浏览器（或者如 TailwindCSS 优先级冲突），你可以使用 `@ant-design/cssinjs` 取消默认的降权操作（请注意版本保持与 antd 一致）：
|
||||
|
||||
```tsx
|
||||
import { StyleProvider } from '@ant-design/cssinjs';
|
||||
|
||||
@ -6,7 +6,7 @@ title: 贡献指南
|
||||
toc: false
|
||||
---
|
||||
|
||||
这篇指南会指导你如何为 Ant Design 贡献一份自己的力量，请在你要提 issue 或者 pull request 之前花几分钟来阅读一遍这篇指南。
|
||||
这篇指南会指导你如何为 Ant Design 贡献自己的一份力量，请你在提 issue 或者 pull request 之前花几分钟来阅读一遍这篇指南。
|
||||
|
||||
## 行为准则
|
||||
|
||||
@ -18,11 +18,11 @@ toc: false
|
||||
|
||||
## 分支管理
|
||||
|
||||
基于我们的 [发布周期](/changelog)，我们长期维护两个分支 `master` 和 `feature`。如果你要修一个 bug，那么请发 pull request 到 `master`，我们会每周从 master 发布一个 patch 版本；如果你要提一个增加新功能的 pull request，那么请基于 `feature` 分支来做，每月末我们会合并 feature 到 master，并发布一个包含新特性的 minor 版本。
|
||||
基于我们的 [发布周期](/changelog)，我们长期维护两个分支 `master` 和 `feature`。如果你要修一个 bug，那么请发 pull request 到 `master`，每周我们会从 master 发布一个 patch 版本；如果你要提一个增加新功能的 pull request，那么请基于 `feature` 分支来做，每月末我们会合并 feature 到 master，并发布一个包含新特性的 minor 版本。
|
||||
|
||||
## Bugs
|
||||
|
||||
我们使用 [GitHub Issues](https://github.com/ant-design/ant-design/issues) 来做 bug 追踪。 如果你想要你发现的 bug 被快速解决，最好的办法就是通过我们提供的 [issue 小助手](http://new-issue.ant.design) 来提 issue。并且能使用这个 [模板](https://u.ant.design/codesandbox-repro) 来提供重现。
|
||||
我们使用 [GitHub Issues](https://github.com/ant-design/ant-design/issues) 来做 bug 追踪。 如果你想要你发现的 bug 被快速解决，最好的办法就是通过我们提供的 [issue 小助手](http://new-issue.ant.design) 来提 issue，并且能使用这个 [模板](https://u.ant.design/codesandbox-repro) 来提供重现。
|
||||
|
||||
在你报告一个 bug 之前，请先确保已经搜索过已有的 issue 和阅读了我们的 [常见问题](/docs/react/faq)。
|
||||
|
||||
@ -52,20 +52,20 @@ Ant Design 团队会关注所有的 pull request，我们会 review 以及合并
|
||||
|
||||
1. 基于 [正确的分支](#分支管理) 做修改。
|
||||
2. 在项目根目录下运行了 `npm install`。
|
||||
3. 如果你修复了一个 bug 或者新增了一个功能，请确保写了相应的测试，这很重要。
|
||||
4. 确认所有的测试都是通过的 `npm run test`。 小贴士：开发过程中可以用 `npm test -- --watch TestName` 来运行指定的测试。
|
||||
3. 如果你修复了一个 bug 或者新增了一个功能，请确保编写了相应的测试，这很重要。
|
||||
4. 确认所有的测试都通过了 `npm run test`。小贴士：开发过程中可以用 `npm test -- --watch TestName` 来运行指定的测试。
|
||||
5. 运行 `npm test -- -u` 来更新 [jest snapshot](https://jestjs.io/zh-Hans/docs/snapshot-testing) 并且把这些更新也提交上来（如果有的话）。
|
||||
6. 确认所有的 UI 改动通过 `npm run test-image`，可以运行 `npm run test-image -- -u` 更新 UI 快照并且把这些更新也提交上来（如果有的话），**UI 测试基于 [Docker](https://docs.docker.com/get-docker/)，根据平台下载对应的安装程序。**
|
||||
7. 确保你的代码通过了 lint 检查 `npm run lint`. 小贴士: Lint 会在你 `git commit` 的时候自动运行（通过[Git Hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks)）。
|
||||
7. 确保你的代码通过了 lint 检查 `npm run lint`。小贴士: Lint 会在你 `git commit` 的时候自动运行（通过[Git Hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks)）。
|
||||
8. 最后请确保所有 GitHub CI 检查通过，如果失败，可点击 `detail` 进入详情查看原因。
|
||||
|
||||
给 [react-component](https://github.com/react-component/) 发送 pull request：
|
||||
|
||||
由于 antd 的大部分组件都是基于 react-component 的，所以有时候你可能需要给相应的 react-component 仓库发送 pull request。如果你是修复了某个 bug，那么我们在合并你的修改后会尽快发布一个 patch 版本，然后你只要重新安装你的依赖就可以使用新发布的版本了。如果你的 pull request 是新增了某个功能，那么在你的修改合并并且发布版本后，你还需要发送一个 pull request 到 [Ant Design](https://github.com/ant-design/ant-design/) 来升级相应的依赖、文档以及 TypeScript 的类型定义。
|
||||
由于 antd 的大部分组件都是基于 react-component 的，所以有时候你需要给相应的 react-component 仓库发送 pull request。如果你修复了某个 bug，那么我们在合并你的修改后会尽快发布一个 patch 版本，然后你只要重新安装你的依赖就可以使用新发布的版本了。如果你的 pull request 是新增了某个功能，那么在你的修改合并并且发布版本后，你还需要发送一个 pull request 到 [Ant Design](https://github.com/ant-design/ant-design/) 来升级相应的依赖、文档以及 TypeScript 的类型定义。
|
||||
|
||||
## 开发流程
|
||||
|
||||
推荐使用 `npm` 或 `yarn` 作为包管理工具
|
||||
推荐使用 `npm` 或 `yarn` 作为包管理工具。
|
||||
|
||||
在你 clone 了 antd 的代码并且使用
|
||||
|
||||
@ -85,7 +85,7 @@ Ant Design 团队会关注所有的 pull request，我们会 review 以及合并
|
||||
|
||||
### 运行测试用例
|
||||
|
||||
运行测试。(在运行测试前请确保 `NODE_ENV` 环境变量没有被设定，否则可能会引发一些问题)
|
||||
运行测试。（在运行测试前请确保 `NODE_ENV` 环境变量没有被设定，否则可能会引发一些问题）
|
||||
|
||||
<InstallDependencies npm='$ npm test' yarn='$ yarn test'></InstallDependencies>
|
||||
|
||||
@ -103,12 +103,12 @@ Ant Design 团队会关注所有的 pull request，我们会 review 以及合并
|
||||
|
||||
## 配套开发工具
|
||||
|
||||
- CSS in JS 样式提示插件：https://marketplace.visualstudio.com/items?itemName=shezhangzhang.antd-design-token
|
||||
- CSS-in-JS 样式提示插件：https://marketplace.visualstudio.com/items?itemName=shezhangzhang.antd-design-token
|
||||
- 组件属性提示插件：https://github.com/fi3ework/vscode-antd-rush
|
||||
|
||||
## 加入社区
|
||||
|
||||
如果你贡献度足够活跃，希望和 Ant Design 团队一起参与维护工作，你可以[申请成为社区协作者](https://github.com/ant-design/ant-design/wiki/Collaborators#how-to-apply-for-being-a-collaborator)。
|
||||
如果你的贡献度足够高，并且希望和 Ant Design 团队一起参与维护工作，你可以[申请成为社区协作者](https://github.com/ant-design/ant-design/wiki/Collaborators#how-to-apply-for-being-a-collaborator)。
|
||||
|
||||
你还可以参考下面三篇社区成员写的贡献指南，一步一步成为 antd 的贡献者吧：
|
||||
|
||||
|
||||
@ -18,7 +18,7 @@ Ant Design 设计规范和技术上支持灵活的样式定制，以满足业务
|
||||
|
||||
## 配置主题
|
||||
|
||||
在 5.0 版本中我们把影响主题的最小元素称为 **Design Token**。通过修改 Design Token，我们可以呈现出各种各样的主题或者组件。通过在 `ConfigProvider` 中传入 `theme` 属性，可以配置主题。在升级 v5 后，将默认使用 v5 的主题.
|
||||
在 5.0 版本中我们把影响主题的最小元素称为 **Design Token**。通过修改 Design Token，我们可以呈现出各种各样的主题或者组件。通过在 `ConfigProvider` 中传入 `theme` 属性，可以配置主题。在升级 v5 后，将默认使用 v5 的主题。
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
:::warning
|
||||
@ -30,7 +30,7 @@ Ant Design 设计规范和技术上支持灵活的样式定制，以满足业务
|
||||
|
||||
### 修改主题变量
|
||||
|
||||
通过 `theme` 中的 `token` 属性，可以修改一些主题变量。部分主题变量会引起其他主题变量的变化，我们把这些主题变量成为 Seed Token。
|
||||
通过 `theme` 中的 `token` 属性，可以修改一些主题变量。部分主题变量会引起其他主题变量的变化，我们把这些主题变量称为 Seed Token。
|
||||
|
||||
```sandpack
|
||||
const sandpackConfig = {
|
||||
@ -377,7 +377,7 @@ createRoot(document.getElementById('#app')).render(
|
||||
|
||||
我们提供了帮助用户调试主题的工具：[主题编辑器](/theme-editor-cn)
|
||||
|
||||
你可以使用此工具自由地修改 Design Token，以达到您对主题的期望。
|
||||
你可以使用此工具自由地修改 Design Token，以达到你对主题的期望。
|
||||
|
||||
## 基本概念
|
||||
|
||||
|
||||
@ -109,7 +109,7 @@ createRoot(document.getElementById('root')).render(<App />);
|
||||
|
||||
### 4. 下一步
|
||||
|
||||
实际项目开发中，你会需要构建、调试、代理、打包部署等一系列工程化的需求。您可以阅读后面的文档或者使用以下脚手架和范例：
|
||||
在实际项目开发中，你会遇到构建、调试、代理、打包部署等一系列工程化的需求。你可以阅读后面的文档或者使用以下脚手架和范例：
|
||||
|
||||
- [Ant Design Pro](https://pro.ant.design/)
|
||||
- [create-next-app](https://github.com/ant-design/ant-design-examples/tree/main/examples/with-nextjs-inline-style)
|
||||
|
||||
@ -81,7 +81,7 @@ export default App;
|
||||
|
||||
### TypeScript
|
||||
|
||||
`antd` 使用 TypeScript 进行书写并提供了完整的定义文件。（不要引用 `@types/antd`）。
|
||||
`antd` 使用 TypeScript 进行书写并提供了完整的定义文件（不要引用 `@types/antd`）。
|
||||
|
||||
## 链接
|
||||
|
||||
@ -124,7 +124,7 @@ export default App;
|
||||
|
||||
## 如何贡献
|
||||
|
||||
在任何形式的参与前，请先阅读 [贡献者文档](https://github.com/ant-design/ant-design/blob/master/.github/CONTRIBUTING.md)。如果你希望参与贡献，欢迎 [Pull Request](https://github.com/ant-design/ant-design/pulls)，或给我们 [报告 Bug](http://new-issue.ant.design/)。
|
||||
在任何形式的参与前，请先阅读 [贡献者文档](https://github.com/ant-design/ant-design/blob/master/.github/CONTRIBUTING.md)。如果你希望参与贡献，欢迎提交 [Pull Request](https://github.com/ant-design/ant-design/pulls)，或给我们 [报告 Bug](http://new-issue.ant.design/)。
|
||||
|
||||
> 强烈推荐阅读 [《提问的智慧》](https://github.com/ryanhanwu/How-To-Ask-Questions-The-Smart-Way)、[《如何向开源社区提问题》](https://github.com/seajs/seajs/issues/545) 和 [《如何有效地报告 Bug》](http://www.chiark.greenend.org.uk/%7Esgtatham/bugs-cn.html)、[《如何向开源项目提交无法解答的问题》](https://zhuanlan.zhihu.com/p/25795393)，更好的问题更容易获得帮助。
|
||||
|
||||
@ -137,5 +137,5 @@ export default App;
|
||||
通过 Stack Overflow 或者 Segment Fault 提问时，建议加上 `antd` 标签。
|
||||
|
||||
1. [GitHub Discussions](https://github.com/ant-design/ant-design/discussions)
|
||||
2. [<img alt="Stack Overflow" src="https://cdn.sstatic.net/Sites/stackoverflow/company/img/logos/so/so-logo.svg?v=2bb144720a66" width="140" />](http://stackoverflow.com/questions/tagged/antd)(English)
|
||||
3. [<img alt="Segment Fault" src="https://gw.alipayobjects.com/zos/rmsportal/hfYFfCvHTQTUKntlJbMF.svg" width="100" />](https://segmentfault.com/t/antd)(中文)
|
||||
2. [<img alt="Stack Overflow" src="https://cdn.sstatic.net/Sites/stackoverflow/company/img/logos/so/so-logo.svg?v=2bb144720a66" width="140" />](http://stackoverflow.com/questions/tagged/antd) (English)
|
||||
3. [<img alt="Segment Fault" src="https://gw.alipayobjects.com/zos/rmsportal/hfYFfCvHTQTUKntlJbMF.svg" width="100" />](https://segmentfault.com/t/antd)（中文）
|
||||
|
||||
@ -5,9 +5,9 @@ order: 2
|
||||
title: 在 Umi 中使用
|
||||
---
|
||||
|
||||
在真实项目开发中，除了 Ant Design 这样的 UI 库，你可能会还会需要构建工具、路由方案、CSS 方案、数据流方案、请求库和请求方案、国际化方案、权限方案、Icons 方案，等等，才能完成一个完整的项目。我们基于业务场景的场景，推出了基于 React 的企业级应用框架 [Umi](https://umijs.org/)，推荐你在项目中使用。
|
||||
在真实项目开发中，除了 Ant Design 这样的 UI 库，你可能会还会需要构建工具、路由方案、CSS 方案、数据流方案、请求库和请求方案、国际化方案、权限方案、Icons 方案等等，才能完成一个完整的项目。我们基于业务场景，推出了基于 React 的企业级应用框架 [Umi](https://umijs.org/)，推荐你在项目中使用。
|
||||
|
||||
Umi，中文发音为「乌米」，是可扩展的企业级前端应用框架，也是蚂蚁集团的底层前端框架，已直接或间接地服务了 10000+ 应用。Umi 以路由为基础的，同时支持配置式路由和约定式路由，保证路由的功能完备，并以此进行功能扩展。然后配以生命周期完善的插件体系，覆盖从源码到构建产物的每个生命周期，支持各种功能扩展和业务需求。
|
||||
Umi，中文发音为「乌米」，是可扩展的企业级前端应用框架，也是蚂蚁集团的底层前端框架，已直接或间接地服务了 10000+ 应用。Umi 以路由为基础，同时支持配置式路由和约定式路由，保证路由的功能完备，并以此进行功能扩展。然后配以生命周期完善的插件体系，覆盖从源码到构建产物的每个生命周期，支持各种功能扩展和业务需求。
|
||||
|
||||
本文会引导你使用 Umi、Ant Design 和 [Ant Design Pro](https://pro.ant.design/) 从 0 开始创建一个简单应用。
|
||||
|
||||
@ -20,7 +20,7 @@ $ mkdir myapp && cd myapp
|
||||
$ pnpm create umi
|
||||
```
|
||||
|
||||
> 如果你使用 npm，可执行 `npm create umi`，效果一致；如果你使用 yarn，可执行 `yarn create umi`，效果也一致；如果你使用 bun，那说明你是个非常潮的人，可执行 `bunx create-umi`（注意，create 和 umi 之间有个 `-`）。
|
||||
> 如果你使用 npm，可执行 `npm create umi`，效果一致；如果你使用 yarn，可执行 `yarn create umi`，效果也一致；如果你使用 bun，那说明你是个非常潮的人，可执行 `bunx create-umi`（注意，`create` 和 `umi` 之间有个 `-`）。
|
||||
|
||||
这里选「Simple App」，因为我们要从 “0” 开始。
|
||||
|
||||
@ -50,7 +50,7 @@ $ pnpm create umi
|
||||
❯ taobao
|
||||
```
|
||||
|
||||
然后工具会自动安装依赖，并执行 umi 的初始化脚本。
|
||||
然后工具会自动安装依赖，并执行 Umi 的初始化脚本。
|
||||
|
||||
在启动项目之前，我们再安装一些本教程会用到的依赖。
|
||||
|
||||
@ -76,7 +76,7 @@ ready - ║ > Network: http://*********:8000 ║
|
||||
╚════════════════════════════════════════════════════╝
|
||||
```
|
||||
|
||||
跟着提示点击命令行里的 Url，会自动打开浏览器。如果顺利，你会看到如下界面。
|
||||
跟着提示点击命令行里的 url，会自动打开浏览器。如果顺利，你会看到如下界面。
|
||||
|
||||
|
||||
|
||||
@ -126,7 +126,7 @@ export default defineConfig({
|
||||
|
||||
## 实现 Product UI 组件
|
||||
|
||||
随着应用的发展，你会需要在多个页面分享 UI 元素 (或在一个页面使用多次)，在 Umi 里你可以把这部分抽成 component 。我们来编写一个 ProductList component，这样就能在不同的地方显示产品列表了。
|
||||
随着应用的发展，你会需要在多个页面分享 UI 元素（或在一个页面使用多次），在 Umi 里你可以把这部分抽成 component 。我们来编写一个 ProductList 组件，这样就能在不同的地方显示产品列表了。
|
||||
|
||||
新建 `src/components/ProductList.tsx` 文件，内容如下。
|
||||
|
||||
@ -162,7 +162,7 @@ export default ProductList;
|
||||
|
||||
## 准备 Mock 数据
|
||||
|
||||
假设我们已经和后端约定好了 API 接口，那现在就可以使用 Mock 数据来在本地模拟出 API 应该要返回的数据，这样一来前后端开发就可以同时进行，不会因为后端 API 还在开发而导致前端的工作被阻塞。Umi 提供了开箱即用的 [Mock 功能](https://umijs.org/docs/guides/mock)，能够用方便简单的方式来完成 Mock 数据的设置。
|
||||
假设我们已经和后端约定好了 API 接口，那现在就可以使用 Mock 数据来在本地模拟出 API 应该返回的数据，这样一来前后端开发就可以同时进行，不会因为后端 API 还在开发而导致前端的工作被阻塞。Umi 提供了开箱即用的 [Mock 功能](https://umijs.org/docs/guides/mock)，能够用方便简单的方式来完成 Mock 数据的设置。
|
||||
|
||||
创建 `mock` 目录，并在此目录下新增 `products.ts` 文件，内容如下。
|
||||
|
||||
@ -265,7 +265,7 @@ export default function Page() {
|
||||
|
||||
## ProLayout
|
||||
|
||||
一个标准的中后台页面，一般都需要一个布局，这个布局很多时候都是高度雷同的，[ProLayout](https://procomponents.ant.design/components/layout/) 封装了常用的菜单，面包屑，页头等功能，提供了一个不依赖的框架且开箱即用的高级布局组件。并且支持 `side`, `mix`, `top` 三种模式，更是内置了菜单选中，菜单生成面包屑，自动设置页面标题的逻辑。
|
||||
一个标准的中后台页面，一般都需要一个布局，这个布局很多时候都是高度雷同的，[ProLayout](https://procomponents.ant.design/components/layout/) 封装了常用的菜单、面包屑、页头等功能，提供了一个不依赖的框架且开箱即用的高级布局组件。并且支持 `side`, `mix`, `top` 三种模式，更是内置了菜单选中、菜单生成面包屑、自动设置页面标题的逻辑。
|
||||
|
||||
先修改配置，为每个路由新增 name 字段，用于给 ProLayout 做菜单渲染使用。
|
||||
|
||||
@ -321,9 +321,9 @@ export default function Layout() {
|
||||
}
|
||||
```
|
||||
|
||||
这里先用 umi 的 `useAppData` 拿到全局客户端路由 `clientRoutes`，这是一份嵌套结构的路由表，我们把 `clientRoutes[0]` 传给 ProLayout；再通过 `useLocation()` 拿到 location 信息，也传给 ProLayout 来决定哪个菜单应该高亮；同时我们希望点击菜单时做路由跳转，需要定制 ProLayout 的 menuItemRender 方法。
|
||||
这里先用 Umi 的 `useAppData` 拿到全局客户端路由 `clientRoutes`，这是一份嵌套结构的路由表，我们把 `clientRoutes[0]` 传给 ProLayout；再通过 `useLocation()` 拿到 location 信息，也传给 ProLayout 来决定哪个菜单应该高亮；同时我们希望点击菜单时做路由跳转，需要定制 ProLayout 的 `menuItemRender` 方法。
|
||||
|
||||
聪明的你可能已经发现 `src/layouts/index.less` 已经没地方引用他了，为了保持项目文件的整洁，可以选择删掉他。
|
||||
聪明的你可能已经发现 `src/layouts/index.less` 已经不再被引用了。为了保持项目文件的整洁，可以选择将其删除。
|
||||
|
||||
此时浏览器会自动刷新，如果顺利，你会看到如下界面。
|
||||
|
||||
@ -348,14 +348,14 @@ info - File sizes after gzip:
|
||||
event - Build index.html
|
||||
```
|
||||
|
||||
构建会打包所有的资源，包含 JavaScript, CSS, Web Fonts, 图片, Html 等。你可以在 `dist/` 目录下找到这些文件。
|
||||
构建会打包所有的资源，包含 JavaScript, CSS, Web Fonts, 图片, HTML 等。你可以在 `dist/` 目录下找到这些文件。
|
||||
|
||||
## 下一步
|
||||
|
||||
我们已经完成了一个简单应用，你可能还有很多疑问，比如：
|
||||
|
||||
- 如何统一处理出错？
|
||||
- 如何处理更多路由，比如动态路由，嵌套路由，权限路由等？
|
||||
- 如何处理更多路由，比如动态路由、嵌套路由、权限路由等？
|
||||
- 如何使用数据流方案？
|
||||
- 如何修改 webpack 配置或切换到 vite 构建模式？
|
||||
- 等等
|
||||
|
||||
Loading…
Reference in New Issue
Block a user