watermark-js-nine

一个功能强大的网页水印组件，支持文字和图片水印，支持全图平铺或单个水印，支持旋转、透明度等多种配置。

A powerful web watermark component that supports text and image watermarks, full-screen tiling or single watermark, rotation, opacity, and various other configurations.

✨ 特性 Features

• 📝 文字水印 / Text Watermark: 支持自定义文本、字体、颜色、大小，支持多行文本 / Custom text, font, color, size, multiline support
• 🖼️ 图片水印 / Image Watermark: 支持自定义图片、大小、透明度 / Custom image, size, opacity
• 🔄 灵活布局 / Flexible Layout: 支持全图平铺或单个定位（九宫格） / Full-screen tiling or single positioning (9-grid)
• 🎯 智能元素识别 / Smart Element Detection: 自动区分图片元素和普通元素，采用不同的渲染策略 / Auto-detect image vs other elements with different rendering strategies
• 📐 精确控制 / Precise Control: 支持旋转角度、偏移量、间距（毫米单位） / Rotation angle, offset, spacing (in mm)
• 🖨️ 打印支持 / Print Support: 针对打印场景的优化 / Optimization for printing scenarios
• 📦 TypeScript: 完整的类型定义和注释 / Complete type definitions with comments
• 🔀 多水印叠加 / Multiple Watermarks: 支持配置数组叠加多个水印 / Support config array for multiple watermarks

📦 安装 Installation

npm install watermark-js-nine

或者使用 yarn / Or use yarn:

yarn add watermark-js-nine

或者使用 pnpm / Or use pnpm:

pnpm add watermark-js-nine

🚀 使用方法 Usage

引入 Import

import WatermarkNine from "watermark-js-nine";
import type { WatermarkConfig } from "watermark-js-nine";

基本使用 Basic Usage

// 创建平铺文字水印 / Create tiling text watermark
const watermark = new WatermarkNine("target-element-id", {
  type: "text",
  tilling: true, // true=平铺 / tiling, false=单个 / single
  value: "机密文件\nCONFIDENTIAL",
  font: "20pt Arial",
  fillStyle: "rgba(200, 200, 200, 0.5)",
  rotate: -45,
  horizontal: 20, // mm
  vertical: 20, // mm
});

// 初始化 / Initialize
watermark.init();

单个水印（九宫格定位）Single Watermark (9-Grid Position)

const watermark = new WatermarkNine("target-element-id", {
  type: "text",
  tilling: false, // 单个水印 / Single watermark
  value: "版权所有",
  font: "16pt SimSun",
  fillStyle: "rgba(255, 0, 0, 0.8)",
  rotate: 0,
  place: "bottomRight", // 九宫格位置 / 9-grid position
  offset: [-10, -10], // 偏移量 mm / offset mm
});

watermark.init();

图片水印 Image Watermark

const watermark = new WatermarkNine("target-element-id", {
  type: "image",
  tilling: true,
  image: {
    type: "png",
    data: "base64字符串...", // 图片base64数据 / Base64 image data
    size: [50, 50], // 宽高 mm / width, height in mm
    opacity: 50, // 不透明度 0-100 / Opacity 0-100
  },
  rotate: 45,
  horizontal: 80,
  vertical: 80,
});

watermark.init();

多水印叠加 Multiple Watermarks

支持传入配置数组来叠加多个水印。

Supports passing a configuration array to overlay multiple watermarks.

const configs: WatermarkConfig[] = [
  {
    // 背景平铺文字水印 / Background tiling text watermark
    type: "text",
    tilling: true,
    value: "内部资料",
    rotate: -45,
    fillStyle: "rgba(0,0,0,0.1)",
    horizontal: 50,
    vertical: 50,
  },
  {
    // 右上角图片水印 / Top-right image watermark
    type: "image",
    tilling: false,
    place: "topRight",
    image: {
      data: "base64-string...",
      size: [20, 20],
      opacity: 80,
    },
  },
  {
    // 底部中间文字水印 / Bottom-center text watermark
    type: "text",
    tilling: false,
    value: "公司机密",
    place: "bottomCenter",
    fillStyle: "rgba(255,0,0,0.5)",
  },
];

const wm = new WatermarkNine("app", configs);
wm.init();

为图片元素添加水印 Watermark on Image Element

组件会自动识别 <img> 元素，使用 Canvas 直接在图片上绘制水印。

