stylelint-polaris media-query-allowed-list 插件：用 Polaris 断点别名统一媒体查询规范

前端UI组件【免费下载链接】polaris-react-archiveShopifys Polaris Design System - React implementation (Deprecated)项目地址https://gitcode.com/gh_mirrors/po/polaris-react-archive点击查看免费下载导读media-query-allowed-list是 Shopify Polaris 设计系统仓库中stylelint-polaris包提供的一个 Stylelint 自定义插件用于强制样式代码只使用 Polaris 官方断点别名如$p-breakpoints-sm-up与受支持的媒体类型禁止手写min-width、max-width等原始媒体条件。阅读本文后你将掌握该插件的完整配置方法、三个核心选项的语义与取值、其底层源码实现原理以及如何把它接入pnpm lint/pnpm stylelint工作流让你的 SCSS 媒体查询与 Polaris 设计令牌体系保持严格一致。插件定位为什么需要约束媒体查询在 Polaris 设计体系中响应式断点是由设计令牌design tokens统一管理的。仓库中的 breakpoints.ts 定义了全部断点别名像素值xs0pxsm490pxmd768pxlg1040pxxl1440px从 stylelint-polaris/plugins/media-query-allowed-list/README.md 的说明可以看出该插件的目的是确保代码遵循 Polaris 既定的断点约定只使用由 Polaris 令牌生成的断点别名。一旦允许开发者随意手写断点数值就会出现大量与设计令牌脱节的魔数样式系统将失去单一事实来源。从stylelint-polaris包的描述看它是 Polaris Design System Stylelint tooling该插件在包的media-queries覆盖率coverage分类中扮演核心角色与禁用旧版breakpoint/layout-width函数、禁用一批历史断点 mixin 的规则协同工作共同推动样式代码迁移到令牌体系。强制规则Enforced Rules插件强制执行两条核心约定媒体查询必须使用 Polarisbreakpoints别名定义例如media #{$p-breakpoints-sm-up} {}以及/或者使用受支持的媒体类型例如print、screen、forced-colors等。媒体查询中不得包含min-、max-、width或height条件。也就是说(min-width: 0px)、(max-width: 767px)、(height: 100px)这类写法都会被判定为非法。这两条规则共同保证所有断点语义都由$p-breakpoints-*别名最终由 Polaris tokens 编译成具体像素值承载而不是散落在各组件样式文件里的裸数值。Options 参数详解根据 README.md 中的 TypeScript 接口定义插件主选项primary options包含三个字段interface PrimaryOptions { /** * A list of RegExps or string literals to match against media types. */ allowedMediaTypes: (string | RegExp)[]; /** * A list of RegExps or string literals to match against media feature names. * * Note: This is passed directly to the built-in media-feature-name-allowed-list rule. */ allowedMediaFeatureNames: (string | RegExp)[]; /** * A list of RegExps or string literals to match against SCSS interpolation expressions in media queries. */ allowedScssInterpolations: (string | RegExp)[]; }三个字段的含义与用途如下allowedMediaTypes允许出现在媒体查询中的媒体类型media type白名单如print、screen。匹配的是media print {}中print这样的裸类型名。未列入白名单的类型如screen会被报告为非法。allowedMediaFeatureNames允许使用的媒体特性media feature名称白名单如forced-colors、reduced-motion、-ms-high-contrast。需要特别注意该数组会原样透传给 Stylelint 内置的media-feature-name-allowed-list规则由内置规则负责对(forced-colors: active)这类特性条件做检查。allowedScssInterpolations允许出现在媒体查询中的 SCSS 插值表达式白名单如$p-breakpoints-sm-up。插件从#{$p-breakpoints-sm-up}中提取插值内部表达式即$p-breakpoints-sm-up再与白名单做字符串或正则匹配。此外从 index.js 源码的 JSDoc 与运行时逻辑看主选项还支持第四个可选字段disabled布尔值。当disabled: true时插件会直接跳过全部检查见index.js第 76-78 行该能力也在 index.test.js 中有独立测试用例覆盖——设置disabled: true后即使代码写了media (width: 0px) {}也不会被报告。PrimaryOptions的三个数组都标记为optional: true允许只配置其中一部分matchesStringOrRegExp匹配逻辑位于 utils/index.js同时支持字符串字面量与正则表达式正则可写在字符串形式的/pattern/中或直接传入RegExp对象。如何配置最基础的单规则配置如下取自 README.mdconst stylelintConfig { rules: { polaris/media-query-allowed-list: { allowedMediaTypes: [print], allowedMediaFeatureNames: [forced-colors, reduced-motion], allowedScssInterpolations: [ $p-breakpoints-sm-up, $p-breakpoints-md-up, ], }, }, };不过仓库实际推荐的做法是通过stylelint-polaris提供的覆盖率规则统一配置。在 stylelint-polaris/index.js 的media-queries分类中可以看到项目的生产级配置第 239-256 行polaris/media-query-allowed-list: { // Allowed media types and media conditions allowedMediaTypes: [print, screen], allowedMediaFeatureNames: [ forced-colors, -ms-high-contrast, prefers-reduced-motion, ], allowedScssInterpolations: [ matchNameRegExp( String.raw\$p-breakpoints-(xs|sm|md|lg|xl)-(up|down|only), ), ], },这里使用了正则\$p-breakpoints-(xs|sm|md|lg|xl)-(up|down|only)一次性覆盖全部五个断点别名xs/sm/md/lg/xl与三种方向后缀up/down/only并借助matchNameRegExp包装见同一文件第 473-477 行支持可选的 Sass 命名空间前缀例如common.$p-breakpoints-sm-up也能通过校验。测试文件 index.test.js 第 14-18 行使用了同样的正则写法。启用该插件需要确保stylelint-polaris包被加载为 Stylelint 插件在 stylelint-polaris/index.js 第 465 行插件通过./plugins/media-query-allowed-list被注册直接使用单规则时则在 stylelint 配置的plugins数组中指向该插件目录即可测试中通过plugins: [__dirname]加载。运行环境要求根据 stylelint-polaris/package.json该插件所在的shopify/stylelint-polaris包要求 Node20.10.0peerDependencies 为stylelint ^14.15.0 || ^15.0.0并依赖postcss-media-query-parser、postcss-scss、shopify/polaris-tokens等仓库根目录 package.json 中使用的 stylelint 版本为^14.15.0。源码实现原理插件的核心实现位于 index.js规则全名为polaris/media-query-allowed-list第 14 行报告消息为Unexpected media query ${invalidMedia}第 16-21 行。其检查流程可以拆解为三层第一层媒体特性名称检查交给内置规则allowedMediaFeatureNames不会在插件内自行实现匹配而是通过stylelint.utils.checkAgainstRule将配置原样交给内置的media-feature-name-allowed-list规则执行第 82-109 行。插件对内置规则做了唯一一处特判当白名单中包含-ms-high-contrast且内置规则的告警文本命中该名称时直接放行第 89-96 行因为内置规则无法正确处理这个带前缀的特性名——这正是 index.test.js 中media (-ms-high-contrast: active) {}被接受的原因。第二层SCSS 插值检查插件遍历每个media规则root.walkAtRules(media, ...)第 111 行先判断媒体查询参数中是否包含 SCSS 插值hasScssInterpolation匹配#\{.?\}定义于 utils/index.js 第 1-11 行。若包含则用全局匹配提取所有插值通过scssInterpolationExpression剥离#{与}外壳得到内部表达式再与allowedScssInterpolations白名单匹配第 114-133 行。任一插值匹配白名单即视为通过否则报告整条媒体查询。这保证#{$p-breakpoints-sm-up}和#{common.$p-breakpoints-sm-up}这类带命名空间的写法都被正确解析。第三层媒体类型检查使用postcss-media-query-parser将媒体查询参数解析为 AST遍历其中的media-type节点第 135-153 行。对于 SCSS 插值构成的类型已被上一层处理以及命中allowedMediaTypes白名单的类型直接放行其余一律报告。因此media print {}合法而media screen {}当screen不在白名单时会被拒绝。三个层次的检查按特性名称 → SCSS 插值 → 媒体类型的顺序组织任何一层出现未匹配项都会产生一条以polaris/media-query-allowed-list为规则名的告警。如何运行运行全部 lint仓库根目录 package.json 中lint脚本为turbo run lint会依次执行各包 lintpnpm lint或者只运行 stylelint 并传入文件通配符pnpm stylelint file-glob校验全部 SCSS 文件pnpm stylelint **/*.scss校验单个文件以 README.md 中的示例为例该文件路径在仓库当前版本中已不存在仅作命令用法演示pnpm stylelint src/components/typography/textContainer/TextContainer.scss输出示例src/components/typography/textContainer/TextContainer.scss 4:3 ✖ Invalid media query [(min-width: 0px)]. polaris/media-query-allowed-list 6:5 ✖ Invalid media query [print and (min-width: 0px)]. polaris/media-query-allowed-list可以看到第一处直接写了(min-width: 0px)原始条件被拒绝第二处即使组合了受支持的媒体类型print只要混入了min-width条件同样被拒绝——这与媒体查询不得包含min-/max-/width/height条件的强制规则完全一致。告警输出包含文件路径、行列号如4:3以及被拒绝的完整媒体查询原文便于开发者快速定位并改写为media #{$p-breakpoints-*-up} {}形式。测试用例行为边界一览stylelint-polaris/plugins/media-query-allowed-list/index.test.js 使用jest-preset-stylelint与postcss-scss自定义语法给出了插件行为的完整边界。可通过的写法accept包括media #{$p-breakpoints-sm-up} {}—— 使用被允许的 Polaris 断点别名media #{common.$p-breakpoints-sm-up} {}—— 带命名空间的断点别名media print {}—— 使用被允许的媒体类型media not print and #{$p-breakpoints-sm-up} {}—— 媒体类型与断点别名组合media #{$p-breakpoints-sm-up} and #{$p-breakpoints-md-down} {}—— 多个断点别名组合media (forced-colors: active) {}—— 使用被允许的媒体特性名称media (-ms-high-contrast: active) {}—— 使用被允许的带前缀特性名称会被拒绝的写法reject包括media (width: 0px) {}/(min-width: 0px)/(max-width: 0px)media (height: 0px) {}/(min-height: 0px)/(max-height: 0px)media (min-width: 0px) and #{$p-breakpoints-sm-up} {}—— 合法别名与非法条件混用整体拒绝media #{$p-breakpoints-sm-up} and (min-width: 0px) {}—— 顺序互换同样拒绝media not print and (min-width: 0px) {}—— 合法媒体类型与非法条件混用media screen {}—— 未纳入白名单的媒体类型media (-ms-high-contrast: active) and (min-width: 0px) {}—— 合法特性与非法条件混用这些用例清晰地表明插件的检查是逐段校验的任何一段媒体查询类型、特性、插值不在白名单内都会导致整条查询被拒绝从而杜绝部分令牌化、部分手写裸值的中间态。在 stylelint-polaris 整体规范中的位置从 stylelint-polaris/index.js 第 239-301 行可以看到media-query-allowed-list是media-queries覆盖率分类的检查主力其周边规则还包括禁用旧版断点函数function-disallowed-list拒绝breakpoint、layout-width等历史函数禁用历史断点 mixinpolaris/at-rule-disallowed-list拒绝breakpoint-before、breakpoint-after、page-content-breakpoint-*、when-typography-condensed、print-hidden等 30 余个旧版 mixin分类消息为Please use a Polaris breakpoint token。也就是说该插件只是完整断点迁移规范中的一环——它负责新代码只能写什么而配套规则负责旧代码禁止写什么。二者结合让 Polaris 的响应式样式最终收敛到media #{$p-breakpoints-*-up} {}这一统一写法上。总结polaris/media-query-allowed-list是 Polaris 设计系统在样式工程化上用规则保障令牌一致性的典型实践通过allowedMediaTypes、allowedMediaFeatureNames、allowedScssInterpolations三个白名单外加可选的disabled开关把媒体查询的写法收敛到设计令牌生成的断点别名与受支持的媒体特性上。理解其透传内置规则 插值提取 AST 遍历的三层实现后你既能在自己的 Stylelint 配置中独立复用它也能借鉴这种白名单 逐段校验的思路为其他设计系统建立类似的样式约束。赞分享前端UI组件【免费下载链接】polaris-react-archiveShopifys Polaris Design System - React implementation (Deprecated)项目地址https://gitcode.com/gh_mirrors/po/polaris-react-archive点击查看免费下载相关推荐stylelint media-feature-name-allowed-list 规则详解用白名单约束媒体特性名称stylelint media feature name allowed list 规则详解用白名单约束媒体特性名称 media feature name a代码质量静态分析前端stylelint 规则详解media-feature-name-value-allowed-list 媒体特性值白名单校验stylelint 规则详解media feature name value allowed list 媒体特性值白名单校验 本篇指南围绕 stylelint代码质量静态分析前端stylelint 的 media-query-no-invalid 规则按 Media Queries Level 5 语法校验媒体查询stylelint 的 media query no invalid 规则按 Media Queries Level 5 语法校验媒体查询 media que代码质量静态分析前端上一篇Gaggiuino终极指南2024年智能咖啡机改造完全手册下一篇VectorBT量化交易框架深度解析掌握金融数据分析的强大工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考