Strapi 设计系统已升级到 v2

页面摘要： Strapi 设计系统在 Strapi 5 中已升级到 v2，涉及导入结构、组件 API 和样式的变更，包括根导入、Radix-UI 迁移、新的 Field API，以及 62.5% 的新基础字号。

Strapi 设计系统在 Strapi 5 中已完全更新，组件结构、API 和使用方式都发生了重大变化。

本页面是破坏性变更数据库的一部分，提供有关该破坏性变更的信息，以及从 Strapi v4 迁移到 Strapi 5 的附加说明。

破坏性变更说明

在 Strapi v4 中

Strapi 设计系统 v1 采用特定的方式，包括直接导入、styled-components v5，以及某些自此已修订的组件 API。

在 Strapi 5 中

Strapi 设计系统 v2 已完全更新，重点关注可访问性、API 一致性和更好的类型支持。主要变化包括：

使用根导入而非直接组件路径
styled-components 升级到 v6
许多组件迁移到 Radix-UI 原语
表单元素使用新的 Field API
现已包含 TypeScript 类型定义
多个组件被重命名或移除

迁移

本节汇总了关于该破坏性变更的有用说明和操作步骤。

说明

有关详细的迁移信息，请参阅设计系统迁移指南。
应用的基础字号现在为 62.5%（10px），即 1rem = 10px。
许多图标已更新或被替换。

需要注意的主要变化如下：

导入结构变更

- import { Combobox } from '@strapi/design-system/Combobox';
+ import { Combobox } from '@strapi/design-system';

ThemeProvider 迁移

- import { ThemeProvider } from '@strapi/design-system';
+ import { DesignSystemProvider } from '@strapi/design-system';

Field 组件 API 变更

- return <SingleSelect label={label} error={error} required={required} value={value} onChange={handleChange} />;
+ return (
+   <Field.Root error={error} required={required} name={name}>
+     <Field.Label>{label}</Field.Label>
+     <SingleSelect value={value} onChange={handleChange} />
+     <Field.Error />
+     <Field.Hint />
+   </Field.Root>
+ );

Grid 组件结构

- import { Grid, GridItem } from '@strapi/design-system';
+ import { Grid } from '@strapi/design-system';

- <Grid gridCols={4}>
-   <GridItem col={2}>1</GridItem>
-   <GridItem col={2}>2</GridItem>
- </Grid>
+ <Grid.Root gridCols={4}>
+   <Grid.Item>1</Grid.Item>
+   <Grid.Item>2</Grid.Item>
+ </Grid.Root>

组件变更摘要

重命名的组件：ToggleInput → Toggle
移除的组件：Icon、Stack、ToggleCheckbox、Select/Option/OptGroup/SelectList（改用 SingleSelect 或 MultiSelect）
布局组件已移至 CMS：Layout、MainNav、HeaderLayout、TwoColsLayout、GridLayout、ActionLayout、ContentLayout
新的属性命名：对于多态组件，as 现为 tag
Radix-UI 迁移：许多组件，包括 Accordion、Avatar、Checkbox、Dialog、Modal、Popover、Radio、Tabs、Tooltip

手动操作步骤

此迁移没有 codemod。用户需要手动：

将所有设计系统导入更新为使用根导入。
将组件用法迁移到新 API。
更新图标的使用方式。
用来自 @strapi/admin/strapi-admin 的导入替换布局组件。
更新样式以适配新的基础字号。