The component auto-detects <img> elements and uses Canvas to draw watermarks directly on images.

<img id="my-photo" src="photo.jpg" />

const wm = new WatermarkNine("my-photo", {
  type: "text",
  tilling: true,
  value: "© 2026",
  rotate: -30,
});

wm.init();

📋 配置选项 Configuration

WatermarkConfig 接口

| 属性 Property | 类型 Type | 说明 Description | 默认值 Default | | ------------- | ------------------- | ---------------------------------------------------------- | ---------------- | | type | "text" \| "image" | 水印类型 / Watermark type | "text" | | tilling | boolean | 是否平铺：true-全图水印，false-单个水印 / Whether to tile | true | | rotate | number | 旋转角度（度数） / Rotation angle (degrees) | 0 | | offset | [number, number] | 偏移量 [x, y] (mm) / Offset | [0, 0] | | horizontal | number | 横向间距 (mm)，平铺时生效 / Horizontal spacing | 0 | | vertical | number | 纵向间距 (mm)，平铺时生效 / Vertical spacing | 0 | | place | PlaceType | 单个水印位置，非平铺时生效 / Position for single watermark | "middleCenter" |

文字水印配置 Text Configuration

| 属性 Property | 类型 Type | 说明 Description | | ------------- | --------- | ---------------------------------------------------------------- | | value | string | 水印文本，支持 \n 换行 / Watermark text, supports \n newline | | font | string | 字体样式，如 "20pt SimSun" / Font style | | fillStyle | string | 填充颜色，如 "rgba(192,192,192,0.6)" / Fill color |

图片水印配置 Image Configuration

| 属性 Property | 类型 Type | 说明 Description | | ------------- | ------------------ | ------------------------------------------------ | | type | string | 图片类型：png / jpg 等 / Image type | | data | string | 图片 Base64 数据 / Image Base64 data | | size | [number, number] | 图片大小 [width, height] (mm) / Image size | | opacity | number | 不透明度 0-100，100 为完全不透明 / Opacity 0-100 |

位置类型 PlaceType

单个水印支持九宫格定位：

Supported positions for single watermark (9-grid):

┌─────────────┬─────────────┬─────────────┐
│  topLeft    │  topCenter  │  topRight   │
├─────────────┼─────────────┼─────────────┤
│ middleLeft  │middleCenter │ middleRight │
├─────────────┼─────────────┼─────────────┤
│ bottomLeft  │bottomCenter │ bottomRight │
└─────────────┴─────────────┴─────────────┘

🔧 API

Constructor 构造函数

new WatermarkNine(
  elementId: string,           // 目标DOM元素的ID / Target element ID
  config: WatermarkConfig | WatermarkConfig[], // 配置对象或数组 / Config or array
  isPrint?: boolean,           // 是否打印模式 / Print mode (default: false)
  zoom?: number                // 缩放比例 / Zoom level (default: 1)
)

Methods 方法

init(): Promise<void>

初始化并渲染水印。根据目标元素类型自动选择渲染策略：

• 图片元素 (img): 使用 Canvas 直接在图片上绘制
• 其他元素 (div 等): 使用 SVG 覆盖层

Initialize and render the watermark. Auto-selects rendering strategy based on element type:

• Image elements (img): Uses Canvas to draw directly on image
• Other elements (div, etc.): Uses SVG overlay

destroy(): void

移除水印，销毁实例。

Remove the watermark and destroy the instance.

🎨 渲染策略 Rendering Strategy

| 元素类型 Element | 平铺 Tilling | 单个 Single | 渲染方式 Renderer | | ---------------- | ------------ | ----------- | ----------------- | | <img> | ✅ | ✅ | Canvas 2D | | <div> 等 | ✅ | ✅ | SVG Pattern |

📝 更新日志 Changelog

v1.0.5

• 🔄 类名重构：NewWatermark → WatermarkNine
• 📝 更新所有文档和示例代码
• 🐛 修复示例 HTML 文件

v1.0.4

• ✨ 重构代码架构，支持通过元素 ID 初始化
• 🎯 自动识别图片元素和普通元素
• 📦 完善 TypeScript 类型定义和注释
• 🔀 支持多水印配置数组叠加

📄 许可证 License

MIT

🤝 贡献 Contributing

欢迎提交 Issue 和 Pull Request！

Issues and Pull Requests are welcome!