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

``bash
npm install watermark-js-nine
`

或者使用 yarn / Or use yarn:

`bash
yarn add watermark-js-nine
`

或者使用 pnpm / Or use pnpm:

`bash
pnpm add watermark-js-nine
`

🚀 使用方法 Usage

$3

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

$3

`typescript
// 创建平铺文字水印 / 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();
`

$3

`typescript
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();
`

$3

`typescript
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();
`

$3

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

Supports passing a configuration array to overlay multiple watermarks.

`typescript
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();
`

$3

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

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

`html

`

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

wm.init();
`

📋 配置选项 Configuration

$3

| 属性 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" |

$3

| 属性 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 |

$3

| 属性 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 |

$3

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

Supported positions for single watermark (9-grid):

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

🔧 API

$3

`typescript
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)
)
`

$3

#### init(): Promise

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

- 图片元素 (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 |
| ---------------- | ------------ | ----------- | ----------------- |
| | ✅ | ✅ | Canvas 2D |
|

等 | ✅ | ✅ | SVG Pattern |

📝 更新日志 Changelog

$3

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

$3

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

📄 许可证 License

MIT

🤝 贡献 Contributing

欢迎提交 Issue 和 Pull Request！

Issues and Pull Requests are welcome!

Show more