AR 图标 SVG 规范

2026-11-05评分加载中…

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 节)
最近修改: