config: 添加 Playwright MCP 配置和 Ant Design v6 迁移文档

Tevin

3 days ago 8e51a55a18fff55928990fe72a9f4b753ca3d281

config: 添加 Playwright MCP 配置和 Ant Design v6 迁移文档

添加 .mcp.json 配置 Playwright MCP 服务器。
添加 antd-migration-v6.zh-CN.md 迁移参考文档。

Co-Authored-By: ClaudeCode

 .mcp.json

New file
@@ -0,0 +1,9 @@
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp", "start", "--port", "9090"],
      "description": "Playwright browser automation for component testing"
    }
  }
}

 antd-migration-v6.zh-CN.md

New file
@@ -0,0 +1,389 @@
---
group:
  title: 迁移
  order: 2
order: 0
title: 从 v5 到 v6
---

本文档将帮助你从 antd `5.x` 版本升级到 antd `6.x` 版本。本次升级为一次技术升级，虽然组件 API 保持兼容，但在升级前您需要确保您的环境满足新的要求。

## 升级准备

1. 请先升级到 **v5 最新版本**，按照控制台 warning 信息处理已废弃 API。
2. 确认项目可以运行在 **React 18 及以上**版本，v6 不再支持 React 17 及以下。
3. v6 仅支持现代浏览器，并默认使用 **CSS variables**，因此不再支持 IE。

```bash
npm install --save antd@6
# 或
yarn add antd@6
# 或
pnpm add antd@6
```

## v6 有哪些不兼容的变化

### React 版本支持调整

- `antd@6` 要求 React 版本 >= 18，不再支持 React 17 及以下。
- 不再需要 `@ant-design/v5-patch-for-react-19` 来兼容 React 19，如果使用可以移除该依赖。

```diff
- import '@ant-design/v5-patch-for-react-19';
```

### @ant-design/icons 版本升级

- `antd@6` 要求 `@ant-design/icons` 版本 >= 6.0.0。
- ⚠️ **重要**：`@ant-design/icons@6` 与 `antd@5` 不兼容，请确保同时升级两个包。
- 如果你的项目显式依赖 `@ant-design/icons`，需要同步升级到 v6 版本。

```bash
npm install --save @ant-design/icons@6
# 或
yarn add @ant-design/icons@6
# 或
pnpm add @ant-design/icons@6
```

如果你在升级过程中遇到构建错误，请检查 `@ant-design/icons` 版本是否与 `antd` 版本匹配。

### DOM 调整

- v6 对大量组件的 DOM 结构进行了升级和优化，以提升可维护性和一致性。
- 对于大多数正常使用 antd 样式的项目，这不会产生影响。
- ⚠️ 如果你的项目中存在针对组件内部 DOM 节点的自定义样式（例如依赖特定选择器或层级结构），升级后可能需要手动检查并调整样式。

### API 调整

⚠️ 下列 API 已被标记为**废弃（Deprecated）**。尽管这些属性当前仍可使用，但控制台会提示弃用警告，并将在 7.0 中被移除。为保持代码的可维护性和兼容性，**建议尽快迁移到对应的替代属性**。

- `Alert`
  - `closeText` 弃用，变为 `closable.closeIcon`。
  - `message` 弃用，变为 `title`。

- `Anchor`
  - `Anchor children` 弃用，变为 `items`。

- `AutoComplete`
  - `dropdownMatchSelectWidth` 弃用，变为 `popupMatchSelectWidth`。
  - `dropdownStyle` 弃用，变为 `styles.popup.root`。
  - `dropdownClassName` 弃用，变为 `classNames.popup.root`。
  - `popupClassName` 弃用，变为 `classNames.popup.root`。
  - `dropdownRender` 弃用，变为 `popupRender`。
  - `onDropdownVisibleChange` 弃用，变为 `onOpenChange`。
  - `dataSource` 弃用，变为 `options`。

- `Avatar.Group`
  - `maxCount` 弃用，变为 `max={{ count: number }}`。
  - `maxStyle` 弃用，变为 `max={{ style: CSSProperties }}`。
  - `maxPopoverPlacement` 弃用，变为 `max={{ popover: PopoverProps }}`。
  - `maxPopoverTrigger` 弃用，变为 `max={{ popover: PopoverProps }}`。

- `BackTop`
  - `BackTop` 弃用，变为 `FloatButton.BackTop`。

