SVG 挤出与导入兼容性参考

本页保留 SVG 导入和挤出的详细条件。返回第 39 课示例体验编辑器操作。

轮廓、描边与样式

单层纯色填充的闭合轮廓可以挤出。<path>、<line>、<polyline>、<polygon>、 <rect>、<circle> 和 <ellipse> 上的纯色实线描边会展开成闭合的可编辑 Path； 因此仅有描边的开放路径和直线也可挤出。同时有填充和描边时，描边会成为填充图形上方的 独立 Path，两者均可导出 GLB。圆形和方形端帽，以及圆角、斜角和尖角连接会保留。 SVG 的 stroke="none" 占位层会被忽略。导入会保留 fill-rule（包括 evenodd 孔洞）， 并继承 SVG 分组的填充色和线宽。普通填充矩形保持可编辑的 Rect；圆角矩形、椭圆和 闭合折线转换为可编辑的 Path。 内联 style 中的填充、描边、不透明度、填充规则及描边几何属性优先于同名 SVG 属性。 fill="currentColor" 和 stroke="currentColor" 会查找图形、分组、<use> 实例或 SVG 根节点上最近的 color；没有指定时使用黑色。通过 style 指定的描边也可展开。 目前不会解析外部 CSS 样式表。 未闭合的折线仍保持 2D。挤出导入时， 圆角矩形会保留 SVG 中不同的 rx 与 ry，生成椭圆圆角；只指定其中一个时， 另一个使用相同的值，两个半径分别限制在对应尺寸的一半以内。普通 2D Rect 导入器仍只存储一个圆角半径。可解析的正长度 SVG 虚线间距与 stroke-dashoffset 会展开为多个可编辑的实体轮廓；奇数长度的虚线模式也可以使用。圆形端帽配合 零长度虚线段可生成挤出的圆点。non-scaling-stroke 会先将中心线投影到 SVG 变换后的坐标系，再以指定宽度展开为可编辑的 3D 轮廓，因此分组变换和 viewBox 缩放不会放大描边宽度。宽度在导入时固定；之后在编辑器中缩放视图，3D 网格仍按 普通空间对象缩放。裁剪路径或 slice 视口下的非缩放描边、零长度间隙、其他端帽下的 零长度虚线段、没有纯色描边的开放路径、渐变及不支持的 SVG 元素继续以 2D 显示。

图案和渐变

使用 patternUnits="userSpaceOnUse"、整数像素尺寸和内嵌基本图形的 <pattern> 会导入为重复的 2D 填充。图案内可以用本地 <use> 引用基本图形； 图案本身也可以通过本地 href 继承其他图案的属性和内容。瓦片内的 fill/stroke 可以引用本地线性或径向渐变（包括渐变继承），<image> 可以使用内嵌的 PNG、JPEG、WebP 或 AVIF 数据。导入后图案仍是可编辑的 2D 填充，渐变色标与图片内容则封装在瓦片资源中。外部图片、外部引用、 循环引用和其他颜料服务器仍不支持。支持的 patternTransform（matrix、 translate、scale、rotate 和 skew）会保留在可编辑填充中；数值形式的 图案原点 x/y 也会在不同位置的图形之间保持对齐，包括从分组继承填充的图形。 继承的图案会转换为各子图形上可编辑的填充。 放大画布时，SVG 图案瓦片会从矢量源重新绘制；重复间距仍保持画布坐标中的 原始尺寸，栅格尺寸受纹理上限约束。 第 39 课示例的 Gradient + image pattern sample 按钮可在编辑器画布中查看这两种瓦片内容。 矩形上的圆形 <radialGradient> 使用 userSpaceOnUse、明确的数字圆心与半径， 且焦点和圆心重合时，也会保留为 2D 渐变。其他自包含的径向渐变可应用于 矩形、圆形、椭圆、Path 和多边形；椭圆渐变、偏移焦点和渐变变换会作为 栅格化的 SVG 图片填充导入。图形仍可编辑，渐变色标则固化在图片中， 暂不能单独编辑。 放大画布时，SVG 图片填充会从矢量源重新绘制，直到纹理尺寸上限， 使高倍率下的边缘保持更清晰。 无法生成有效闭合网格的描边会保留原始 2D 节点。 展开后的描边轮廓在坐标归一化时保留六位小数，避免细小细节在最终网格校验前被压扁。

引用与视口

本地 <use href="#id"> 和旧式 xlink:href 可引用上述图形或分组，并生成独立实例， 包括前向引用和重复引用。实例的像素位移、变换及继承填充会在挤出前生效， 且各自拥有可编辑的 ID。 循环引用和无法解析的引用会被跳过。<use> 也可以引用带 viewBox 的 <symbol>， 实例或符号本身需要指定正数像素 width 和 height；实例尺寸优先。 preserveAspectRatio 支持 meet 的各项对齐方式、none，以及挤出轮廓的 slice 裁切； 最终尺寸缺失或无效时会跳过该实例；暂不导入外部引用。 带显式正数像素宽高和 viewBox 的内嵌 <svg> 也会生成可编辑的视口分组。 其 x/y、变换和 preserveAspectRatio 会作用于挤出后的子图形。 本地 <use> 可以引用这样的 <svg>，并独立覆盖视口尺寸。内嵌 SVG 视口默认会裁切 挤出轮廓（包括 slice）；设置 overflow="visible" 可保留超出视口的几何。 完整位于视口内的图形保持分组关系，移动视口分组时其 3D 网格会一同移动； 跨过边缘的图形则转换为裁切后的 Path。

