@purekit/watermark

一款轻量级、高性能、支持复杂图文布局的前端水印 SDK。支持防篡改监控、多行文本、图片水印及灵活的 Flex 布局策略。

📦 安装 (Installation)

npm

  npm install @purekit/watermark

pnpm

  pnpm add @purekit/watermark

yarn

yarn add @purekit/watermark

🚀快速开始 (Quick Start)

1.基础用法 支持直接传入字符串或数组（自动换行）。

import Watermark from '@purekit/watermark';

// 单行文本
Watermark.apply("内部绝密资料");

// 多行文本（自动垂直居中排列）
Watermark.apply(["绝密文件", "严禁外传", "2023-10-01"]);

2. 进阶配置 通过配置对象控制样式、旋转和间距。

Watermark.apply({
   content: "User: 10086",
   rotate: -25,
   fontColor: "rgba(200, 0, 0, 0.15)",
   fontSize: 20,
   zIndex: 9999
});

3. 🔥 复杂图文布局 (核心特性) 支持类似 Flexbox 的布局系统，可无限嵌套实现图文混排。

Watermark.apply({
  layout: 'repeat',
  gap: [40, 40], // 瓦片间距
  content: {
    type: 'group',
    layout: 'row', // 水平排列：左图右文
    gap: 15,       // 内容间距
    items: [
      // 左侧图片
      {
        type: 'image',
        image: 'https://example.com/logo.png',
        width: 30,
        height: 30
      },
      // 右侧垂直文字组
      {
        type: 'group',
        layout: 'column', // 垂直排列
        gap: 5,
        items: [
          { type: 'text', text: '内部资料', fontSize: 16, fontWeight: 'bold' },
          { type: 'text', text: 'UID: 9527', fontSize: 12, fontColor: '#666' }
        ]
      }
    ]
  }
});

📚 API 文档 全局配置 (WatermarkOptions)

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | content | string \| any[] \| object | — | 水印内容，支持字符串、数组或完整配置对象。 | | el | string \| HTMLElement | document.body | 水印挂载的容器，支持 CSS 选择器或 DOM 元素。 | | width | number | auto | 单个水印瓦片的宽度。 | | height | number | auto | 单个水印瓦片的高度。 | | rotate | number | -20 | 水印旋转角度（单位：度）。 | | gap | [number, number] | [100, 100] | 水印瓦片在 X / Y 方向的间距。 | | offset | [number, number] | [20, 20] | 水印整体相对于容器左上角的偏移量。 | | layout | 'repeat' \| 'center' \| 'rb' | 'repeat' | 布局模式：repeat 平铺；center 居中；rb 右下角。 | | zIndex | number | 9999 | 水印层 DOM 的层级（z-index）。 | | monitor | boolean | true | 是否开启防篡改监控（MutationObserver）。 | | fontColor | string | 'rgba(0,0,0,0.15)' | 全局默认字体颜色。 | | fontSize | number | 16 | 全局默认字体大小（px）。 |

内容节点结构 (Content Node)

当 content 为对象时，支持以下三种类型节点：

1. 文本节点 (type: 'text')

| 属性 | 说明 | |------|------| | text | 文本内容（支持 \n 或 <br> 换行，换行后自动转为 Column Group）。 | | fontSize | 字体大小。 | | fontColor | 字体颜色。 | | fontWeight | 字重（bold / normal）。 |

2. 图片节点 (type: 'image')

| 属性 | 说明 | |------|------| | image | 图片 URL 或 Base64。 | | width | 图片渲染宽度。 | | height | 图片渲染高度。 |

3. 分组节点 (type: 'group')

| 属性 | 说明 | |------|------| | layout | 排列方向：row（水平）或 column（垂直）。 | | items | 子节点数组 Array<Node>。 | | gap | 组内元素间距（子元素会自动继承该间距）。 |

⚠️ 注意事项

1. SSR 兼容性：在 Next.js / Nuxt.js 中使用时，请确保在 onMounted 或 useEffect 中调用，避免服务端执行 document 报错。
2. 定位要求：如果指定 el 为某个局部容器，请确保该容器设置了 position: relative (组件会自动尝试设置，但建议显式声明)。
3. 安全说明：前端水印主要起警示作用，无法完全防止技术手段移除。