AR 图标 SVG 规范
AR 投射中的图标以 SVG 提供。SVG 上传到 Pilot 后,由 Pilot 端按本页规则解析并绘制,其解析能力是标准 SVG 的一个子集。本页汇总 AR 图标 SVG 的要求与自查方法,配合 AR 投射教程使用。绘制在图标旁边的名称文字由程序单独绘制,不要画进 SVG。
如何使用本规范
本规范的要求分两类,不必逐条对照通读:
- 必备项:无条件恒生效,不满足图标就无法正常显示。数量很少,见下方速览,务必全部满足。
- 场景项与边界值:只在特定显示方式、特定开关下才生效,或是正常设计几乎碰不到的数值上限。按你的实际场景查阅对应小节即可。
为帮助你快速判断某条规则是否与自己相关,正文中的关键约束都标注了触发前提(如「恒生效」「仅近大远小模式」「仅开启动态线宽时」)与不满足的后果(如「图标不显示」「渲染为灰色」)。
必备项速览(无条件满足即可让图标正常显示、可换色):
| 必备项 | 一句话要求 |
|---|---|
| 文件类型 | 用 SVG,单位只用 px 或不写 |
| 画布 | 必须有 viewBox,width / height 与 viewBox 同值(坐标空间建议用 24 / 48) |
| 图层命名 | 每个图形元素的 id 带状态后缀(_normal / _select × _color / _bg) |
| 颜色写法 | 只用 #RGB / #RRGGBB / rgb() / 命名色 |
| 镂空 | 需要空心时,同一个 <path> 内写 fill-rule="evenodd" |
细则与更多场景项见后续各节,遇到异常可对照第六节按症状排查。
一、前置:两种显示方式
图标在 AR 画面里有两种显示方式,部分要求取决于你用的是哪一种,请先确认:
| 显示方式 | 表现 | 需要提供 |
|---|---|---|
| 近大远小 | 图标尺寸随目标距离变化,近大远小,并限制在最大 / 最小尺寸之间 | 两张图:大尺寸状态图 + 小尺寸状态图 |
| 保持大小不变 | 图标尺寸固定,只随屏幕分辨率整体缩放,不随距离变化 | 一张图 |
此外还有「只显示文字、不显示图标」的配置,此时不需要提供图片。
二、基础格式与画布
2.1 基础格式
| 项目 | 要求 |
|---|---|
| 文件类型 | SVG |
| 其他格式 | PNG / JPG / WebP 不能直接提交,需转成 SVG(位图只能内嵌,见第五节) |
| 单位 | 只能用 px 或不写单位 |
| 禁用单位 | pt、mm、cm、in、em、ex。这些单位会被换算,导致图形缩小到几乎看不见 |
2.2 画布与尺寸
- 必须有
viewBox(或至少有width/height,两者都没有会导致尺寸不可控)。 viewBox坐标空间建议用 24 或 48,不要用 512 / 1024(大坐标空间会导致镂空判定失效,见第四节)。width/height写设计稿原始尺寸即可,与viewBox同值,不要预乘放大倍率。
注意: 根节点的
width/height会成为图标显示尺寸的下限。写大了,程序侧配置的最大 / 最小尺寸会被覆盖,表现为「图标偏大,且改配置无反应」。
<!-- ✅ 正确:设计稿 24×24 -->
<!-- 放大到多少像素显示,由程序侧配置决定 -->
<svg width="24" height="24" viewBox="0 0 24 24"> … </svg>
<!-- ❌ 错误:40 会成为显示尺寸的硬下限,最小尺寸配置失效 -->
<svg width="40" height="40" viewBox="0 0 15 15"> … </svg>
其他限制:
- 不要用百分比宽高(
width="100%"),会被算成 0。 - 不要嵌套
<svg>,内层会覆盖根节点的尺寸和viewBox,导致整图错乱。 preserveAspectRatio支持,但一般不需要用。
2.3 宽高比
宽高比要求取决于显示方式:
近大远小模式必须是 1:1 正方形,width 必须等于 height(或 viewBox 为正方形)。非正方形不会被拉伸,而是:
| 情况 | 实际后果 |
|---|---|
| 宽 > 高(扁图) | 内容贴在正方形画布上半部,下方留白,图标偏上、视觉尺寸偏小 |
| 宽 < 高(高图) | 等比放大后超出画布高度,底部被裁掉 |
保持大小不变模式可以非正方形,但有两个配套条件(由程序侧填写,需与图对齐):
- 程序侧填写的图片宽高比必须等于 SVG 自身的宽高比,否则同样出现留白或裁切。
- 程序侧填写的显示宽高比与图片宽高比必须一致,否则图会被真正拉伸。
说明: 部分接入方式支持「只填一个维度、另一个自动按比例推算」,但通过配置文件(JSON)接入的方式不支持自动推算,需要你自己算准。
三、图层与颜色
3.1 图层命名规则
一张 SVG 会按图形元素的 id 自动拆成 4 个图层。每个图形元素的 id 必须包含状态后缀:
id 里同时包含 | 归属图层 | 颜色能否被程序替换 |
|---|---|---|
_normal + _color | 未选中 · 主体 | 可以(只换 RGB,透明度保留) |
_normal + _bg | 未选中 · 背景 / 描边 | 不可以,保留你画的颜色 |
_select + _color | 选中 · 主体 | 可以 |
_select + _bg | 选中 · 背景 / 描边 | 不可以,保留你画的颜色 |
命名示例:
ic_pin_normal_color 未选中时的主体
ic_pin_normal_bg 未选中时的黑色描边
ic_pin_select_color 选中时的主体
ic_pin_select_bg 选中时的黑色描边
ic_pin_normal_select_color 两种状态下都显示的主体
规则明细(均恒生效):
- 一个元素可以同时属于多个图层。想让某元素在未选中和选中时都显示,就写成
xxx_normal_select_color。 - 只提供
_normal不提供_select,图标被选中时会整体消失。 id不带任何后缀,会落进「未选中 · 背景」兜底层,结果是既不能换色、选中时也会消失。- 后缀可以只写在
<g>上,组内没有自己id的子元素会自动继承。
注意:
_color图层永远盖在_bg图层之上,与 SVG 里的图层顺序无关。因此你的设计必须能拆成「可换色前景在上 / 固定色背景在下」两层,不能出现「固定色元素需要盖住可换色元素」的层叠关系。
注意: 不要留隐藏图层。
display="none"会被强制打开显示,visibility="hidden"不生效。用不到的图层请直接删除。
边界限制:id 总长度不超过 63 个字符(超出部分会被截断,若后缀被切掉则分层失效);<g> 分组嵌套深度不超过 127 层。
3.2 颜色写法
颜色写法恒生效。颜色只支持 4 种写法:
#RGB 例:#0E8
#RRGGBB 例:#00EE8B
rgb(r, g, b) 例:rgb(0, 238, 139)
标准命名色 例:black、white、red
以下写法不被支持,会导致图标渲染成灰色或透明度丢失,请勿使用:
| 写法 | 结果 |
|---|---|
#RRGGBBAA(八位色,带透明度) | 透明度被丢弃,半透明变成完全不透明 |
rgba(...) | 渲染为灰色 |
currentColor | 渲染为灰色 |
hsl(...) / hsla(...) | 渲染为灰色 |
transparent | 渲染为灰色 |
透明度只能用 opacity / fill-opacity / stroke-opacity 属性表达,不能写进颜色值里。
说明: 图标出现莫名的灰色,通常就是用了上表中不被支持的颜色写法。
四、形状与元素约束
4.1 镂空(空心效果)
镂空有三条硬性要求:
- 所有镂空必须显式写
fill-rule="evenodd"。 - 镂空路径必须和外轮廓写在同一个
<path>里。拆成两个<path>或两个元素无法形成镂空。 - 不要用「两个同方向的嵌套轮廓 +
nonzero填充规则、期望填实」的画法。两种绘制方式对它的判断结果相反,会出现实心 / 镂空来回跳变。
镂空靠「包含关系」推算,这个推算有可靠性边界:
| 镂空形状 | 是否可靠 |
|---|---|
| 圆形、椭圆形、外凸形状 | 可靠 |
| 矩形镂空 + 厚边框 | 容易被判定成实心,镂空丢失 |
| 相互交叉的路径 | 判定不可靠 |
viewBox 坐标空间过大(512 / 1024) | 极易被判定成实心 |
这也是 2.2 节要求「viewBox 用 24 / 48 小坐标空间」的原因。
4.2 可用与禁用的元素
可用元素:
svg g defs path rect circle ellipse line polyline polygon
image linearGradient radialGradient stop
路径命令 M L H V C S Q T A Z(含小写)全部支持,弧线可用。
以下元素会被丢弃,请勿使用:
| 元素 | 说明 |
|---|---|
text | 文字请勿画进 SVG,由程序单独绘制 |
use / symbol | 不支持引用复用,请展开成实体图形 |
clipPath | 不支持裁剪,请直接画成最终形状 |
mask | 不支持遮罩 |
filter | 不支持滤镜(阴影、模糊等一律无效) |
marker | 不支持标记 |
pattern | 不支持图案填充 |
| 各类动画元素 | 不支持 |
4.3 属性白名单
只有以下属性会生效:
style display id transform
fill fill-opacity fill-rule
stroke stroke-opacity stroke-width
stroke-linecap stroke-linejoin stroke-miterlimit
stroke-dasharray stroke-dashoffset
stop-color stop-opacity offset font-size
白名单之外的属性一律忽略,常见的有 clip-path、mask、filter、paint-order、vector-effect、mix-blend-mode、class、visibility、marker-start / marker-mid / marker-end。
结构性限制:
- 不支持
<style>样式表 +class选择器,样式需写成元素属性。 - 内联
style="fill:#fff;stroke:none"属性可以用。 - 不要在同一元素上同时写
fill="..."和style="fill:..."。谁生效取决于属性书写顺序,不遵循 CSS 标准优先级。 <defs>里只有渐变会被保留,把图形放进defs再引用无效。
边界限制:单个元素的属性数量不超过 253 个;没有实际路径的空图形会被忽略。
4.4 描边与变换
transform 全套支持:matrix、translate、scale、rotate、skewX、skewY。
注意: 带描边的元素不要用非等比缩放(如
scale(2,1))或倾斜(skew)。描边宽度按横纵缩放的平均值换算,会明显失真。需要这类变形时,请在设计工具里先把描边展开成路径。
边界限制:stroke-dasharray 虚线最多支持 8 段,超出的会被丢弃。
五、内嵌位图与动态线宽
本节两项均为场景项:只有当你需要内嵌位图、或程序侧开启了动态线宽时才需关注,其余情况可跳过。
5.1 内嵌位图
如果确实需要位图(照片、复杂纹理),只能内嵌在 SVG 里,且尽量避免使用:
- 必须用 Base64 Data URI:
<image xlink:href="data:image/png;base64,..." />。 - 写文件路径或网络 URL 无效,会显示成灰色棋盘格占位图。
- 不支持
transform。你需要直接在<image>上写绝对的x/y/width/height,不能靠外层<g transform>定位。 - 放大时是最近邻采样、无平滑插值。位图像素尺寸要不小于实际显示像素,否则锯齿明显。
- 同一元素内,位图先绘制,填充和描边后绘制(会盖在位图上)。
href和xlink:href两种写法都识别。
5.2 开启「线宽随距离变化」时的额外限制
程序侧有一个「线宽随图标缩放动态变化」的开关(内置的标注点 / Pin 点默认开启)。开启后,同一张 SVG 会在两种绘制方式之间切换:
- 方式 A:预先转成位图再绘制(默认)。
- 方式 B:实时矢量绘制(仅在图标被选中或位于画面中央区域时启用)。
两种方式能力不同,此时 SVG 只能使用两者的能力交集:
| SVG 特性 | 方式 A(位图) | 方式 B(矢量) | 开启动态线宽时能用吗 |
|---|---|---|---|
| 纯路径 + 纯实色 | 支持 | 支持 | 可用 |
fill-rule="evenodd" 镂空 | 支持 | 支持 | 可用 |
| 多段渐变 | 完整 | 只保留首尾两个色标 | 不建议 |
| 描边渐变 | 支持 | 不绘制 | 禁用 |
| 虚线 | 支持 | 变成实线 | 禁用 |
| 内嵌位图 | 支持 | 消失 | 禁用 |
| 线宽随缩放变化 | 固定 | 支持 | 由该开关决定 |
不满足能力交集时,图标靠近画面中心或被选中时外观会发生变化。
说明: 保持大小不变模式永远不会使用方式 B,不受本节限制。不需要动态线宽时,可让程序侧关闭该开关,表现最可预测。
六、自查与排错
6.1 常见问题自查
| 症状 | 原因定位 |
|---|---|
| 图标完全不显示 | 格式 / 单位错误;用了不支持的元素;或程序侧未开启图标显示 |
| 选中后图标消失 | 缺少 _select 图层,或 id 没带后缀落进兜底层(3.1 节) |
| 程序换色不生效 | id 缺 _color 后缀;或 id 超 63 字符被截断(3.1 节) |
| 出现莫名灰色 | 用了 rgba() / currentColor / hsl()(3.2 节) |
| 半透明变不透明 | 用了 #RRGGBBAA 八位色(3.2 节) |
| 图标偏大,改配置无反应 | 根节点 width / height 预乘了放大倍率(2.2 节) |
| 图标偏上 / 底部被裁 | 近大远小模式用了非 1:1 的图(2.3 节) |
| 图标被拉伸变形 | 保持大小不变模式下,显示比例与图片比例不一致(2.3 节) |
| 该空心的地方变成实心 | 缺 fill-rule="evenodd";或矩形镂空 + 厚边框;或 viewBox 坐标空间过大(4.1 节) |
| 描边粗细不均匀 | 用了非等比缩放或倾斜变换(4.4 节) |
| 阴影 / 模糊 / 裁剪效果丢失 | 用了 filter / mask / clipPath,均不支持(4.2 节) |
| 显示成灰色棋盘格 | 内嵌位图不是 Base64 Data URI(5.1 节) |
| 隐藏图层意外显示出来 | 隐藏图层会被强制显示,请直接删除(3.1 节) |
| 靠近画面中心或选中时外观突变 | 开了动态线宽,但用了能力交集外的特性(5.2 节) |