自定义仪表

外观

颜色、材质与特效 ​

绘图颜色用于文字、形状、路径、阴影和渐变。先让作品在普通 SDR 与明暗主题下清晰可读，再按需要增加 HDR 或材质效果。

颜色写法 ​

jsx
<Text color="#54800A">十六进制颜色</Text>
<Text color="#54800A99">带透明度的颜色</Text>
<Text color={$env.foreground}>环境前景色</Text>
<Circle width={30} height={30} fill={{space: 'displayP3', r: 0.6, g: 0.9, b: 0.2, a: 1}}/>

"clear" 表示透明。RGB 对象中的色彩分量用 0…1 范围表达；对需要保持设备一致性的主要读数，优先采用环境色。

渐变 ​

渐变使用一个对象描述，颜色可以是普通颜色，也可以带明确位置。

jsx
<Rectangle width={220} height={16} cornerRadius={8}
  gradient={{type: 'linear', angle: 0, colors: ['#54800A', '#C2F54F']}}/>
属性用途
typelinear、radial、angular
colors颜色数组，或 {color, location} 色标数组
angle渐变方向角度，0° 向右，90° 向下
jsx
<Rectangle width={200} height={80} gradient={{angle: 90, colors: [
  {color: 'clear', location: 0},
  {color: '#00000099', location: 0.6},
  {color: 'black', location: 1}
]}}/>

透明度、圆角、模糊和阴影 ​

属性说明
opacity整体透明度
background节点背景色
cornerRadius圆角
blur模糊本节点内容，0…128
shadowColor、shadowOpacity、shadowRadius、shadowX/Y外阴影
innerShadow={{color, opacity, radius, x, y}}内阴影
glow={{color, opacity, radius}}发光
clip几何裁切，可用 rectangle 或 ellipse 描述

少量特效足以区分层级。小号卡片上的过强光晕、阴影或模糊容易影响读数。

Mask：第一个是内容，第二个是遮罩 ​

jsx
<Mask width={180} height={80}>
  <Rectangle width="fill" height="fill" fill={$env.accent}/>
  <Rectangle width="fill" height="fill" gradient={{angle: 0, colors: ['clear', 'black']}}/>
</Mask>

第二个子节点提供透明度遮罩，不是把“黑色当作擦除”。完全不透明的黑色和白色在 alpha 遮罩中都会保留内容；透明色才会让内容消失。

Material：模糊后面的内容 ​

blur 模糊的是组件自身；Material 用原生材质处理它后面的内容。style 可以是 ultraThin、thin、regular、thick、ultraThick，默认 ultraThin。

要在地图上做渐变材质，把地图与“Mask + Material”作为叠放的兄弟节点。不要把整个 Map 放进透明遮罩或像素滤镜里。完整示例见地图与渐变材质。

HDR 颜色 ​

HDR('#FFFFFF') 或 new HDR('#FFFFFF') 为绘图颜色标记增强意图。它们返回可传递给组件和渐变的普通颜色数据。

jsx
<Text color={HDR($env.foreground)} fontSize={64}>78</Text>

只有在 HUD 模式、开启相应 HDR 增强、系统与屏幕具备条件 时，标记的颜色才会使用增强显示。普通仪表模式、关闭增强、预览与保存的 PNG 使用基础 SDR 颜色；普通颜色字符串不会因为旁边存在 HDR 内容就一起增强。

原生地图和材质与绘图有自己的显示路径，不应根据一张网页配图或列表缩略图判断 HDR 亮度。$env.mode 不表示 HDR 是否开启，公开环境中没有 HDR 可用性字段。