Watermark 水印
给一块区域或整个页面铺上重复的文字或图片水印,用于标记内部资料、防止截图外传。
引入
import { NsWatermark } from '@ns/ui'
基础用法
把要加水印的内容放进默认插槽,用 content 设置水印文字。水印层盖在内容上面,不影响点击和选择文字。
<script setup lang="ts">
import { NsWatermark } from '@ns/ui'
</script>
<template>
<NsWatermark content="NsUI">
<div style="height: 300px">这是一个带有水印的区域</div>
</NsWatermark>
</template>
多行文字
content 传数组时每个元素一行,多行文字居中对齐。总高度超过 height 时,水印块会按文字实际高度扩大,不会切掉下面的行。
<template>
<NsWatermark :content="['NsUI', 'Vue 3 组件库']">
<div style="height: 300px">多行水印示例</div>
</NsWatermark>
</template>
常见的写法是用户名加日期,截图外传时能看出是谁截的:
<template>
<NsWatermark :content="['张三 工号 1024', '2026-11-18 内部资料']" :gap="[60, 60]">
<div style="height: 240px; padding: 16px">
<NsParagraph>这是一份内部报表,水印里有查看人和日期。</NsParagraph>
<NsButton type="primary">水印不影响点击</NsButton>
</div>
</NsWatermark>
</template>
图片水印
image 传图片地址,width、height 是图片的绘制尺寸。同时传了 content 时,图片加载失败会退回文字水印。
<template>
<NsWatermark image="/logo.png" :width="48" :height="48" :alpha="0.3">
<div style="height: 300px">图片水印示例</div>
</NsWatermark>
</template>
图片地址错了、加载失败时,有 content 就显示文字水印,没有就不显示:
<template>
<NsWatermark image="/images/broken.png" content="图片加载失败,显示文字">
<div style="height: 200px">图片加载失败的示例</div>
</NsWatermark>
</template>
自定义字体
font 设置颜色、字号、字重、字体和字体样式,没写的字段用默认值。fontWeight 取 CSS font-weight 的合法值:'normal'、'bold'、'lighter'、'bolder' 或数字(如 300、600)。
<template>
<NsWatermark
content="机密文件"
:font="{ color: 'rgba(255, 77, 79, 0.3)', fontSize: 20, fontWeight: 'bold' }"
:gap="[80, 80]"
:rotate="-30"
>
<div style="height: 300px">红色水印样式</div>
</NsWatermark>
</template>
font 的各个字段分别改,放在一起对比。水印是画在 canvas 上的,color 要写具体的颜色值,不能用 var(--ns-...) 这类 CSS 变量:
<script setup lang="ts">
import { NsWatermark } from '@ns/ui'
import type { FontConfig } from '@ns/ui'
const items: { label: string; font: FontConfig }[] = [
{ label: '默认', font: {} },
{ label: 'fontSize: 20', font: { fontSize: 20 } },
{ label: "fontWeight: 'bold'", font: { fontWeight: 'bold' } },
{ label: "fontWeight: 'lighter'", font: { fontWeight: 'lighter' } },
{ label: "fontStyle: 'italic'", font: { fontStyle: 'italic' } },
{ label: "fontStyle: 'oblique'", font: { fontStyle: 'oblique' } },
{ label: "fontFamily: 'serif'", font: { fontFamily: 'serif' } },
{ label: "fontFamily: 'monospace'", font: { fontFamily: 'monospace' } },
{ label: "color: 'rgba(24, 144, 255, 0.3)'", font: { color: 'rgba(24, 144, 255, 0.3)' } }
]
</script>
<template>
<div class="grid">
<div v-for="item in items" :key="item.label">
<p class="label">{{ item.label }}</p>
<NsWatermark content="NsUI 水印" :font="item.font" :gap="[40, 40]">
<div class="box" />
</NsWatermark>
</div>
</div>
</template>
<style scoped>
.grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
gap: var(--ns-spacing-4);
}
.label {
margin: 0 0 4px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.box {
height: 140px;
border: 1px solid var(--ns-border-color-light);
}
</style>
旋转、间距和偏移
rotate 是旋转角度,gap 是相邻两个水印之间的水平、垂直间距,offset 是整个水印图案的平移量。水印块的大小按文字宽度和旋转后的范围自动计算,长文字和旋转后的文字都能完整显示。
<template>
<NsWatermark content="rotate -45" :rotate="-45" :gap="[120, 120]" :offset="[0, 0]">
<div style="height: 300px" />
</NsWatermark>
</template>
不同的旋转角度,默认是 -22,负数逆时针、正数顺时针:
<template>
<div class="grid">
<div v-for="angle in [0, -22, -45, 30, 90]" :key="angle">
<p class="label">rotate {{ angle }}{{ angle === -22 ? '(默认)' : '' }}</p>
<NsWatermark content="NsUI" :rotate="angle" :gap="[40, 40]">
<div class="box" />
</NsWatermark>
</div>
</div>
</template>
<style scoped>
.grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(160px, 1fr));
gap: var(--ns-spacing-4);
}
.label {
margin: 0 0 4px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.box {
height: 140px;
border: 1px solid var(--ns-border-color-light);
}
</style>
不同的间距和偏移,gap 默认 [100, 100],offset 默认 [50, 50]:
<template>
<div class="grid">
<div>
<p class="label">gap [20, 20]</p>
<NsWatermark content="NsUI" :gap="[20, 20]"><div class="box" /></NsWatermark>
</div>
<div>
<p class="label">gap [100, 100](默认)</p>
<NsWatermark content="NsUI"><div class="box" /></NsWatermark>
</div>
<div>
<p class="label">gap [160, 40]</p>
<NsWatermark content="NsUI" :gap="[160, 40]"><div class="box" /></NsWatermark>
</div>
<div>
<p class="label">offset [0, 0]</p>
<NsWatermark content="NsUI" :offset="[0, 0]"><div class="box" /></NsWatermark>
</div>
<div>
<p class="label">offset [50, 50](默认)</p>
<NsWatermark content="NsUI"><div class="box" /></NsWatermark>
</div>
<div>
<p class="label">offset [120, 10]</p>
<NsWatermark content="NsUI" :offset="[120, 10]"><div class="box" /></NsWatermark>
</div>
</div>
</template>
<style scoped>
.grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
gap: var(--ns-spacing-4);
}
.label {
margin: 0 0 4px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.box {
height: 160px;
border: 1px solid var(--ns-border-color-light);
}
</style>
透明度
alpha 是整个水印的透明度,0 到 1,默认 1。它和颜色本身的透明度叠加:默认颜色已经是 15% 的不透明度,alpha 再调低会更淡。下面用了不透明的蓝色,方便看出区别:
<template>
<div class="grid">
<div v-for="alpha in [1, 0.6, 0.3, 0.1]" :key="alpha">
<p class="label">alpha {{ alpha }}{{ alpha === 1 ? '(默认)' : '' }}</p>
<NsWatermark
content="NsUI"
:alpha="alpha"
:font="{ color: 'rgb(24, 144, 255)', fontSize: 16 }"
:gap="[40, 40]"
>
<div class="box" />
</NsWatermark>
</div>
</div>
</template>
<style scoped>
.grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(160px, 1fr));
gap: var(--ns-spacing-4);
}
.label {
margin: 0 0 4px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.box {
height: 140px;
border: 1px solid var(--ns-border-color-light);
}
</style>
调整参数
拖动滑块、修改文字,水印立即重新生成:
<script setup lang="ts">
import { computed, ref } from 'vue'
import { NsInput, NsSlider, NsWatermark } from '@ns/ui'
const content = ref('NsUI 水印')
const fontSize = ref(16)
const rotate = ref(-22)
const gapX = ref(100)
const gapY = ref(100)
const offsetX = ref(50)
const offsetY = ref(50)
const alpha = ref(1)
const font = computed(() => ({ fontSize: fontSize.value }))
const gap = computed<[number, number]>(() => [gapX.value, gapY.value])
const offset = computed<[number, number]>(() => [offsetX.value, offsetY.value])
</script>
<template>
<div class="controls">
<span>content</span>
<NsInput v-model="content" placeholder="水印文字" />
<span>fontSize {{ fontSize }}</span>
<NsSlider v-model="fontSize" :min="12" :max="40" />
<span>rotate {{ rotate }}</span>
<NsSlider v-model="rotate" :min="-90" :max="90" />
<span>gap {{ gapX }} / {{ gapY }}</span>
<div class="pair">
<NsSlider v-model="gapX" :min="0" :max="200" />
<NsSlider v-model="gapY" :min="0" :max="200" />
</div>
<span>offset {{ offsetX }} / {{ offsetY }}</span>
<div class="pair">
<NsSlider v-model="offsetX" :min="0" :max="200" />
<NsSlider v-model="offsetY" :min="0" :max="200" />
</div>
<span>alpha {{ alpha.toFixed(1) }}</span>
<NsSlider v-model="alpha" :min="0" :max="1" :step="0.1" />
</div>
<NsWatermark
:content="content"
:font="font"
:rotate="rotate"
:gap="gap"
:offset="offset"
:alpha="alpha"
>
<div class="box" />
</NsWatermark>
</template>
<style scoped>
.controls {
display: grid;
grid-template-columns: 136px 1fr;
gap: var(--ns-spacing-2) var(--ns-spacing-4);
align-items: center;
max-width: 560px;
margin-bottom: var(--ns-spacing-4);
font-size: var(--ns-font-size-sm);
}
.pair {
display: grid;
grid-template-columns: 1fr 1fr;
gap: var(--ns-spacing-4);
}
.box {
height: 300px;
border: 1px solid var(--ns-border-color-light);
}
</style>
层级
z-index 是水印层的 z-index,默认 9。内容里有层级更高的定位元素时会盖住水印,这时把 z-index 调大:
<template>
<div class="grid">
<div>
<p class="label">默认 9:被 z-index 为 10 的卡片盖住</p>
<NsWatermark content="NsUI" :gap="[40, 40]">
<div class="box"><div class="raised">z-index: 10</div></div>
</NsWatermark>
</div>
<div>
<p class="label">z-index 11:水印盖在卡片上面</p>
<NsWatermark content="NsUI" :gap="[40, 40]" :z-index="11">
<div class="box"><div class="raised">z-index: 10</div></div>
</NsWatermark>
</div>
</div>
</template>
<style scoped>
.grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
gap: var(--ns-spacing-4);
}
.label {
margin: 0 0 4px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.box {
display: flex;
align-items: center;
justify-content: center;
height: 180px;
border: 1px solid var(--ns-border-color-light);
}
.raised {
position: relative;
z-index: 10;
display: flex;
align-items: center;
justify-content: center;
width: 60%;
height: 60%;
border-radius: var(--ns-border-radius);
background: var(--ns-color-primary-bg);
}
</style>
默认颜色随主题变化
不传 font.color 时,组件按容器的文字颜色判断明暗:亮色主题下是 rgba(0, 0, 0, 0.15),暗色主题下是 rgba(255, 255, 255, 0.15)。切换 <html> 的 data-theme、class,或者系统切换明暗模式时会自动重新生成。
判断依据是容器的文字颜色,所以放在深色区域、文字是白色时,水印也会自动用浅色:
<template>
<div class="grid">
<NsWatermark content="NsUI" :gap="[40, 40]">
<div class="box">文字颜色跟着主题</div>
</NsWatermark>
<div class="dark">
<NsWatermark content="NsUI" :gap="[40, 40]">
<div class="box">深色区域,文字是白色,水印用浅色</div>
</NsWatermark>
</div>
</div>
</template>
<style scoped>
.grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
gap: var(--ns-spacing-4);
}
.box {
height: 160px;
padding: var(--ns-spacing-3);
box-sizing: border-box;
border: 1px solid var(--ns-border-color-light);
}
.dark {
color: var(--ns-color-white);
background: #1f2937;
}
</style>
全屏水印
fullscreen 为 true 时水印层改成 position: fixed,铺满整个视口。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsWatermark } from '@ns/ui'
const show = ref(false)
</script>
<template>
<NsButton @click="show = !show">{{ show ? '关闭' : '打开' }}全屏水印</NsButton>
<NsWatermark v-if="show" content="NsUI" fullscreen />
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| content | string | string[] | undefined | 水印文字,数组表示多行;空字符串和空数组不显示水印 |
| image | string | undefined | 图片水印地址,优先于文字;加载失败时退回文字水印 |
| width | number | 120 | 水印内容的最小宽度(px),文字更宽时按文字宽度;图片按这个宽度绘制 |
| height | number | 64 | 水印内容的最小高度(px),多行文字更高时按文字高度;图片按这个高度绘制 |
| rotate | number | -22 | 旋转角度(度) |
| zIndex | number | 9 | 水印层的 z-index |
| gap | [number, number] | [100, 100] | 水印之间的间距 [水平, 垂直](px) |
| offset | [number, number] | [50, 50] | 水印图案整体平移 [水平, 垂直](px),即 background-position |
| font | FontConfig | 见下表 | 字体配置 |
| alpha | number | 1 | 透明度,0 到 1 |
| fullscreen | boolean | false | 是否铺满整个视口(position: fixed) |
FontConfig
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| color | string | 随主题变化 | 文字颜色。不传时亮色下是 rgba(0, 0, 0, 0.15),暗色下是 rgba(255, 255, 255, 0.15) |
| fontSize | number | 14 | 字号(px) |
| fontWeight | 'normal' | 'bold' | 'lighter' | 'bolder' | number | 'normal' | 字重 |
| fontFamily | string | 'sans-serif' | 字体 |
| fontStyle | 'normal' | 'italic' | 'oblique' | 'normal' | 字体样式 |
Slots
| 插槽 | 说明 |
|---|---|
| default | 需要添加水印的内容 |
类型
import type { FontConfig, WatermarkProps } from '@ns/ui'
interface FontConfig {
color?: string
fontSize?: number
fontWeight?: 'normal' | 'bold' | 'lighter' | 'bolder' | number
fontFamily?: string
fontStyle?: 'normal' | 'italic' | 'oblique'
}
interface WatermarkProps {
content?: string | string[]
image?: string
width?: number
height?: number
rotate?: number
zIndex?: number
gap?: [number, number]
offset?: [number, number]
font?: FontConfig
alpha?: number
fullscreen?: boolean
}
注意事项
- 图片水印需要图片服务器允许跨域:组件设置了
crossOrigin = 'anonymous',否则画布无法导出,图片加载失败时退回文字水印(没有文字就不显示)。 - 容器是
overflow: hidden,容器里没有挂到body上的下拉框、气泡这类弹层超出容器的部分会被切掉。 - 防删除只保护水印层本身:在开发者工具里删掉水印层,或者改它的
style、class、hidden,组件会立刻重建;删掉整个容器或改容器的样式不在保护范围内。 - 水印层的样式全部写在 inline 上并带
!important,类名是ns-watermark__layer,它不是 Vue 管理的节点。 - 水印是用 canvas 画好后作为重复的背景图铺满的,容器尺寸变化不需要重新生成。
优化点
- [ ] 支持富文本水印(不同行不同字号、颜色)
- [ ] 支持交错排列
- [ ] 支持指定挂载容器