在微信小程序 Skyline 下编写或迁移 WXSS 时…

适用于微信小程序 Skyline 渲染环境下的 WXSS 样式支持查询、兼容性迁移和不生效排查。

适用场景

解决思路

1. 按需求查文档：基础数据类型与语法符号查 `references/basics.md`；布局/定位/盒模型查 `references/layout.md`；Flex 布局查 `references/flex.md`；背景/边框/滤镜/遮罩查 `references/visual.md`；文本/字体查 `references/text.md`；动画/过渡/变换查 `references/animation.md`；属性是否支持查本文档 Quick Reference；渐变/滤镜具体限制查「渐变与滤镜限制」；WXSS 语法检查用「WXSS CLI」。
2. 用 `skyline` CLI 校验：运行 `npx skyline-cli --help` 查看用法；运行 `npx skyline-cli wxss list` 列出所有支持的 WXSS 属性；运行 `echo "view { color: red; }" | npx skyline-cli wxss check --json` 从 stdin 读取 WXSS 文本并检查语法；运行 `npx skyline-cli wxss check --json --miniprogram-root ${PROJECT_ROOT} --files pages/index/index.wxss pages/list/list.wxss` 检查小程序工程内的 WXSS 文件。
3. 禁止使用不生效属性：`float` 改 flex 布局；`contain` 改用 `-wx-contain`；`resize` 无替代；`writing-mode` 无替代；`text-indent` 用 `padding-left` 模拟；`overflow-wrap` 改用 `word-break`；`text-decoration-thickness` 无替代；`background-attachment` 无替代；`background-clip` 无替代；`background-origin` 无替代；`mask-origin / mask-clip / mask-mode` 无替代；`justify-items` 无替代；`list-style-type / list-style-image / list-style-position` 无替代。
4. 对可用属性使用受支持的值：`display: grid` 不支持，改用 `display: flex`；`position: sticky` 不支持，改用 `position: relative`，sticky 需求用 `sticky-header` 组件；`overflow: auto` 不支持，改用 `overflow: hidden`，滚动用 `scroll-view`。
5. 注意渐变限制：`radial-gradient` 仅支持 `circle` 形状（不支持 `ellipse`），尺寸仅支持 `px`，颜色停止仅支持 `%`；`linear-gradient` 停止位置仅支持 `%` 和固定长度单位（`px`、`rpx` 等）；`conic-gradient` 完全支持（无额外限制）。
6. 注意背景/遮罩多值限制：`background-image` / `mask-image` 最多支持 2 个值；`background-position` 最多支持 2 组值；`background-repeat` / `background-size` 不支持多组值。
7. `calc()` 支持长度计算，但不支持角度计算，需直接写角度值。
8. `text-overflow: ellipsis` 在 Skyline 下仅在 `<text>` 组件上生效，在 `<view>` 上不生效；推荐使用 `<text>` 组件的 `overflow` 和 `max-lines` 属性；详见 `skyline-components` 技能了解 text 组件属性限制。
9. `filter` / `backdrop-filter` 不支持 `url()` 和 `drop-shadow()`，也不支持多个函数组合；用 `box-shadow` 替代 `drop-shadow`；支持的函数：`blur()`、`brightness()`、`contrast()`、`grayscale()`、`hue-rotate()`、`invert()`、`opacity()`、`saturate()`、`sepia()`。
10. `text-decoration-line` 仅支持单个值（`none`、`underline`、`overline`、`line-through`），不支持多值组合如 `underline line-through`。
11. `mask-image` 的 `linear-gradient()` 和 `radial-gradient()` 不支持，仅 `url()` 形式可用。
12. 注意简写属性的部分有效行为：`background` 中 `background-attachment`、`background-origin`、`background-clip` 不生效；`text-decoration` 中 `text-decoration-thickness` 不生效；`mask` 中 `mask-origin`、`mask-clip` 不生效；`mask-position` 简写有效，会自动展开为 `mask-position-x` + `mask-position-y`，类似 `background-position` 机制。
13. 布局属性速查：`display` 支持 `none`、`block`、`inline`、`inline-block`、`flex`、`inline-flex`，不支持 `grid`、`flow-root`；`position` 支持 `static`、`relative`、`absolute`、`fixed`，不支持 `sticky`；`overflow` 支持 `visible`、`hidden`，不支持 `auto`、`scroll`、`overflow-x`、`overflow-y`；`visibility` 支持 `visible`、`hidden`，不支持 `collapse`；`box-sizing` 支持 `content-box`、`border-box`，不支持 `padding-box`；`aspect-ratio` 支持 `auto`、`<number>`、`<number>/<number>`；`content` 支持 `none`、`normal`、`<string>`、`<url>`；`direction` 不支持。
14. 文本属性速查：`white-space` 支持 `normal`、`nowrap`，不支持 `pre`、`pre-wrap`、`pre-line`；`font-weight` 支持 `normal`、`bold`、数值(100-900)，不支持 `bolder`、`lighter`；`font-style` 支持 `normal`、`italic`，不支持 `oblique`；`word-break` 支持 `normal`、`break-all`、`keep-all`，`break-word` 映射为 `normal`；`vertical-align` 支持 `baseline`、`top`、`middle`、`bottom`，不支持 `text-top`、`text-bottom`；`text-align` 支持 `left`、`center`、`right`、`justify`、`start`、`end`，不支持 `justify-all`、`match-parent`；`text-decoration-line` 仅支持单值 `none`、`underline`、`overline`、`line-through`，不支持多值组合和 `blink`；`text-overflow` 支持 `clip`、`ellipsis`（仅 text 组件生效）。
15. 边框与背景速查：`border-*-style` 支持 `none`、`solid`、`dashed`、`dotted`，不支持 `hidden`、`double`、`groove`、`ridge`、`inset`、`outset`；`background-repeat` 支持 `repeat`、`repeat-x`、`repeat-y`、`no-repeat`，不支持 `space`、`round`。
16. Flex 属性全部支持：`flex-direction`、`flex-wrap`、`align-items`、`align-self`、`align-content`、`justify-content`、`flex-grow`、`flex-shrink`、`flex-basis`、`order` 的所有定义值完全支持。
17. 注意非标准默认值：`display` 默认 `flex`（`defaultDisplayBlock: true` 时为 `block`）；`position` 默认 `relative`；`box-sizing` 默认 `border-box`（`defaultContentBox: true` 时为 `content-box`）；`flex-direction` 默认 `column`（`defaultDisplayBlock: true` 时为 `row`）；`align-items` 默认 `stretch`（`defaultDisplayBlock: true` 时为 `normal`）；`text-align` 默认 `start`；`mask-repeat` 默认 `no-repeat`。
18. 可直接使用完全支持的其他属性：`pointer-events`、`text-decoration-style`、`background-size`、`transform`、`opacity`、`transition-*`、`animation-*`、`border-radius`、`box-shadow`、`text-shadow`、`color`、`font-size`、`font-family`、`font-feature-settings`、`line-height`、`letter-spacing`、`word-spacing`、`z-index`、`aspect-ratio`、`content`、`will-change`（仅 `auto`/`contents`）、`conic-gradient`。
19. 按相关技能处理关联问题：Skyline JSON 配置查 `skyline-config`，因为 `rendererOptions` 影响默认 `display`/`flex-direction`/`align-items`/`box-sizing`；组件使用查 `skyline-components`，用 `scroll-view` 替代 `overflow:auto`；Worklet 动画查 `skyline-worklet`，了解 `transform`/`opacity` 动画最佳实践；Skyline 概览查 `skyline-overview`，了解渲染引擎概览与迁移指南。
20. 按 References 目录结构查阅：`references/animation.md`、`references/basics.md`、`references/flex.md`、`references/layout.md`、`references/text.md`、`references/visual.md`。
21. 在从 WebView 迁移到 Skyline 时，逐项评估样式兼容性，重点检查上述不支持属性、受限值、渐变/滤镜/遮罩限制、简写属性部分失效项和非标准默认值。
22. 排查样式不生效问题时，先用 `npx skyline-cli wxss check --json` 或工程内文件检查命令校验 WXSS 语法，再对照 Quick Reference 和强制规则定位不支持的属性/值/限制。

适用边界 · 注意事项

• 非微信小程序 Skyline 渲染环境（如 WebView、其他小程序平台或普通 Web 页面）不适用。
• 需要使用的 CSS 属性/值已被 Skyline 明确不支持且无替代方案时，不能靠本技能直接实现，需要调整设计或改用组件/其他方案。
• 无法运行 Node/npx 或 `skyline-cli` 时，不能执行 CLI 校验，只能依赖人工查表，校验能力受限。