Watermark

基础布局

基于 Canvas 的水印组件，为内容区域平铺文字或图片水印，支持多行文本、图片水印、旋转角度、平铺间距、偏移、透明度与 z-index 自定义，全屏 Portal 模式，以及 useWatermark Hook 自定义组合

Component Demo

Basic usage and examples of the Watermark component

基础用法

受保护内容区域

水印默认以 -22° 倾斜、半透明灰色文字平铺在内容之上，不遮挡阅读，也不影响内容的正常交互。

Watermark 包裹需要保护的内容：水印层使用 Canvas 生成图案后以 background-repeat 平铺，pointer-events: none 保证所有交互都能穿透到内容

多行文本

多行文本水印

content 传入字符串数组时每个元素渲染为一行，配合 font 选项可以调整水印的视觉重量。

多行文本自动整体居中排列，font 中的 fontSize、fontWeight、color 等选项与 Canvas 文本绘制参数一一对应

图片水印

使用站点图标作为水印图片：width 将其缩放为 48px 后重复平铺，跨域加载后绘制到 Canvas。

图片以跨域方式异步加载后绘制到 Canvas；width、height 未设置时按图片原始尺寸绘制，只设置一个维度时按原图比例缩放

自定义样式

角度 -22°间距 100px透明度 30%字号 16px

可调参数水印

拖动上方滑块实时调整旋转角度、平铺间距、透明度、字号与颜色，所有变化都会立即重新生成水印图案。

rotate、gap、opacity、font 均支持实时调整，任何参数变化都会自动重新生成水印图案

全屏水印

fullscreen 模式下水印层通过 Portal 渲染到 body，以 position: fixed 覆盖整个视口；由于 pointer-events: none，页面其余部分仍可正常交互

Hook 自定义组合

任意容器上的水印

useWatermark 返回生成的 dataUrl 与平铺块尺寸，可挂到任意元素的背景上自行组合；Watermark 组件本身即基于该 Hook 实现。

useWatermark 返回 dataUrl 与平铺块尺寸，可挂到任意元素的背景上自行组合；Watermark 组件本身即基于该 Hook 实现

API Documentation

Complete API reference for the Watermark component

Props

Watermark

属性名	类型	默认值	描述
`content`	`string \| string[]`	-	水印文本内容，字符串数组表示多行文本；与 image 二选一，都为空时不渲染水印层
`image`	`string`	-	水印图片地址，以跨域方式加载后绘制到 Canvas；与 content 二选一，图片加载失败时不渲染水印层
`font`	`WatermarkFontOptions`	`{ color: "rgba(0, 0, 0, 0.15)", fontFamily: "sans-serif", fontSize: 14, fontStyle: "normal", fontWeight: "normal", textAlign: "center" }`	文本水印字体选项：颜色、字体族、字号、字体样式、字重与对齐方式
`rotate`	`number`	`-22`	水印旋转角度（度），正数表示顺时针旋转
`gap`	`[number, number]`	`[100, 100]`	水印平铺间距：[水平间距, 垂直间距]（像素）
`width`	`number`	`内容自动计算`	平铺块宽度（像素）：文本模式下覆盖自动计算的平铺块宽度，图片模式下缩放绘制图片的宽度（只设置一个维度时按原图比例缩放）
`height`	`number`	`内容自动计算`	平铺块高度（像素）：文本模式下覆盖自动计算的平铺块高度，图片模式下缩放绘制图片的高度（只设置一个维度时按原图比例缩放）
`offset`	`[number, number]`	`[0, 0]`	水印层背景偏移：[水平偏移, 垂直偏移]（像素），可微调图案起始位置
`opacity`	`number`	`1`	水印整体透明度，范围 0 ~ 1，超出范围自动收敛到边界值；与 font.color 的 alpha 叠加生效（最终透明度 = color alpha × opacity），图片水印同样适用
`zIndex`	`number`	-	水印层 z-index；未设置时水印层作为最后一个定位子元素自然覆盖内容
`fullscreen`	`boolean`	`false`	开启后水印层通过 Portal 渲染到 body 并以 position: fixed 覆盖整个视口，内容仍在原位置正常渲染
`children`	`ReactNode`	-	被水印覆盖的内容，渲染在水印层下方
`className`	`string`	-	外层容器元素的自定义类名
`style`	`CSSProperties`	-	外层容器元素的内联样式

useWatermark

属性名	类型	默认值	描述
`content`	`string \| string[]`	-	水印文本内容，与组件的 content 行为一致
`image`	`string`	-	水印图片地址，与组件的 image 行为一致
`font`	`WatermarkFontOptions`	`{ color: "rgba(0, 0, 0, 0.15)", fontFamily: "sans-serif", fontSize: 14 }`	文本水印字体选项，与组件的 font 行为一致
`rotate`	`number`	`-22`	旋转角度，与组件的 rotate 行为一致
`gap`	`[number, number]`	`[100, 100]`	平铺间距，与组件的 gap 行为一致
`width`	`number`	-	平铺块宽度，与组件的 width 行为一致
`height`	`number`	-	平铺块高度，与组件的 height 行为一致
`opacity`	`number`	`1`	整体透明度，与组件的 opacity 行为一致
`dataUrl / width / height`	`UseWatermarkResult`	-	返回的生成结果：dataUrl 为图案 Data URL（空字符串表示尚未生成或配置为空），width/height 为平铺块尺寸（像素），配合 backgroundImage 与 backgroundSize 使用

Common Props

属性名	类型	默认值	描述
`...rest`	`HTMLAttributes`	-	透传原生元素属性（如 `onClick`、`role` 等，作用于外层容器元素）

Type Definitions

WatermarkProps

水印容器组件属性接口

export interface WatermarkProps extends Omit<HTMLAttributes<HTMLDivElement>, 'content'> {
  children?: ReactNode;
  className?: string;
  content?: string | string[];
  font?: WatermarkFontOptions;
  fullscreen?: boolean;
  gap?: [number, number];
  height?: number;
  image?: string;
  offset?: [number, number];
  opacity?: number;
  rotate?: number;
  width?: number;
  zIndex?: number;
}

WatermarkFontOptions

文本水印字体选项

export interface WatermarkFontOptions {
  color?: string;
  fontFamily?: string;
  fontSize?: number;
  fontStyle?: string;
  fontWeight?: number | string;
  textAlign?: WatermarkTextAlign;
}

WatermarkTextAlign

文本水印对齐方式联合类型

export type WatermarkTextAlign = 'center' | 'end' | 'left' | 'right' | 'start';

UseWatermarkOptions

水印图案生成 Hook 配置项

export interface UseWatermarkOptions {
  content?: string | string[];
  font?: WatermarkFontOptions;
  gap?: [number, number];
  height?: number;
  image?: string;
  opacity?: number;
  rotate?: number;
  width?: number;
}

UseWatermarkResult

水印图案生成 Hook 返回值

export interface UseWatermarkResult {
  dataUrl: string;
  height: number;
  width: number;
}