Shopify Polaris 从 v10 升级到 v11 完全指南

Shopify Polaris 从 v10 升级到 v11 完全指南

polaris polaris: 是Shopify开发的一套设计系统，包含了用于构建Web界面的组件和样式指南。 项目地址: https://gitcode.com/gh_mirrors/po/polaris

前言

Shopify Polaris 是 Shopify 官方推出的 React 组件库，为开发者提供了一套完整的 UI 组件和设计系统。随着 v11 版本的发布，Polaris 带来了一些重要的变更，本文将全面解析从 v10 升级到 v11 的关键点，帮助开发者顺利完成迁移。

环境要求变更

Node.js 支持

v11 版本不再支持 Node.js 14，最低要求提升至 Node.js 16，推荐使用 Node.js 18。

影响评估：

• 检查你的 CI/CD 环境和本地开发环境的 Node.js 版本
• 更新 .nvmrc 或相关版本管理文件

React 支持

v11 移除了对 React 16 和 17 的支持，最低要求为 React 18。

升级建议：

• 先升级 React 到 18 版本
• 检查 React 18 的新特性是否会影响现有代码

Webpack 支持

Webpack 4 不再受支持，最低要求为 Webpack 5。

迁移步骤：

1. 更新 webpack 及相关插件
2. 检查 webpack 配置兼容性
3. 测试构建流程

TypeScript 变更

TypeScript 类型定义文件位置从 build/ts/latest 移动到 build/ts，且不再支持多版本 TypeScript 类型定义。

注意事项：

• 更新类型引用路径
• 确保项目使用较新的 TypeScript 版本

组件变更详解

已移除的组件

文本相关组件

v11 移除了多个文本组件，统一使用新的 Text 组件：

• DisplayText
• Heading
• Subheading
• Caption
• TextStyle
• VisuallyHidden

迁移方案：

// 旧代码
<Heading>标题</Heading>

// 新代码
<Text as="h2" variant="headingMd">标题</Text>

迁移工具：

npx @shopify/polaris-migrator v10-react-replace-text-components <path>

其他移除的组件

• KonamiCode：趣味组件，如需使用可复制旧版源码
• Collapsible 的 preventMeasuringOnChildrenUpdate 属性

重命名的组件

多个组件被重命名为 Legacy 前缀，表示它们将在未来版本中被替代：

• Stack → LegacyStack
• Card → LegacyCard
• Filters → LegacyFilters
• Tabs → LegacyTabs

同时，Alpha 前缀的组件移除了 Alpha 标记：

• AlphaStack → Stack
• AlphaCard → Card
• AlphaFilters → Filters
• AlphaTabs → Tabs

迁移策略：

1. 先将旧组件更新为 Legacy 版本
2. 逐步迁移到新的无 Legacy 前缀组件

属性变更

面包屑属性变更

多个组件的 breadcrumbs 属性被 backAction 替代：

• SkeletonPage
• Page
• Breadcrumbs

迁移示例：

// 旧代码
<Page breadcrumbs={[{url: '/', content: 'Home'}]}>

// 新代码
<Page backAction={{url: '/', content: 'Home'}}>

迁移工具：

npx @shopify/polaris-migrator v11-react-update-page-breadcrumbs <path>

设计令牌变更

v11 对设计令牌进行了调整，主要涉及以下类别：

• 边框(Border)
• 颜色(Color)
• 深度(Depth)
• 动效(Motion)
• 旧版(Legacy)
• Z轴(Z-index)

迁移建议：

1. 审查项目中使用的设计令牌
2. 使用 Polaris 迁移工具检查不兼容的令牌
3. 逐步更新到新的令牌系统

推荐迁移流程

组件迁移步骤

1. 安装迁移工具：

   npm install -g @shopify/polaris-migrator
   

2. 运行自动迁移：

   npx @shopify/polaris-migrator v10-react-replace-text-components src/
   

3. 手动检查：

   • 使用提供的正则表达式搜索残留的旧组件
   • 视觉回归测试确保 UI 一致性

令牌迁移步骤

1. 全局搜索 @shopify/polaris-tokens 引用
2. 对照新旧令牌对照表更新
3. 检查自定义样式是否受到影响

常见问题解答

Q: 为什么移除了这么多文本组件？ A: 为了简化设计系统，统一使用更灵活的 Text 组件，提高一致性和可维护性。

Q: 迁移后样式有差异怎么办？ A: 检查是否使用了正确的 variant 和属性，Text 组件提供了更细粒度的控制能力。

Q: 必须立即迁移所有组件吗？ A: 可以分阶段迁移，Legacy 组件会暂时保留，但建议尽快完成迁移。

结语

从 Polaris v10 升级到 v11 是一次重要的版本迭代，虽然带来了一些破坏性变更，但这些变更是为了更好的设计系统一致性和未来发展。按照本文提供的迁移指南，结合官方迁移工具，可以高效完成升级工作。建议在开发环境中充分测试后再部署到生产环境。

polaris polaris: 是Shopify开发的一套设计系统，包含了用于构建Web界面的组件和样式指南。 项目地址: https://gitcode.com/gh_mirrors/po/polaris