Element Plus Watermark 水印组件完全指南从基础用法到 Canvas 渲染原理【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plusel-watermark是 Element Plus 提供的页面水印组件用于在页面或指定容器上叠加文本或图片水印常用于版权保护、身份标识与防截图场景。本文以 docs/en-US/component/watermark.md 为核心骨架结合仓库源码 packages/components/watermark 的实现细节系统讲解其全部配置项、四种典型用法以及底层的 Canvas 绘制与防篡改机制帮助你快速上手并理解其工作原理。快速上手基础用法最基础的用法是给一段内容套上一层水印。组件默认渲染一个position: relative的容器包裹插槽内容并通过绝对定位的子节点在容器上层叠加平铺的水印template el-watermark :fontfont div styleheight: 500px / /el-watermark /template script setup langts import { reactive, watch } from vue import { isDark } from ~/composables/dark const font reactive({ color: rgba(0, 0, 0, .15), }) watch( isDark, () { font.color isDark.value ? rgba(255, 255, 255, .15) : rgba(0, 0, 0, .15) }, { immediate: true } ) /script示例代码来自 docs/examples/watermark/basic.vue。默认水印文字为Element Plus颜色为半透明的rgba(0, 0, 0, .15)因此不会遮挡正文内容。上例还演示了在暗色模式下通过响应式font对象自动切换水印颜色的做法——这也是官方文档示例的标准写法可直接迁移到自己的项目中。组件会为容器追加一个覆盖层其样式在 watermark.vue 中生成绝对定位、宽高占满容器、pointer-events: none保证水印不拦截任何鼠标事件用户依旧可以正常点击、拖拽被覆盖的内容。多行文字水印通过content属性传入字符串数组即可渲染多行水印文字template el-watermark :fontfont :content[Element, Element Plus] div styleheight: 500px / /el-watermark /template完整示例见 docs/examples/watermark/multi-line.vue。从源码 getMarkSize 可以看到多行水印的尺寸计算逻辑逐行调用ctx.measureText测量文本宽度取所有行中的最大值作为水印宽度水印高度 单行高度 × 行数 (行数 - 1) × fontGap其中fontGap是行与行之间的间隙默认 3px测量时优先使用fontBoundingBoxAscent/Descent在不支持这两个字段的低版本浏览器如 Firefox 116中回退到actualBoundingBoxAscent/Descent保证跨浏览器一致性。图片水印image属性用于指定水印图片设置后图片的优先级高于文字内容template el-watermark :width130 :height30 imagehttps://element-plus.org/images/element-plus-logo.svg div styleheight: 500px / /el-watermark /template完整示例见 docs/examples/watermark/image.vue。官方文档特别提醒为保证图片高清且不被拉伸建议上传至少为期望宽高 2 倍2x甚至 3 倍3x的图片资源。源码中图片水印的加载逻辑在 renderWatermark通过new Image()异步加载图片onload后以图片作为水印内容绘制如果图片加载失败onerror会自动回退到文字水印避免页面出现空白水印同时设置img.crossOrigin anonymous与img.referrerPolicy no-referrer避免跨域图片导致 Canvas 被污染而无法导出 DataURL。若你的图片地址涉及跨域请确保服务端已配置正确的 CORS 响应头。自定义配置实时预览水印效果官方文档提供了自定义配置示例见 docs/examples/watermark/custom.vue通过表单控件实时驱动水印参数可以直观预览每种配置的效果template el-watermark :contentconfig.content :fontconfig.font :z-indexconfig.zIndex :rotateconfig.rotate :gapconfig.gap :offsetconfig.offset !-- 被水印覆盖的业务内容 -- /el-watermark /template script setup langts import { reactive } from vue const config reactive({ content: Element Plus, font: { fontSize: 16, color: rgba(0, 0, 0, 0.15) }, zIndex: -1, rotate: -22, gap: [100, 100] as [number, number], offset: [] as unknown as [number, number], }) /script示例中用到了el-input编辑水印文字、el-color-picker调整颜色、el-slider控制字号/层级/旋转角度以及el-input-number调节间距gap与偏移offset。这种配置面板 实时水印的组合非常适合在后台管理系统中做成可配置的安全水印。需要说明的是示例中zIndex: -1表示把水印层置于容器背景之下img { z-index: 10 }让图片内容显示在水印之上二者叠加演示了层级控制的两种取向实际业务中请根据内容与安全需求决定水印是浮于内容之上还是垫在内容之下。完整 APIAttributes、Font 与 SlotsAttributes 属性名称说明类型默认值width水印的宽度content存在时默认值为其自身宽度number120height水印的高度content存在时默认值为其自身高度number64rotate水印绘制时的旋转角度单位°number-22z-index追加的水印元素的 z-indexnumber9image图片源建议使用 2x 或 3x 图片优先级高于文字string—content水印文字内容string \| string[]Element Plusfont文字样式FontFontgap水印之间的间距[number, number][100, 100]offset水印相对容器左上角的偏移默认值为gap/2[number, number][gap[0]/2, gap[1]/2]对应 TypeScript 类型定义与默认值可在 watermark.ts 中确认组件内withDefaults也明确声明了zIndex: 9、rotate: -22、content: Element Plus、gap: [100, 100]四个默认值见 watermark.vue。关于offset的默认行为源码中有更精细的处理当未传入offset时offsetLeft取gap[0] / 2、offsetTop取gap[1] / 2即默认从gap/2处开始平铺当显式传入的偏移大于gap/2时会进一步收缩覆盖层尺寸并调整backgroundPosition确保水印边缘不会被裁切见 getMarkStyle。Font 字体样式名称说明类型默认值color字体颜色stringrgba(0,0,0,.15)fontSize字体大小number \| string16fontWeight字重normal \| bold \| lighter \| bolder \| numbernormalfontFamily字体族stringsans-seriffontGap^(2.11.5)字体行间距number3fontStyle字体样式none \| normal \| italic \| obliquenormaltextAlign文字对齐方式left \| right \| center \| start \| endcentertextBaseline文字基线top \| hanging \| middle \| alphabetic \| ideographic \| bottomhanging其中fontGap为 2.11.5 版本新增属性。源码中所有字体属性都有独立的 computed 兜底逻辑未传入时逐项取默认值见 watermark.vue。textAlign在绘制时会映射为[alignRatio, spaceRatio]组合left/start为[0, 0.5]、center为[0.5, 0]、right/end为[1, -0.5]分别用于计算文字在画布上的横向起点和旋转预留空间的补偿方向见 useClips.ts。Slots 插槽名称说明default水印所覆盖的容器内容组件模板即div[refcontainerRef]slot /见 watermark.vue。测试用例也验证了插槽内容会被正常渲染见 watermark.test.tsx。若不传任何插槽内容组件会渲染出一个空容器水印依然会平铺显示因此它也可以直接包在任意块级元素外层使用。源码原理Canvas 绘制、平铺与防篡改理解这几个源码细节有助于你在复杂场景下预判组件行为1. 高清适配绘制前先通过getPixelRatio()取window.devicePixelRatio在 prepareCanvas 中把画布的实际像素尺寸放大ratio倍再按同样比例缩放字号mergedFontSize fontSize * ratio最后把生成的 DataURL 以 CSS 像素尺寸平铺到背景上。这正是2x/3x 图片在高分屏上不模糊以及文字水印始终清晰的底层原因。2. 旋转与边界裁剪单块水印先按内容尺寸绘制再复制到max(width, height)的正方形画布上围绕中心旋转指定角度随后计算旋转后四角边界getRotatePos精确裁出包含完整旋转内容的最小区域避免斜向水印出现切头切尾。最后按gap将三块水印拼成一张更小的平铺贴图见 useClips.ts大幅减少背景图的重复绘制开销。3. 响应式更新与防篡改组件对props做了deep: true, flush: post的深度监听任何参数变化都会重新渲染水印。同时通过useMutationObserver监听容器 DOM 变化一旦检测到水印节点被删除或属性被修改见 reRendering会立即销毁并重建水印——这为用户通过开发者工具删掉水印节点提供了基础防御能力。组件在onBeforeUnmount时也会主动销毁水印节点避免内存泄漏。4. SSR 友好水印绘制依赖document与canvas因此useClips被设计为惰性 Hook源码注释明确说明 This is a lazy hook function since SSR no need this水印只在客户端onMounted后渲染服务端渲染时不会报错可安全用于 SSR 项目。总结与使用建议el-watermark是一个开箱即用的轻量组件默认零配置即可给任意容器铺上倾斜的半透明文字水印需要更精细的控制时可通过content多行、image图片建议 2x/3x 资源、font全套字体样式以及gap/offset/rotate/z-index微调布局与视觉。其内部基于 Canvas 绘制 DataURL 背景平铺实现兼顾高分屏清晰度与渲染性能并通过 MutationObserver 提供基础的防篡改能力。需要说明的是水印是视觉层面的防护手段无法阻止高级手段直接修改 DOM 或截图后处理对强安全场景建议与服务端加解密、权限控制等方案配合使用。【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考