mirror of
https://github.com/ant-design/ant-design.git
synced 2024-11-24 02:59:58 +08:00
docs: v5 docs completion (#37757)
* docs: v5 docs completion * chore: code clean
This commit is contained in:
MadCcc
GitHub
parent
3a7c1e0061
commit
7f951021bf
@ -347,7 +347,6 @@ export interface MapToken extends SeedToken, ColorPalettes, ColorMapToken, Commo
|
||||
// 🔥🔥🔥🔥🔥🔥🔥 DO NOT MODIFY THIS. PLEASE CONTACT DESIGNER. 🔥🔥🔥🔥🔥🔥🔥
|
||||
export interface AliasToken extends MapToken {
|
||||
// Background
|
||||
colorFillSecondary: string;
|
||||
colorFillContentHover: string;
|
||||
colorFillAlter: string;
|
||||
colorBgContainerDisabled: string;
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
order: 7
|
||||
title: 5.0 定制主题
|
||||
title: 定制主题
|
||||
---
|
||||
|
||||
Ant Design 设计规范和技术上支持灵活的样式定制，以满足业务和品牌上多样化的视觉需求，包括但不限于全局样式（主色、圆角、边框）和指定组件的视觉定制。
|
||||
@ -12,222 +12,415 @@ Ant Design 设计规范和技术上支持灵活的样式定制，以满足业务
|
||||
3. 支持针对某个/某些组件主题变量；
|
||||
4. ...
|
||||
|
||||
> TODO: 这里需要一张 GIF 展示动态主题能力
|
||||
## 在 ConfigProvider 中配置主题
|
||||
|
||||
## Design Token
|
||||
|
||||
在正式介绍 5.0 定制主题的方案之前，我们需要对主题的组成部分有一个基本的了解。
|
||||
|
||||
与 4.x 版本相同的是，5.0 也提供了一批变量用于更改主题的各项参数。 在 4.x 中我们使用了 less 变量来实现定制主题的能力；而在 5.0 的 CSS-in-JS 方案中，我们使用 JS 变量作为动态主题的基础，这些变量我们统称为 **Design Token**。
|
||||
|
||||
### 基本组成
|
||||
|
||||
用过 4.x 定制主题的同学应该知道，在 4.x 中所有的 less 变量都是平铺的，`default.less` 这个文件就长达 1000+ 行。在 Design Token 中我们对原有的变量进行了精简，并且在设计师的引导下产出了一套更加贴合设计的三层结构，将 Design Token 拆解为 **Seed Token**、**Map Token** 和 **Alias Token** 三部分。
|
||||
|
||||
这三组 Token 并不是简单的分组，而是一个三层的派生关系，由 Seed Token 派生 Map Token，再由 Map Token 派生 Alias Token。这中间经历的过程实际上也是设计到代码的过程，Seed Token 和 Map Token 主要是由设计师产出并展开，命名逻辑会更偏向设计；到了 Alias Token 实际上已经是 Token 投入到代码中使用的环节，所以命名逻辑会逐渐偏向使用侧。
|
||||
|
||||
设计师对于这三种 Token 的定义是这样的：
|
||||
|
||||
- **Seed Token**：基础变量基础变量（Seed Token）意味着所有设计意图的起源。在 Ant Design 中，我们会基于 Seed Token 自动派生一套具有设计语义的梯度变量（Map Token）
|
||||
- **Map Token**：梯度变量梯度变量（Map Token） 是基于 Seed 派生的梯度变量，我们精心设计的梯度变量模型具有良好的设计语义，可保证在亮暗色模式切换时保证视觉梯度的一致性。
|
||||
- **Alias Token**：别名变量别名变量（Alias Token）是 Map Token 的别名。Alias Token 用于批量控制某些共性组件的样式。
|
||||
|
||||
### 基本算法
|
||||
|
||||
> TODO
|
||||
|
||||
### 演变过程
|
||||
|
||||
> TODO
|
||||
|
||||
### Component Token
|
||||
|
||||
除了整体的 Token 链路之外，各个组件也会开放自己的 Component Token 来实现针对组件的样式定制能力，不同的组件之间不会相互影响。一般来说会是一些具体场景下的 CSS 变量，我们会单独提出来作为 Component Token。
|
||||
|
||||
> TODO: 需要对各个组件补充 Component Token 的说明，这里可以链接到某个组件的页面
|
||||
|
||||
## 在代码中定制主题
|
||||
|
||||
### 使用 ConfigProvider
|
||||
|
||||
我们为 ConfigProvider 添加了 `theme` 属性，用于传递主题配置，你可以在这里任意修改在上文中提到的 Design Token 和 Component Token。
|
||||
通过在 ConfigProvider 中传入 theme，可以配置主题，在升级 v5 后，将默认使用 v5 的主题，以下是将主题切换至 v4 的示例：
|
||||
|
||||
```tsx
|
||||
import { ConfigProvider, Button } from 'antd';
|
||||
import React from 'react';
|
||||
import { ConfigProvider, Button, theme } from 'antd';
|
||||
|
||||
export default () => (
|
||||
const { defaultAlgorithmV4 } = theme;
|
||||
|
||||
const App: React.FC = () => (
|
||||
<ConfigProvider
|
||||
theme={{
|
||||
token: {
|
||||
colorPrimary: '#1890ff',
|
||||
radiusBase: 2,
|
||||
},
|
||||
algorithm: defaultAlgorithmV4,
|
||||
}}
|
||||
>
|
||||
<Button />
|
||||
</ConfigProvider>
|
||||
);
|
||||
|
||||
export default App;
|
||||
```
|
||||
|
||||
> 完整的主题配置将会在 v4 兼容包中提供。
|
||||
|
||||
## 定制主题
|
||||
|
||||
`theme` 是一系列 **Design Token** 的集合，当我们传入 `theme` 后，antd 的组件就会根据相应的 **Design Token** 改变自己的样式。
|
||||
|
||||
我们将依次介绍四类 **Design Token**
|
||||
|
||||
### 基础变量（Seed Token）
|
||||
|
||||
在大部分情况下，使用 **Seed Token** 就可以基本满足定制主题的需要，比如我们可以通过改变 `colorPrimary` 来改变主题色，antd 内部的算法会自动的根据 **Seed Token** 计算出对应的一系列颜色并应用：
|
||||
|
||||
```tsx
|
||||
const theme = {
|
||||
token: {
|
||||
colorPrimary: '#1890ff',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 梯度变量（Map Token）
|
||||
|
||||
**Map Token** 是基于 Seed 派生的梯度变量。定制 Map Token 推荐通过 `theme.algorithm` 来实现，这样可以保证 Map Token 之间的梯度关系。也可以通过 `theme.token` 覆盖，用于单独修改一些 map token 的值。
|
||||
|
||||
```tsx
|
||||
const theme = {
|
||||
token: {
|
||||
colorPrimaryBg: '#e6f7ff',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 别名变量（Alias Token）
|
||||
|
||||
Alias Token 用于批量控制某些共性组件的样式，基本上是 Map Token 别名，或者特殊处理过的 Map Token。
|
||||
|
||||
```tsx
|
||||
const theme = {
|
||||
token: {
|
||||
colorLink: '#1890ff',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 组件变量（Component Token）
|
||||
|
||||
除了整体的 Token 链路之外，各个组件也会开放自己的 Component Token 来实现针对组件的样式定制能力，不同的组件之间不会相互影响。同样地，也可以通过这种方式来覆盖组件的其他 Design Token。
|
||||
|
||||
```tsx
|
||||
const theme = {
|
||||
components: {
|
||||
Menu: {
|
||||
colorItemText: 'rgba(0, 0, 0, 0.88)',
|
||||
colorLink: '#1890ff',
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 基本算法（algorithm)
|
||||
|
||||
基本算法用于将 Seed Token 展开为 Map Token，比如由一个基本色算出一个梯度色板，或者由一个基本的圆角算出各种大小的圆角。在 v5 中，我们默认提供了三种算法，分别是默认算法（defaultAlgorithm）、暗色算法（darkAlgorithm）和紧凑算法（compactAlgorithm）。算法可以任意地组合使用，比如可以将暗色算法和紧凑算法组合使用，得到一个暗色和紧凑相结合的主题。
|
||||
|
||||
```tsx
|
||||
import { theme } from 'antd';
|
||||
|
||||
const { darkAlgorithm, compactAlgorithm } = theme;
|
||||
|
||||
const theme = {
|
||||
algorithm: [darkAlgorithm, compactAlgorithm],
|
||||
};
|
||||
```
|
||||
|
||||
### 演变过程
|
||||
|
||||
|
||||
|
||||
## 动态主题的其他使用方式
|
||||
|
||||
### 动态切换
|
||||
|
||||
在 v5 中，动态切换主题对用户来说是非常简单的，你可以在任何时候通过 `ConfigProvider` 的 `theme` 属性来动态切换主题，而不用额外配置任何东西。
|
||||
|
||||
### 局部主题
|
||||
|
||||
> TODO
|
||||
可以嵌套使用 `ConfigProvider` 来实现局部主题的更换。在子主题中未被改变的 Design Token 将会继承父主题。
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import { ConfigProvider, Button } from 'antd';
|
||||
|
||||
const App: React.FC = () => (
|
||||
<ConfigProvider
|
||||
theme={{
|
||||
token: {
|
||||
colorPrimary: '#1677ff',
|
||||
},
|
||||
}}
|
||||
>
|
||||
<Button />
|
||||
<ConfigProvider
|
||||
theme={{
|
||||
token: {
|
||||
colorPrimary: '#1890ff',
|
||||
},
|
||||
}}
|
||||
>
|
||||
<Button />
|
||||
</ConfigProvider>
|
||||
</ConfigProvider>
|
||||
);
|
||||
|
||||
export default App;
|
||||
```
|
||||
|
||||
### 使用 Design Token
|
||||
|
||||
如果你希望使用当前主题下的 Design Token，我们提供了 `useToken` 这个 hook 来获取 Design Token。
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import { Button, theme } from 'antd';
|
||||
|
||||
const { useToken } = theme;
|
||||
|
||||
const App: React.FC = () => {
|
||||
const { token } = useToken();
|
||||
|
||||
return <Button style={{ backgroundColor: token.colorPrimary }}>Button</Button>;
|
||||
};
|
||||
|
||||
export default App;
|
||||
```
|
||||
|
||||
### 在 umi 4 中定制主题
|
||||
|
||||
> TODO
|
||||
|
||||
### API (暂定)
|
||||
## API
|
||||
|
||||
#### Theme
|
||||
### Theme
|
||||
|
||||
| 属性 | 类型 | 默认值 | 说明 |
|
||||
| 属性 | 说明 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| token | `AliasToken` | - | 用于修改 Design Token |
|
||||
| algorithm | `(token: SeedToken) => MapToken` \| `((token: SeedToken) => MapToken)[]` | `defaultAlgorithm` | 用于修改 Seed Token 到 Map Token 的算法 |
|
||||
| components | OverrideToken | - | 用于修改各个组件的 Component Token 以及覆盖该组件消费的 Alias Token |
|
||||
| token | 用于修改 Design Token | `AliasToken` | - |
|
||||
| algorithm | 用于修改 Seed Token 到 Map Token 的算法 | `(token: SeedToken) => MapToken` \| `((token: SeedToken) => MapToken)[]` | `defaultAlgorithm` |
|
||||
| components | 用于修改各个组件的 Component Token 以及覆盖该组件消费的 Alias Token | OverrideToken | - |
|
||||
|
||||
#### OverrideToken
|
||||
### OverrideToken
|
||||
|
||||
| 属性 | 类型 | 默认值 | 说明 |
|
||||
| 属性 | 说明 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Component` (可以是任意 antd 组件名，如 `Button`) | `ComponentToken & AliasToken` | - | 用于修改 Component Token 以及覆盖该组件消费的 Alias Token |
|
||||
| `Component` (可以是任意 antd 组件名，如 `Button`) | 用于修改 Component Token 以及覆盖该组件消费的 Alias Token | `ComponentToken & AliasToken` | - |
|
||||
|
||||
#### SeedToken
|
||||
### SeedToken
|
||||
|
||||
| 属性 | 类型 | 默认值 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| colorPrimary | `string` | `#1677ff` | 品牌主色 |
|
||||
| colorSuccess | `string` | `#52c41a` | 成功色 |
|
||||
| colorWarning | `string` | `#faad14` | 警戒色 |
|
||||
| colorError | `string` | `#f5222d` | 错误色 |
|
||||
| colorInfo | `string` | `#1677ff` | 信息色 |
|
||||
| colorTextBase | `string` | `#000` | 基础文本色 |
|
||||
| colorTextLightSolid | `string` | `#fff` | 亮色文本色 |
|
||||
| colorBgBase | `string` | `#fff` | 基础背景色 |
|
||||
| fontFamily | `string` | `-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji'` | 字体 |
|
||||
| fontSizeBase | `number` | `14` | 基础字号 |
|
||||
| gridUnit | `number` | `4` | - |
|
||||
| gridBaseStep | `number` | `2` | - |
|
||||
| 属性 | 说明 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| colorPrimary | 品牌主色 | `string` | `#1677ff` |
|
||||
| colorSuccess | 成功色 | `string` | `#52c41a` |
|
||||
| colorWarning | 警戒色 | `string` | `#faad14` |
|
||||
| colorError | 错误色 | `string` | `#f5222d` |
|
||||
| colorInfo | 信息色 | `string` | `#1677ff` |
|
||||
| colorTextBase | 基础文本色 | `string` | `#000` |
|
||||
| colorTextLightSolid | 亮色文本色 | `string` | `#fff` |
|
||||
| colorBgBase | 基础背景色 | `string` | `#fff` |
|
||||
| fontFamily | 字体 | `string` | `-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji'` |
|
||||
| fontSizeBase | 基础字号 | `number` | `14` |
|
||||
| gridUnit | - | `number` | `4` |
|
||||
| gridBaseStep | - | `number` | `2` |
|
||||
| lineWidth | `number` | `1` | 基础线宽 |
|
||||
| lineType | `string` | `solid` | 线条样式 |
|
||||
| motionUnit | `number` | `0.1` | 动画时长变化单位 |
|
||||
| motionBase | `number` | `0` | 动画基础时长 |
|
||||
| motionEaseOutCirc | `string` | `cubic-bezier(0.08, 0.82, 0.17, 1)` | - |
|
||||
| motionEaseInOutCirc | `string` | `cubic-bezier(0.78, 0.14, 0.15, 0.86)` | - |
|
||||
| motionEaseOut | `string` | `cubic-bezier(0.215, 0.61, 0.355, 1)` | - |
|
||||
| motionEaseInOut | `string` | `cubic-bezier(0.645, 0.045, 0.355, 1)` | - |
|
||||
| motionEaseOutBack | `string` | `cubic-bezier(0.12, 0.4, 0.29, 1.46)` | - |
|
||||
| motionEaseInQuint | `string` | `cubic-bezier(0.645, 0.045, 0.355, 1)` | - |
|
||||
| motionEaseOutQuint | `string` | `cubic-bezier(0.23, 1, 0.32, 1)` | - |
|
||||
| radiusBase | `number` | `6` | 基础圆角 |
|
||||
| sizeUnit | `number` | `4` | 尺寸变化单位 |
|
||||
| sizeBaseStep | `number` | `4` | 尺寸基础大小 |
|
||||
| sizePopupArrow | `number` | `16` | 组件箭头尺寸 |
|
||||
| controlHeight | `number` | `32` | - |
|
||||
| zIndexBase | `number` | `0` | 基础 `z-index` |
|
||||
| zIndexPopupBase | `number` | `1000` | 浮层基础 `z-index` |
|
||||
| opacityImage | `number` | `1` | - |
|
||||
| wireframe | `boolean` | `false` | 线框化 |
|
||||
| motionEaseOutCirc | - | `string` | `cubic-bezier(0.08, 0.82, 0.17, 1)` |
|
||||
| motionEaseInOutCirc | `string` | `cubic-bezier(0.78, 0.14, 0.15, 0.86)` |
|
||||
| motionEaseOut | - | `string` | `cubic-bezier(0.215, 0.61, 0.355, 1)` | - |
|
||||
| motionEaseInOut | - | `string` | `cubic-bezier(0.645, 0.045, 0.355, 1)` |
|
||||
| motionEaseOutBack | - | `string` | `cubic-bezier(0.12, 0.4, 0.29, 1.46)` |
|
||||
| motionEaseInQuint | - | `string` | `cubic-bezier(0.645, 0.045, 0.355, 1)` |
|
||||
| motionEaseOutQuint | - | `string` | `cubic-bezier(0.23, 1, 0.32, 1)` |
|
||||
| radiusBase | 基础圆角 | `number` | `6` |
|
||||
| sizeUnit | 尺寸变化单位 | `number` | `4` |
|
||||
| sizeBaseStep | 尺寸基础大小 | `number` | `4` |
|
||||
| sizePopupArrow | 组件箭头尺寸 | `number` | `16` |
|
||||
| controlHeight | - | `number` | `32` |
|
||||
| zIndexBase | 基础 `z-index` | `number` | `0` |
|
||||
| zIndexPopupBase | 浮层基础 `z-index` | `number` | `1000` |
|
||||
| opacityImage | - | `number` | `1` |
|
||||
| wireframe | 线框化 | `boolean` | `false` |
|
||||
|
||||
#### MapToken
|
||||
### MapToken
|
||||
|
||||
| 属性 | 类型 | 默认值 | 说明 |
|
||||
| 属性 | 说明 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| colorText | `string` | `rgba(0, 0, 0, 0.88)` | 一级文本色 |
|
||||
| colorTextSecondary | `string` | `rgba(0, 0, 0, 0.65)` | 二级文本色 |
|
||||
| colorTextTertiary | `string` | `rgba(0, 0, 0, 0.45)` | 三级文本色 |
|
||||
| colorTextQuaternary | `string` | `rgba(0, 0, 0, 0.25)` | 四级文本色 |
|
||||
| colorFill | `string` | `rgba(0, 0, 0, 0.15)` | 一级填充色 |
|
||||
| colorFillSecondary | `string` | `rgba(0, 0, 0, 0.06)` | 二级填充色 |
|
||||
| colorFillTertiary | `string` | `rgba(0, 0, 0, 0.04)` | 三级填充色 |
|
||||
| colorFillQuaternary | `string` | `rgba(0, 0, 0, 0.02)` | 四级填充色 |
|
||||
| colorBgContainer | `string` | `#ffffff` | 组件容器背景色 |
|
||||
| colorBgElevated | `string` | `#ffffff` | 浮层容器背景色 |
|
||||
| colorBgLayout | `string` | `#f5f5f5` | 布局背景色 |
|
||||
| colorBgSpotlight | `string` | `rgba(0, 0, 0, 0.85)` | - |
|
||||
| colorBorder | `string` | `#d9d9d9` | 一级边框色 |
|
||||
| colorBorderSecondary | `string` | `#f0f0f0` | 二级边框色 |
|
||||
| colorSplit | `string` | `rgba(0, 0, 0, 0.06)` | 分割线颜色 |
|
||||
| colorPrimaryBg | `string` | `#e6f4ff` | 主色的浅色背景颜色 |
|
||||
| colorPrimaryBgHover | `string` | `#bae0ff` | 主色的浅色背景色悬浮态 |
|
||||
| colorPrimaryBorder | `string` | `#91caff` | 主色的描边色 |
|
||||
| colorPrimaryBorderHover | `string` | `#69b1ff` | 主色的描边色悬浮态 |
|
||||
| colorPrimaryHover | `string` | `#4096ff` | 主色的深色悬浮态 |
|
||||
| colorPrimary | `string` | `#1677ff` | 品牌主色 |
|
||||
| colorPrimaryActive | `string` | `#0958d9` | 主色的深色激活态 |
|
||||
| colorPrimaryTextHover | `string` | `#4096ff` | 主色的文本悬浮态 |
|
||||
| colorPrimaryText | `string` | `#1677ff` | 主色的文本默认态 |
|
||||
| colorPrimaryTextActive | `string` | `#0958d9` | 主色的文本激活态 |
|
||||
| colorSuccessBg | `string` | `#f6ffed` | 成功色的浅色背景颜色 |
|
||||
| colorSuccessBgHover | `string` | `#d9f7be` | 成功色的浅色背景色悬浮态 |
|
||||
| colorSuccessBorder | `string` | `#b7eb8f` | 成功色的描边色 |
|
||||
| colorSuccessBorderHover | `string` | `#95de64` | 成功色的描边色悬浮态 |
|
||||
| colorSuccessHover | `string` | `#95de64` | 成功色的深色悬浮态 |
|
||||
| colorSuccess | `string` | `#52c41a` | 成功色 |
|
||||
| colorSuccessActive | `string` | `#389e0d` | 成功色的深色激活态 |
|
||||
| colorSuccessTextHover | `string` | `#73d13d` | 成功色的文本悬浮态 |
|
||||
| colorSuccessText | `string` | `#52c41a` | 成功色的文本默认态 |
|
||||
| colorSuccessTextActive | `string` | `#389e0d` | 成功色的文本激活态 |
|
||||
| colorWarningBg | `string` | `#fffbe6` | 警戒色的浅色背景颜色 |
|
||||
| colorWarningBgHover | `string` | `#fff1b8` | 警戒色的浅色背景色悬浮态 |
|
||||
| colorWarningBorder | `string` | `#ffe58f` | 警戒色的描边色 |
|
||||
| colorWarningBorderHover | `string` | `#ffd666` | 警戒色的描边色悬浮态 |
|
||||
| colorWarningHover | `string` | `#ffd666` | 警戒色的深色悬浮态 |
|
||||
| colorWarning | `string` | `#faad14` | 警戒色 |
|
||||
| colorWarningActive | `string` | `#d48806` | 警戒色的深色激活态 |
|
||||
| colorWarningTextHover | `string` | `#ffc53d` | 警戒色的文本悬浮态 |
|
||||
| colorWarningText | `string` | `#faad14` | 警戒色的文本默认态 |
|
||||
| colorWarningTextActive | `string` | `#d48806` | 警戒色的文本激活态 |
|
||||
| colorErrorBg | `string` | `#fff1f0` | 错误色的浅色背景颜色 |
|
||||
| colorErrorBgHover | `string` | `#ffccc7` | 错误色的浅色背景色悬浮态 |
|
||||
| colorErrorBorder | `string` | `#ffa39e` | 错误色的描边色 |
|
||||
| colorErrorBorderHover | `string` | `#ff7875` | 错误色的描边色悬浮态 |
|
||||
| colorErrorHover | `string` | `#ff7875` | 错误色的深色悬浮态 |
|
||||
| colorError | `string` | `#ff4d4f` | 错误色 |
|
||||
| colorErrorActive | `string` | `#cf1322` | 错误色的深色激活态 |
|
||||
| colorErrorTextHover | `string` | `#ff4d4f` | 错误色的文本悬浮态 |
|
||||
| colorErrorText | `string` | `#f5222d` | 错误色的文本默认态 |
|
||||
| colorErrorTextActive | `string` | `#cf1322` | 错误色的文本激活态 |
|
||||
| colorInfoBg | `string` | `#e6f4ff` | 信息色的浅色背景颜色 |
|
||||
| colorInfoBgHover | `string` | `#bae0ff` | 信息色的浅色背景色悬浮态 |
|
||||
| colorInfoBorder | `string` | `#91caff` | 信息色的描边色 |
|
||||
| colorInfoBorderHover | `string` | `#69b1ff` | 信息色的描边色悬浮态 |
|
||||
| colorInfoHover | `string` | `#69b1ff` | 信息色的深色悬浮态 |
|
||||
| colorInfo | `string` | `#e6f4ff` | 信息色 |
|
||||
| colorInfoActive | `string` | `#0958d9` | 信息色的深色激活态 |
|
||||
| colorInfoTextHover | `string` | `#4096ff` | 信息色的文本悬浮态 |
|
||||
| colorInfoText | `string` | `#1677ff` | 信息色的文本默认态 |
|
||||
| colorInfoTextActive | `string` | `#0958d9` | 信息色的文本激活态 |
|
||||
| colorBgMask | `string` | `rgba(0, 0, 0, 0.45)` | 浮层的背景蒙层颜色 |
|
||||
| sizeSpace | `number` | `12` | - |
|
||||
| sizeSpaceSM | `number` | `16` | - |
|
||||
| sizeSpaceXS | `number` | `8` | - |
|
||||
| sizeSpaceXXS | `number` | `4` | - |
|
||||
| gridSpaceSM | `number` | `4` | - |
|
||||
| gridSpaceBase | `number` | `8` | - |
|
||||
| gridSpaceLG | `number` | `12` | - |
|
||||
| gridSpaceXL | `number` | `16` | - |
|
||||
| gridSpaceXXL | `number` | `28` | - |
|
||||
| lineWidthBold | `number` | `2` | 较粗的线宽 |
|
||||
| motionDurationFast | `string` | `0.1s` | 动画速度快 |
|
||||
| motionDurationMid | `string` | `0.2s` | 动画速度中等 |
|
||||
| motionDurationSlow | `string` | `0.3s` | 动画速度慢 |
|
||||
| radiusXS | `number` | `2` | 更小的圆角 |
|
||||
| radiusSM | `number` | `4` | 较小的圆角 |
|
||||
| radiusLG | `number` | `8` | 较大的圆角 |
|
||||
| radiusOuter | `number` | `4` | 向外的圆角（常用于箭头与其他元素相接处） |
|
||||
| controlHeightXS | `number` | `24` | - |
|
||||
| controlHeightSM | `number` | `16` | - |
|
||||
| controlHeightLG | `number` | `40` | - |
|
||||
| colorText | 一级文本色 | `string` | `rgba(0, 0, 0, 0.88)` |
|
||||
| colorTextSecondary | 二级文本色 | `string` | `rgba(0, 0, 0, 0.65)` |
|
||||
| colorTextTertiary | 三级文本色 | `string` | `rgba(0, 0, 0, 0.45)` |
|
||||
| colorTextQuaternary | 四级文本色 | `string` | `rgba(0, 0, 0, 0.25)` |
|
||||
| colorFill | 一级填充色 | `string` | `rgba(0, 0, 0, 0.15)` |
|
||||
| colorFillSecondary | 二级填充色 | `string` | `rgba(0, 0, 0, 0.06)` |
|
||||
| colorFillTertiary | 三级填充色 | `string` | `rgba(0, 0, 0, 0.04)` |
|
||||
| colorFillQuaternary | 四级填充色 | `string` | `rgba(0, 0, 0, 0.02)` |
|
||||
| colorBgContainer | 组件容器背景色 | `string` | `#ffffff` |
|
||||
| colorBgElevated | 浮层容器背景色 | `string` | `#ffffff` |
|
||||
| colorBgLayout | 布局背景色 | `string` | `#f5f5f5` |
|
||||
| colorBgSpotlight | - | `string` | `rgba(0, 0, 0, 0.85)` |
|
||||
| colorBorder | 一级边框色 | `string` | `#d9d9d9` |
|
||||
| colorBorderSecondary | 二级边框色 | `string` | `#f0f0f0` |
|
||||
| colorSplit | 分割线颜色 | `string` | `rgba(0, 0, 0, 0.06)` |
|
||||
| colorPrimaryBg | 主色的浅色背景颜色 | `string` | `#e6f4ff` |
|
||||
| colorPrimaryBgHover | 主色的浅色背景色悬浮态 | `string` | `#bae0ff` |
|
||||
| colorPrimaryBorder | 主色的描边色 | `string` | `#91caff` |
|
||||
| colorPrimaryBorderHover | 主色的描边色悬浮态 | `string` | `#69b1ff` |
|
||||
| colorPrimaryHover | 主色的深色悬浮态 | `string` | `#4096ff` |
|
||||
| colorPrimary | 品牌主色 | `string` | `#1677ff` |
|
||||
| colorPrimaryActive | 主色的深色激活态 | `string` | `#0958d9` |
|
||||
| colorPrimaryTextHover | 主色的文本悬浮态 | `string` | `#4096ff` |
|
||||
| colorPrimaryText | 主色的文本默认态 | `string` | `#1677ff` |
|
||||
| colorPrimaryTextActive | 主色的文本激活态 | `string` | `#0958d9` |
|
||||
| colorSuccessBg | 成功色的浅色背景颜色 | `string` | `#f6ffed` |
|
||||
| colorSuccessBgHover | 成功色的浅色背景色悬浮态 | `string` | `#d9f7be` |
|
||||
| colorSuccessBorder | 成功色的描边色 | `string` | `#b7eb8f` |
|
||||
| colorSuccessBorderHover | 成功色的描边色悬浮态 | `string` | `#95de64` |
|
||||
| colorSuccessHover | 成功色的深色悬浮态 | `string` | `#95de64` |
|
||||
| colorSuccess | 成功色 | `string` | `#52c41a` |
|
||||
| colorSuccessActive | 成功色的深色激活态 | `string` | `#389e0d` |
|
||||
| colorSuccessTextHover | 成功色的文本悬浮态 | `string` | `#73d13d` |
|
||||
| colorSuccessText | 成功色的文本默认态 | `string` | `#52c41a` |
|
||||
| colorSuccessTextActive | 成功色的文本激活态 | `string` | `#389e0d` |
|
||||
| colorWarningBg | 警戒色的浅色背景颜色 | `string` | `#fffbe6` |
|
||||
| colorWarningBgHover | 警戒色的浅色背景色悬浮态 | `string` | `#fff1b8` |
|
||||
| colorWarningBorder | 警戒色的描边色 | `string` | `#ffe58f` |
|
||||
| colorWarningBorderHover | 警戒色的描边色悬浮态 | `string` | `#ffd666` |
|
||||
| colorWarningHover | 警戒色的深色悬浮态 | `string` | `#ffd666` |
|
||||
| colorWarning | 警戒色 | `string` | `#faad14` |
|
||||
| colorWarningActive | 警戒色的深色激活态 | `string` | `#d48806` |
|
||||
| colorWarningTextHover | 警戒色的文本悬浮态 | `string` | `#ffc53d` |
|
||||
| colorWarningText | 警戒色的文本默认态 | `string` | `#faad14` |
|
||||
| colorWarningTextActive | 警戒色的文本激活态 | `string` | `#d48806` |
|
||||
| colorErrorBg | 错误色的浅色背景颜色 | `string` | `#fff1f0` |
|
||||
| colorErrorBgHover | 错误色的浅色背景色悬浮态 | `string` | `#ffccc7` |
|
||||
| colorErrorBorder | 错误色的描边色 | `string` | `#ffa39e` |
|
||||
| colorErrorBorderHover | 错误色的描边色悬浮态 | `string` | `#ff7875` |
|
||||
| colorErrorHover | 错误色的深色悬浮态 | `string` | `#ff7875` |
|
||||
| colorError | 错误色 | `string` | `#ff4d4f` |
|
||||
| colorErrorActive | 错误色的深色激活态 | `string` | `#cf1322` |
|
||||
| colorErrorTextHover | 错误色的文本悬浮态 | `string` | `#ff4d4f` |
|
||||
| colorErrorText | 错误色的文本默认态 | `string` | `#f5222d` |
|
||||
| colorErrorTextActive | 错误色的文本激活态 | `string` | `#cf1322` |
|
||||
| colorInfoBg | 信息色的浅色背景颜色 | `string` | `#e6f4ff` |
|
||||
| colorInfoBgHover | 信息色的浅色背景色悬浮态 | `string` | `#bae0ff` |
|
||||
| colorInfoBorder | 信息色的描边色 | `string` | `#91caff` |
|
||||
| colorInfoBorderHover | 信息色的描边色悬浮态 | `string` | `#69b1ff` |
|
||||
| colorInfoHover | 信息色的深色悬浮态 | `string` | `#69b1ff` |
|
||||
| colorInfo | 信息色 | `string` | `#e6f4ff` |
|
||||
| colorInfoActive | 信息色的深色激活态 | `string` | `#0958d9` |
|
||||
| colorInfoTextHover | 信息色的文本悬浮态 | `string` | `#4096ff` |
|
||||
| colorInfoText | 信息色的文本默认态 | `string` | `#1677ff` |
|
||||
| colorInfoTextActive | 信息色的文本激活态 | `string` | `#0958d9` |
|
||||
| colorBgMask | 浮层的背景蒙层颜色 | `string` | `rgba(0, 0, 0, 0.45)` |
|
||||
| sizeSpace | - | `number` | `12` |
|
||||
| sizeSpaceSM | - | `number` | `16` |
|
||||
| sizeSpaceXS | - | `number` | `8` |
|
||||
| sizeSpaceXXS | - | `number` | `4` |
|
||||
| gridSpaceSM | - | `number` | `4` |
|
||||
| gridSpaceBase | - | `number` | `8` |
|
||||
| gridSpaceLG | - | `number` | `12` |
|
||||
| gridSpaceXL | - | `number` | `16` |
|
||||
| gridSpaceXXL | - | `number` | `28` |
|
||||
| lineWidthBold | 较粗的线宽 | `number` | `2` |
|
||||
| motionDurationFast | 动画速度快 | `string` | `0.1s` |
|
||||
| motionDurationMid | 动画速度中等 | `string` | `0.2s` |
|
||||
| motionDurationSlow | 动画速度慢 | `string` | `0.3s` |
|
||||
| radiusXS | 更小的圆角 | `number` | `2` |
|
||||
| radiusSM | 较小的圆角 | `number` | `4` |
|
||||
| radiusLG | 较大的圆角 | `number` | `8` |
|
||||
| radiusOuter | 向外的圆角（常用于箭头与其他元素相接处） | `number` | `4` |
|
||||
| controlHeightXS | - | `number` | `24` |
|
||||
| controlHeightSM | - | `number` | `16` |
|
||||
| controlHeightLG | - | `number` | `40` |
|
||||
|
||||
#### AliasToken (待补全)
|
||||
### AliasToken (待补全)
|
||||
|
||||
| 属性 | 类型 | 默认值 | 说明 |
|
||||
| ------------------- | -------- | --------- | ---------------------------------------- |
|
||||
| controlItemBgActive | `string` | `#e6f4ff` | 用于控件类组件中的单项的激活态选中样式。 |
|
||||
| 属性 | 说明 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| colorFillContent | - | `string` | `rgba(0, 0, 0, 0.06)` |
|
||||
| colorFillContentHover | - | `string` | `rgba(0, 0, 0, 0.12)` |
|
||||
| colorFillAlter | - | `string` | `rgba(0, 0, 0, 0.02)` |
|
||||
| colorBgContainerDisabled | - | `string` | `rgba(0, 0, 0, 0.04)` |
|
||||
| colorBorderBg | - | `string` | `#ffffff` |
|
||||
| colorSplit | - | `string` | `rgba(0, 0, 0, 0.06)` |
|
||||
| colorTextPlaceholder | - | `string` | `rgba(0, 0, 0, 0.25)` |
|
||||
| colorTextDisabled | - | `string` | `rgba(0, 0, 0, 0.25)` |
|
||||
| colorTextHeading | - | `string` | `rgba(0, 0, 0, 0.85)` |
|
||||
| colorTextLabel | - | `string` | `rgba(0, 0, 0, 0.65)` |
|
||||
| colorTextDescription | - | `string` | `rgba(0, 0, 0, 0.45)` |
|
||||
| colorBgTextHover | - | `string` | `rgba(0, 0, 0, 0.06)` |
|
||||
| colorBgTextActive | - | `string` | `rgba(0, 0, 0, 0.15)` |
|
||||
| colorIcon | - | `string` | `rgba(0, 0, 0, 0.45)` |
|
||||
| colorIconHover | - | `string` | `rgba(0, 0, 0, 0.88)` |
|
||||
| colorLink | - | `string` | `#1677ff` |
|
||||
| colorLinkHover | - | `string` | `#69b1ff` |
|
||||
| colorLinkActive | - | `string` | `#0958d9` |
|
||||
| colorHighlight | - | `string` | `#ff4d4f` |
|
||||
| controlOutline | - | `string` | `rgba(5, 145, 255, 0.1)` |
|
||||
| colorWarningOutline | - | `string` | `rgba(255, 215, 5, 0.1)` |
|
||||
| colorErrorOutline | - | `string` | `rgba(255, 22, 5, 0.06)` |
|
||||
| fontSizeSM | - | `number` | `12` |
|
||||
| fontSize | - | `number` | `14` |
|
||||
| fontSizeLG | - | `number` | `16` |
|
||||
| fontSizeXL | - | `number` | `20` |
|
||||
| fontSizeIcon | - | `number` | `12` |
|
||||
| fontSizeHeading1 | - | `number` | `38` |
|
||||
| fontSizeHeading2 | - | `number` | `30` |
|
||||
| fontSizeHeading3 | - | `number` | `24` |
|
||||
| fontSizeHeading4 | - | `number` | `20` |
|
||||
| fontSizeHeading5 | - | `number` | `16` |
|
||||
| fontWeightStrong | - | `number` | `600` |
|
||||
| lineHeight | - | `number` | `1.5714` |
|
||||
| lineHeightLG | - | `number` | `1.5` |
|
||||
| lineHeightSM | - | `number` | `1.6667` |
|
||||
| lineHeightHeading1 | - | `number` | `1.2105` |
|
||||
| lineHeightHeading2 | - | `number` | `1.2667` |
|
||||
| lineHeightHeading3 | - | `number` | `1.3333` |
|
||||
| lineHeightHeading4 | - | `number` | `1.4` |
|
||||
| lineHeightHeading5 | - | `number` | `1.5` |
|
||||
| controlLineWidth | - | `number` | `1` |
|
||||
| controlLineType | - | `string` | `solid` |
|
||||
| controlRadius | - | `number` | `6` |
|
||||
| controlRadiusXS | - | `number` | `2` |
|
||||
| controlRadiusSM | - | `number` | `4` |
|
||||
| controlRadiusLG | - | `number` | `8` |
|
||||
| controlOutlineWidth | - | `number` | `8` |
|
||||
| controlItemBgHover | - | `string` | `rgba(0, 0, 0, 0.04)` |
|
||||
| controlItemBgActive | - | `string` | `#e6f4ff` |
|
||||
| controlItemBgActiveHover | - | `string` | `#bae0ff` |
|
||||
| controlInteractiveSize | - | `number` | `16` |
|
||||
| controlItemBgActiveDisabled | - | `string` | `rgba(0, 0, 0, 0.15)` |
|
||||
| controlTmpOutline | - | `string` | `rgba(0, 0, 0, 0.02)` |
|
||||
| opacityLoading | - | `number` | `0.65` |
|
||||
| padding | - | `number` | `16` |
|
||||
| paddingSM | - | `number` | `12` |
|
||||
| paddingXS | - | `number` | `8` |
|
||||
| paddingXXS | - | `number` | `4` |
|
||||
| paddingLG | - | `number` | `24` |
|
||||
| paddingXL | - | `number` | `32` |
|
||||
| paddingTmp | - | `number` | `20` |
|
||||
| margin | - | `number` | `16` |
|
||||
| marginSM | - | `number` | `12` |
|
||||
| marginXS | - | `number` | `8` |
|
||||
| marginXXS | - | `number` | `4` |
|
||||
| marginLG | - | `number` | `24` |
|
||||
| marginXL | - | `number` | `32` |
|
||||
| marginXXL | - | `number` | `48` |
|
||||
| boxShadow | - | `string` | `0 1px 2px 0 rgba(0, 0, 0, 0.03), 0 1px 6px -1px rgba(0, 0, 0, 0.02), 0 2px 4px 0 rgba(0, 0, 0, 0.02)` |
|
||||
| boxShadowSecondary | - | `string` | `0 6px 16px 0 rgba(0, 0, 0, 0.08), 0 3px 6px -4px rgba(0, 0, 0, 0.12), 0 9px 28px 8px rgba(0, 0, 0, 0.05)` |
|
||||
| linkDecoration | - | `React.CSSProperties['textDecoration']` | `none` |
|
||||
| linkHoverDecoration | - | `React.CSSProperties['textDecoration']` | `none` |
|
||||
| linkFocusDecoration | - | `React.CSSProperties['textDecoration']` | `none` |
|
||||
| controlPaddingHorizontal | - | `number` | `12` |
|
||||
| controlPaddingHorizontalSM | - | `number` | `8` |
|
||||
| screenXS | - | `number` | `480` |
|
||||
| screenXSMin | - | `number` | `480` |
|
||||
| screenXSMax | - | `number` | `479` |
|
||||
| screenSM | - | `number` | `576` |
|
||||
| screenSMMin | - | `number` | `576` |
|
||||
| screenSMMax | - | `number` | `575` |
|
||||
| screenMD | - | `number` | `768` |
|
||||
| screenMDMin | - | `number` | `768` |
|
||||
| screenMDMax | - | `number` | `767` |
|
||||
| screenLG | - | `number` | `992` |
|
||||
| screenLGMin | - | `number` | `992` |
|
||||
| screenLGMax | - | `number` | `991` |
|
||||
| screenXL | - | `number` | `1200` |
|
||||
| screenXLMin | - | `number` | `1200` |
|
||||
| screenXLMax | - | `number` | `1199` |
|
||||
| screenXXL | - | `number` | `1600` |
|
||||
| screenXXLMin | - | `number` | `1599` |
|
||||
| screenXXLMax | - | `number` | `1600` |
|
||||
|
||||
### 调试主题
|
||||
## 调试主题
|
||||
|
||||
我们提供了帮助用户调试主题的工具：[主题编辑器](https://ant-design.github.io/antd-token-previewer/~demos/docs-theme-editor-simple)
|
||||
|
||||
@ -237,8 +430,6 @@ export default () => (
|
||||
|
||||
- [Ant Design 4.x 主题](https://ant-design.github.io/antd-token-previewer/~demos/docs-v4-theme)
|
||||
|
||||
> 可以引导用户贡献一些优质主题并收集起来
|
||||
|
||||
## FAQ
|
||||
|
||||
### 为什么 `theme` 从 `undefined` 变为对象或者变为 `undefined` 时组件重新 mount 了？
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
order: 7
|
||||
title: 5.0 定制主题
|
||||
title: 定制主题
|
||||
---
|
||||
|
||||
Ant Design 设计规范和技术上支持灵活的样式定制，以满足业务和品牌上多样化的视觉需求，包括但不限于全局样式（主色、圆角、边框）和指定组件的视觉定制。
|
||||
@ -12,222 +12,415 @@ Ant Design 设计规范和技术上支持灵活的样式定制，以满足业务
|
||||
3. 支持针对某个/某些组件主题变量；
|
||||
4. ...
|
||||
|
||||
> TODO: 这里需要一张 GIF 展示动态主题能力
|
||||
## 在 ConfigProvider 中配置主题
|
||||
|
||||
## Design Token
|
||||
|
||||
在正式介绍 5.0 定制主题的方案之前，我们需要对主题的组成部分有一个基本的了解。
|
||||
|
||||
与 4.x 版本相同的是，5.0 也提供了一批变量用于更改主题的各项参数。 在 4.x 中我们使用了 less 变量来实现定制主题的能力；而在 5.0 的 CSS-in-JS 方案中，我们使用 JS 变量作为动态主题的基础，这些变量我们统称为 **Design Token**。
|
||||
|
||||
### 基本组成
|
||||
|
||||
用过 4.x 定制主题的同学应该知道，在 4.x 中所有的 less 变量都是平铺的，`default.less` 这个文件就长达 1000+ 行。在 Design Token 中我们对原有的变量进行了精简，并且在设计师的引导下产出了一套更加贴合设计的三层结构，将 Design Token 拆解为 **Seed Token**、**Map Token** 和 **Alias Token** 三部分。
|
||||
|
||||
这三组 Token 并不是简单的分组，而是一个三层的派生关系，由 Seed Token 派生 Map Token，再由 Map Token 派生 Alias Token。这中间经历的过程实际上也是设计到代码的过程，Seed Token 和 Map Token 主要是由设计师产出并展开，命名逻辑会更偏向设计；到了 Alias Token 实际上已经是 Token 投入到代码中使用的环节，所以命名逻辑会逐渐偏向使用侧。
|
||||
|
||||
设计师对于这三种 Token 的定义是这样的：
|
||||
|
||||
- **Seed Token**：基础变量基础变量（Seed Token）意味着所有设计意图的起源。在 Ant Design 中，我们会基于 Seed Token 自动派生一套具有设计语义的梯度变量（Map Token）
|
||||
- **Map Token**：梯度变量梯度变量（Map Token） 是基于 Seed 派生的梯度变量，我们精心设计的梯度变量模型具有良好的设计语义，可保证在亮暗色模式切换时保证视觉梯度的一致性。
|
||||
- **Alias Token**：别名变量别名变量（Alias Token）是 Map Token 的别名。Alias Token 用于批量控制某些共性组件的样式。
|
||||
|
||||
### 基本算法
|
||||
|
||||
> TODO
|
||||
|
||||
### 演变过程
|
||||
|
||||
> TODO
|
||||
|
||||
### Component Token
|
||||
|
||||
除了整体的 Token 链路之外，各个组件也会开放自己的 Component Token 来实现针对组件的样式定制能力，不同的组件之间不会相互影响。一般来说会是一些具体场景下的 CSS 变量，我们会单独提出来作为 Component Token。
|
||||
|
||||
> TODO: 需要对各个组件补充 Component Token 的说明，这里可以链接到某个组件的页面
|
||||
|
||||
## 在代码中定制主题
|
||||
|
||||
### 使用 ConfigProvider
|
||||
|
||||
我们为 ConfigProvider 添加了 `theme` 属性，用于传递主题配置，你可以在这里任意修改在上文中提到的 Design Token 和 Component Token。
|
||||
通过在 ConfigProvider 中传入 theme，可以配置主题，在升级 v5 后，将默认使用 v5 的主题，以下是将主题切换至 v4 的示例：
|
||||
|
||||
```tsx
|
||||
import { ConfigProvider, Button } from 'antd';
|
||||
import React from 'react';
|
||||
import { ConfigProvider, Button, theme } from 'antd';
|
||||
|
||||
export default () => (
|
||||
const { defaultAlgorithmV4 } = theme;
|
||||
|
||||
const App: React.FC = () => (
|
||||
<ConfigProvider
|
||||
theme={{
|
||||
token: {
|
||||
colorPrimary: '#1890ff',
|
||||
radiusBase: 2,
|
||||
},
|
||||
algorithm: defaultAlgorithmV4,
|
||||
}}
|
||||
>
|
||||
<Button />
|
||||
</ConfigProvider>
|
||||
);
|
||||
|
||||
export default App;
|
||||
```
|
||||
|
||||
> 完整的主题配置将会在 v4 兼容包中提供。
|
||||
|
||||
## 定制主题
|
||||
|
||||
`theme` 是一系列 **Design Token** 的集合，当我们传入 `theme` 后，antd 的组件就会根据相应的 **Design Token** 改变自己的样式。
|
||||
|
||||
我们将依次介绍四类 **Design Token**
|
||||
|
||||
### 基础变量（Seed Token）
|
||||
|
||||
在大部分情况下，使用 **Seed Token** 就可以基本满足定制主题的需要，比如我们可以通过改变 `colorPrimary` 来改变主题色，antd 内部的算法会自动的根据 **Seed Token** 计算出对应的一系列颜色并应用：
|
||||
|
||||
```tsx
|
||||
const theme = {
|
||||
token: {
|
||||
colorPrimary: '#1890ff',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 梯度变量（Map Token）
|
||||
|
||||
**Map Token** 是基于 Seed 派生的梯度变量。定制 Map Token 推荐通过 `theme.algorithm` 来实现，这样可以保证 Map Token 之间的梯度关系。也可以通过 `theme.token` 覆盖，用于单独修改一些 map token 的值。
|
||||
|
||||
```tsx
|
||||
const theme = {
|
||||
token: {
|
||||
colorPrimaryBg: '#e6f7ff',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 别名变量（Alias Token）
|
||||
|
||||
Alias Token 用于批量控制某些共性组件的样式，基本上是 Map Token 别名，或者特殊处理过的 Map Token。
|
||||
|
||||
```tsx
|
||||
const theme = {
|
||||
token: {
|
||||
colorLink: '#1890ff',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 组件变量（Component Token）
|
||||
|
||||
除了整体的 Token 链路之外，各个组件也会开放自己的 Component Token 来实现针对组件的样式定制能力，不同的组件之间不会相互影响。同样地，也可以通过这种方式来覆盖组件的其他 Design Token。
|
||||
|
||||
```tsx
|
||||
const theme = {
|
||||
components: {
|
||||
Menu: {
|
||||
colorItemText: 'rgba(0, 0, 0, 0.88)',
|
||||
colorLink: '#1890ff',
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 基本算法（algorithm)
|
||||
|
||||
基本算法用于将 Seed Token 展开为 Map Token，比如由一个基本色算出一个梯度色板，或者由一个基本的圆角算出各种大小的圆角。在 v5 中，我们默认提供了三种算法，分别是默认算法（defaultAlgorithm）、暗色算法（darkAlgorithm）和紧凑算法（compactAlgorithm）。算法可以任意地组合使用，比如可以将暗色算法和紧凑算法组合使用，得到一个暗色和紧凑相结合的主题。
|
||||
|
||||
```tsx
|
||||
import { theme } from 'antd';
|
||||
|
||||
const { darkAlgorithm, compactAlgorithm } = theme;
|
||||
|
||||
const theme = {
|
||||
algorithm: [darkAlgorithm, compactAlgorithm],
|
||||
};
|
||||
```
|
||||
|
||||
### 演变过程
|
||||
|
||||
|
||||
|
||||
## 动态主题的其他使用方式
|
||||
|
||||
### 动态切换
|
||||
|
||||
在 v5 中，动态切换主题对用户来说是非常简单的，你可以在任何时候通过 `ConfigProvider` 的 `theme` 属性来动态切换主题，而不用额外配置任何东西。
|
||||
|
||||
### 局部主题
|
||||
|
||||
> TODO
|
||||
可以嵌套使用 `ConfigProvider` 来实现局部主题的更换。在子主题中未被改变的 Design Token 将会继承父主题。
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import { ConfigProvider, Button } from 'antd';
|
||||
|
||||
const App: React.FC = () => (
|
||||
<ConfigProvider
|
||||
theme={{
|
||||
token: {
|
||||
colorPrimary: '#1677ff',
|
||||
},
|
||||
}}
|
||||
>
|
||||
<Button />
|
||||
<ConfigProvider
|
||||
theme={{
|
||||
token: {
|
||||
colorPrimary: '#1890ff',
|
||||
},
|
||||
}}
|
||||
>
|
||||
<Button />
|
||||
</ConfigProvider>
|
||||
</ConfigProvider>
|
||||
);
|
||||
|
||||
export default App;
|
||||
```
|
||||
|
||||
### 使用 Design Token
|
||||
|
||||
如果你希望使用当前主题下的 Design Token，我们提供了 `useToken` 这个 hook 来获取 Design Token。
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import { Button, theme } from 'antd';
|
||||
|
||||
const { useToken } = theme;
|
||||
|
||||
const App: React.FC = () => {
|
||||
const { token } = useToken();
|
||||
|
||||
return <Button style={{ backgroundColor: token.colorPrimary }}>Button</Button>;
|
||||
};
|
||||
|
||||
export default App;
|
||||
```
|
||||
|
||||
### 在 umi 4 中定制主题
|
||||
|
||||
> TODO
|
||||
|
||||
### API (暂定)
|
||||
## API
|
||||
|
||||
#### Theme
|
||||
### Theme
|
||||
|
||||
| 属性 | 类型 | 默认值 | 说明 |
|
||||
| 属性 | 说明 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| token | `AliasToken` | - | 用于修改 Design Token |
|
||||
| algorithm | `(token: SeedToken) => MapToken` \| `((token: SeedToken) => MapToken)[]` | `defaultAlgorithm` | 用于修改 Seed Token 到 Map Token 的算法 |
|
||||
| components | OverrideToken | - | 用于修改各个组件的 Component Token 以及覆盖该组件消费的 Alias Token |
|
||||
| token | 用于修改 Design Token | `AliasToken` | - |
|
||||
| algorithm | 用于修改 Seed Token 到 Map Token 的算法 | `(token: SeedToken) => MapToken` \| `((token: SeedToken) => MapToken)[]` | `defaultAlgorithm` |
|
||||
| components | 用于修改各个组件的 Component Token 以及覆盖该组件消费的 Alias Token | OverrideToken | - |
|
||||
|
||||
#### OverrideToken
|
||||
### OverrideToken
|
||||
|
||||
| 属性 | 类型 | 默认值 | 说明 |
|
||||
| 属性 | 说明 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Component` (可以是任意 antd 组件名，如 `Button`) | `ComponentToken & AliasToken` | - | 用于修改 Component Token 以及覆盖该组件消费的 Alias Token |
|
||||
| `Component` (可以是任意 antd 组件名，如 `Button`) | 用于修改 Component Token 以及覆盖该组件消费的 Alias Token | `ComponentToken & AliasToken` | - |
|
||||
|
||||
#### SeedToken
|
||||
### SeedToken
|
||||
|
||||
| 属性 | 类型 | 默认值 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| colorPrimary | `string` | `#1677ff` | 品牌主色 |
|
||||
| colorSuccess | `string` | `#52c41a` | 成功色 |
|
||||
| colorWarning | `string` | `#faad14` | 警戒色 |
|
||||
| colorError | `string` | `#f5222d` | 错误色 |
|
||||
| colorInfo | `string` | `#1677ff` | 信息色 |
|
||||
| colorTextBase | `string` | `#000` | 基础文本色 |
|
||||
| colorTextLightSolid | `string` | `#fff` | 亮色文本色 |
|
||||
| colorBgBase | `string` | `#fff` | 基础背景色 |
|
||||
| fontFamily | `string` | `-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji'` | 字体 |
|
||||
| fontSizeBase | `number` | `14` | 基础字号 |
|
||||
| gridUnit | `number` | `4` | - |
|
||||
| gridBaseStep | `number` | `2` | - |
|
||||
| 属性 | 说明 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| colorPrimary | 品牌主色 | `string` | `#1677ff` |
|
||||
| colorSuccess | 成功色 | `string` | `#52c41a` |
|
||||
| colorWarning | 警戒色 | `string` | `#faad14` |
|
||||
| colorError | 错误色 | `string` | `#f5222d` |
|
||||
| colorInfo | 信息色 | `string` | `#1677ff` |
|
||||
| colorTextBase | 基础文本色 | `string` | `#000` |
|
||||
| colorTextLightSolid | 亮色文本色 | `string` | `#fff` |
|
||||
| colorBgBase | 基础背景色 | `string` | `#fff` |
|
||||
| fontFamily | 字体 | `string` | `-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji'` |
|
||||
| fontSizeBase | 基础字号 | `number` | `14` |
|
||||
| gridUnit | - | `number` | `4` |
|
||||
| gridBaseStep | - | `number` | `2` |
|
||||
| lineWidth | `number` | `1` | 基础线宽 |
|
||||
| lineType | `string` | `solid` | 线条样式 |
|
||||
| motionUnit | `number` | `0.1` | 动画时长变化单位 |
|
||||
| motionBase | `number` | `0` | 动画基础时长 |
|
||||
| motionEaseOutCirc | `string` | `cubic-bezier(0.08, 0.82, 0.17, 1)` | - |
|
||||
| motionEaseInOutCirc | `string` | `cubic-bezier(0.78, 0.14, 0.15, 0.86)` | - |
|
||||
| motionEaseOut | `string` | `cubic-bezier(0.215, 0.61, 0.355, 1)` | - |
|
||||
| motionEaseInOut | `string` | `cubic-bezier(0.645, 0.045, 0.355, 1)` | - |
|
||||
| motionEaseOutBack | `string` | `cubic-bezier(0.12, 0.4, 0.29, 1.46)` | - |
|
||||
| motionEaseInQuint | `string` | `cubic-bezier(0.645, 0.045, 0.355, 1)` | - |
|
||||
| motionEaseOutQuint | `string` | `cubic-bezier(0.23, 1, 0.32, 1)` | - |
|
||||
| radiusBase | `number` | `6` | 基础圆角 |
|
||||
| sizeUnit | `number` | `4` | 尺寸变化单位 |
|
||||
| sizeBaseStep | `number` | `4` | 尺寸基础大小 |
|
||||
| sizePopupArrow | `number` | `16` | 组件箭头尺寸 |
|
||||
| controlHeight | `number` | `32` | - |
|
||||
| zIndexBase | `number` | `0` | 基础 `z-index` |
|
||||
| zIndexPopupBase | `number` | `1000` | 浮层基础 `z-index` |
|
||||
| opacityImage | `number` | `1` | - |
|
||||
| wireframe | `boolean` | `false` | 线框化 |
|
||||
| motionEaseOutCirc | - | `string` | `cubic-bezier(0.08, 0.82, 0.17, 1)` |
|
||||
| motionEaseInOutCirc | `string` | `cubic-bezier(0.78, 0.14, 0.15, 0.86)` |
|
||||
| motionEaseOut | - | `string` | `cubic-bezier(0.215, 0.61, 0.355, 1)` | - |
|
||||
| motionEaseInOut | - | `string` | `cubic-bezier(0.645, 0.045, 0.355, 1)` |
|
||||
| motionEaseOutBack | - | `string` | `cubic-bezier(0.12, 0.4, 0.29, 1.46)` |
|
||||
| motionEaseInQuint | - | `string` | `cubic-bezier(0.645, 0.045, 0.355, 1)` |
|
||||
| motionEaseOutQuint | - | `string` | `cubic-bezier(0.23, 1, 0.32, 1)` |
|
||||
| radiusBase | 基础圆角 | `number` | `6` |
|
||||
| sizeUnit | 尺寸变化单位 | `number` | `4` |
|
||||
| sizeBaseStep | 尺寸基础大小 | `number` | `4` |
|
||||
| sizePopupArrow | 组件箭头尺寸 | `number` | `16` |
|
||||
| controlHeight | - | `number` | `32` |
|
||||
| zIndexBase | 基础 `z-index` | `number` | `0` |
|
||||
| zIndexPopupBase | 浮层基础 `z-index` | `number` | `1000` |
|
||||
| opacityImage | - | `number` | `1` |
|
||||
| wireframe | 线框化 | `boolean` | `false` |
|
||||
|
||||
#### MapToken
|
||||
### MapToken
|
||||
|
||||
| 属性 | 类型 | 默认值 | 说明 |
|
||||
| 属性 | 说明 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| colorText | `string` | `rgba(0, 0, 0, 0.88)` | 一级文本色 |
|
||||
| colorTextSecondary | `string` | `rgba(0, 0, 0, 0.65)` | 二级文本色 |
|
||||
| colorTextTertiary | `string` | `rgba(0, 0, 0, 0.45)` | 三级文本色 |
|
||||
| colorTextQuaternary | `string` | `rgba(0, 0, 0, 0.25)` | 四级文本色 |
|
||||
| colorFill | `string` | `rgba(0, 0, 0, 0.15)` | 一级填充色 |
|
||||
| colorFillSecondary | `string` | `rgba(0, 0, 0, 0.06)` | 二级填充色 |
|
||||
| colorFillTertiary | `string` | `rgba(0, 0, 0, 0.04)` | 三级填充色 |
|
||||
| colorFillQuaternary | `string` | `rgba(0, 0, 0, 0.02)` | 四级填充色 |
|
||||
| colorBgContainer | `string` | `#ffffff` | 组件容器背景色 |
|
||||
| colorBgElevated | `string` | `#ffffff` | 浮层容器背景色 |
|
||||
| colorBgLayout | `string` | `#f5f5f5` | 布局背景色 |
|
||||
| colorBgSpotlight | `string` | `rgba(0, 0, 0, 0.85)` | - |
|
||||
| colorBorder | `string` | `#d9d9d9` | 一级边框色 |
|
||||
| colorBorderSecondary | `string` | `#f0f0f0` | 二级边框色 |
|
||||
| colorSplit | `string` | `rgba(0, 0, 0, 0.06)` | 分割线颜色 |
|
||||
| colorPrimaryBg | `string` | `#e6f4ff` | 主色的浅色背景颜色 |
|
||||
| colorPrimaryBgHover | `string` | `#bae0ff` | 主色的浅色背景色悬浮态 |
|
||||
| colorPrimaryBorder | `string` | `#91caff` | 主色的描边色 |
|
||||
| colorPrimaryBorderHover | `string` | `#69b1ff` | 主色的描边色悬浮态 |
|
||||
| colorPrimaryHover | `string` | `#4096ff` | 主色的深色悬浮态 |
|
||||
| colorPrimary | `string` | `#1677ff` | 品牌主色 |
|
||||
| colorPrimaryActive | `string` | `#0958d9` | 主色的深色激活态 |
|
||||
| colorPrimaryTextHover | `string` | `#4096ff` | 主色的文本悬浮态 |
|
||||
| colorPrimaryText | `string` | `#1677ff` | 主色的文本默认态 |
|
||||
| colorPrimaryTextActive | `string` | `#0958d9` | 主色的文本激活态 |
|
||||
| colorSuccessBg | `string` | `#f6ffed` | 成功色的浅色背景颜色 |
|
||||
| colorSuccessBgHover | `string` | `#d9f7be` | 成功色的浅色背景色悬浮态 |
|
||||
| colorSuccessBorder | `string` | `#b7eb8f` | 成功色的描边色 |
|
||||
| colorSuccessBorderHover | `string` | `#95de64` | 成功色的描边色悬浮态 |
|
||||
| colorSuccessHover | `string` | `#95de64` | 成功色的深色悬浮态 |
|
||||
| colorSuccess | `string` | `#52c41a` | 成功色 |
|
||||
| colorSuccessActive | `string` | `#389e0d` | 成功色的深色激活态 |
|
||||
| colorSuccessTextHover | `string` | `#73d13d` | 成功色的文本悬浮态 |
|
||||
| colorSuccessText | `string` | `#52c41a` | 成功色的文本默认态 |
|
||||
| colorSuccessTextActive | `string` | `#389e0d` | 成功色的文本激活态 |
|
||||
| colorWarningBg | `string` | `#fffbe6` | 警戒色的浅色背景颜色 |
|
||||
| colorWarningBgHover | `string` | `#fff1b8` | 警戒色的浅色背景色悬浮态 |
|
||||
| colorWarningBorder | `string` | `#ffe58f` | 警戒色的描边色 |
|
||||
| colorWarningBorderHover | `string` | `#ffd666` | 警戒色的描边色悬浮态 |
|
||||
| colorWarningHover | `string` | `#ffd666` | 警戒色的深色悬浮态 |
|
||||
| colorWarning | `string` | `#faad14` | 警戒色 |
|
||||
| colorWarningActive | `string` | `#d48806` | 警戒色的深色激活态 |
|
||||
| colorWarningTextHover | `string` | `#ffc53d` | 警戒色的文本悬浮态 |
|
||||
| colorWarningText | `string` | `#faad14` | 警戒色的文本默认态 |
|
||||
| colorWarningTextActive | `string` | `#d48806` | 警戒色的文本激活态 |
|
||||
| colorErrorBg | `string` | `#fff1f0` | 错误色的浅色背景颜色 |
|
||||
| colorErrorBgHover | `string` | `#ffccc7` | 错误色的浅色背景色悬浮态 |
|
||||
| colorErrorBorder | `string` | `#ffa39e` | 错误色的描边色 |
|
||||
| colorErrorBorderHover | `string` | `#ff7875` | 错误色的描边色悬浮态 |
|
||||
| colorErrorHover | `string` | `#ff7875` | 错误色的深色悬浮态 |
|
||||
| colorError | `string` | `#ff4d4f` | 错误色 |
|
||||
| colorErrorActive | `string` | `#cf1322` | 错误色的深色激活态 |
|
||||
| colorErrorTextHover | `string` | `#ff4d4f` | 错误色的文本悬浮态 |
|
||||
| colorErrorText | `string` | `#f5222d` | 错误色的文本默认态 |
|
||||
| colorErrorTextActive | `string` | `#cf1322` | 错误色的文本激活态 |
|
||||
| colorInfoBg | `string` | `#e6f4ff` | 信息色的浅色背景颜色 |
|
||||
| colorInfoBgHover | `string` | `#bae0ff` | 信息色的浅色背景色悬浮态 |
|
||||
| colorInfoBorder | `string` | `#91caff` | 信息色的描边色 |
|
||||
| colorInfoBorderHover | `string` | `#69b1ff` | 信息色的描边色悬浮态 |
|
||||
| colorInfoHover | `string` | `#69b1ff` | 信息色的深色悬浮态 |
|
||||
| colorInfo | `string` | `#e6f4ff` | 信息色 |
|
||||
| colorInfoActive | `string` | `#0958d9` | 信息色的深色激活态 |
|
||||
| colorInfoTextHover | `string` | `#4096ff` | 信息色的文本悬浮态 |
|
||||
| colorInfoText | `string` | `#1677ff` | 信息色的文本默认态 |
|
||||
| colorInfoTextActive | `string` | `#0958d9` | 信息色的文本激活态 |
|
||||
| colorBgMask | `string` | `rgba(0, 0, 0, 0.45)` | 浮层的背景蒙层颜色 |
|
||||
| sizeSpace | `number` | `12` | - |
|
||||
| sizeSpaceSM | `number` | `16` | - |
|
||||
| sizeSpaceXS | `number` | `8` | - |
|
||||
| sizeSpaceXXS | `number` | `4` | - |
|
||||
| gridSpaceSM | `number` | `4` | - |
|
||||
| gridSpaceBase | `number` | `8` | - |
|
||||
| gridSpaceLG | `number` | `12` | - |
|
||||
| gridSpaceXL | `number` | `16` | - |
|
||||
| gridSpaceXXL | `number` | `28` | - |
|
||||
| lineWidthBold | `number` | `2` | 较粗的线宽 |
|
||||
| motionDurationFast | `string` | `0.1s` | 动画速度快 |
|
||||
| motionDurationMid | `string` | `0.2s` | 动画速度中等 |
|
||||
| motionDurationSlow | `string` | `0.3s` | 动画速度慢 |
|
||||
| radiusXS | `number` | `2` | 更小的圆角 |
|
||||
| radiusSM | `number` | `4` | 较小的圆角 |
|
||||
| radiusLG | `number` | `8` | 较大的圆角 |
|
||||
| radiusOuter | `number` | `4` | 向外的圆角（常用于箭头与其他元素相接处） |
|
||||
| controlHeightXS | `number` | `24` | - |
|
||||
| controlHeightSM | `number` | `16` | - |
|
||||
| controlHeightLG | `number` | `40` | - |
|
||||
| colorText | 一级文本色 | `string` | `rgba(0, 0, 0, 0.88)` |
|
||||
| colorTextSecondary | 二级文本色 | `string` | `rgba(0, 0, 0, 0.65)` |
|
||||
| colorTextTertiary | 三级文本色 | `string` | `rgba(0, 0, 0, 0.45)` |
|
||||
| colorTextQuaternary | 四级文本色 | `string` | `rgba(0, 0, 0, 0.25)` |
|
||||
| colorFill | 一级填充色 | `string` | `rgba(0, 0, 0, 0.15)` |
|
||||
| colorFillSecondary | 二级填充色 | `string` | `rgba(0, 0, 0, 0.06)` |
|
||||
| colorFillTertiary | 三级填充色 | `string` | `rgba(0, 0, 0, 0.04)` |
|
||||
| colorFillQuaternary | 四级填充色 | `string` | `rgba(0, 0, 0, 0.02)` |
|
||||
| colorBgContainer | 组件容器背景色 | `string` | `#ffffff` |
|
||||
| colorBgElevated | 浮层容器背景色 | `string` | `#ffffff` |
|
||||
| colorBgLayout | 布局背景色 | `string` | `#f5f5f5` |
|
||||
| colorBgSpotlight | - | `string` | `rgba(0, 0, 0, 0.85)` |
|
||||
| colorBorder | 一级边框色 | `string` | `#d9d9d9` |
|
||||
| colorBorderSecondary | 二级边框色 | `string` | `#f0f0f0` |
|
||||
| colorSplit | 分割线颜色 | `string` | `rgba(0, 0, 0, 0.06)` |
|
||||
| colorPrimaryBg | 主色的浅色背景颜色 | `string` | `#e6f4ff` |
|
||||
| colorPrimaryBgHover | 主色的浅色背景色悬浮态 | `string` | `#bae0ff` |
|
||||
| colorPrimaryBorder | 主色的描边色 | `string` | `#91caff` |
|
||||
| colorPrimaryBorderHover | 主色的描边色悬浮态 | `string` | `#69b1ff` |
|
||||
| colorPrimaryHover | 主色的深色悬浮态 | `string` | `#4096ff` |
|
||||
| colorPrimary | 品牌主色 | `string` | `#1677ff` |
|
||||
| colorPrimaryActive | 主色的深色激活态 | `string` | `#0958d9` |
|
||||
| colorPrimaryTextHover | 主色的文本悬浮态 | `string` | `#4096ff` |
|
||||
| colorPrimaryText | 主色的文本默认态 | `string` | `#1677ff` |
|
||||
| colorPrimaryTextActive | 主色的文本激活态 | `string` | `#0958d9` |
|
||||
| colorSuccessBg | 成功色的浅色背景颜色 | `string` | `#f6ffed` |
|
||||
| colorSuccessBgHover | 成功色的浅色背景色悬浮态 | `string` | `#d9f7be` |
|
||||
| colorSuccessBorder | 成功色的描边色 | `string` | `#b7eb8f` |
|
||||
| colorSuccessBorderHover | 成功色的描边色悬浮态 | `string` | `#95de64` |
|
||||
| colorSuccessHover | 成功色的深色悬浮态 | `string` | `#95de64` |
|
||||
| colorSuccess | 成功色 | `string` | `#52c41a` |
|
||||
| colorSuccessActive | 成功色的深色激活态 | `string` | `#389e0d` |
|
||||
| colorSuccessTextHover | 成功色的文本悬浮态 | `string` | `#73d13d` |
|
||||
| colorSuccessText | 成功色的文本默认态 | `string` | `#52c41a` |
|
||||
| colorSuccessTextActive | 成功色的文本激活态 | `string` | `#389e0d` |
|
||||
| colorWarningBg | 警戒色的浅色背景颜色 | `string` | `#fffbe6` |
|
||||
| colorWarningBgHover | 警戒色的浅色背景色悬浮态 | `string` | `#fff1b8` |
|
||||
| colorWarningBorder | 警戒色的描边色 | `string` | `#ffe58f` |
|
||||
| colorWarningBorderHover | 警戒色的描边色悬浮态 | `string` | `#ffd666` |
|
||||
| colorWarningHover | 警戒色的深色悬浮态 | `string` | `#ffd666` |
|
||||
| colorWarning | 警戒色 | `string` | `#faad14` |
|
||||
| colorWarningActive | 警戒色的深色激活态 | `string` | `#d48806` |
|
||||
| colorWarningTextHover | 警戒色的文本悬浮态 | `string` | `#ffc53d` |
|
||||
| colorWarningText | 警戒色的文本默认态 | `string` | `#faad14` |
|
||||
| colorWarningTextActive | 警戒色的文本激活态 | `string` | `#d48806` |
|
||||
| colorErrorBg | 错误色的浅色背景颜色 | `string` | `#fff1f0` |
|
||||
| colorErrorBgHover | 错误色的浅色背景色悬浮态 | `string` | `#ffccc7` |
|
||||
| colorErrorBorder | 错误色的描边色 | `string` | `#ffa39e` |
|
||||
| colorErrorBorderHover | 错误色的描边色悬浮态 | `string` | `#ff7875` |
|
||||
| colorErrorHover | 错误色的深色悬浮态 | `string` | `#ff7875` |
|
||||
| colorError | 错误色 | `string` | `#ff4d4f` |
|
||||
| colorErrorActive | 错误色的深色激活态 | `string` | `#cf1322` |
|
||||
| colorErrorTextHover | 错误色的文本悬浮态 | `string` | `#ff4d4f` |
|
||||
| colorErrorText | 错误色的文本默认态 | `string` | `#f5222d` |
|
||||
| colorErrorTextActive | 错误色的文本激活态 | `string` | `#cf1322` |
|
||||
| colorInfoBg | 信息色的浅色背景颜色 | `string` | `#e6f4ff` |
|
||||
| colorInfoBgHover | 信息色的浅色背景色悬浮态 | `string` | `#bae0ff` |
|
||||
| colorInfoBorder | 信息色的描边色 | `string` | `#91caff` |
|
||||
| colorInfoBorderHover | 信息色的描边色悬浮态 | `string` | `#69b1ff` |
|
||||
| colorInfoHover | 信息色的深色悬浮态 | `string` | `#69b1ff` |
|
||||
| colorInfo | 信息色 | `string` | `#e6f4ff` |
|
||||
| colorInfoActive | 信息色的深色激活态 | `string` | `#0958d9` |
|
||||
| colorInfoTextHover | 信息色的文本悬浮态 | `string` | `#4096ff` |
|
||||
| colorInfoText | 信息色的文本默认态 | `string` | `#1677ff` |
|
||||
| colorInfoTextActive | 信息色的文本激活态 | `string` | `#0958d9` |
|
||||
| colorBgMask | 浮层的背景蒙层颜色 | `string` | `rgba(0, 0, 0, 0.45)` |
|
||||
| sizeSpace | - | `number` | `12` |
|
||||
| sizeSpaceSM | - | `number` | `16` |
|
||||
| sizeSpaceXS | - | `number` | `8` |
|
||||
| sizeSpaceXXS | - | `number` | `4` |
|
||||
| gridSpaceSM | - | `number` | `4` |
|
||||
| gridSpaceBase | - | `number` | `8` |
|
||||
| gridSpaceLG | - | `number` | `12` |
|
||||
| gridSpaceXL | - | `number` | `16` |
|
||||
| gridSpaceXXL | - | `number` | `28` |
|
||||
| lineWidthBold | 较粗的线宽 | `number` | `2` |
|
||||
| motionDurationFast | 动画速度快 | `string` | `0.1s` |
|
||||
| motionDurationMid | 动画速度中等 | `string` | `0.2s` |
|
||||
| motionDurationSlow | 动画速度慢 | `string` | `0.3s` |
|
||||
| radiusXS | 更小的圆角 | `number` | `2` |
|
||||
| radiusSM | 较小的圆角 | `number` | `4` |
|
||||
| radiusLG | 较大的圆角 | `number` | `8` |
|
||||
| radiusOuter | 向外的圆角（常用于箭头与其他元素相接处） | `number` | `4` |
|
||||
| controlHeightXS | - | `number` | `24` |
|
||||
| controlHeightSM | - | `number` | `16` |
|
||||
| controlHeightLG | - | `number` | `40` |
|
||||
|
||||
#### AliasToken (待补全)
|
||||
### AliasToken (待补全)
|
||||
|
||||
| 属性 | 类型 | 默认值 | 说明 |
|
||||
| ------------------- | -------- | --------- | ---------------------------------------- |
|
||||
| controlItemBgActive | `string` | `#e6f4ff` | 用于控件类组件中的单项的激活态选中样式。 |
|
||||
| 属性 | 说明 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| colorFillContent | - | `string` | `rgba(0, 0, 0, 0.06)` |
|
||||
| colorFillContentHover | - | `string` | `rgba(0, 0, 0, 0.12)` |
|
||||
| colorFillAlter | - | `string` | `rgba(0, 0, 0, 0.02)` |
|
||||
| colorBgContainerDisabled | - | `string` | `rgba(0, 0, 0, 0.04)` |
|
||||
| colorBorderBg | - | `string` | `#ffffff` |
|
||||
| colorSplit | - | `string` | `rgba(0, 0, 0, 0.06)` |
|
||||
| colorTextPlaceholder | - | `string` | `rgba(0, 0, 0, 0.25)` |
|
||||
| colorTextDisabled | - | `string` | `rgba(0, 0, 0, 0.25)` |
|
||||
| colorTextHeading | - | `string` | `rgba(0, 0, 0, 0.85)` |
|
||||
| colorTextLabel | - | `string` | `rgba(0, 0, 0, 0.65)` |
|
||||
| colorTextDescription | - | `string` | `rgba(0, 0, 0, 0.45)` |
|
||||
| colorBgTextHover | - | `string` | `rgba(0, 0, 0, 0.06)` |
|
||||
| colorBgTextActive | - | `string` | `rgba(0, 0, 0, 0.15)` |
|
||||
| colorIcon | - | `string` | `rgba(0, 0, 0, 0.45)` |
|
||||
| colorIconHover | - | `string` | `rgba(0, 0, 0, 0.88)` |
|
||||
| colorLink | - | `string` | `#1677ff` |
|
||||
| colorLinkHover | - | `string` | `#69b1ff` |
|
||||
| colorLinkActive | - | `string` | `#0958d9` |
|
||||
| colorHighlight | - | `string` | `#ff4d4f` |
|
||||
| controlOutline | - | `string` | `rgba(5, 145, 255, 0.1)` |
|
||||
| colorWarningOutline | - | `string` | `rgba(255, 215, 5, 0.1)` |
|
||||
| colorErrorOutline | - | `string` | `rgba(255, 22, 5, 0.06)` |
|
||||
| fontSizeSM | - | `number` | `12` |
|
||||
| fontSize | - | `number` | `14` |
|
||||
| fontSizeLG | - | `number` | `16` |
|
||||
| fontSizeXL | - | `number` | `20` |
|
||||
| fontSizeIcon | - | `number` | `12` |
|
||||
| fontSizeHeading1 | - | `number` | `38` |
|
||||
| fontSizeHeading2 | - | `number` | `30` |
|
||||
| fontSizeHeading3 | - | `number` | `24` |
|
||||
| fontSizeHeading4 | - | `number` | `20` |
|
||||
| fontSizeHeading5 | - | `number` | `16` |
|
||||
| fontWeightStrong | - | `number` | `600` |
|
||||
| lineHeight | - | `number` | `1.5714` |
|
||||
| lineHeightLG | - | `number` | `1.5` |
|
||||
| lineHeightSM | - | `number` | `1.6667` |
|
||||
| lineHeightHeading1 | - | `number` | `1.2105` |
|
||||
| lineHeightHeading2 | - | `number` | `1.2667` |
|
||||
| lineHeightHeading3 | - | `number` | `1.3333` |
|
||||
| lineHeightHeading4 | - | `number` | `1.4` |
|
||||
| lineHeightHeading5 | - | `number` | `1.5` |
|
||||
| controlLineWidth | - | `number` | `1` |
|
||||
| controlLineType | - | `string` | `solid` |
|
||||
| controlRadius | - | `number` | `6` |
|
||||
| controlRadiusXS | - | `number` | `2` |
|
||||
| controlRadiusSM | - | `number` | `4` |
|
||||
| controlRadiusLG | - | `number` | `8` |
|
||||
| controlOutlineWidth | - | `number` | `8` |
|
||||
| controlItemBgHover | - | `string` | `rgba(0, 0, 0, 0.04)` |
|
||||
| controlItemBgActive | - | `string` | `#e6f4ff` |
|
||||
| controlItemBgActiveHover | - | `string` | `#bae0ff` |
|
||||
| controlInteractiveSize | - | `number` | `16` |
|
||||
| controlItemBgActiveDisabled | - | `string` | `rgba(0, 0, 0, 0.15)` |
|
||||
| controlTmpOutline | - | `string` | `rgba(0, 0, 0, 0.02)` |
|
||||
| opacityLoading | - | `number` | `0.65` |
|
||||
| padding | - | `number` | `16` |
|
||||
| paddingSM | - | `number` | `12` |
|
||||
| paddingXS | - | `number` | `8` |
|
||||
| paddingXXS | - | `number` | `4` |
|
||||
| paddingLG | - | `number` | `24` |
|
||||
| paddingXL | - | `number` | `32` |
|
||||
| paddingTmp | - | `number` | `20` |
|
||||
| margin | - | `number` | `16` |
|
||||
| marginSM | - | `number` | `12` |
|
||||
| marginXS | - | `number` | `8` |
|
||||
| marginXXS | - | `number` | `4` |
|
||||
| marginLG | - | `number` | `24` |
|
||||
| marginXL | - | `number` | `32` |
|
||||
| marginXXL | - | `number` | `48` |
|
||||
| boxShadow | - | `string` | `0 1px 2px 0 rgba(0, 0, 0, 0.03), 0 1px 6px -1px rgba(0, 0, 0, 0.02), 0 2px 4px 0 rgba(0, 0, 0, 0.02)` |
|
||||
| boxShadowSecondary | - | `string` | `0 6px 16px 0 rgba(0, 0, 0, 0.08), 0 3px 6px -4px rgba(0, 0, 0, 0.12), 0 9px 28px 8px rgba(0, 0, 0, 0.05)` |
|
||||
| linkDecoration | - | `React.CSSProperties['textDecoration']` | `none` |
|
||||
| linkHoverDecoration | - | `React.CSSProperties['textDecoration']` | `none` |
|
||||
| linkFocusDecoration | - | `React.CSSProperties['textDecoration']` | `none` |
|
||||
| controlPaddingHorizontal | - | `number` | `12` |
|
||||
| controlPaddingHorizontalSM | - | `number` | `8` |
|
||||
| screenXS | - | `number` | `480` |
|
||||
| screenXSMin | - | `number` | `480` |
|
||||
| screenXSMax | - | `number` | `479` |
|
||||
| screenSM | - | `number` | `576` |
|
||||
| screenSMMin | - | `number` | `576` |
|
||||
| screenSMMax | - | `number` | `575` |
|
||||
| screenMD | - | `number` | `768` |
|
||||
| screenMDMin | - | `number` | `768` |
|
||||
| screenMDMax | - | `number` | `767` |
|
||||
| screenLG | - | `number` | `992` |
|
||||
| screenLGMin | - | `number` | `992` |
|
||||
| screenLGMax | - | `number` | `991` |
|
||||
| screenXL | - | `number` | `1200` |
|
||||
| screenXLMin | - | `number` | `1200` |
|
||||
| screenXLMax | - | `number` | `1199` |
|
||||
| screenXXL | - | `number` | `1600` |
|
||||
| screenXXLMin | - | `number` | `1599` |
|
||||
| screenXXLMax | - | `number` | `1600` |
|
||||
|
||||
### 调试主题
|
||||
## 调试主题
|
||||
|
||||
我们提供了帮助用户调试主题的工具：[主题编辑器](https://ant-design.github.io/antd-token-previewer/~demos/docs-theme-editor-simple)
|
||||
|
||||
@ -237,8 +430,6 @@ export default () => (
|
||||
|
||||
- [Ant Design 4.x 主题](https://ant-design.github.io/antd-token-previewer/~demos/docs-v4-theme)
|
||||
|
||||
> 可以引导用户贡献一些优质主题并收集起来
|
||||
|
||||
## FAQ
|
||||
|
||||
### 为什么 `theme` 从 `undefined` 变为对象或者变为 `undefined` 时组件重新 mount 了？
|
||||
|
||||
@ -1,81 +0,0 @@
|
||||
---
|
||||
order: 7.1
|
||||
title: Dynamic Theme (Experimental)
|
||||
---
|
||||
|
||||
Except [less customize theme](/docs/react/customize-theme), We also provide CSS Variable version to enable dynamic theme. You can check on [ConfigProvider](/components/config-provider/#components-config-provider-demo-theme) demo.
|
||||
|
||||
## Caveats
|
||||
|
||||
- This function depends on CSS Variables. Please check the [browser compatibility](https://caniuse.com/css-variables).
|
||||
- This function requires at least `antd@4.17.0-alpha.0`.
|
||||
|
||||
## How to use
|
||||
|
||||
### Import antd.variable.min.css
|
||||
|
||||
Replace your import style file with CSS Variable version:
|
||||
|
||||
```diff
|
||||
-- import 'antd/dist/antd.min.css';
|
||||
++ import 'antd/dist/antd.variable.min.css';
|
||||
```
|
||||
|
||||
Note: You need remove `babel-plugin-import` for the dynamic theme.
|
||||
|
||||
### Static config
|
||||
|
||||
Call ConfigProvider static function to modify theme color:
|
||||
|
||||
```ts
|
||||
import { ConfigProvider } from 'antd';
|
||||
|
||||
ConfigProvider.config({
|
||||
theme: {
|
||||
primaryColor: '#25b864',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## Conflict resolve
|
||||
|
||||
CSS Variable use `--ant` prefix by default. When exist multiple antd style file in your project, you can modify prefix to fix it.
|
||||
|
||||
### Adjust
|
||||
|
||||
Modify `prefixCls` on the root of ConfigProvider:
|
||||
|
||||
```tsx
|
||||
import { ConfigProvider } from 'antd';
|
||||
|
||||
export default () => (
|
||||
<ConfigProvider prefixCls="custom">
|
||||
<MyApp />
|
||||
</ConfigProvider>
|
||||
);
|
||||
```
|
||||
|
||||
Also need call the static function to modify `prefixCls`:
|
||||
|
||||
```ts
|
||||
ConfigProvider.config({
|
||||
prefixCls: 'custom',
|
||||
theme: {
|
||||
primaryColor: '#25b864',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### Compile less
|
||||
|
||||
Since prefix modified. Origin `antd.variable.css` should also be replaced:
|
||||
|
||||
```bash
|
||||
lessc --js --modify-var="ant-prefix=custom" antd/dist/antd.variable.less modified.css
|
||||
```
|
||||
|
||||
### Related changes
|
||||
|
||||
In order to implement CSS Variable and maintain original usage compatibility, we added `@root-entry-name: xxx;` entry injection to the `dist/antd.xxx.less` file to support less dynamic loading of the corresponding less file. Under normal circumstances, you do not need to pay attention to this change. However, if your project directly references the less file in the `lib|es` directory. You need to configure `@root-entry-name: default;` (or `@root-entry-name: variable;`) at the entry of less so that less can find the correct entry.
|
||||
|
||||
In addition, we migrated `@import'motion'` and `@import'reset'` in `lib|es/style/minxins/index.less` to `lib|es/style/themes/xxx.less` In, because these two files rely on theme-related variables. If you use the relevant internal method, please adjust it yourself. Of course, we still recommend using the `antd.less` files in the `dist` directory directly instead of calling internal files, because they are often affected by refactoring.
|
||||
@ -1,81 +0,0 @@
|
||||
---
|
||||
order: 7.1
|
||||
title: 动态主题（实验性）
|
||||
---
|
||||
|
||||
除了 [less 定制主题](/docs/react/customize-theme) 外，我们还提供了 CSS Variable 版本以支持动态切换主题能力。你可以在 [ConfigProvider](/components/config-provider/#components-config-provider-demo-theme) 进行体验。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 该功能通过动态修改 CSS Variable 实现，因而在 IE 中页面将无法正常展示。请先确认你的用户环境是否需要支持 IE。
|
||||
- 该功能在 `antd@4.17.0-alpha.0` 版本起支持。
|
||||
|
||||
## 如何使用
|
||||
|
||||
### 引入 antd.variable.min.css
|
||||
|
||||
替换当前项目引入样式文件为 CSS Variable 版本：
|
||||
|
||||
```diff
|
||||
-- import 'antd/dist/antd.min.css';
|
||||
++ import 'antd/dist/antd.variable.min.css';
|
||||
```
|
||||
|
||||
注：如果你使用了 `babel-plugin-import`，需要将其去除。
|
||||
|
||||
### 静态方法配置
|
||||
|
||||
调用 ConfigProvider 配置方法设置主题色：
|
||||
|
||||
```ts
|
||||
import { ConfigProvider } from 'antd';
|
||||
|
||||
ConfigProvider.config({
|
||||
theme: {
|
||||
primaryColor: '#25b864',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## 冲突解决
|
||||
|
||||
默认情况下，CSS Variable 会以 `--ant` 作为前缀。当你的项目中引用多份 css 文件时，可以通过修改前缀的方式避免冲突。
|
||||
|
||||
### 代码调整
|
||||
|
||||
通过 ConfigProvider 在顶层修改 `prefixCls`：
|
||||
|
||||
```tsx
|
||||
import { ConfigProvider } from 'antd';
|
||||
|
||||
export default () => (
|
||||
<ConfigProvider prefixCls="custom">
|
||||
<MyApp />
|
||||
</ConfigProvider>
|
||||
);
|
||||
```
|
||||
|
||||
通过静态方法设置主题色以及对应 `prefixCls`：
|
||||
|
||||
```ts
|
||||
ConfigProvider.config({
|
||||
prefixCls: 'custom',
|
||||
theme: {
|
||||
primaryColor: '#25b864',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### 编译 less
|
||||
|
||||
由于前缀变更，你需要重新生成一份对应的 css 文件。
|
||||
|
||||
```bash
|
||||
lessc --js --modify-var="ant-prefix=custom" antd/dist/antd.variable.less modified.css
|
||||
```
|
||||
|
||||
### 相关变更
|
||||
|
||||
为了实现 CSS Variable 并保持原始用法兼容性，我们于 `dist/antd.xxx.less` 文件中添加了 `@root-entry-name: xxx;` 入口注入以支持 less 动态加载对应的 less 文件。一般情况下，你不需要关注该变化。但是，如果你的项目中直接引用了 `lib|es` 目录下的 less 文件，那么你需要在 less 入口处配置 `@root-entry-name: default;` （或者 `@root-entry-name: variable;`）以使 less 可以找到正确的入口。
|
||||
|
||||
此外，我们将 `lib|es/style/minxins/index.less` 中的 `@import 'motion'` 和 `@import 'reset'` 迁移至了 `lib|es/style/themes/xxx.less` 中，因为这两个文件依赖了主题相关变量。如果你使用了相关内部方法，请自行调整。当然，我们还是建议直接使用 `dist` 目录下的 `antd.less` 文件而非调用内部文件，因为它们经常会受重构影响。
|
||||
@ -1,219 +0,0 @@
|
||||
---
|
||||
order: 7
|
||||
title: Customize Theme
|
||||
---
|
||||
|
||||
Ant Design allows you to customize our design tokens to satisfy UI diversity from business or brand requirements, including primary color, border radius, border color, etc.
|
||||
|
||||
|
||||
|
||||
## Ant Design Less variables
|
||||
|
||||
We are using [Less](http://lesscss.org/) as the development language for styling. A set of less variables are defined for each design aspect that can be customized to your needs.
|
||||
|
||||
There are some major variables below, all less variables could be found in [Default Variables](https://github.com/ant-design/ant-design/blob/master/components/style/themes/default.less).
|
||||
|
||||
```less
|
||||
@primary-color: #1890ff; // primary color for all components
|
||||
@link-color: #1890ff; // link color
|
||||
@success-color: #52c41a; // success state color
|
||||
@warning-color: #faad14; // warning state color
|
||||
@error-color: #f5222d; // error state color
|
||||
@font-size-base: 14px; // major text font size
|
||||
@heading-color: rgba(0, 0, 0, 0.85); // heading text color
|
||||
@text-color: rgba(0, 0, 0, 0.65); // major text color
|
||||
@text-color-secondary: rgba(0, 0, 0, 0.45); // secondary text color
|
||||
@disabled-color: rgba(0, 0, 0, 0.25); // disable state color
|
||||
@border-radius-base: 2px; // major border radius
|
||||
@border-color-base: #d9d9d9; // major border color
|
||||
@box-shadow-base: 0 3px 6px -4px rgba(0, 0, 0, 0.12), 0 6px 16px 0 rgba(0, 0, 0, 0.08),
|
||||
0 9px 28px 8px rgba(0, 0, 0, 0.05); // major shadow for layers
|
||||
```
|
||||
|
||||
Please report an issue if the existing list of variables is not enough for you.
|
||||
|
||||
## How to do it
|
||||
|
||||
We will use [modifyVars](http://lesscss.org/usage/#using-less-in-the-browser-modify-variables) provided by less.js to override the default values of the variables, You can use this [example](https://github.com/ant-design/create-react-app-antd) as a live playground. We now introduce some popular way to do it depends on different workflow.
|
||||
|
||||
### Customize in webpack
|
||||
|
||||
We take a typical `webpack.config.js` file as example to customize its [less-loader](https://github.com/webpack-contrib/less-loader) options.
|
||||
|
||||
```diff
|
||||
// webpack.config.js
|
||||
module.exports = {
|
||||
rules: [{
|
||||
test: /\.less$/,
|
||||
use: [{
|
||||
loader: 'style-loader',
|
||||
}, {
|
||||
loader: 'css-loader', // translates CSS into CommonJS
|
||||
}, {
|
||||
loader: 'less-loader', // compiles Less to CSS
|
||||
+ options: {
|
||||
+ lessOptions: { // If you are using less-loader@5 please spread the lessOptions to options directly
|
||||
+ modifyVars: {
|
||||
+ 'primary-color': '#1DA57A',
|
||||
+ 'link-color': '#1DA57A',
|
||||
+ 'border-radius-base': '2px',
|
||||
+ },
|
||||
+ javascriptEnabled: true,
|
||||
+ },
|
||||
+ },
|
||||
}],
|
||||
// ...other rules
|
||||
}],
|
||||
// ...other config
|
||||
}
|
||||
```
|
||||
|
||||
Note:
|
||||
|
||||
1. Don't exclude `node_modules/antd` when using less-loader.
|
||||
2. `lessOptions` usage is supported at [less-loader@6.0.0](https://github.com/webpack-contrib/less-loader/releases/tag/v6.0.0).
|
||||
|
||||
### Customize in Umi
|
||||
|
||||
You can easily use [theme](https://umijs.org/config/#theme) field in `.umirc.ts` or [config/config.ts](https://github.com/ant-design/ant-design-pro/blob/v5/config/config.ts) file of your project root directory if you are using [Umi](http://umijs.org/), which could be an object or a javascript file path.
|
||||
|
||||
```js
|
||||
"theme": {
|
||||
"primary-color": "#1DA57A",
|
||||
},
|
||||
```
|
||||
|
||||
Or just [a javascript file path](https://github.com/ant-design/ant-design-pro/blob/b7e7983661eb5e53dc807452e9653e93e74276d4/.webpackrc.js#L18):
|
||||
|
||||
```js
|
||||
"theme": "./theme.js",
|
||||
```
|
||||
|
||||
### Customize in create-react-app
|
||||
|
||||
Follow [Use in create-react-app](/docs/react/use-with-create-react-app).
|
||||
|
||||
### Customize in less file
|
||||
|
||||
Another approach to customize theme is creating a `less` file within variables to override `antd.less`.
|
||||
|
||||
```css
|
||||
@import '~antd/es/style/themes/default.less';
|
||||
@import '~antd/dist/antd.less'; // Import Ant Design styles by less entry
|
||||
@import 'your-theme-file.less'; // variables to override above
|
||||
```
|
||||
|
||||
Note: This way will load the styles of all components, regardless of your demand, which cause `style` option of `babel-plugin-import` not working.
|
||||
|
||||
### Dynamic theme
|
||||
|
||||
Runtime update theme color please [ref this doc](/docs/react/customize-theme-variable).
|
||||
|
||||
## How to avoid modifying global styles?
|
||||
|
||||
Currently ant-design is designed as a whole experience and modify global styles (eg `body` etc). If you need to integrate ant-design as a part of an existing website, it's likely you want to prevent ant-design to override global styles.
|
||||
|
||||
While there's no canonical way to do it, you can take one of the following paths :
|
||||
|
||||
### Configure webpack to load an alternate less file and scope global styles
|
||||
|
||||
It's possible to configure webpack to load an alternate less file:
|
||||
|
||||
```ts
|
||||
new webpack.NormalModuleReplacementPlugin( /node_modules\/antd\/lib\/style\/index\.less/, path.resolve(rootDir, 'src/myStylesReplacement.less') )
|
||||
|
||||
#antd { @import '~antd/es/style/core/index.less'; @import '~antd/es/style/themes/default.less'; }
|
||||
```
|
||||
|
||||
Where the src/myStylesReplacement.less file loads the same files as the index.less file, but loads them within the scope of a top-level selector : the result is that all of the "global" styles are being applied with the #antd scope.
|
||||
|
||||
### Use a postcss processor to scope all styles
|
||||
|
||||
See an example of usage with [gulp and postcss-prefixwrap](https://gist.github.com/sbusch/a90eafaf5a5b61c6d6172da6ff76ddaa).
|
||||
|
||||
## Not working?
|
||||
|
||||
You must import styles as less format. A common mistake would be importing multiple copied of styles that some of them are css format to override the less styles.
|
||||
|
||||
- If you import styles by specifying the `style` option of [babel-plugin-import](https://github.com/ant-design/babel-plugin-import), change it from `'css'` to `true`, which will import the `less` version of antd.
|
||||
- If you import styles from `'antd/dist/antd.css'`, change it to `antd/dist/antd.less`.
|
||||
|
||||
## Official Themes 🌈
|
||||
|
||||
We have some official themes, try them out and give us some feedback!
|
||||
|
||||
- 🌑 Dark Theme (supported in 4.0.0+)
|
||||
- 📦 Compact Theme (supported in 4.1.0+)
|
||||
- ☁️ [Aliyun Console Theme (Beta)](https://github.com/ant-design/ant-design-aliyun-theme)
|
||||
|
||||
### Use dark or compact theme
|
||||
|
||||
|
||||
|
||||
Method 1: using Umi 3
|
||||
|
||||
If you're using [Umi 3](http://umijs.org):
|
||||
|
||||
```js
|
||||
// .umirc.ts or config/config.ts
|
||||
export default {
|
||||
antd: {
|
||||
dark: true, // active dark theme
|
||||
compact: true, // active compact theme
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
Method 2: Import [antd/dist/antd.dark.less](https://unpkg.com/browse/antd@4.x/dist/antd.dark.less) or [antd/dist/antd.compact.less](https://unpkg.com/browse/antd@4.x/dist/antd.compact.less) in the style file:
|
||||
|
||||
```less
|
||||
@import '~antd/dist/antd.dark.less'; // Introduce the official dark less style entry file
|
||||
@import '~antd/dist/antd.compact.less'; // Introduce the official compact less style entry file
|
||||
```
|
||||
|
||||
If the project does not use Less, you can import [antd.dark.css](https://unpkg.com/browse/antd@4.x/dist/antd.dark.css) or [antd/dist/antd.compact.css](https://unpkg.com/browse/antd@4.x/dist/antd.compact.css) in the CSS file:
|
||||
|
||||
```css
|
||||
@import '~antd/dist/antd.dark.css';
|
||||
@import '~antd/dist/antd.compact.css';
|
||||
```
|
||||
|
||||
> Note that you don't need to import `antd/dist/antd.less` or `antd/dist/antd.css` anymore, please remove it, and remove babel-plugin-import `style` config too. You can't enable two or more theme at the same time by this method.
|
||||
|
||||
Method 3: using [less-loader](https://github.com/webpack-contrib/less-loader) in `webpack.config.js` to introduce as needed:
|
||||
|
||||
```diff
|
||||
const { getThemeVariables } = require('antd/dist/theme');
|
||||
|
||||
// webpack.config.js
|
||||
module.exports = {
|
||||
rules: [{
|
||||
test: /\.less$/,
|
||||
use: [{
|
||||
loader: 'style-loader',
|
||||
}, {
|
||||
loader: 'css-loader', // translates CSS into CommonJS
|
||||
}, {
|
||||
loader: 'less-loader', // compiles Less to CSS
|
||||
+ options: {
|
||||
+ lessOptions: { // If you are using less-loader@5 please spread the lessOptions to options directly
|
||||
+ modifyVars: getThemeVariables({
|
||||
+ dark: true, // Enable dark mode
|
||||
+ compact: true, // Enable compact mode
|
||||
+ }),
|
||||
+ javascriptEnabled: true,
|
||||
+ },
|
||||
+ },
|
||||
}],
|
||||
}],
|
||||
};
|
||||
```
|
||||
|
||||
## Related Articles
|
||||
|
||||
- [Using Ant Design in Sass-Styled Webpack Projects with `antd-scss-theme-plugin`](https://intoli.com/blog/antd-scss-theme-plugin/)
|
||||
- [How to Customize Ant Design with React & Webpack… the Missing Guide](https://medium.com/@GeoffMiller/how-to-customize-ant-design-with-react-webpack-the-missing-guide-c6430f2db10f)
|
||||
- [Theming Ant Design with Sass and Webpack](https://gist.github.com/Kruemelkatze/057f01b8e15216ae707dc7e6c9061ef7)
|
||||
- [Using Sass/Scss with React App (create-react-app)](https://medium.com/@mzohaib.qc/using-sass-scss-with-react-app-create-react-app-d03072083ef8)
|
||||
- [Dynamic Theming in Browser using Ant Design](https://medium.com/@mzohaib.qc/ant-design-dynamic-runtime-theme-1f9a1a030ba0)
|
||||
- [Zero config custom theme generator](https://www.npmjs.com/package/@emeks/antd-custom-theme-generator)
|
||||
@ -1,197 +0,0 @@
|
||||
---
|
||||
order: 7
|
||||
title: 定制主题
|
||||
---
|
||||
|
||||
Ant Design 设计规范和技术上支持灵活的样式定制，以满足业务和品牌上多样化的视觉需求，包括但不限于全局样式（主色、圆角、边框）和指定组件的视觉定制。
|
||||
|
||||
|
||||
|
||||
## Ant Design 的样式变量
|
||||
|
||||
antd 的样式使用了 [Less](http://lesscss.org/) 作为开发语言，并定义了一系列全局/组件的样式变量，你可以根据需求进行相应调整。
|
||||
|
||||
以下是一些最常用的通用变量，所有样式变量可以在 [这里](https://github.com/ant-design/ant-design/blob/master/components/style/themes/default.less) 找到。
|
||||
|
||||
```less
|
||||
@primary-color: #1890ff; // 全局主色
|
||||
@link-color: #1890ff; // 链接色
|
||||
@success-color: #52c41a; // 成功色
|
||||
@warning-color: #faad14; // 警告色
|
||||
@error-color: #f5222d; // 错误色
|
||||
@font-size-base: 14px; // 主字号
|
||||
@heading-color: rgba(0, 0, 0, 0.85); // 标题色
|
||||
@text-color: rgba(0, 0, 0, 0.65); // 主文本色
|
||||
@text-color-secondary: rgba(0, 0, 0, 0.45); // 次文本色
|
||||
@disabled-color: rgba(0, 0, 0, 0.25); // 失效色
|
||||
@border-radius-base: 2px; // 组件/浮层圆角
|
||||
@border-color-base: #d9d9d9; // 边框色
|
||||
@box-shadow-base: 0 3px 6px -4px rgba(0, 0, 0, 0.12), 0 6px 16px 0 rgba(0, 0, 0, 0.08),
|
||||
0 9px 28px 8px rgba(0, 0, 0, 0.05); // 浮层阴影
|
||||
```
|
||||
|
||||
如果以上变量不能满足你的定制需求，可以给我们提 issue。
|
||||
|
||||
## 定制方式
|
||||
|
||||
原理上是使用 less 提供的 [modifyVars](http://lesscss.org/usage/#using-less-in-the-browser-modify-variables) 的方式进行覆盖变量，可以在本地运行 [例子](https://github.com/ant-design/create-react-app-antd) 查看定制效果。下面将针对不同的场景提供一些常用的定制方式。
|
||||
|
||||
### 在 webpack 中定制主题
|
||||
|
||||
我们以 webpack@4 为例进行说明，以下是一个 `webpack.config.js` 的典型例子，对 [less-loader](https://github.com/webpack-contrib/less-loader) 的 options 属性进行相应配置。
|
||||
|
||||
```diff
|
||||
// webpack.config.js
|
||||
module.exports = {
|
||||
rules: [{
|
||||
test: /\.less$/,
|
||||
use: [{
|
||||
loader: 'style-loader',
|
||||
}, {
|
||||
loader: 'css-loader', // translates CSS into CommonJS
|
||||
}, {
|
||||
loader: 'less-loader', // compiles Less to CSS
|
||||
+ options: {
|
||||
+ lessOptions: { // 如果使用less-loader@5，请移除 lessOptions 这一级直接配置选项。
|
||||
+ modifyVars: {
|
||||
+ 'primary-color': '#1DA57A',
|
||||
+ 'link-color': '#1DA57A',
|
||||
+ 'border-radius-base': '2px',
|
||||
+ },
|
||||
+ javascriptEnabled: true,
|
||||
+ },
|
||||
+ },
|
||||
}],
|
||||
// ...other rules
|
||||
}],
|
||||
// ...other config
|
||||
}
|
||||
```
|
||||
|
||||
注意：
|
||||
|
||||
1. less-loader 的处理范围不要过滤掉 `node_modules` 下的 antd 包。
|
||||
2. `lessOptions` 的配置写法在 [less-loader@6.0.0](https://github.com/webpack-contrib/less-loader/releases/tag/v6.0.0) 里支持。
|
||||
|
||||
### 在 Umi 里配置主题
|
||||
|
||||
如果你在使用 [Umi](https://umijs.org/zh-CN/config#theme)，那么可以很方便地在项目根目录的 `.umirc.ts` 或 [config/config.ts](https://github.com/ant-design/ant-design-pro/blob/v5/config/config.ts) 文件中 [theme](https://umijs.org/zh-CN/config#theme) 字段进行主题配置。`theme` 可以配置为一个对象或文件路径。
|
||||
|
||||
```js
|
||||
"theme": {
|
||||
"primary-color": "#1DA57A",
|
||||
},
|
||||
```
|
||||
|
||||
或者 [一个 js 文件](https://github.com/ant-design/ant-design-pro/blob/b7e7983661eb5e53dc807452e9653e93e74276d4/.webpackrc.js#L18)：
|
||||
|
||||
```js
|
||||
"theme": "./theme.js",
|
||||
```
|
||||
|
||||
### 在 create-react-app 中定制主题
|
||||
|
||||
参考 [在 create-react-app 中使用](/docs/react/use-with-create-react-app) 进行配置即可。
|
||||
|
||||
### 配置 less 变量文件
|
||||
|
||||
另外一种方式是建立一个单独的 `less` 变量文件，引入这个文件覆盖 `antd.less` 里的变量。
|
||||
|
||||
```css
|
||||
@import '~antd/es/style/themes/default.less';
|
||||
@import '~antd/dist/antd.less'; // 引入官方提供的 less 样式入口文件
|
||||
@import 'your-theme-file.less'; // 用于覆盖上面定义的变量
|
||||
```
|
||||
|
||||
注意，这种方式已经载入了所有组件的样式，不需要也无法和按需加载插件 `babel-plugin-import` 的 `style` 属性一起使用。
|
||||
|
||||
### 动态主题色
|
||||
|
||||
在运行时调整主题色请[参考此处](/docs/react/customize-theme-variable)。
|
||||
|
||||
## 没有生效？
|
||||
|
||||
注意样式必须加载 less 格式，一个常见的问题就是引入了多份样式，less 的样式被 css 的样式覆盖了。
|
||||
|
||||
- 如果你在使用 [babel-plugin-import](https://github.com/ant-design/babel-plugin-import) 的 `style` 配置来引入样式，需要将配置值从 `'css'` 改为 `true`，这样会引入 less 文件。
|
||||
- 如果你是通过 `'antd/dist/antd.css'` 引入样式的，改为 `antd/dist/antd.less`。
|
||||
|
||||
## 官方主题 🌈
|
||||
|
||||
我们提供了一些官方主题，欢迎在项目中试用，并且给我们提供反馈。
|
||||
|
||||
- 🌑 暗黑主题（4.0.0+ 支持）
|
||||
- 📦 紧凑主题（4.1.0+ 支持）
|
||||
- ☁️ [阿里云控制台主题（Beta）](https://github.com/ant-design/ant-design-aliyun-theme)
|
||||
|
||||
### 使用暗黑主题和紧凑主题
|
||||
|
||||
|
||||
|
||||
方式一：使用 Umi 3
|
||||
|
||||
如果你在使用 [Umi 3](http://umijs.org/zh-CN)：
|
||||
|
||||
```js
|
||||
// .umirc.ts or config/config.ts
|
||||
export default {
|
||||
antd: {
|
||||
dark: true, // 开启暗色主题
|
||||
compact: true, // 开启紧凑主题
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
方式二：是在样式文件全量引入 [antd.dark.less](https://unpkg.com/browse/antd@4.x/dist/antd.dark.less) 或 [antd.compact.less](https://unpkg.com/browse/antd@4.x/dist/antd.compact.less)。
|
||||
|
||||
```less
|
||||
@import '~antd/dist/antd.dark.less'; // 引入官方提供的暗色 less 样式入口文件
|
||||
@import '~antd/dist/antd.compact.less'; // 引入官方提供的紧凑 less 样式入口文件
|
||||
```
|
||||
|
||||
如果项目不使用 Less，可在 CSS 文件中全量引入 [antd.dark.css](https://unpkg.com/browse/antd@4.x/dist/antd.dark.css) 或 [antd.compact.css](https://unpkg.com/browse/antd@4.x/dist/antd.compact.css)。
|
||||
|
||||
```css
|
||||
@import '~antd/dist/antd.dark.css';
|
||||
@import '~antd/dist/antd.compact.css';
|
||||
```
|
||||
|
||||
> 注意这种方式下你不需要再引入 `antd/dist/antd.less` 或 `antd/dist/antd.css` 了，可以安全移除掉。也不需要开启 babel-plugin-import 的 `style` 配置。通过此方式不能同时配置两种及以上主题。
|
||||
|
||||
方式三：是用在 `webpack.config.js` 使用 [less-loader](https://github.com/webpack-contrib/less-loader) 按需引入：
|
||||
|
||||
```diff
|
||||
const { getThemeVariables } = require('antd/dist/theme');
|
||||
|
||||
// webpack.config.js
|
||||
module.exports = {
|
||||
rules: [{
|
||||
test: /\.less$/,
|
||||
use: [{
|
||||
loader: 'style-loader',
|
||||
}, {
|
||||
loader: 'css-loader', // translates CSS into CommonJS
|
||||
}, {
|
||||
loader: 'less-loader', // compiles Less to CSS
|
||||
+ options: {
|
||||
+ lessOptions: { // 如果使用less-loader@5，请移除 lessOptions 这一级直接配置选项。
|
||||
+ modifyVars: getThemeVariables({
|
||||
+ dark: true, // 开启暗黑模式
|
||||
+ compact: true, // 开启紧凑模式
|
||||
+ }),
|
||||
+ javascriptEnabled: true,
|
||||
+ },
|
||||
+ },
|
||||
}],
|
||||
}],
|
||||
};
|
||||
```
|
||||
|
||||
## 社区教程
|
||||
|
||||
- [Using Ant Design in Sass-Styled Webpack Projects with `antd-scss-theme-plugin`](https://intoli.com/blog/antd-scss-theme-plugin/)
|
||||
- [How to Customize Ant Design with React & Webpack… the Missing Guide](https://medium.com/@GeoffMiller/how-to-customize-ant-design-with-react-webpack-the-missing-guide-c6430f2db10f)
|
||||
- [Theming Ant Design with Sass and Webpack](https://gist.github.com/Kruemelkatze/057f01b8e15216ae707dc7e6c9061ef7)
|
||||
- [Using Sass/Scss with React App (create-react-app)](https://medium.com/@mzohaib.qc/using-sass-scss-with-react-app-create-react-app-d03072083ef8)
|
||||
- [Dynamic Theming in Browser using Ant Design](https://medium.com/@mzohaib.qc/ant-design-dynamic-runtime-theme-1f9a1a030ba0)
|
||||
- [Zero config custom theme generator](https://www.npmjs.com/package/@emeks/antd-custom-theme-generator)
|
||||
@ -1,327 +0,0 @@
|
||||
---
|
||||
order: 8
|
||||
title: V3 to V4
|
||||
---
|
||||
|
||||
This document will help you upgrade from antd `3.x` version to antd `4.x` version. If you are using `2.x` or older version, please refer to the previous [upgrade document](https://github.com/ant-design/ant-design/blob/2adf8ced24da7b3cb46a3475854a83d76a98c536/CHANGELOG.en-US.md#300) to 3.x.
|
||||
|
||||
## Upgrade preparation
|
||||
|
||||
1. Please upgrade to the latest version of 3.x first, and remove / modify related APIs according to the console warning message.
|
||||
2. Upgrade project React 16.12.0 or above.
|
||||
- If you are still using React 15, please refer to [React 16 Upgrade Documentation](https://reactjs.org/blog/2017/09/26/react-v16.0.html#breaking-changes).
|
||||
- For the remaining React 16 obsolete lifecycle APIs, please refer to [Migration Guide](https://reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path).
|
||||
|
||||
## Incompatible changes in v4
|
||||
|
||||
### Design specification
|
||||
|
||||
- Line height changes from `1.5`(`21px`) to `1.5715`(`22px`).
|
||||
- Darken font color from `rgba(0, 0, 0, 0.65)` to `rgba(0, 0, 0, 0.85)`. `4.6.0`
|
||||
- Basic rounded corner adjustment, changed from `4px` to `2px`.
|
||||
- Exchanged Selected and Hovered color.
|
||||
- Global shadow optimization, adjusted to three layers of shadows to distinguish control hierarchies.
|
||||
- Icon in the bubble confirmation box has been changed from a question mark to an exclamation mark.
|
||||
- The color of selected components is changed to `@blue-1: #E6F7FF`, and the corresponding hover color is changed to `@gray-2: #FAFAFA`.
|
||||
- The color of the error was adjusted from `@red-5: #F5222D` to`@red-5: #FF4D4F`.
|
||||
- The color brightness of the dividing line has been reduced from `#E8E8E8` to`#F0F0F0`.
|
||||
- DatePicker interactive redo, range selection can now select start and end time separately.
|
||||
- Table change default background color from transparent to white.
|
||||
- Smaller Tabs bar width.
|
||||
- New Tabs interaction and dom structure is changed in `4.3.0`.
|
||||
|
||||
### Compatibility
|
||||
|
||||
- The minimum supported version of IE is IE 11.
|
||||
- The minimum supported version of React is React 16.9, and some components have started to refactor using hooks.
|
||||
- Internal using `useMemo` for performance, do not use mutable data as props.
|
||||
- The minimum supported version of less.js is `3.1.0`, we recommend using less `4.x`.
|
||||
|
||||
#### Remove deprecated API
|
||||
|
||||
- LocaleProvider has been removed, please use `ConfigProvider` instead.
|
||||
- Mention removed, use `Mentions` instead.
|
||||
- Removed the `iconType` property of Alert. Please use `icon` instead.
|
||||
- Removed the `iconType` attribute of Modal.xxx. Please use `icon` instead.
|
||||
- Removed the Form.create method, `form` is now available in `Form.useForm`.
|
||||
- Removed the `id` attribute of Form.Item. Please use `htmlFor` instead.
|
||||
- The `setContentRef` property of Typography has been removed, please use `ref` instead.
|
||||
- Removed the `allowEmpty` property of TimePicker, please use `allowClear` instead.
|
||||
- Removed `AfterClose` attribute of Tag, please use `OnClose` instead.
|
||||
- Removed the `noHovering` property of Card, please use `hoverable` instead.
|
||||
- Removed the `vertical` property of Carousel. Please use `dotPosition` instead.
|
||||
- Removed `wrapClassName` property of Drawer, please use `className` instead.
|
||||
- Removed the `autosize` property of TextArea. Please use `autoSize` instead.
|
||||
- Removed the `offset` attribute of Affix. Please use `offsetTop` instead.
|
||||
- Removed the `onSearchChange` property of Transfer. Please use `onSearch` instead.
|
||||
- Removed the `body` attribute of Transfer. Please use `children` instead.
|
||||
- Removed the `lazy` attribute of Transfer, which did not really optimize the effect.
|
||||
- Removed `combobox` mode, please use `AutoComplete` instead.
|
||||
- Removed the `rowSelection.hideDefaultSelections` property of Table, please use `SELECTION_ALL` and `SELECTION_INVERT` in `rowSelection.selections` instead, [Custom Selection](/components/table/#components-table-demo-row-selection-custom).
|
||||
- Deprecated Button.Group, please use `Space` instead.
|
||||
- less variables were changed like DatePicker/TimePicker/Calendar related variables or [@btn-padding-base](https://github.com/ant-design/ant-design/issues/28141), please check [3.x variables](https://github.com/ant-design/ant-design/blob/3.x-stable/components/style/themes/default.less) and [4.x variables](https://github.com/ant-design/ant-design/blob/master/components/style/themes/default.less) for more details.
|
||||
|
||||
#### Icon upgrade
|
||||
|
||||
In `antd @ 3.9.0`, we introduced the svg icon ([Why use the svg icon?](https://github.com/ant-design/ant-design/issues/10353)). The icon API using the string name cannot be loaded on demand, so the svg icon file is fully introduced, which greatly increases the size of the packaged product. In 4.0, we adjusted the icon usage API to support tree shaking, reducing the default package size of antd by about 150 KB (Gzipped).
|
||||
|
||||
Legacy Icon usage will be discarded:
|
||||
|
||||
```jsx
|
||||
import { Icon, Button } from 'antd';
|
||||
|
||||
const Demo = () => (
|
||||
<div>
|
||||
<Icon type="smile" />
|
||||
<Button icon="smile" />
|
||||
</div>
|
||||
);
|
||||
```
|
||||
|
||||
It will be imported on demand in v4:
|
||||
|
||||
```diff
|
||||
import { Button } from 'antd';
|
||||
|
||||
// tree-shaking supported
|
||||
- import { Icon } from 'antd';
|
||||
+ import { SmileOutlined } from '@ant-design/icons';
|
||||
|
||||
const Demo = () => (
|
||||
<div>
|
||||
- <Icon type="smile" />
|
||||
+ <SmileOutlined />
|
||||
<Button icon={<SmileOutlined />} />
|
||||
</div>
|
||||
);
|
||||
|
||||
// or directly import
|
||||
import SmileOutlined from '@ant-design/icons/SmileOutlined';
|
||||
```
|
||||
|
||||
You will still be able to continue using the compatibility pack:
|
||||
|
||||
```jsx
|
||||
import { Button } from 'antd';
|
||||
import { Icon } from '@ant-design/compatible';
|
||||
|
||||
const Demo = () => (
|
||||
<div>
|
||||
<Icon type="smile" />
|
||||
<Button icon="smile" />
|
||||
</div>
|
||||
);
|
||||
```
|
||||
|
||||
#### Component refactoring
|
||||
|
||||
- Form rewrite.
|
||||
- No need to use `Form.create`.
|
||||
- Nest fields definition changes from `'xxx.yyy'` to `['xxx', 'yyy']`.
|
||||
- `validateTrigger` no long collect field value.
|
||||
- See [here](/components/form/v3) for migration documentation.
|
||||
- DatePicker rewrite
|
||||
- Provide the `picker` property for selector switching.
|
||||
- Range selection can now select start and end times individually.
|
||||
- `onPanelChange` will also trigger when panel value changed.
|
||||
- [Date cell className of Custom style demo](/components/date-picker/#components-date-picker-demo-date-render) changed from `ant-calendar-date` to `ant-picker-cell-inner`.
|
||||
- Tree, Select, TreeSelect, AutoComplete rewrite
|
||||
- use virtual scrolling.
|
||||
- `onBlur` no longer trigger value change and return React origin `event` object instead.
|
||||
- If config `validateTrigger` as `onBlur` with compatible Form, please change to `onChange` instead.
|
||||
- AutoComplete no longer support `optionLabelProp`. Please set Option `value` directly.
|
||||
- AutoComplete options definition align with Select. Please use `options` instead of `dataSource`.
|
||||
- Select remove `dropdownMenuStyle` prop.
|
||||
- Use `listHeight` to config popup height instead of `dropdownStyle`.
|
||||
- `filterOption` return origin data with second params instead. No need to use `option.props.children` for matching.
|
||||
- Tree, TreeSelect will display `label` when `title` and `label` are both set. The adjustment is for aligning behavior with `labelInValue`. [New behavior](https://codesandbox.io/s/keen-curran-d3qnp) (show 'label' on first node). [Old behavior](https://codesandbox.io/s/muddy-darkness-57lb3) (show 'title' on first node).
|
||||
- The Grid component uses flex layout.
|
||||
- Button's `danger` is now treated as a property instead of a button type.
|
||||
- Input, Select set `value` to `undefined` is uncontrolled mode now.
|
||||
- Table rewrite.
|
||||
- will keep at least one column even if `columns` is empty.
|
||||
- Nest `dataIndex` definition changes from `'xxx.yyy'` to `['xxx', 'yyy']`.
|
||||
- Pagination
|
||||
- will default set `showSizeChanger` to `true` since `4.1.0`. This change also applied on Table component.
|
||||
- `onChange` will also trigger when `pageSize` value changed.
|
||||
- Tabs rewrite. ([4.3.0](https://github.com/ant-design/ant-design/pull/24552))
|
||||
- Dom structrue is changed, please check style if you override tabs css.
|
||||
- `onPrevClick` 和 `onNextClick` would be not working anymore since we improve tabs scroll behavior.
|
||||
|
||||
```diff
|
||||
<Table
|
||||
columns={[
|
||||
{
|
||||
title: 'Age',
|
||||
- dataIndex: 'user.age',
|
||||
+ dataIndex: ['user', 'age'],
|
||||
},
|
||||
]}
|
||||
/>
|
||||
```
|
||||
|
||||
## Start upgrading
|
||||
|
||||
You can manually check the code one by one against the above list for modification. In addition, we also provide a codemod cli tool [@ant-design/codemod-v4](https://github.com/ant-design/codemod-v4) To help you quickly upgrade to v4.
|
||||
|
||||
Before running codemod cli, please submit your local code changes.
|
||||
|
||||
```shell
|
||||
# Run directly through npx
|
||||
npx -p @ant-design/codemod-v4 antd4-codemod src
|
||||
|
||||
# Or global installation
|
||||
# Use npm
|
||||
npm i -g @ant-design/codemod-v4
|
||||
# Use yarn
|
||||
yarn global add @ant-design/codemod-v4
|
||||
|
||||
# Execute
|
||||
antd4-codemod src
|
||||
```
|
||||
|
||||
<img src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*QdcbQoLC-cQAAAAAAAAAAABkARQnAQ" alt="codemod running" width="720" />
|
||||
|
||||
For parts that cannot be modified automatically, codemod will prompt on the command line, and it is recommended to modify them manually as prompted. After modification, you can run the above command repeatedly to check.
|
||||
|
||||
<img src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*KQwWSrPirlUAAAAAAAAAAABkARQnAQ" alt="contains an invalid icon" width="720" />
|
||||
|
||||
> Note that codemod cannot cover all scenarios, and it is recommended to check for incompatible changes one by one.
|
||||
|
||||
### Migration tool modification details
|
||||
|
||||
`@ant-design/codemod-v4` will help you migrate to antd v4. Obsolete components will be kept running through @ant-design/compatible. Generally, you don't need to migrate manually. The following sections detail the overall migration and changes.
|
||||
|
||||
#### Install compatible package
|
||||
|
||||
Install `@ant-design/compatible` with `v4-compatible-v3` tag:
|
||||
|
||||
```bash
|
||||
npm install --save @ant-design/compatible@v4-compatible-v3
|
||||
```
|
||||
|
||||
#### Import the obsolete Form and Mention components via @ant-design/compatible package
|
||||
|
||||
```diff
|
||||
- import { Form, Input, Button, Mention } from 'antd';
|
||||
+ import { Form, Mention } from '@ant-design/compatible';
|
||||
+ import '@ant-design/compatible/assets/index.css';
|
||||
+ import { Input, Button } from 'antd';
|
||||
|
||||
ReactDOM.render( (
|
||||
<div>
|
||||
<Form>
|
||||
{getFieldDecorator('username')(<Input />)}
|
||||
<Button>Submit</Button>
|
||||
</Form>
|
||||
<Mention
|
||||
style={{ width: '100%' }}
|
||||
onChange={onChange}
|
||||
defaultValue={toContentState('@afc163')}
|
||||
defaultSuggestions={['afc163', 'benjycui']}
|
||||
onSelect={onSelect}
|
||||
/>
|
||||
</div>
|
||||
);
|
||||
```
|
||||
|
||||
> **Note:** Old Form imported from `@ ant-design / compatible` has change the class name from `.ant-form` to `.ant-legacy-form`. Need to be modified accordingly if override the style.
|
||||
|
||||
#### Replace component's string icon prop with the new `@ant-design/icons`
|
||||
|
||||
```diff
|
||||
import { Avatar, Button, Result } from 'antd';
|
||||
+ import { QuestionOutlined, UserOutlined } from '@ant-design/icons';
|
||||
|
||||
ReactDOM.render(
|
||||
<div>
|
||||
- <Button type="primary" shape="circle" icon="search" />
|
||||
+ <Button type="primary" shape="circle" icon={SearchOutlined} />
|
||||
- <Avatar shape="square" icon="user" />
|
||||
+ <Avatar shape="square" icon={UserOutlined} />
|
||||
<Result
|
||||
- icon="question"
|
||||
+ icon={<QuestionOutlined />}
|
||||
title="Great, we have done all the operations!"
|
||||
extra={<Button type="primary">Next</Button>}
|
||||
/>
|
||||
</div>,
|
||||
mountNode,
|
||||
);
|
||||
|
||||
```
|
||||
|
||||
#### Replace v3 Icon with `@ant-design/icons`
|
||||
|
||||
```diff
|
||||
- import { Icon, Input } from 'antd';
|
||||
+ import { Input } from 'antd';
|
||||
+ import Icon, { CodeFilled, SmileOutlined, SmileTwoTone } from '@ant-design/icons';
|
||||
|
||||
const HeartSvg = () => (
|
||||
<svg width="1em" height="1em" fill="currentColor" viewBox="0 0 1024 1024">
|
||||
<path d="M923 plapla..." />
|
||||
</svg>
|
||||
);
|
||||
|
||||
const HeartIcon = props => <Icon component={HeartSvg} {...props} />;
|
||||
|
||||
ReactDOM.render(
|
||||
<div>
|
||||
- <Icon type="code" theme="filled" />
|
||||
+ <CodeFilled />
|
||||
- <Icon type="smile" theme="twoTone" twoToneColor="#eb2f96" />
|
||||
+ <SmileTwoTone twoToneColor="#eb2f96" />
|
||||
- <Icon type="code" theme={props.fill ? 'filled' : 'outlined'} />
|
||||
+ <LegacyIcon type="code" theme={props.fill ? 'filled' : 'outlined'} />
|
||||
<HeartIcon />
|
||||
<Icon viewBox="0 0 24 24">
|
||||
<title>Cool Home</title>
|
||||
<path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z" />
|
||||
</Icon>
|
||||
<Input suffix={<SmileOutlined />} />
|
||||
</div>,
|
||||
mountNode,
|
||||
);
|
||||
|
||||
```
|
||||
|
||||
#### Replace v3 LocaleProvider with v4 ConfigProvider
|
||||
|
||||
```diff
|
||||
- import { LocaleProvider } from 'antd';
|
||||
+ import { ConfigProvider } from 'antd';
|
||||
|
||||
ReactDOM.render(
|
||||
- <LocaleProvider {...yourConfig}>
|
||||
+ <ConfigProvider {...yourConfig}>
|
||||
<Main />
|
||||
- </LocaleProvider>
|
||||
+ </ConfigProvider>
|
||||
mountNode,
|
||||
);
|
||||
```
|
||||
|
||||
#### Replace `Modal.method()` icon string with `@ant-design/icons`
|
||||
|
||||
```diff
|
||||
import { Modal } from 'antd';
|
||||
+ import { AntDesignOutlined } from '@ant-design/icons';
|
||||
|
||||
Modal.confirm({
|
||||
- icon: 'ant-design',
|
||||
+ icon: <AntDesignOutlined />,
|
||||
title: 'Do you Want to delete these items?',
|
||||
content: 'Some descriptions',
|
||||
onOk() {
|
||||
console.log('OK');
|
||||
},
|
||||
onCancel() {
|
||||
console.log('Cancel');
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## Encounter problems
|
||||
|
||||
v4 made a lot of detailed improvements and refactoring. We collected all known incompatible changes and related impacts as much as possible, but there may be some scenarios we have not considered. If you encounter problems during the upgrade, please go to [GitHub issues](http://new-issue.ant.design/) and [codemod Issues](https://github.com/ant-design/codemod-v4/issues) for feedback. We will respond and improve this document as soon as possible.
|
||||
@ -1,328 +0,0 @@
|
||||
---
|
||||
order: 8
|
||||
title: 从 v3 到 v4
|
||||
---
|
||||
|
||||
本文档将帮助你从 antd `3.x` 版本升级到 antd `4.x` 版本，如果你是 `2.x` 或者更老的版本，请先参考之前的[升级文档](https://github.com/ant-design/ant-design/blob/2adf8ced24da7b3cb46a3475854a83d76a98c536/CHANGELOG.zh-CN.md#300)升级到 3.x。
|
||||
|
||||
## 升级准备
|
||||
|
||||
1. 请先升级到 3.x 的最新版本，按照控制台 warning 信息移除/修改相关的 API。
|
||||
2. 升级项目 React 16.12.0 以上。
|
||||
- 如果你仍在使用 React 15，请参考 [React 16 升级文档](https://reactjs.org/blog/2017/09/26/react-v16.0.html#breaking-changes)。
|
||||
- 其余 React 16 废弃生命周期 API 请参考 [迁移导引](https://reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)。
|
||||
|
||||
## 4.0 有哪些不兼容的变化
|
||||
|
||||
### 设计规范调整
|
||||
|
||||
- 行高从 `1.5`(`21px`) 调整为 `1.5715`(`22px`)。
|
||||
- 字体颜色从 `rgba(0, 0, 0, 0.65)` 调深为 `rgba(0, 0, 0, 0.85)`。`4.6.0`
|
||||
- 基础圆角调整，由 `4px` 改为 `2px`。
|
||||
- Selected 颜色和 Hovered 颜色进行了交换。
|
||||
- 全局阴影优化，调整为三层阴影区分控件层次关系。
|
||||
- 气泡确认框中图标的使用改变，由问号改为感叹号。
|
||||
- 部分组件选中颜色统一改为 `@blue-1: #E6F7FF`，对应 `hover` 颜色改为 `@gray-2: #FAFAFA`。
|
||||
- 报错色色值调整，由 `@red-5: #F5222D` 改为 `@red-5: #FF4D4F`。
|
||||
- 分割线颜色明度降低，由 `#E8E8E8` 改为 `#F0F0F0`。
|
||||
- DatePicker 交互重做，面板和输入框分离，范围选择现可单独选择开始和结束时间。
|
||||
- Table 默认背景颜色从透明修改为白色。
|
||||
- Tabs 火柴棍样式缩短为和文字等长。
|
||||
- Tabs 交互重做，DOM 结构改变。`4.3.0`
|
||||
|
||||
### 兼容性调整
|
||||
|
||||
- IE 最低支持版本为 IE 11。
|
||||
- React 最低支持版本为 React 16.9，部分组件开始使用 hooks 进行重构。
|
||||
- 重构通过 `useMemo` 进行性能优化，请勿使用 mutable data 作为参数。
|
||||
- 最低支持的 less 版本为 3.1.0，建议升级到 less 4.x 最新版本。
|
||||
|
||||
#### 移除废弃的 API
|
||||
|
||||
- 移除了 LocaleProvider，请使用 `ConfigProvider` 替代。
|
||||
- 移除了 Mention，请使用 `Mentions` 替代。
|
||||
- 移除了 Alert 的 `iconType` 属性，请使用 `icon` 替代。
|
||||
- 移除了 Modal.xxx 的 `iconType` 属性，请使用 `icon` 替代。
|
||||
- 移除了 Form.create 方法，`form` 现可由 `Form.useForm` 获取。
|
||||
- 移除了 Form.Item 的 `id` 属性，请使用 `htmlFor` 替代。
|
||||
- 移除了 Typography 的 `setContentRef` 属性，请使用 `ref` 替代。
|
||||
- 移除了 TimePicker 的 `allowEmpty` 属性，请使用 `allowClear` 替代。
|
||||
- 移除了 Tag 的 `afterClose` 属性，请使用 `onClose` 替代。
|
||||
- 移除了 Card 的 `noHovering` 属性，请使用 `hoverable` 替代。
|
||||
- 移除了 Carousel 的 `vertical` 属性，请使用 `dotPosition` 替代。
|
||||
- 移除了 Drawer 的 `wrapClassName` 属性，请使用 `className` 替代。
|
||||
- 移除了 TextArea 的 `autosize` 属性，请使用 `autoSize` 替代。
|
||||
- 移除了 Affix 的 `offset` 属性，请使用 `offsetTop` 替代。
|
||||
- 移除了 Transfer 的 `onSearchChange` 属性，请使用 `onSearch` 替代。
|
||||
- 移除了 Transfer 的 `body` 属性，请使用 `children` 替代。
|
||||
- 移除了 Transfer 的 `lazy` 属性，它并没有起到真正的优化效果。
|
||||
- 移除了 Select 的 `combobox` 模式，请使用 `AutoComplete` 替代。
|
||||
- 移除了 Table 的 `rowSelection.hideDefaultSelections` 属性，请在 `rowSelection.selections` 中使用 `SELECTION_ALL` 和 `SELECTION_INVERT` 替代，[自定义选择项](/components/table/#components-table-demo-row-selection-custom)。
|
||||
- 废弃 Button.Group，请使用 `Space` 代替。
|
||||
|
||||
#### 图标升级
|
||||
|
||||
在 `antd@3.9.0` 中，我们引入了 svg 图标（[为何使用 svg 图标？](https://github.com/ant-design/ant-design/issues/10353)）。使用了字符串命名的图标 API 无法做到按需加载，因而全量引入了 svg 图标文件，这大大增加了打包产物的尺寸。在 4.0 中，我们调整了图标的使用 API 从而支持 tree shaking，减少 antd 默认包体积约 150 KB(Gzipped)。
|
||||
|
||||
旧版 Icon 使用方式将被废弃：
|
||||
|
||||
```jsx
|
||||
import { Icon, Button } from 'antd';
|
||||
|
||||
const Demo = () => (
|
||||
<div>
|
||||
<Icon type="smile" />
|
||||
<Button icon="smile" />
|
||||
</div>
|
||||
);
|
||||
```
|
||||
|
||||
4.0 中会采用按需引入的方式：
|
||||
|
||||
```diff
|
||||
import { Button } from 'antd';
|
||||
|
||||
// tree-shaking supported
|
||||
- import { Icon } from 'antd';
|
||||
+ import { SmileOutlined } from '@ant-design/icons';
|
||||
|
||||
const Demo = () => (
|
||||
<div>
|
||||
- <Icon type="smile" />
|
||||
+ <SmileOutlined />
|
||||
<Button icon={<SmileOutlined />} />
|
||||
</div>
|
||||
);
|
||||
|
||||
// or directly import
|
||||
import SmileOutlined from '@ant-design/icons/SmileOutlined';
|
||||
```
|
||||
|
||||
你将仍然可以通过兼容包继续使用：
|
||||
|
||||
```jsx
|
||||
import { Button } from 'antd';
|
||||
import { Icon } from '@ant-design/compatible';
|
||||
|
||||
const Demo = () => (
|
||||
<div>
|
||||
<Icon type="smile" />
|
||||
<Button icon="smile" />
|
||||
</div>
|
||||
);
|
||||
```
|
||||
|
||||
#### 组件重构
|
||||
|
||||
- Form 重写
|
||||
- 不再需要 `Form.create`。
|
||||
- 嵌套字段支持从 `'xxx.yyy'` 改成 `['xxx', 'yyy']`。
|
||||
- `validateTrigger` 不再收集字段值。
|
||||
- 迁移文档请查看[此处](/components/form/v3)。
|
||||
- DatePicker 重写
|
||||
- 提供 `picker` 属性用于选择器切换。
|
||||
- 范围选择现在可以单独选择开始和结束时间。
|
||||
- `onPanelChange` 在面板值变化时也会触发。
|
||||
- [自定义单元格样式](/components/date-picker-cn/#components-date-picker-demo-date-render)的类名从 `ant-calendar-date` 改为 `ant-picker-cell-inner`。
|
||||
- Tree、Select、TreeSelect、AutoComplete 重新写
|
||||
- 使用虚拟滚动。
|
||||
- `onBlur` 时不再修改选中值，且返回 React 原生的 `event` 对象。
|
||||
- 如果你在使用兼容包的 Form 且配置了 `validateTrigger` 为 `onBlur`，请改至 `onChange` 以做兼容。
|
||||
- AutoComplete 不再支持 `optionLabelProp`，请直接设置 Option `value` 属性。
|
||||
- AutoComplete 选项与 Select 对齐，请使用 `options` 代替 `dataSource`。
|
||||
- Select 移除 `dropdownMenuStyle` 属性。
|
||||
- 如果你需要设置弹窗高度请使用 `listHeight` 来代替 `dropdownStyle` 的高度样式。
|
||||
- `filterOption` 第二个参数直接返回原数据，不在需要通过 `option.props.children` 来进行匹配。
|
||||
- Tree、TreeSelect 同时指定 `title` 和 `label` 的时候，会选择显示 `label`。为了 `labelInValue` 行为一致进行了该调整。[新行为](https://codesandbox.io/s/keen-curran-d3qnp)（在第一个节点展示 'label'），[旧行为](https://codesandbox.io/s/muddy-darkness-57lb3)（在第一个节点展示 'title'）。
|
||||
- Tree 传入内容采用 `treeData` 属性，来代替 `TreeNode` 方式，TreeNode 依然可用，但是会在控制台抛出警告。
|
||||
- Grid 组件使用 flex 布局。
|
||||
- Button 的 `danger` 现在作为一个属性而不是按钮类型。
|
||||
- Input、Select 的 `value` 为 `undefined` 时改为非受控状态。
|
||||
- Table 重写
|
||||
- 在没有 `columns` 时仍然会保留一列。
|
||||
- 嵌套 `dataIndex` 支持从 `'xxx.yyy'` 改成 `['xxx', 'yyy']`。
|
||||
- Pagination 重写
|
||||
- 自 `4.1.0` 起大于 50 条数据默认会展示 `pageSize` 切换器，这条规则同样会运用于 Table 上。
|
||||
- `onChange` 方法在 `pageSize` 值改变时也会触发。
|
||||
- Tabs 重写（[4.3.0](https://github.com/ant-design/ant-design/pull/24552)）
|
||||
- Dom 结构变化，如有覆盖样式需要仔细检查。
|
||||
- 横向滚动交互变化，`onPrevClick` 和 `onNextClick` 不再工作。
|
||||
- less 变量变化，如 DatePicker/TimePicker/Calendar 相关变量已全部重构，又如 [@btn-padding-base](https://github.com/ant-design/ant-design/issues/28141) 等进行了重命名，具体变化请自行对比 [3.x 变量](https://github.com/ant-design/ant-design/blob/3.x-stable/components/style/themes/default.less) 和 [4.x 变量](https://github.com/ant-design/ant-design/blob/master/components/style/themes/default.less)。
|
||||
|
||||
```diff
|
||||
<Table
|
||||
columns={[
|
||||
{
|
||||
title: 'Age',
|
||||
- dataIndex: 'user.age',
|
||||
+ dataIndex: ['user', 'age'],
|
||||
},
|
||||
]}
|
||||
/>
|
||||
```
|
||||
|
||||
## 开始升级
|
||||
|
||||
你可以手动对照上面的列表逐条检查代码进行修改，另外，我们也提供了一个 codemod cli 工具 [@ant-design/codemod-v4](https://github.com/ant-design/codemod-v4) 以帮助你快速升级到 v4 版本。
|
||||
|
||||
在运行 codemod cli 前，请先提交你的本地代码修改。
|
||||
|
||||
```shell
|
||||
# 通过 npx 直接运行
|
||||
npx -p @ant-design/codemod-v4 antd4-codemod src
|
||||
|
||||
# 或者全局安装
|
||||
# 使用 npm
|
||||
npm i -g @ant-design/codemod-v4
|
||||
# 或者使用 yarn
|
||||
yarn global add @ant-design/codemod-v4
|
||||
|
||||
# 运行
|
||||
antd4-codemod src
|
||||
```
|
||||
|
||||
<img src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*QdcbQoLC-cQAAAAAAAAAAABkARQnAQ" alt="codemod running" width="720" />
|
||||
|
||||
对于无法自动修改的部分，codemod 会在命令行进行提示，建议按提示手动修改。修改后可以反复运行上述命令进行检查。
|
||||
|
||||
<img src="https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*KQwWSrPirlUAAAAAAAAAAABkARQnAQ" alt="contains an invalid icon" width="720" />
|
||||
|
||||
> 注意 codemod 不能涵盖所有场景，建议还是要按不兼容的变化逐条排查。
|
||||
|
||||
### 迁移工具修改详情
|
||||
|
||||
`@ant-design/codemod-v4` 会帮你迁移到 antd v4, 废弃的组件则通过 `@ant-design/compatible` 保持运行, 一般来说你无需手动迁移。下方内容详细介绍了整体的迁移和变化，你也可以参照变动手动修改。
|
||||
|
||||
#### 安装兼容包
|
||||
|
||||
安装 `@ant-design/compatible` 通过指定 `v4-compatible-v3` tag 确认为 v4 兼容 v3 版本：
|
||||
|
||||
```bash
|
||||
npm install --save @ant-design/compatible@v4-compatible-v3
|
||||
```
|
||||
|
||||
#### 将已废弃的 `Form` 和 `Mention` 组件通过 `@ant-design/compatible` 包引入
|
||||
|
||||
```diff
|
||||
- import { Form, Input, Button, Mention } from 'antd';
|
||||
+ import { Form, Mention } from '@ant-design/compatible';
|
||||
+ import '@ant-design/compatible/assets/index.css';
|
||||
+ import { Input, Button } from 'antd';
|
||||
|
||||
ReactDOM.render(
|
||||
<>
|
||||
<Form>
|
||||
{getFieldDecorator('username')(<Input />)}
|
||||
<Button>Submit</Button>
|
||||
</Form>
|
||||
<Mention
|
||||
style={{ width: '100%' }}
|
||||
onChange={onChange}
|
||||
defaultValue={toContentState('@afc163')}
|
||||
defaultSuggestions={['afc163', 'benjycui']}
|
||||
onSelect={onSelect}
|
||||
/>
|
||||
</>
|
||||
);
|
||||
```
|
||||
|
||||
> **注意：**从 `@ant-design/compatible` 引入的老版本 Form 组件，样式类名会从 `.ant-form` 变成 `.ant-legacy-form`，如果你对其进行了样式覆盖，也需要相应修改。
|
||||
|
||||
#### 用新的 `@ant-design/icons` 替换字符串类型的 `icon` 属性值
|
||||
|
||||
```diff
|
||||
import { Avatar, Button, Result } from 'antd';
|
||||
+ import { QuestionOutlined, UserOutlined } from '@ant-design/icons';
|
||||
|
||||
ReactDOM.render(
|
||||
<div>
|
||||
- <Button type="primary" shape="circle" icon="search" />
|
||||
+ <Button type="primary" shape="circle" icon={SearchOutlined} />
|
||||
- <Avatar shape="square" icon="user" />
|
||||
+ <Avatar shape="square" icon={UserOutlined} />
|
||||
<Result
|
||||
- icon="question"
|
||||
+ icon={<QuestionOutlined />}
|
||||
title="Great, we have done all the operations!"
|
||||
extra={<Button type="primary">Next</Button>}
|
||||
/>
|
||||
</div>,
|
||||
mountNode,
|
||||
);
|
||||
|
||||
```
|
||||
|
||||
#### 将 v3 Icon 组件转换成 `@ant-design/icons` 中引入
|
||||
|
||||
```diff
|
||||
- import { Icon, Input } from 'antd';
|
||||
+ import { Input } from 'antd';
|
||||
+ import Icon, { CodeFilled, SmileOutlined, SmileTwoTone } from '@ant-design/icons';
|
||||
|
||||
const HeartSvg = () => (
|
||||
<svg width="1em" height="1em" fill="currentColor" viewBox="0 0 1024 1024">
|
||||
<path d="M923 plapla..." />
|
||||
</svg>
|
||||
);
|
||||
|
||||
const HeartIcon = props => <Icon component={HeartSvg} {...props} />;
|
||||
|
||||
ReactDOM.render(
|
||||
<div>
|
||||
- <Icon type="code" theme="filled" />
|
||||
+ <CodeFilled />
|
||||
- <Icon type="smile" theme="twoTone" twoToneColor="#eb2f96" />
|
||||
+ <SmileTwoTone twoToneColor="#eb2f96" />
|
||||
- <Icon type="code" theme={props.fill ? 'filled' : 'outlined'} />
|
||||
+ <LegacyIcon type="code" theme={props.fill ? 'filled' : 'outlined'} />
|
||||
<HeartIcon />
|
||||
<Icon viewBox="0 0 24 24">
|
||||
<title>Cool Home</title>
|
||||
<path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z" />
|
||||
</Icon>
|
||||
<Input suffix={<SmileOutlined />} />
|
||||
</div>,
|
||||
mountNode,
|
||||
);
|
||||
|
||||
```
|
||||
|
||||
#### 将 v3 LocaleProvider 组件转换成 v4 ConfigProvider 组件
|
||||
|
||||
```diff
|
||||
- import { LocaleProvider } from 'antd';
|
||||
+ import { ConfigProvider } from 'antd';
|
||||
|
||||
ReactDOM.render(
|
||||
- <LocaleProvider {...yourConfig}>
|
||||
+ <ConfigProvider {...yourConfig}>
|
||||
<Main />
|
||||
- </LocaleProvider>
|
||||
+ </ConfigProvider>
|
||||
mountNode,
|
||||
);
|
||||
```
|
||||
|
||||
#### 将 `Modal.method()` 中字符串 icon 属性的调用转换成从 `@ant-design/icons` 中引入
|
||||
|
||||
```diff
|
||||
import { Modal } from 'antd';
|
||||
+ import { AntDesignOutlined } from '@ant-design/icons';
|
||||
|
||||
Modal.confirm({
|
||||
- icon: 'ant-design',
|
||||
+ icon: <AntDesignOutlined />,
|
||||
title: 'Do you Want to delete these items?',
|
||||
content: 'Some descriptions',
|
||||
onOk() {
|
||||
console.log('OK');
|
||||
},
|
||||
onCancel() {
|
||||
console.log('Cancel');
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## 遇到问题
|
||||
|
||||
v4 做了非常多的细节改进和重构，我们尽可能收集了已知的所有不兼容变化和相关影响，但是有可能还是有一些场景我们没有考虑到。如果你在升级过程中遇到了问题，请到 [GitHub issues](http://new-issue.ant.design/) 和 [codemod Issues](https://github.com/ant-design/codemod-v4/issues) 进行反馈。我们会尽快响应和相应改进这篇文档。
|
||||
@ -139,7 +139,7 @@ export default {
|
||||
export default App;
|
||||
```
|
||||
|
||||
- BackTop components are removed in 5.0.0, and moved to FloatButton components, If you need to use, you can import it from the FloatButton components.
|
||||
- BackTop is deprecated in `5.0.0`, and is merged into FloatButton.
|
||||
|
||||
```diff
|
||||
- import { BackTop } from 'antd';
|
||||
@ -159,6 +159,8 @@ export default {
|
||||
|
||||
#### Migrate with codemod
|
||||
|
||||
> Not provided yet, coming soon after `5.0.0` release.
|
||||
|
||||
```bash
|
||||
# Run directly through npx
|
||||
npx -p @ant-design/codemod-v5 antd5-codemod src
|
||||
@ -177,22 +179,6 @@ antd5-codemod src
|
||||
|
||||
At the same time, you can also use the codemod tool to apply a single change for a certain change. The following is a description of all the migration scripts:
|
||||
|
||||
##### popup-visible-to-open
|
||||
|
||||
Change prop of components with popup from `visible` to `open`。
|
||||
|
||||
```bash
|
||||
antd5-codemod popup-visible-to-open <path>
|
||||
```
|
||||
|
||||
##### popup-classname-to-popupClassName
|
||||
|
||||
Change `className` of popup in components to `popupClassName`。
|
||||
|
||||
```bash
|
||||
antd5-codemod popup-classname-to-popupClassName <path>
|
||||
```
|
||||
|
||||
#### Install compatible package
|
||||
|
||||
Install `@ant-design/compatible` with `v5-compatible-v4` tag:
|
||||
|
||||
@ -140,7 +140,7 @@ export default {
|
||||
export default App;
|
||||
```
|
||||
|
||||
- BackTop 组件在 5.0.0 中移除，移至 FloatButton 悬浮按钮中，如需使用，可以从 FloatButton 中引入。
|
||||
- BackTop 组件在 `5.0.0` 中废弃，移至 FloatButton 悬浮按钮中。如需使用，可以从 FloatButton 中引入。
|
||||
|
||||
```diff
|
||||
- import { BackTop } from 'antd';
|
||||
@ -160,6 +160,8 @@ export default {
|
||||
|
||||
#### 使用迁移工具修改
|
||||
|
||||
> 将会在 5.0 正式版发布后提供。
|
||||
|
||||
```bash
|
||||
# 通过 npx 直接运行
|
||||
npx -p @ant-design/codemod-v5 antd5-codemod <path>
|
||||
@ -178,22 +180,6 @@ antd5-codemod src
|
||||
|
||||
同时也可以针对某项改动使用迁移工具单独执行，下面是所有迁移脚本的说明：
|
||||
|
||||
##### popup-visible-to-open
|
||||
|
||||
将含有弹出框的组件属性 `visible` 改为 `open`。
|
||||
|
||||
```bash
|
||||
antd5-codemod popup-visible-to-open <path>
|
||||
```
|
||||
|
||||
##### popup-classname-to-popupClassName
|
||||
|
||||
将弹出框的 `className` 属性统一为 `popupClassName`。
|
||||
|
||||
```bash
|
||||
antd5-codemod popup-classname-to-popupClassName <path>
|
||||
```
|
||||
|
||||
#### 安装兼容包
|
||||
|
||||
安装 `@ant-design/compatible` 通过指定 `v5-compatible-v4` tag 确认为 v5 兼容 v4 版本：
|
||||
|
||||
@ -32,9 +32,9 @@ if (typeof window !== 'undefined' && navigator.serviceWorker) {
|
||||
|
||||
if (typeof window !== 'undefined') {
|
||||
// Redirect to `ant.design` if is not next version anymore
|
||||
if (location.hostname === 'next.ant.design') {
|
||||
location.href = location.href.replace('next.ant.design', 'ant.design');
|
||||
}
|
||||
// if (location.hostname === 'next.ant.design') {
|
||||
// location.href = location.href.replace('next.ant.design', 'ant.design');
|
||||
// }
|
||||
|
||||
// eslint-disable-next-line global-require
|
||||
require('../../static/style');
|
||||
|
||||
Loading…
Reference in New Issue
Block a user