选择 API

先根据任务所在环境选择软件包：

需求	软件包
在 iOS、Android 或浏览器渲染	`react-native-image-marker` Core 2.1
在不安装 React Native 的浏览器、Vite 或 WebView 中渲染	`@image-marker/web` 0.1
构建 React Native 或 Web 可视化编辑工作区	`react-native-image-marker-editor`
不渲染，只创建、验证或迁移 Recipe JSON	`@image-marker/recipe`
在 Node.js 服务中渲染	`@image-marker/node`
在终端或 CI 中渲染、检查	`@image-marker/cli`

三个公开方法共用相同的输出选项。请根据图层类型进行选择：

方法	适用场景	图层顺序
`Marker.markText`	一个或多个文本水印	文本数组顺序
`Marker.markImage`	一个或多个图像水印	图像数组顺序
`Marker.mark`	同时包含文本和图像水印	严格按照 `watermarks` 数组顺序
`Marker.createRecipe`	将同一组有序图层用于一张或多张图片	严格按照 Recipe `layers` 数组顺序

markText 和 markImage 仍受支持。当一次渲染需要同时包含文本和图像图层，或不同类型图层之间的顺序很重要时，请使用 mark。

浏览器专用应用推荐使用 @image-marker/web。它不引入 React Native peer 依赖，同时提供 /headless、/editor-adapter 和随包提供的隐形水印 Worker。

import Marker, { ImageFormat, Position } from 'react-native-image-marker';

const result = await Marker.markText({
  backgroundImage: { src: require('./background.jpg') },
  watermarkTexts: [
    {
      text: 'PRIVATE',
      position: { position: Position.center },
      style: {
        color: '#FFFFFF99',
        fontSize: 42,
        bold: true,
        rotate: -18,
      },
    },
  ],
  saveFormat: ImageFormat.png,
});

import Marker, { ImageFormat, Position } from 'react-native-image-marker';

const result = await Marker.markImage({
  backgroundImage: { src: require('./background.jpg') },
  watermarkImages: [
    {
      src: require('./logo.png'),
      position: {
        position: Position.topRight,
        X: 20,
        Y: 20,
      },
      scale: 0.5,
      alpha: 0.9,
    },
  ],
  saveFormat: ImageFormat.png,
});

import Marker, { ImageFormat, Position } from 'react-native-image-marker';

const result = await Marker.mark({
  backgroundImage: { src: require('./background.jpg') },
  watermarks: [
    {
      type: 'image',
      src: require('./logo.png'),
      position: { position: Position.topRight, X: 20, Y: 20 },
      scale: 0.5,
    },
    {
      type: 'text',
      text: 'Acme Studio',
      position: { position: Position.bottomCenter, Y: 24 },
      style: { color: '#FFFFFF', fontSize: 28 },
    },
  ],
  saveFormat: ImageFormat.png,
});

什么时候创建 Recipe

当水印结构保持不变、只有底图或显示内容发生变化时，适合使用 createRecipe。Recipe v2 接受现代的有序 layers 数组与嵌套 output；每张图片的 backgroundImage、filename 和可选 variables 应传给 apply() 或 applyMany()。文字模板可以读取 {{variableName}}、{{index}} 和 {{filename}}；visibleWhen 可以按条件保留图层。

applyMany() 会独立报告每一项，并保持输入顺序。默认并发为 1；Web 最多允许 4 个活动任务，iOS 和 Android 固定为 1，以控制原生内存压力。传入 AbortSignal 后会停止排队任务，并在支持时取消活动原生任务。

需要保存 Recipe 时请设置 schemaVersion: 2，保留稳定的图层 id，并持久化 recipe.toJSON()。导入已保存的 v1 文档时先运行一次 migrateWatermarkRecipe()。

图层顺序

图层按照数组顺序渲染。后面的图层会绘制在前面的图层之上。使用 Marker.mark 时这一点尤为重要，因为文本和图像图层共用同一个数组。

已删除的 v1 属性

Core 2 必须使用复数数组和当前的定位属性：

新代码中避免使用	改用
文本上的 `positionOptions`	`position`
`watermarkImage`	`watermarkImages`
`watermarkPositions`	每个图像图层上的 `position`
为混合内容分别调用方法	一次调用 `Marker.mark`