更新记录

1.0.0（2026-07-19）

首发：自研 编写高性能 SVG 渲染核心（内置 SVG 渲染/内置 SVG 解析/自研渲染引擎 全自研 软件渲染，无额外系统依赖），把 SVG 字符串/文件渲染为 P

平台兼容性

uni-app x(5.14)

nex-svg —— 高性能 SVG 渲染（SVG → PNG）

把 SVG（字符串 / 文件）渲染为 PNG 位图（路径输出 / base64），并读取 SVG 尺寸信息。 自研 SVG 渲染核心，全自研、无额外系统依赖， 提供 uni-app 可调的 JS API。

仅支持 App 端（Android / iOS），不支持 H5 / 小程序。

能力总览（8 个 API）

<text> 文字渲染（字体来源）

含 <text> 的 SVG 现在可渲染文字（v1 曾因无系统字体而不渲染，已补齐）：

• 系统字体：进程级 fontdb 在首次渲染时懒加载系统字体（幂等），<text> 按系统 / 注册字体渲染。
• 注册自备字体：registerFontFile('/path/to/font.ttf') 累积注册；setDefaultFontFamily('Noto Sans') 设回退字族。
• 诚实边界：核心不内置重字体（含 CJK）——某字形能否显示取决于设备是否装有该字体或你是否注册了覆盖字体（缺字回退不 panic，但可能不出该字形）。需保证 CJK 显示时，请随包打字体文件 + registerFontFile 注册。

尺寸语义（width / height）

• width=0 && height=0：用 SVG 自身尺寸（intrinsic size）。
• width>0 && height>0：输出恰为 width×height 画布，内容按较小因子等比缩放适配（保持宽高比，可能留透明边）。
• 仅给一边（另一边为 0）：另一边按 SVG 宽高比等比推导。

返回类型

type SvgResult = {
  width: number;     // 输出位图宽度（像素）
  height: number;    // 输出位图高度（像素）
  sizeBytes: number; // 写入 PNG 文件字节数
};

错误（原生层抛异常，UTS 透传）

• Io：文件读写错误（如 SVG 文件不存在、输出目录不可写）。
• Decode：SVG 解析失败（非法 XML / 非 SVG / 尺寸非法）。
• Render：渲染或 PNG 编码失败（含内部 panic 兜底）。
• InvalidParam：渲染尺寸超上限（width*height > 64Mi 像素 或单边 > 32768）、源过大等。

用法示例

import { svgToPng, svgFileToPng, svgToPngBase64, svgInfo } from '@/uni_modules/nex-svg';

// 1) 字符串 SVG → PNG 文件（用 SVG 自身尺寸）
const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100"><rect width="100" height="100" fill="#f00"/></svg>';
const r = svgToPng(svg, 0, 0, `${uni.env.CACHE_PATH}/out.png`);
console.log(r.width, r.height, r.sizeBytes); // 100 100 <bytes>

// 2) 缩放到指定画布
svgToPng(svg, 256, 256, `${uni.env.CACHE_PATH}/out@256.png`);

// 3) 文件 SVG → PNG
svgFileToPng(`${uni.env.CACHE_PATH}/icon.svg`, 0, 0, `${uni.env.CACHE_PATH}/icon.png`);

// 4) 小图直出 base64（可直接用于 <内置图像编解码 :src="'data:内置图像编解码/png;base64,' + b64" />）
const b64 = svgToPngBase64(svg, 64, 64);

// 5) 读尺寸
const info = JSON.parse(svgInfo(svg)); // { width: 100, height: 100, viewBox: "0 0 100 100" }

已知边界（v1，诚实标注）

• 字体 / 文本：v1 使用默认配置，未加载任何系统字体。含 <text> 文本元素的 SVG 其文字可能不渲染（形状 / 路径 / 渐变 / 裁剪等正常）。接入 fontdb / 系统字体为后续项。
• 输出格式：仅 PNG 光栅输出。SVG→SVG（优化）、SVG→PDF、.svgz（gzip 压缩 SVG）输入为后续项。
• 尺寸上限：渲染目标 width*height ≤ 64Mi 像素（≈8192×8192）、单边 ≤ 32768，源 SVG ≤ 16MiB； 超限返回 InvalidParam（防进程级 OOM，跨原生边界 = App 闪退、JS 无法 try/catch）。
• 真机 / cli 编译验证：UTS 桥接已按 原生绑定层 真实生成的 Kotlin/Swift 绑定对账写就， HBuilderX cli --compile 与真机端到端验证为后续项（gated）。

实现说明

• 跨语言边界 安全：所有可失败函数返回 Result；渲染前先做尺寸守卫；内置 SVG 渲染 内部可达 panic 用 catch_unwind 兜成 Render 错误，绝不跨原生边界 abort。
• 契约（命名 / 签名 / 类型）以 docs/svg-plugin-contract.md 为准；字段一律 camelCase。