北极星北极星候鸟
Codemod转换以帮助升级您的Polaris代码库。
使用
例子
NPX @shopify/polaris-migrator
迁移-迁移名称，请参阅下面文档站点上的可用迁移。路径-执行迁移的文件或目录——干做一次预演，没有代码会被编辑吗——打印输出更改后的输出以供比较
迁移
v11
v11-react-update-page-breadcrumbs
替换旧的Page组件面包屑新道具backActionProp，它接受LinkAction对象。
例子
-
例子
NPX @shopify/polaris-migrator v11-react-update-page-breadcrumb
v11-styles-replace-custom-property-border
用相应的北极星自定义属性替换值替换已弃用的边框CSS自定义属性。
例子
-border - radius: var(——p-border-radius-base);+border - radius: var(——p-border-radius-1);
例子
NPX @shopify/polaris-migrator v11-style -replace-custom-property-border
v11-styles-replace-custom-property-color
用对应的北极星自定义属性替换值替换已弃用的颜色CSS自定义属性。
例子
-颜色:var(——p-text);;+颜色:var(——p-color-text);
例子
NPX @shopify/polaris-migrator v11-style -replace-custom-property-color
v11-styles-replace-custom-property-depth
用相应的替换静态值替换已弃用的深度CSS自定义属性。
例子
-不必:var(——p-shadow-transparent);+Box-shadow: 0 0 0 0透明;
例子
NPX @shopify/polaris-migrator v11-style -replace-custom-property-depth
v11-styles-replace-custom-property-legacy
用相应的替换值(不同的Polaris自定义属性或静态值)替换废弃的遗留CSS自定义属性。
例子
-z - index: var(——p-override-loading-z-index);+z - index: var(——p-z-index-6);-宽度:var(——p-choice-size);+宽度:20 px;
例子
@shopify/polaris-migrator v11-style -replace-custom-property-legacy
v11-styles-replace-custom-property-motion
用对应的北极星自定义属性替换值替换弃用的运动CSS自定义属性。
例子
-transition-timing-function: var(——p-linear);+transition-timing-function: var(——p-motion-linear);
例子
NPX @shopify/polaris-migrator v11-style -replace-custom-property-motion
v11-styles-replace-custom-property-zindex
将弃用的z-index CSS自定义属性替换为对应的北极星自定义属性替换值。
例子
-z - index: var(——p-z-1);+z - index: var(——p-z-index-1);
例子
NPX @shopify/polaris-migrator v11-style -replace-custom-property-zindex
v10
v10-react-replace-text-components
替换遗留文本组件DisplayText，标题，副标题，标题，TextStyle,VisuallyHidden这首新单曲文本组件。
例子
-显示文本 -<标题>标题标题> < /+显示文本 +标题
例子
NPX @shopify/polaris-migrator v10-react-replace-text-components
v9
的项目@use规则，所有与Sass相关的迁移(例如:replace-sass-spacing)接受名称空间标志指向特定的<名称>。<变量函数| | mixin >。
例子
NPX @shopify/polaris-migrator v9- ——namespace="legacy-polaris-v8"
v9-scss-replace-breakpoints
用新的北极星替换旧的静态断点混合媒体查询变量。
例子
-@include page-content-when-layout-not-stacked {}+@media #{$p-breakpoints- mup} {}
例子
NPX @shopify/polaris-migrator v9-scss-replace-breakpoints
v9-scss-replace-border
替换旧SCSS的使用边境()函数边境声明与相应的北极星形状令牌。
例子
-边界:边境();+边界:var(——p-border-base);-边界:边境(分);+边界:var(——p-border-divider);
例子
NPX @shopify/polaris-migrator v9-scss-replace-border
v9-scss-replace-border-radius
替换旧SCSS的使用这个特性())作用于这个特性声明与相应的北极星形状令牌。
例子
-border - radius: border - radius ();+border - radius: var(——p-border-radius-1);-border - radius: border - radius(大);+border - radius: var(——p-border-radius-large);
例子
NPX @shopify/polaris-migrator v9-scss-replace-border-radius
v9-scss-replace-border-width
替换旧SCSS的使用边框宽度())作用于边境和边框宽度声明与相应的北极星形状令牌。
例子
-边框宽度:边框宽度();+边框宽度:var(——p-border-width-1);-边框宽度:边框宽度(厚);+边框宽度:var(——p-border-width-2);
例子
NPX @shopify/polaris-migrator v9-scss-replace-border-width
v9-scss-replace-color
替换旧的SCSS颜色()函数与支持的CSS自定义属性令牌等效(例如:var(——p-surface)）.这将只替换映射值的有限子集。看到color-maps.ts查看基于CSS属性的颜色映射的完整列表。
例子
-颜色:颜色(“墨水”);-背景:颜色(白色);+颜色:var(——p-text);+背景:var(——p-surface);
例子
NPX @shopify/polaris-migrator v9-scss-replace-color
v9-scss-replace-duration
替换旧的SCSS持续时间()函数与相应的北极星运动令牌。
例子
-transition-duration: legacy-polaris-v8.duration(“慢”);+transition-duration: var(——p -时间- 300);-过渡:不透明度legacy-polaris-v8.duration('slow')线性;+过渡:不透明度var(—p-duration-300)线性;
例子
NPX @shopify/polaris-migrator v9-scss-replace-duration
v9-scss-replace-easing
替换旧的SCSS宽松()函数与相应的北极星运动令牌。
例子
-transition-timing-function: legacy-polaris-v8.easing(“的”);+transition-timing-function: var(——p-ease-in);-过渡:不透明度300ms;+过渡:不透明度300ms var(—p-ease-in);
例子
NPX @shopify/polaris-migrator v9-scss-replace-easing
v9-scss-replace-font-family
替换旧的SCSS字体类型()函数与相应的北极星字体令牌。
例子
-字体类型:字体类型(等宽字体);+字体类型:var(——p-font-family-mono);
例子
@shopify/polaris-migrator v9-scss-replace-font-family
v9-scss-replace-font-size
替换旧的SCSS字体大小()函数与相应的北极星字体令牌。
例子
-Font-size: Font-size (input, base);+字体大小:var(——p -字体大小- 200);;
例子
NPX @shopify/polaris-migrator v9-scss-replace-font-size
v9-scss-replace-line-height
替换旧的SCSS行高()函数与相应的北极星字体令牌。
例子
-Line-height: Line-height (title, base);+字体类型:var(——p-font-line-height-2);
例子
NPX @shopify/polaris-migrator v9-scss-replace-line-height
v9-scss-replace-spacing
替换旧的SCSS间距()函数与支持的CSS自定义属性令牌等效(例如:var(——p-space-4)）.
例子
-填充:间距();-边距:间距(松)、间距(紧);+填充:var(——p-space-4);+Margin: var(——p-space-5);
例子
NPX @shopify/polaris-migrator v9-scss-replace-spacing
v9-scss-replace-text-emphasis
用相应的声明和CSS自定义属性替换旧的静态mixins。
例子
-@include text-emphasis-normal;+颜色:var(——p-text);+粗细:var(——p-font-weight-regular);
例子
NPX @shopify/polaris-migrator v9- css-replace-text-emphasis
v9-scss-replace-z-index
替换旧的SCSSz - index ()函数与支持的CSS自定义属性令牌等效(例如:var(——p-z-1)）.
的任何调用z - index ()对应于z-index设计标记，即。——p-z-1将被替换为一个CSS变量声明。方法的调用fixed-element-stacking-order美元Sass地图，即z - index(模态,fixed-element-stacking-order美元)。
例子
-.decl-1 {-z - index: z - index(内容);-}-.decl-2 {-Z-index: Z-index (modal， $fixed-element-stacking-order)-}+decl-1 {+z - index: var(——p-z-1);+}+.decl-2 {+z - index: var(——p-z-11)+}
调用的z - index在算术表达式内，将附加注释，以供审查和手动迁移。通常在这些情况下，您需要将建议的代码更改包装在calc但是，这可能会根据代码库中的具体情况而延迟。
例子
.decl-3 {+/* polaris-migrator:无法迁移以下表达式。请手动升级。* /+/* z-index: var(——p-z-1) + 1 */Z-index: Z-index (content) + 1}
调用的z - index使用自定义sass map属性，还将添加评论以供审查和手动迁移。
例子
.decl-3 {+/* polaris-migrator:无法迁移以下表达式。请手动升级。* /+/* z-index:地图。获取($custom-sass-map, modal) */Z-index: Z-index (modal， $custom-sass-map)}
在这些情况下，您可能还需要运行NPX sass-migrator module 为了确保map.get在**范围内。
请注意，这也可能在您的代码库中创建额外的代码更改，我们建议仅在存在大量迁移实例的情况下运行此操作z - index来map.get。否则可能更容易添加使用“sass:地图”到你的.scss手动文件。
例子
NPX @shopify/polaris-migrator v9-scss-replace-z-index
v9-styles-tokenize-font
用Polaris自定义属性替换遗留的静态字体值字体大小，粗细,行高声明。
例子
-字体大小:16 px;+字体大小:var(——p -字体大小- 200);-粗细:400;+粗细:var(——p-font-weight-regular);-行高:20 px;+字体类型:var(——p-font-line-height-2);
例子
NPX @shopify/polaris-migrator v9-style -tokenize-font
v9-styles-tokenize-motion
更换定时(女士，年代)中的转换声明(过渡，transition-duration，transition-delay,transition-timing-function)和动画声明(动画，动画，animation-delay,animation-timing-function)和相应的北极星运动令牌。
例子
-transition-duration: 100毫秒;+transition-duration: var(——p -时间- 100);-transition-timing-function:线性;+transition-timing-function: var(——p-linear);-过渡:不透明度100ms线性;+过渡:不透明度var(—p-duration-100)线性;-过渡:不透明度100ms线性，左100ms线性;+过渡:不透明度var(—p-duration-100)线性，左变量var(—p-duration-100)线性;-动画:100毫秒;+动画:var(——p -时间- 100);-animation-timing-function:线性;+animation-timing-function: var(——p-linear);-动画:100ms线性淡出;+动画:var(——p-duration-100)线性淡出;-动画:100ms线性滑动，100ms线性滑动;+var(——p-duration-100) linear slideIn, var(——p-duration-100) linear slideIn;
例子
NPX @shopify/polaris-migrator v9-style -tokenize-motion
v9-styles-tokenize-shape
替换旧SCSS的使用快速眼动()函数和硬编码长度(px，快速眼动)边境，边框宽度,这个特性声明与相应的北极星形状令牌。
例子
-边框:1px实心透明;+Border: var(——p-border-width-1)实心透明;-边框宽度:0.0625快速眼动;+边框宽度:var(——p-border-width-1);-border - radius: 4 px;+border - radius: var(——p-border-radius-1);
例子
NPX @shopify/polar -migrator v9-replace-border-declarations
v9-styles-tokenize-space
替换长度和函数(px，快速眼动和快速眼动())中的空格声明(填充，保证金,差距)，并使用相应的北极星间距标记。
例子
-填充:16 px;+填充:var(——p-space-4);-保证金:1快速眼动;+保证金:var(——p-space-4);-差距:快速眼动(16 px);+差距:var(——p-space-4);
例子
NPX @shopify/polaris-migrator v9-style -tokenize-space
v9-styles-replace-custom-property-border
用相应的替换值(不同的Polaris自定义属性或静态值)替换已弃用的边框CSS自定义属性。
例子
-border - radius: var(——p-border-radius-base);+border - radius: var(——p-border-radius-1);-border - radius: var(——p-text-field-focus-ring-border-radius);+border - radius: 7 px;
例子
NPX @shopify/polaris-migrator v9-style -replace-custom-property-border
v9-styles-replace-custom-property-depth
用相应的替换值替换弃用的深度CSS自定义属性(不同的Polaris自定义属性或静态值)。
例子
-不必:var(——p-button-drop-shadow);+不必:var(——p-shadow-button);-Box-shadow: 1px var(——p-shadow-from-ambient-light);+Box-shadow: 1px 1px rgba(23,24,24,0.05);
例子
NPX @shopify/polaris-migrator v9-style -replace-custom-property-depth
v9-styles-replace-custom-property-font
用相应的北极星自定义属性替换值替换已弃用的字体CSS自定义属性。
例子
-粗细:var(——p-badge-font-weight);+粗细:var(——p-font-weight-regular);
例子
NPX @shopify/polaris-migrator v9-style -replace-custom-property-font
v9-styles-replace-custom-property-motion
用对应的北极星自定义属性替换值替换弃用的运动CSS自定义属性。
例子
-转换:转换var(—p-duration-1-0-0) var(—p-ease);+转换:转换var(——p-duration-100) var(——p-ease);
例子
NPX @shopify/polaris-migrator v9-style -replace-custom-property-motion
v9-styles-replace-custom-property-legacy
用相应的替换值(不同的Polaris自定义属性或静态值)替换废弃的遗留CSS自定义属性。
例子
-宽度:var(——p-icon-size);+宽度:var(——p-icon-size-small);-显示:var(——p-override-none);+显示:没有;
例子
NPX @shopify/polaris-migrator v9-style -replace-custom-property-legacy
通用的迁移
styles-replace-custom-property
用映射值(不同的Polaris自定义属性或静态值)替换CSS自定义属性的通用代码。
例子
-颜色:var(——p-text);+颜色:var(——p-color-text);-动画:var(——p-fast);+动画:100毫秒;
此迁移可以通过两种方式运行:
- 使用的组合
——decl，——从,——以标志来替换单个自定义属性，或 - 使用一个
——地图标志，指向定义多个自定义属性替换的文件
选项1:
例子
NPX @shopify/polaris-migrator style -replace-custom-property \——decl = " <名称>”——从=“< >提案”=“<道具> " <路径>
选项2:
例子
NPX @shopify/polaris-migrator style -replace-custom-property \——地图= " < replacement-maps > " <路径>
例子replacement-maps.js(附选项2):
例子
出口默认的｛颜色：｛“——p-text”：“——p-color-text”，}，' / ^动画/ '：｛“——p-fast”：“100 ms”，}，}；
styles-insert-stylelint-disable
插入样式和禁用注释stylelint-polaris>= v5，以便现有的故障不会阻止代码库初始化筛选器。
例子
+// style - font -disable-next-line——由polaris-migrator生成填充:1快速眼动;
例子
NPX @shopify/polaris-migrator style -insert-style -disable
react-rename-component
用于重命名任何组件及其道具类型的通用代码。
例子
-
例子
npx @shopify/polaris-migrator react-rename-component ——renameFrom="MyComponent"——renameTo="MyRenamedComponent"——renamePropsFrom="MyComponentPropType"——renamePropsTo="MyRenamedComponentPropType"
react-rename-component-prop
用于重命名任何组件道具的通用代码。
例子
-
例子
——componentName="MyComponent"——from="prop"——to="newProp"
scss-remove-unused-at-use
删除未使用的通用代码@use在SCSS文件中导入。
例子
-@use“全局样式/遗产”;//不使用' legacy '命名空间。可安全拆卸。. class {颜色:蓝色;}
例子
——url='import/url'
创建迁移
有时候也被称为“codemods”，迁移是将一些代码从一种形式修改为另一种形式的JavaScript函数(例如;在…的不同版本之间移动@shopify /北极星）.ast(抽象语法树)用于以离散的强类型步骤(称为“节点”)“遍历”代码。然后将对节点(以及AST)所做的所有更改写成代码的新/“迁移”版本。
polaris-migrator支持两种类型的迁移:
- SCSS迁移
- 打印稿迁移
创建SCSS迁移
运行纱新迁移的生成新的迁移scss-migration模板:
例子
00纱线新迁移$ yarn workspace @shopify/polaris-migrator生成美元扑通一声地？请选择一个发电机。(使用方向键)❯scss-migrationtypescript-migration
接下来，提供迁移的名称。例如;v9-scss-replace-function：
例子
？请选择一个发电机。sass-migration？迁移名称(如:scss-replace-function)
生成器将在迁移文件夹:
例子
迁移└──v9-scss-取代-函数├──v9-scss-取代-函数。ts└──测试├──v9-scss-取代-函数。输入。scss├──v9-scss-取代-函数。输出。scss└──v9-scss-取代-函数。测试。ts
SCSS迁移功能
每个迁移器都有一个默认导出样式int规则API。PostCSS AST作为根并且可以内联改变，或者发出警告/错误报告。
继续这个例子，如果我们的目标是替换Sass函数，那么下面是迁移的样子你好()与世界()。
例子
/ / polaris-migrator / src /迁移/ replace-sass-function / replace-sass-function.ts进口｛isSassFunction，StopWalkingFunctionNodes，createSassMigrator作为v9ReplaceHelloWorld，}从“. . / . . /工具/萨斯”；进口类型｛PolarisMigrator}从“. . / . . /工具/萨斯”；常量replaceHelloWorld：PolarisMigrator＝（＿，｛方法}，上下文）=＞｛返回（根）=＞｛方法。walkDecls（根，（decl）=＞｛常量parsedValue＝valueParser（decl。价值）；parsedValue。走（（节点）=＞｛如果（isSassFunction（“你好”，节点））｛如果（上下文。修复）｛节点。价值＝“世界”；}其他的｛方法。报告（｛节点：decl，严重程度：“错误”，消息：不再支持方法hello()。请迁移到世界()。”，}）；}返回StopWalkingFunctionNodes；}}）；如果（上下文。修复）｛decl。价值＝parsedValue。toString（）；}}）；}；}；出口默认的v9ReplaceHelloWorld（“replace-hello-world”，replaceHelloWorld）；
中可以看到一个更完整的示例styles-tokenize-space.ts。
测试
模板还将生成可用于测试迁移的起始测试文件。OB欧宝娱乐APP在你的迁移中测试文件夹中，可以看到3个文件:
v9-scss-replace-function.test.ts-运行fixture并设置额外的迁移选项v9-scss-replace-function.input.scss—起始源输入OB欧宝娱乐APPv9-scss-replace-function.output.scss—迁移后的预期输出
主测试文件将加载输入/输出fixture来测试您的迁移。您可以配置额外的fixture和测试迁移选项(参见replace-sass-spacing.test.ts作为一个例子)。
运行迁移
通过筛选到迁移包，从工作区根目录本地运行测试:
例子
NPX turbo run test——filter=polaris-migrator——v9-scss-replace-function
在另一个代码库中测试
一旦确信迁移准备好了，创建一个新的拉取请求，包括您的迁移和一个新的变更集。
在你的PR中，你可以在文本中添加评论/ snapit创建一个新的快照发布。一旦创建，这个快照可以在一个单独的代码库中使用:
例子
# example快照发布NPX @shopify/polaris-migrator@0.0.0-snapshot-release-20220919213536 v9-scss-replace-function "./app/**/*.scss"
检查和格式化迁移
迁移程序不包括默认格式化程序。建议在运行迁移后运行您自己的筛选器和格式化程序。例如，如果您正在使用ESLint和/或更漂亮：
例子
NPX eslint——修复。NPX更漂亮——写。
检查迁移
运行迁移可能会修改数千个文件。对于更复杂的迁移，可以添加注释，建议手动检查更改。您可以在文本编辑器中快速手动搜索此注释:
例子
北极星-移居者：不能迁移下面的表达式。请手动升级。
在应用迁移之后，将不需要手工检查的更改从需要手工检查的更改中提交出来可能会有所帮助。你可以用几种不同的方法来实现这一点，但我们建议将你所有的修改都暂存，然后取消那些包含手动检查注释的修改:
例子
#隐藏带有"polaris-migrator:"注释的文件$(grep -r -l "polaris-migrator:")#暂存所有没有"polaris-migrator:"注释的文件Git添加。#带着"polaris-migrator:"注释回来Git stash pop#(可选)如果有两个"polaris-migrator:"注释的文件# _and_完成修复，现在添加完整的修复Git add -p#提交所有完整的修复:git提交现在你剩下的修改只有“polaris-migrator:”注释