输出与图像质量

输出格式

每次渲染都会返回结构化 MarkerResult。下表描述的是 result.uri；请读取 result.format、result.mimeType、result.output 和 result.metadata，不要从文件名推断。

`saveFormat`	iOS `result.uri`	Android `result.uri`	Web `result.uri`	最适合
`ImageFormat.jpg`	缓存文件路径	缓存文件路径	JPEG 数据 URL	照片和较小文件
`ImageFormat.png`	缓存文件路径	缓存文件路径	PNG 数据 URL	透明、二维码、图标和清晰边缘
`ImageFormat.webp`	明确拒绝	缓存文件路径	WebP 数据 URL	已知平台上的现代小体积输出
`ImageFormat.base64`	PNG 数据 URL	PNG 数据 URL	PNG 数据 URL	明确需要 base64 时在内存中传递

JPEG 是兼容性默认选项。当输出行为很重要时，请显式设置格式。

const result = await Marker.markImage({
  backgroundImage: { src: require('./background.png') },
  watermarkImages: [
    {
      src: require('./logo.png'),
      trimTransparentPadding: true,
    },
  ],
  filename: 'marked-photo',
  saveFormat: ImageFormat.png,
});

await shareOrDownload(result.uri);

质量

quality 接受 0–100 之间的整数，其中 100 表示最高质量。它对 JPEG 的影响最明显，因为 PNG 输出是无损的。浏览器与原生 JPEG 编码器使用相同数值时，仍可能产生不同的字节与文件大小。

对于二维码、条形码、像素画和线条图标，请选择 PNG。即使质量设置得很高，JPEG 压缩也可能使清晰边缘变得模糊。

JPEG 与透明度

JPEG 没有 alpha 通道。当透明像素保存为 JPEG 时，matteColor 用于选择填充其背后的纯色。默认颜色为白色。

saveFormat: ImageFormat.jpg,
quality: 92,
matteColor: '#FFFFFF',

旋转背景图

默认的 RotationCanvasMode.expand 会扩大输出画布，使旋转后的完整图像仍然可见。选择 crop 可保持原始画布大小，并裁剪画布以外的内容。

backgroundImage: {
  src: require('./background.jpg'),
  rotate: 30,
},
rotationCanvasMode: RotationCanvasMode.crop,

文件名与存储

在原生目标上，平台支持的文件输出位于应用缓存目录中。filename 必须是安全的基本文件名，而不能是目录路径。提供的 .jpg、.jpeg、.png 或 .webp 后缀会被规范化，以匹配 saveFormat。

缓存输出不会自动出现在照片图库中。当你需要永久保存副本时，请将返回的路径传给你选用的媒体库或文件系统包。

Web 不会写入缓存文件；result.uri 是 data URL，且 Web 不使用 filename。保存时可设置链接的 download 属性，或接入自己的浏览器文件流程。

数据 URL 会让更多图像数据占用 JavaScript 内存。这适用于所有 Web 输出以及原生 base64 输出，因此应避免不必要地使用超大源图。

方向与元数据

Core 2 会先把来源方向应用到像素，再进行合成，并以 result.metadata.orientation === 'normalized' 报告。重新编码的输出会主动剥离复制的 EXIF、GPS 和其他来源元数据，以 result.metadata.policy === 'strip' 报告，从而避免过期方向与意外位置泄露。需要签名来源时请使用显式 Content Credentials adapter。