Skip to main content

Strapi 设计系统已升级到 v2

🌐 The Strapi Design System has been upgraded to v2

在 Strapi 5 中， Strapi Design System 已经被完全更新，组件结构、API 和使用模式都发生了重大变化。

此页面是重大更改数据库的一部分，提供关于重大更改的信息以及从 Strapi v4 迁移到 Strapi 5 的附加说明。

🌐 This page is part of the breaking changes database and provides information about the breaking change and additional instructions to migrate from Strapi v4 to Strapi 5.

 Is this breaking change affecting plugins?Yes
 Is this breaking change automatically handled by a codemod?No

重大变更描述​

🌐 Breaking change description

在 Strapi v4 中

Strapi 设计系统 v1 使用了一种特定的方法，包括直接导入、styled-components v5 和某些组件 API，这些 API 后来已被修订。

🌐 Strapi Design System v1 used a specific approach with direct imports, styled-components v5, and certain component APIs that have since been revised.

在 Strapi 5 中

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

🌐 Strapi Design System v2 has been completely updated with a focus on accessibility, API consistency, and better typing support. Major changes include:

  • 根导入而不是直接组件路径
  • Styled-components 已升级到 v6
  • 许多组件迁移到 Radix-UI 原语
  • 表单元素的新字段 API
  • 现在包含 TypeScript 定义
  • 几个组件已重命名或删除

迁移​

🌐 Migration

本节重新组合了有关引入的重大更改的有用说明和程序。

🌐 This section regroups useful notes and procedures about the introduced breaking change.

注意​

🌐 Notes

  • 有关详细的迁移信息，请参阅 the Design System migration guide。
  • 该应用的基础字体大小现在是 62.5% (10px)，因此 1rem = 10px。
  • 许多图标已更新或替换。

需要注意的关键变化包括以下内容：

🌐 Key changes to be aware of include the following:

导入结构变化​

🌐 Import structure changes

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

ThemeProvider 迁移​

🌐 ThemeProvider migration

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

字段组件 API 变更​

🌐 Field components API changes

- 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 component structure

- 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>

组件变更摘要​

🌐 Component changes summary

  • 重命名的组件：ToggleInput → Toggle
  • 已移除组件：Icon、Stack、ToggleCheckbox、Select/Option/OptGroup/SelectList（请改用 SingleSelect 或 MultiSelect）
  • 布局组件已迁移到CMS：Layout、MainNav、HeaderLayout、TwoColsLayout、GridLayout、ActionLayout、ContentLayout
  • 新属性命名：多态组件中的 as 现在是 tag
  • Radix-UI 迁移：许多组件包括手风琴、头像、复选框、对话框、模态框、弹出框、单选框、标签页、工具提示

手动操作​

🌐 Manual procedure

此迁移没有代码修改工具。用户需要手动：

🌐 There is no codemod for this migration. Users will need to manually:

  1. 更新所有设计系统导入以使用根导入。
  2. 将组件用法迁移到新 API。
  3. 更新图标使用。
  4. 将 Layout 组件替换为从 @strapi/admin/strapi-admin 导入的组件。
  5. 更新样式以适应新的基本字体大小。