裁剪与可见性

本地 clip-path="url(#id)" 和内联 CSS clip-path 也会裁切可挤出的轮廓。 <clipPath> 可以包含 Path、多边形、折线、矩形、圆形、椭圆、嵌套分组， 也可以通过本地 <use> 复用这些图形。 多个裁剪图形取并集，clip-rule="evenodd" 可以生成孔洞；分组和重复 <use> 实例上的裁剪会跟随各自的变换。多级裁剪彼此相交，也会与 SVG 视口裁切相交。 clipPathUnits="objectBoundingBox" 支持单个图形以及分组裁剪，分组的包围盒 会计入所支持子图形的变换。 被裁切的轮廓仍是可编辑的 Path；完整落在裁剪区域内的图形保持原节点及分组关系。 无法解析或尚未支持的裁剪定义保持 2D。遮罩、滤镜、裁剪路径中的文本及外部裁剪引用 暂不转换为 3D。 display="none" 或继承 visibility="hidden" 的元素不会生成 3D 网格； 子元素可以显式设置 visibility="visible"。 传入完整的 <svg> 根节点后，若有以像素指定的 width/height 和 viewBox， 导入会应用视口缩放及 preserveAspectRatio。可挤出的填充图形也会保留嵌套分组中的 skewX、skewY 和 matrix(...) 剪切变换；变换后的轮廓会采样为仍可编辑的折线路径。 只有合成变换包含剪切时才会采样；普通 viewBox 缩放仍保留矩形和曲线路径的原有形式。 没有显式像素视口尺寸时，继续使用 viewBox 的原坐标。未挤出的 2D 图形仍使用原导入器， 其源 SVG 剪切变换尚不能准确保留。 设置 preserveAspectRatio="slice" 后，可挤出的填充轮廓会按视口裁切， 包括孔洞及被裁成多个独立区域的图形。完整位于视口内的矩形或曲线路径仍保持原有形式。 不支持挤出的 2D 图形仍沿用普通导入器，此辅助函数不会裁切它们。

示例与性能

在第 39 课示例中点击 Repeated use sample 可以查看同一定义以不同填充色重复实例化， 以及中间的普通矩形。 点击 Symbol viewport sample 可以比较同一个带孔洞的符号在两个视口中的效果： 第一个使用符号自身的尺寸，第二个指定实例尺寸。 点击 Nested SVG viewport sample 可以比较直接绘制的内嵌 SVG 视口与 通过 <use> 引用的第二个实例；两者的挤出轮廓都会按各自视口裁切。 点击 Group bounds + clip use sample 可以查看变换分组上的包围盒裁剪， 以及通过本地 <use> 复用的两个裁剪窗口。 点击 Paint style + currentColor sample 可以比较继承颜色、实例独立颜色、 内联填充覆盖以及内联描边。 点击 Stroke caps + joins sample 可以比较圆形与方形端帽、独立的 3D 描边轮廓、 分组变换下的非缩放描边，以及挤出后的虚线描边与圆点。 点击 Clip paths + repeated use sample 可以查看两个分别裁剪、带孔洞的实例， 以及通过对象包围盒中的多个图形共同裁剪出的形状。

SVG 预检会判断轮廓能否生成网格。近期缓存最多保留 256 份、合计 8 MiB 的 CPU 几何数组，使异步画布更新创建 3D 伴生网格时能够复用预检结果；旧条目会被逐出。 GPU 几何另由每个画布独立缓存。运行 pnpm bench:svg-import:browser 可用仓库中的 Ghostscript Tiger SVG 等实际素材查看导入和编辑耗时。 也可以下载该 SVG，通过第 39 课示例中的 Upload SVG 导入，检查可编辑图层和不同缩放倍率。

重叠图层与 GLB

导入的 SVG 图层相互重叠时，挤出体正面仍按原 SVG 的绘制顺序显示，嵌套分组内的 图层也是如此；后绘制的图层会盖在先绘制的图层上。 导出的 GLB 也会按正面从上到下的顺序列出挤出节点，本项目的 glTF 导入器会保留 该遍历顺序。对于同平面的不透明、未倾斜挤出体，导出时还会给重叠图层分配 不超过最薄挤出体厚度 5% 的层间距，让 glTF 查看器通过深度缓冲区区分图层； 画布中的可编辑图形不会移动。互不相交的图层组分别处理，远处的独立 3D 网格 不会让它们全部失效；投影包围盒与倾斜或透明挤出体、不同高度图形或独立网格重叠的图层组 则保留原始变换。模型尺度或观察距离极大时，外部 查看器的深度缓冲精度仍可能不足以区分这些小间距。