- `Breadcrumb`
  - `routes` 弃用，变为 `items`。
  - `Breadcrumb.Item` 和 `Breadcrumb.Separator` 弃用，变为 `items`。

- `Button.Group`
  - `Button.Group` 弃用，变为 `Space.Compact`。

- `Button`
  - `iconPosition` 弃用，变为 `iconPlacement`。

- `Calendar`
  - `dateFullCellRender` 弃用，变为 `fullCellRender`。
  - `dateCellRender` 弃用，变为 `cellRender`。
  - `monthFullCellRender` 弃用，变为 `fullCellRender`。
  - `monthCellRender` 弃用，变为 `cellRender`。

- `Card`
  - `headStyle` 弃用，变为 `styles.header`。
  - `bodyStyle` 弃用，变为 `styles.body`。
  - `bordered` 弃用，变为 `variant`。

- `Carousel`
  - `dotPosition` 弃用，变为 `dotPlacement`。

- `Cascader`
  - `dropdownClassName` 弃用，变为 `classNames.popup.root`。
  - `dropdownStyle` 弃用，变为 `styles.popup.root`。
  - `dropdownRender` 弃用，变为 `popupRender`。
  - `dropdownMenuColumnStyle` 弃用，变为 `popupMenuColumnStyle`。
  - `onDropdownVisibleChange` 弃用，变为 `onOpenChange`。
  - `onPopupVisibleChange` 弃用，变为 `onOpenChange`。
  - `bordered` 弃用，变为 `variant`。

- `Collapse`
  - `destroyInactivePanel` 弃用，变为 `destroyOnHidden`。
  - `expandIconPosition` 弃用，变为 `expandIconPlacement`。

- `Collapse.Panel`
  - `disabled` 弃用，变为 `collapsible="disabled"`。

- `ConfigProvider`
  - `dropdownMatchSelectWidth` 弃用，变为 `popupMatchSelectWidth`。

- `DatePicker.RangePicker`
  - `dropdownClassName` 弃用，变为 `classNames.popup.root`。
  - `popupClassName` 弃用，变为 `classNames.popup.root`。
  - `popupStyle` 弃用，变为 `styles.popup.root`。
  - `bordered` 弃用，变为 `variant`。
  - `onSelect` 弃用，变为 `onCalendarChange`。

- `DatePicker`
  - `dropdownClassName` 弃用，变为 `classNames.popup.root`。
  - `popupClassName` 弃用，变为 `classNames.popup.root`。
  - `popupStyle` 弃用，变为 `styles.popup.root`。
  - `bordered` 弃用，变为 `variant`。
  - `onSelect` 弃用，变为 `onCalendarChange`。

- `Descriptions`
  - `labelStyle` 弃用，变为 `styles.label`。
  - `contentStyle` 弃用，变为 `styles.content`。

- `Divider`
  - `type` 弃用，变为 `orientation`。
  - `orientationMargin` 弃用，变为 `styles.content.margin`。

- `Drawer`
  - `headerStyle` 弃用，变为 `styles.header`。
  - `bodyStyle` 弃用，变为 `styles.body`。
  - `footerStyle` 弃用，变为 `styles.footer`。
  - `contentWrapperStyle` 弃用，变为 `styles.wrapper`。
  - `maskStyle` 弃用，变为 `styles.mask`。
  - `drawerStyle` 弃用，变为 `styles.section`。
  - `destroyInactivePanel` 弃用，变为 `destroyOnHidden`。
  - `width` 弃用，变为 `size`。
  - `height` 弃用，变为 `size`。

- `Dropdown.Button`
  - `Dropdown.Button` 弃用，变为 `Space.Compact + Dropdown + Button`。

- `Dropdown`
  - `dropdownRender` 弃用，变为 `popupRender`。
  - `destroyPopupOnHide` 弃用，变为 `destroyOnHidden`。
  - `overlayClassName` 弃用，变为 `classNames.root`。
  - `overlayStyle` 弃用，变为 `styles.root`。
  - `placement: xxxCenter` 弃用，变为 `placement: xxx`。

- `Empty`
  - `imageStyle` 弃用，变为 `styles.image`。

- `FloatButton`
  - `description` 弃用，变为 `content`。

