wechat-miniprogram/skyline-skills/skyline-wxss

Skyline WXSS 样式支持

适用场景

• 检查某个 CSS 属性/值在 Skyline 下是否可用
• 排查 WXSS 样式在 Skyline 下不生效的问题
• 从 WebView 迁移到 Skyline 时评估样式兼容性
• 使用渐变、滤镜、遮罩等高级样式时了解限制
• 查阅 Skyline 支持的 CSS 属性语法

文档索引

WXSS CLI

请务必调用 skyline CLI 对 WXSS 进行检查，确保用法正确。

npx skyline-cli --help

列出所有支持的 WXSS 属性

npx skyline-cli wxss list

从 stdin 读取 WXSS 文本并检查语法

echo "view { color: red;  }" | npx skyline-cli wxss check --json

检查小程序工程内的 WXSS 文件

npx skyline-cli wxss check --json --miniprogram-root ${PROJECT_ROOT} --files pages/index/index.wxss pages/list/list.wxss

强制规则

NEVER: 使用不支持的 CSS 属性

以下属性设置后不生效：

MUST: 使用支持的属性值

部分属性可用但特定值不支持，会被静默忽略：

Incorrect:

.container {
  display: grid;           /* grid 不支持 */
  position: sticky;        /* sticky 不支持 */
  overflow: auto;          /* auto 不支持 */
}

Correct:

.container {
  display: flex;           /* 使用 flex 替代 grid */
  position: relative;      /* sticky 需使用 sticky-header 组件 */
  overflow: hidden;        /* 使用 hidden，滚动用 scroll-view */
}

MUST: 注意渐变限制

渐变限制汇总：

• radial-gradient 仅支持 circle 形状（不支持 ellipse），尺寸仅支持 px，颜色停止仅支持 %
• linear-gradient 停止位置仅支持 % 和固定长度单位（px、rpx 等）
• conic-gradient 完全支持（无额外限制）

MUST: 注意背景/遮罩多值限制

• background-image / mask-image 最多支持 2 个值
• background-position 最多支持 2 组值
• background-repeat / background-size 不支持多组值

MUST: calc() 不支持角度类型

calc() 支持长度计算，但不支持角度计算，需直接写角度值。

MUST: text-overflow 仅在 text 组件生效

text-overflow: ellipsis 在 Skyline 下仅在 `<text>` 组件上生效，在 <view> 上不生效。推荐使用 <text> 组件的 overflow 和 max-lines 属性。

⚠️ 详见 skyline-components 技能了解 text 组件的属性限制。

NEVER: 使用 filter 的 url() 和 drop-shadow()

filter/backdrop-filter 不支持 url() 和 drop-shadow()，也不支持多个函数组合。用 box-shadow 替代 drop-shadow。

支持的函数：blur(), brightness(), contrast(), grayscale(), hue-rotate(), invert(), opacity(), saturate(), sepia()。

MUST: text-decoration-line 仅支持单值

仅支持单个值（none, underline, overline, line-through），不支持多值组合如 underline line-through。

MUST: mask-image 渐变不可用

mask-image 的 linear-gradient() 和 radial-gradient() 不支持，仅 url() 形式可用。

MUST: 注意简写属性的部分有效行为

以下 CSS 简写属性在展开后，部分子属性不生效：

💡 mask-position 简写有效：会自动展开为 mask-position-x + mask-position-y（类似 background-position 的机制）。

Quick Reference

布局属性速查

文本属性速查

边框与背景速查

Flex 属性（全部支持）

以下 Flex 属性的所有定义值完全支持： flex-direction, flex-wrap, align-items, align-self, align-content, justify-content, flex-grow, flex-shrink, flex-basis, order

非标准默认值

以下属性的默认值与 Web 标准不同，需注意：

完全支持的其他属性

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

相关技能

References 目录结构

references/
├── animation.md
├── basics.md
├── flex.md
├── layout.md
├── text.md
└── visual.md