iter(g54): 新增 watermark 水印组件

2026-10-26 12:18:24 +08:00
parent 30f5a4558d
commit 818e20eb95
12 changed files with 229 additions and 10 deletions
@@ -52,3 +52,4 @@ export { datePicker } from './datePicker.js';
 export { backTop } from './backTop.js';
 export { colorPicker } from './colorPicker.js';
 export { tour } from './tour.js';
+export { watermark } from './watermark.js';
@@ -590,4 +590,14 @@ export interface TourHandle {
  close: () => void;           // 立即关闭
 }

+/*** 水印入参 ***/
+export interface WatermarkProps {
+  text: string;      // 水印文字，支持 \n 多行
+  opacity?: number;  // 透明度；缺省 0.12
+  rotate?: number;   // 旋转角度（度）；缺省 -20
+  gap?: number;      // 平铺间距像素；缺省 140
+  fontSize?: number; // 字号像素；缺省 14
+  color?: string;    // 颜色（CSS 串或令牌名）；缺省取 --ua-color-text-muted 的实色
+}
+
 export type { ColumnDef, RowKey }; // 再导出常用内核类型，方便调用方
@@ -0,0 +1,42 @@
+import { h } from '@ui-arch/frame';
+import type { WatermarkProps } from './types.js';
+
+/*** 取令牌实色：canvas 不认 var(--ua-*)，先解析成计算值，解析不到再退回中性灰 ***/
+function tokenColor(expr: string): string {
+  const name = /^var\((--[\w-]+)\)$/.exec(expr.trim())?.[1]; // 形如 var(--ua-color-text-muted)
+  if (!name) return expr; // 已经是实际色值，直接用
+  const v = getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+  return v || 'rgb(128 128 128)'; // 兜底：中性灰，避免透明水印
+}
+
+/*** 生成平铺单元：一块 gap 见方的画布，居中画一行旋转文字，靠 background-repeat 铺满 ***/ 
+function tile(props: WatermarkProps): string {
+  const gap = props.gap ?? 140;        // 平铺单元尺寸
+  const size = props.fontSize ?? 14;   // 字号
+  const ratio = window.devicePixelRatio || 1; // 高分屏按 DPR 放大，避免糊
+  const cv = document.createElement('canvas');
+  cv.width = gap * ratio;
+  cv.height = gap * ratio;
+  const ctx = cv.getContext('2d');
+  if (!ctx) return ''; // 卫语句：环境不支持 canvas 时不出图
+  ctx.scale(ratio, ratio);
+  ctx.translate(gap / 2, gap / 2);
+  ctx.rotate(((props.rotate ?? -20) * Math.PI) / 180);
+  ctx.font = `${size}px system-ui, sans-serif`;
+  ctx.fillStyle = tokenColor(props.color ?? 'var(--ua-color-text-muted)');
+  ctx.globalAlpha = props.opacity ?? 0.12;
+  ctx.textAlign = 'center';
+  ctx.textBaseline = 'middle';
+  props.text.split('\n').forEach((line, i, arr) => {
+    ctx.fillText(line, 0, (i - (arr.length - 1) / 2) * (size + 4)); // 多行按行距垂直居中
+  });
+  return cv.toDataURL('image/png');
+}
+
+/*** 水印：内容容器 + 覆盖层，覆盖层用 repeat 背景平铺，pointer-events:none 不挡交互 ***/ 
+export function watermark(props: WatermarkProps, ...children: unknown[]): HTMLElement {
+  const img = tile(props);
+  const layer = h('div', { class: 'ua-watermark-layer', 'aria-hidden': 'true' }) as HTMLElement;
+  if (img) layer.style.backgroundImage = `url(${img})`; // 画布不可用时降级为无水印，不影响内容
+  return h('div', { class: 'ua-watermark' }, h('div', { class: 'ua-watermark-body' }, ...children), layer) as HTMLElement;
+}
@@ -66,7 +66,8 @@
      "datePicker(props)：日期选择，单月网格 + 翻月 / 今天快捷键，value 为 YYYY-MM-DD 信号，min/max 闭区间限制，方向键逐日逐周可导航",
      "backTop(props)：返回顶部悬浮按钮，越过阈值才浮现，外环 conic-gradient 显示已滚比例，点击平滑回顶",
      "colorPicker(props)：颜色选择，预设色板（缺省语义令牌色）+ 原生取色器 + 手输 CSS 颜色串，value 为颜色串信号",
