Skip to main content

Strapi 设计系统已升级到 v2

¥The Strapi Design System has been upgraded to v2

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

¥The Strapi Design System  has been completely updated in Strapi 5 with significant changes to component structure, APIs, and usage patterns.

此页面是 重大变更数据库 的一部分，提供有关重大更改的信息以及从 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 中

¥In 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 中

¥In 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:

  • 根导入而不是直接组件路径

    ¥Root imports instead of direct component paths

  • Styled-components 升级到 v6

    ¥Styled-components upgraded to v6

  • 许多组件迁移到 Radix-UI 原语

    ¥Many components migrated to Radix-UI primitives

  • 表单元素的新字段 API

    ¥New Field API for form elements

  • 现在包含 TypeScript 定义

    ¥TypeScript definitions now included

  • 几个组件已重命名或删除

    ¥Several components renamed or removed

迁移​

¥Migration

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

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

注意​

¥Notes

  • 有关详细的迁移信息，请参阅 设计系统迁移指南 。

    ¥For detailed migration information, refer to the Design System migration guide .

  • 应用的基本字体大小现在是 62.5% (10px)，因此 1rem = 10px。

    ¥The base font-size for the app is now 62.5% (10px), so 1rem = 10px.

  • 许多图标已更新或替换。

    ¥Many icons have been updated or replaced.

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

¥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

    ¥Renamed components: ToggleInput → Toggle

  • 已删除的组件：Icon、Stack、ToggleCheckbox、Select/Option/OptGroup/SelectList（改用 SingleSelect 或 MultiSelect）

    ¥Removed components: Icon, Stack, ToggleCheckbox, Select/Option/OptGroup/SelectList (use SingleSelect or MultiSelect instead)

  • 布局组件移至 CMS：Layout、MainNav、HeaderLayout、TwoColsLayout、GridLayout、ActionLayout、ContentLayout

    ¥Layout components moved to CMS: Layout, MainNav, HeaderLayout, TwoColsLayout, GridLayout, ActionLayout, ContentLayout

  • 新 prop 命名:as 现在是多态组件的 tag

    ¥New prop naming: as is now tag for polymorphic components

  • Radix-UI 迁移：许多组件包括 Accordion、Avatar、Checkbox、Dialog、Modal、Popover、Radio、Tabs、Tooltip

    ¥Radix-UI migrations: Many components including Accordion, Avatar, Checkbox, Dialog, Modal, Popover, Radio, Tabs, Tooltip

手动程序​

¥Manual procedure

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

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

  1. 更新所有设计系统导入以使用根导入。

    ¥Update all Design System imports to use root imports.

  2. 将组件用法迁移到新 API。

    ¥Migrate component usages to the new APIs.

  3. 更新图标使用。

    ¥Update icon usage.

  4. 用从 @strapi/admin/strapi-admin 导入的组件替换布局组件。

    ¥Replace Layout components with imports from @strapi/admin/strapi-admin.

  5. 更新样式以适应新的基本字体大小。

    ¥Update styling to account for the new base font size.