- `Image`
  - `wrapperStyle` 弃用，变为 `styles.root`。
  - `visible` 弃用，变为 `open`。
  - `onVisibleChange` 弃用，变为 `onOpenChange`。
  - `maskClassName` 弃用，变为 `classNames.cover`。
  - `rootClassName` 弃用，变为 `classNames.root`。
  - `toolbarRender` 弃用，变为 `actionsRender`。

- `Input.Group`
  - `Input.Group` 弃用，变为 `Space.Compact`。

- `InputNumber`
  - `bordered` 弃用，变为 `variant`。
  - `addonAfter` 弃用，变为 `Space.Compact`。
  - `addonBefore` 弃用，变为 `Space.Compact`。

- `Mentions`
  - `Mentions.Option` 弃用，变为 `options`。

- `Menu`
  - `children` 弃用，变为 `items`。

- `Modal`
  - `bodyStyle` 弃用，变为 `styles.body`。
  - `maskStyle` 弃用，变为 `styles.mask`。
  - `destroyOnClose` 弃用，变为 `destroyOnHidden`。

- `Notification`
  - `btn` 弃用，变为 `actions`。
  - `message` 弃用，变为 `title`。

- `Progress`
  - `strokeWidth` 弃用，变为 `size`。
  - `width` 弃用，变为 `size`。
  - `trailColor` 弃用，变为 `railColor`。
  - `gapPosition` 弃用，变为 `gapPlacement`。

- `Select`
  - `dropdownMatchSelectWidth` 弃用，变为 `popupMatchSelectWidth`。
  - `dropdownStyle` 弃用，变为 `styles.popup.root`。
  - `dropdownClassName` 弃用，变为 `classNames.popup.root`。
  - `popupClassName` 弃用，变为 `classNames.popup.root`。
  - `dropdownRender` 弃用，变为 `popupRender`。
  - `onDropdownVisibleChange` 弃用，变为 `onOpenChange`。
  - `bordered` 弃用，变为 `variant`。

- `Slider`
  - `tooltipPrefixCls` 弃用，变为 `tooltip.prefixCls`。
  - `getTooltipPopupContainer` 弃用，变为 `tooltip.getPopupContainer`。
  - `tipFormatter` 弃用，变为 `tooltip.formatter`。
  - `tooltipPlacement` 弃用，变为 `tooltip.placement`。
  - `tooltipVisible` 弃用，变为 `tooltip.open`。

- `Space.Compact`
  - `direction` 弃用，变为 `orientation`。

- `Space`
  - `direction` 弃用，变为 `orientation`。
  - `split` 弃用，变为 `separator`。

- `Splitter`
  - `layout` 弃用，变为 `orientation`。

- `Countdown`
  - `<Statistic.Countdown />` 弃用，变为 `<Statistic.Timer type="countdown" />`。

- `Statistic`
  - `valueStyle` 弃用，变为 `styles.content`。

- `Steps`
  - `labelPlacement` 弃用，变为 `titlePlacement`。
  - `progressDot` 弃用，变为 `type="dot"`。
  - `direction` 弃用，变为 `orientation`。
  - `items.description` 弃用，变为 `items.content`。

- `Table`
  - `pagination.position` 弃用，变为 `pagination.placement`。
  - `onSelectInvert` 弃用，变为 `onChange`。
  - `filterDropdownOpen` 弃用，变为 `filterDropdownProps.open`。
  - `onFilterDropdownOpenChange` 弃用，变为 `filterDropdownProps.onOpenChange`。
  - `filterCheckall` 弃用，变为 `locale.filterCheckAll`。

- `Tabs`
  - `popupClassName` 弃用，变为 `classNames.popup`。
  - `tabPosition` 弃用，变为 `tabPlacement`。
  - `destroyInactiveTabPane` 弃用，变为 `destroyOnHidden`。
  - `Tabs.TabPane` 弃用，变为 `items`。

- `Tag`
  - `bordered={false}` 弃用，变为 `variant="filled"`。
  - `color="xxx-inverse"` 弃用，变为 `variant="solid"`。

- `TimePicker`
  - `addon` 弃用，变为 `renderExtraFooter`。

- `Timeline`
  - `Timeline.Item` 弃用，变为 `items`。
  - `pending` 弃用，变为 `items`。
  - `pendingDot` 弃用，变为 `items`。
  - `mode=left|right` 弃用，变为 `mode=start|end`。