-      "tour(props)：引导漫游，返回 { el, start, close } 句柄；聚光框按 target 选择器定位，卡片自动选方位，Esc / 跳过走 onClose"
+      "tour(props)：引导漫游，返回 { el, start, close } 句柄；聚光框按 target 选择器定位，卡片自动选方位，Esc / 跳过走 onClose",
+      "watermark(props, ...children)：内容容器 + 平铺水印覆盖层，canvas 生成单元、颜色取自令牌，覆盖层不挡交互"
    ],
    "keyTypes": [
      "ButtonProps",
@@ -2281,6 +2282,56 @@
          "卡片优先落在目标下方，空间不足自动翻到上方，左右夹在视口内；滚动 / 缩放会实时重算",
          "末步按钮文案变「完成」并触发 onFinish；× 或 Esc 触发 onClose，焦点归还开启前的元素"
        ]
+      },
+      {
+        "id": "watermark",
+        "title": "水印 Watermark",
+        "demo": "sec-watermark",
+        "props": [
+          {
+            "n": "text",
+            "t": "string",
+            "r": 1,
+            "d": "水印文字，支持 \\n 多行"
+          },
+          {
+            "n": "opacity",
+            "t": "number",
+            "d": "透明度；缺省 0.12"
+          },
+          {
+            "n": "rotate",
+            "t": "number",
+            "d": "旋转角度（度）；缺省 -20"
+          },
+          {
+            "n": "gap",
+            "t": "number",
+            "d": "平铺间距像素；缺省 140"
+          },
+          {
+            "n": "fontSize",
+            "t": "number",
+            "d": "字号像素；缺省 14"
+          },
+          {
+            "n": "color",
+            "t": "string",
+            "d": "颜色（CSS 串或 var(--ua-*) 令牌）；缺省取 --ua-color-text-muted 的实色"
+          },
+          {
+            "n": "children",
+            "t": "...unknown[]",
+            "d": "被水印覆盖的内容，作为第二个及之后的实参传入"
+          }
+        ],
+        "example": "watermark({ text: '内部资料\\n仅限内网', gap: 160 }, card({ title: '受保护内容' }, h('p', null, '正文')))",
+        "steps": [
+          "第一个参数是配置，其后所有实参都被当作内容渲染在水印层下方",
+          "组件用一块 gap 见方的 canvas 画单个旋转单元，再 background-repeat 铺满，因此不需要监听尺寸变化",
+          "color 传 var(--ua-*) 时会先解析成计算值（canvas 不认 CSS 变量），所以暗色主题下颜色会自动跟随",
+          "覆盖层为 pointer-events:none，下方按钮/输入框照常可点；watermark 根节点自带圆角与裁剪"
+        ]
      }
    ]
  }
@@ -3222,3 +3222,20 @@ button.ua-step-dot:hover {
  .ua-tour-card { animation: none; }
  .ua-tour-spot { transition: none; }
 }
+.ua-watermark {
+  position: relative;
+  overflow: hidden;
+  border-radius: var(--ua-radius-md);
+}
+.ua-watermark-body {
+  position: relative;
+  z-index: 1;
+}
+.ua-watermark-layer {
+  position: absolute;
+  inset: 0;
+  z-index: 2;
+  pointer-events: none;
+  background-repeat: repeat;
+  background-position: 0 0;
+}