Shopify Polaris 从 v10 升级到 v11 完全指南-优快云博客

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

概述

Shopify Polaris v11.0.0 是一个重要的版本更新，带来了多项重大变更，包括依赖版本支持调整、组件移除和重命名、以及设计令牌（Tokens）的更新。本文将为您提供从 v10 升级到 v11 的完整指南，包含详细的迁移步骤、代码示例和最佳实践。

环境要求变更

Node.js 支持

mermaid

React 支持

React 16 和 17 不再支持
React 18 成为最低支持版本

Webpack 支持

Webpack 4 不再支持
Webpack 5 成为最低支持版本

TypeScript 变更

Polaris 不再支持多个 TypeScript 版本，现在只构建一套基于当前项目 TypeScript 版本的类型定义。

// v10 中的类型导入
import { ComponentProps } from '@shopify/polaris/build/ts/latest';

// v11 中的类型导入  
import { ComponentProps } from '@shopify/polaris/build/ts';

组件迁移指南

文本组件统一迁移

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

移除的组件	推荐的替代方案
`DisplayText`	`Text` + `variant` 属性
`Heading`	`Text` + `as="h2"` + `variant`
`Subheading`	`Text` + `as="h3"` + `variant`
`Caption`	`Text` + `as="p"` + `variant`
`TextStyle`	`Text` + 相应属性
`VisuallyHidden`	`Text` + `visuallyHidden` 属性

迁移命令

# 迁移所有文本组件
npx @shopify/polaris-migrator v10-react-replace-text-components <path>

# 迁移特定文本组件
npx @shopify/polaris-migrator v10-react-replace-text-components --componentName='DisplayText' <path>

代码示例对比

// v10 代码
<DisplayText size="medium">销售数据</DisplayText>
<Heading>在线商店仪表板</Heading>
<TextStyle variation="subdued">无供应商列表</TextStyle>

// v11 代码  
<Text as="p" variant="headingXl">销售数据</Text>
<Text as="h2" variant="headingMd">在线商店仪表板</Text>
<Text as="span" color="subdued">无供应商列表</Text>

布局组件重命名

mermaid

迁移步骤

首先迁移旧组件到 Legacy 版本

# 迁移 Stack 到 LegacyStack
npx @shopify/polaris-migrator react-rename-component <path> \
  --renameFrom="Stack" --renameTo="LegacyStack" \
  --renamePropsFrom="StackProps" --renamePropsTo="LegacyStackProps"

# 迁移 Card 到 LegacyCard  
npx @shopify/polaris-migrator react-rename-component <path> \
  --renameFrom="Card" --renameTo="LegacyCard" \
  --renamePropsFrom="CardProps" --renamePropsTo="LegacyCardProps"

然后迁移 Alpha 组件到正式名称

# 迁移 AlphaCard 到 Card
npx @shopify/polaris-migrator react-rename-component <path> \
  --renameFrom="AlphaCard" --renameTo="Card" \
  --renamePropsFrom="AlphaCardProps" --renamePropsTo="CardProps"

面包屑导航属性更新

v11 将 breadcrumbs 属性统一改为 backAction：

// v10 代码
<Page breadcrumbs={[{url: '/', content: '首页'}]}>
<SkeletonPage breadcrumbs>

// v11 代码
<Page backAction={{url: '/', content: '首页'}}>
<SkeletonPage backAction>

迁移命令

# 迁移 Page 组件的 breadcrumbs
npx @shopify/polaris-migrator v11-react-update-page-breadcrumbs <path>

# 迁移 SkeletonPage 和 Breadcrumbs 组件
npx @shopify/polaris-migrator react-rename-component-prop <path> \
  --componentName="SkeletonPage" --from="breadcrumbs" --to="backAction"

npx @shopify/polaris-migrator react-rename-component-prop <path> \
  --componentName="Breadcrumbs" --from="breadcrumbs" --to="backAction"

设计令牌迁移

v11 引入了新的设计令牌系统，需要迁移自定义样式：

颜色令牌迁移

// v10 自定义样式
.element {
  color: var(--p-color-text);
  background: var(--p-color-bg-surface);
}

// v11 迁移后
.element {
  color: var(--p-text);
  background: var(--p-surface);
}

边框和间距令牌

// v10
border: var(--p-border-width-1) solid var(--p-color-border);
padding: var(--p-space-4);

// v11  
border: var(--p-border-width-1) solid var(--p-border);
padding: var(--p-space-400);

迁移命令

# 迁移边框令牌
npx @shopify/polaris-migrator v11-styles-replace-custom-property-border <path>

# 迁移颜色令牌
npx @shopify/polaris-migrator v11-styles-replace-custom-property-color <path>

# 迁移深度令牌
npx @shopify/polaris-migrator v11-styles-replace-custom-property-depth <path>

迁移工作流程

逐步迁移指南

环境准备

# 检查当前环境
node --version  # 确保 ≥16
npm ls react    # 确保 ≥18

依赖更新

{
  "dependencies": {
    "@shopify/polaris": "^11.0.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "devDependencies": {
    "@shopify/polaris-migrator": "^1.0.0"
  }
}

执行迁移

# 安装迁移工具
npm install -g @shopify/polaris-migrator

# 执行完整迁移
npx @shopify/polaris-migrator v10-react-replace-text-components src/
npx @shopify/polaris-migrator react-rename-component src/ \
  --renameFrom="Stack" --renameTo="LegacyStack"
npx @shopify/polaris-migrator v11-react-update-page-breadcrumbs src/

手动检查和处理

# 检查未迁移的组件
grep -r "DisplayText\|Heading\|Subheading" src/ --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx"

# 检查未迁移的样式
grep -r "--p-color-" src/ --include="*.css" --include="*.scss"

常见问题解决

迁移后验证正则表达式

// 检查未迁移的文本组件
/<(DisplayText|Heading|Subheading|Caption|TextStyle|VisuallyHidden)[\s>]/g

// 检查未迁移的布局组件  
/<(Stack|Card|Filters|Tabs|Inline)[\s>]/g

// 检查未迁移的breadcrumbs属性
/breadcrumbs(=| )/g

样式覆盖处理

如果项目中有自定义样式覆盖，需要手动更新类名：

/* v10 自定义样式 */
.Polaris-DisplayText--sizeLarge {
  font-size: 2rem;
}

/* v11 需要更新为 */
.Polaris-Text--variantHeading2xl {
  font-size: 2rem;
}

性能优化建议

迁移后的包大小优化

# 分析包大小
npx webpack-bundle-analyzer dist/main.js

# 移除不再使用的组件引用
import { 
  DisplayText, 
  Heading, 
  // 其他已移除组件...
} from '@shopify/polaris'; // ← 移除这些导入

Tree Shaking 优化

确保只导入需要的组件：

// 推荐：按需导入
import { Text, Card, Button } from '@shopify/polaris';

// 避免：整体导入
import * as Polaris from '@shopify/polaris';

总结

Shopify Polaris v11 的迁移虽然涉及多个重大变更，但通过系统化的迁移策略和工具支持，可以相对顺利地完成升级。关键步骤包括：

环境准备：确保 Node.js、React、Webpack 满足最低要求
组件迁移：使用官方迁移工具自动化处理文本组件和布局组件
令牌更新：迁移设计令牌到新命名规范
全面测试：验证所有功能正常，处理边缘情况

遵循本文的迁移指南，您将能够高效、安全地将项目从 Polaris v10 升级到 v11，享受新版本带来的性能改进和开发体验提升。

立即行动：开始您的迁移之旅，体验 Polaris v11 更现代化、更一致的组件库！

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

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