- `Tooltip`
  - `overlayStyle` 弃用，变为 `styles.root`。
  - `overlayInnerStyle` 弃用，变为 `styles.container`。
  - `overlayClassName` 弃用，变为 `classNames.root`。
  - `destroyTooltipOnHide` 弃用，变为 `destroyOnHidden`。

- `Transfer`
  - `listStyle` 弃用，变为 `styles.section`。
  - `operationStyle` 弃用，变为 `styles.actions`。
  - `operations` 弃用，变为 `actions`。

- `TreeSelect`
  - `dropdownMatchSelectWidth` 弃用，变为 `popupMatchSelectWidth`。
  - `dropdownStyle` 弃用，变为 `styles.popup.root`。
  - `dropdownClassName` 弃用，变为 `classNames.popup.root`。
  - `popupClassName` 弃用，变为 `classNames.popup.root`。
  - `dropdownRender` 弃用，变为 `popupRender`。
  - `onDropdownVisibleChange` 弃用，变为 `onOpenChange`。
  - `bordered` 弃用，变为 `variant`。

### 弹层类组件（Modal、Drawer 等）

- 新增 `mask` 蒙层功能，并支持模糊效果。
- 默认开启，可通过以下方式关闭模糊：

```tsx
import { ConfigProvider, Drawer, Modal } from 'antd';

export default () => (
  <ConfigProvider
    modal={{
      mask: {
        blur: false,
      },
    }}
    drawer={{
      mask: {
        blur: false,
      },
    }}
  >
    <Modal />
    <Drawer />
  </ConfigProvider>
);
```

### Tag margin 调整

v6 移除了 `Tag` 组件末尾的默认外边距（以前 Tag 末尾会额外留出一段 `margin-inline-end`）。如果你的布局或自定义样式依赖这一行为，请使用 `ConfigProvider` 的 `tag.styles` 进行补充：

```tsx
import { ConfigProvider, Tag } from 'antd';

export default () => (
  <ConfigProvider
    tag={{
      styles: {
        root: {
          marginInlineEnd: 8,
        },
      },
    }}
  >
    <Tag>Tag A</Tag>
    <Tag>Tag B</Tag>
    <Tag>Tag C</Tag>
  </ConfigProvider>
);
```

### Form `onFinish` 取值不再包含 Form.List 全部数据

v5 版本中，Form.List 会被认为是一个 Field，以至于提交时会包含 Form.List 下的所有数据结构即便其子元素的 Form.Item 没有注册过。在 v6 中，Form.List 不再包含未注册的子项数据。因而你不再需要通过 `getFieldsValue({ strict: true })` 来过滤未注册字段。

```diff
    const onFinish = (values) => {
--    const realValues = getFieldsValue({ strict: true });
++    const realValues = values;

      // ...
    }

    <Form onFinish={onFinish} />
```

### 浏览器支持调整

- 默认开启 **CSS variables**，仅支持现代浏览器。
- IE 浏览器不再支持，部分旧版国产浏览器可能存在兼容性问题，请在应用发布前确认目标浏览器的支持情况。

### 原子级通过别名安装 v6

- 如果你需要控制升级的影响范围，可以尝试[原子级迁移](https://github.com/ant-design/ant-design/discussions/55957)方案。请注意，这并非我们推荐的升级路径。

## 升级影响排查 Checklist

为了确保升级到 v6 后项目正常运行，请参考以下检查清单逐项确认：

- **React 版本**：确认项目使用的 React 版本 >= 18，并且不再引入 `@ant-design/v5-patch-for-react-19`。
- **@ant-design/icons 版本**：确认 `@ant-design/icons` 版本已升级到 >= 6.0.0，与 `antd@6` 匹配。
- **浏览器兼容性**：确认目标用户浏览器均为现代浏览器，且支持 CSS variables。
- **自定义样式检查**：如果有针对组件内部 DOM 节点的 CSS 定制，验证在 v6 下是否依然生效。
- **弹层蒙层配置**：Modal、Drawer 等弹层是否需要关闭 `mask` 的模糊效果，如不需要可保持默认。
- **构建工具配置**：确认升级后构建无报错，CSS 变量和 CSS-in-JS 能正常工作。
- **控制台 warning**：运行应用并观察控制台，处理所有 `legacy API` 的提示。

## 遇到问题

如果您在升级过程中遇到问题，请到 [GitHub issues](https://new-issue.ant.design/) 进行反馈。我们会尽快响应并在文档中完善相关说明。