---
group:
  title: 项目开发规范
  order: 12
title: 1.v4至v6版本迁移说明
---

## 升级准备

组件库版本v6，基于`antd@6.x`，已按官方升级API进行调整

- 确认项目内已安装 `antd` 版本 `>= 6.6.2`（与当前组件库依赖一致），
- 相关图标库也需要同步升级至 `@ant-design/icons` 版本 `>= 6.0.0`
- 升级过程中先验证 `antd v5 to v6 ` 的用法，再根据当前组件库 [更新日志](/guide/update) 上的内容进行验证

## v4与v6API差异

- `StandardModal`
    - 移除API `hideRequiredMark`，替换`requiredMark`使用
    - 新增API `formConfig`
    - 移除API `dragAble`
    - 若使用时单独配置`mask`，则优先级高于组件内`mask.closeable`限制

- `StandardDrawer`
    - 移除API `hideRequiredMark`，替换`requiredMark`使用
    - 若使用时单独配置`mask`，则优先级高于组件内`mask.closeable`限制
 
- `WrapperContent`、`SubfieldContent`、`StandardList`
  - `loadingTip` 自 6.0.0 起弃用，暂时保留兼容，请使用 `loadingConfig.description`。
  - `loadingConfig.tip` → `loadingConfig.description`。
  - `loadingConfig.wrapperClassName` → `loadingConfig.classNames.root`。
  - `StandardList` 补齐 `loadingTip` / `loadingConfig` 的实际支持；此前只有 `loading` 生效。

## Spin 配置迁移

```
// 旧配置（暂时兼容，会在开发环境提示迁移）
<WrapperContent loading loadingTip="加载中" loadingConfig={{ wrapperClassName: 'page-loading' }}>
  {children}
</WrapperContent>

// 推荐配置；SubfieldContent、StandardList 使用相同的 loadingConfig
<WrapperContent loading loadingConfig={{ description: '加载中', classNames: { root: 'page-loading' } }}>
  {children}
</WrapperContent>
```

- 文案优先级：`loadingConfig.description` 非 null/undefined 时优先，否则使用 `loadingConfig.tip`，再回退到 `loadingTip`。显式传入 `tip: undefined` 会覆盖 `loadingTip`；空字符串可以清空文案。
- `loadingConfig.spinning` 保留原有覆盖 `loading` 的能力；`SubfieldContent.loadingArea` 的分区逻辑保持不变。
- `classNames` 支持对象及函数，其他语义节点会保留。旧 `wrapperClassName` 与新 `classNames.root` 合并；CSS 同名属性冲突仍按 CSS 层叠规则决定。
- `WrapperContent` 保留旧 wrapperClassName 覆盖默认类名的行为；`SubfieldContent`、`StandardList` 会追加默认布局类名，避免破坏布局。
- Spin 的 `root` 是加载组件根节点，嵌套模式中是内容包装层；旧 `wrapperClassName` 仅在嵌套/全屏模式中兼容，独立 Spin 请直接使用新 API。

## 组合中的 Dropdown 配置迁移

容器底部通过 `footer.buttonGroupConfig.dropdownConfig` 传入，列表操作通过 `buttonGroupConfig.dropdownConfig` 传入；单个按钮也可配置 `dropdownConfig`。这些入口均由 `ButtonGroup` 统一适配，单项配置仍整体优先于按钮组配置。

| 旧配置（dropdownConfig 内） | 推荐配置 |
| --- | --- |
| overlayClassName | classNames.root |
| overlayStyle | styles.root |
| dropdownRender | popupRender |
| destroyPopupOnHide | destroyOnHidden |

```
<StandardList
  options={options}
  buttonGroup={buttons}
  buttonGroupConfig={{
    dropdownConfig: {
      classNames: { root: 'list-actions-popup' },
      styles: { root: { maxHeight: 320, overflowY: 'auto' } },
      destroyOnHidden: true,
    },
  }}
/>
```

Dropdown 的 `classNames.root` / `styles.root` 指向弹出层，不是触发按钮，也不是 Spin 内容包装层；不要写成其他组件使用的 `classNames.popup.root`。`classNames` 和 `styles` 均支持对象或函数。旧/新类名合并，样式逐属性合并且新样式优先；`popupRender`、`destroyOnHidden` 非 null/undefined 时优先（包括 `false`）。旧字段转换后不再透传给 antd。

## 后续组件的弃用提示写法

1. 在公开 Props 类型的字段上使用 `/** @deprecated 自 x.x.x 起，请使用 … */`，编辑器才能给调用方提示；不要仅注释解构变量。
2. 组件顶层调用内部 `useDeprecatedProps(componentName, rules)`，每条规则包含 `name`、`replacement`、`value`，可用 `since` 指定版本（默认 6.0.0）。传入合并全局配置后的真实值；`undefined` 不提示，`false`、空字符串、null 仍视为显式旧配置。
3. Hook 在提交后检查配置更新，仅非生产环境输出，并按组件名、字段、版本在当前模块生命周期去重；多实例、重复渲染不会刷屏，后续才传入旧字段也能提示。SSR 不执行 effect。
4. 属性转换放在独立纯函数中，负责移除旧属性、保留回调和合并语义样式。Spin 使用 `getSpinProps`，Dropdown 使用 `getDropdownProps`，不要把不同组件的 DOM 语义混成通用字段替换。

以上 Hook 和适配函数为组件库内部工具，暂不作为顶层公共导出；旧 API 是“弃用但兼容”，并未移除，也未承诺具体移除版本。

参考：[Ant Design Spin](https://ant.design/components/spin-cn/)、[Ant Design Dropdown](https://ant.design/components/dropdown-cn/)。