A powerful web watermark component supporting text and image watermarks with tiling
npm install watermark-js-ninebash
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`