iter(g02): 新增 image 图片组件

packages/skin/ui/src/image.ts

@@ -0,0 +1,37 @@
+import { h } from '@ui-arch/frame';
+import type { ImageProps } from './types.js';
+
+/*** 图片：缩略图展示，点击 / 回车打开遮罩大图预览（Esc 或点击遮罩关闭），样式只消费 --ua-* 令牌 ***/
+export function image(props: ImageProps): HTMLElement {
+  const style = props.width ? `width:${props.width}px` : '';
+  return h('img', {
+    class: 'ua-image',
+    src: props.src,
+    alt: props.alt ?? '',
+    style,
+    tabindex: '0',          // 可聚焦，键盘用户回车预览
+    role: 'button',
+    'aria-label': '预览图片',
+    onclick: () => openViewer(props.src, props.alt),
+    onkeydown: (e: KeyboardEvent) => e.key === 'Enter' && openViewer(props.src, props.alt),
+  });
+}
+
+/*** 打开全屏遮罩预览层；关闭时自清理、解绑键盘并归还焦点 ***/
+function openViewer(src: string, alt?: string): void {
+  const prev = document.activeElement as HTMLElement | null; // 焦点归还目标
+  const mask = h(
+    'div',
+    { class: 'ua-image-mask', role: 'dialog', 'aria-modal': 'true', 'aria-label': '图片预览' },
+    h('img', { class: 'ua-image-full', src, alt: alt ?? '' }),
+  );
+  const close = () => {
+    mask.remove(); // 卫语句式自清理：遮罩移除 + 键盘解绑 + 焦点归还
+    document.removeEventListener('keydown', onKey);
+    prev?.focus?.();
+  };
+  const onKey = (e: KeyboardEvent) => e.key === 'Escape' && close();
+  mask.addEventListener('click', close);
+  document.addEventListener('keydown', onKey);
+  document.body.appendChild(mask);
+}

packages/skin/ui/src/index.ts

@@ -15,6 +15,7 @@ export { card } from './card.js';
 export { badge } from './badge.js';
 export { tag } from './tag.js';
 export { avatar } from './avatar.js';
+export { image } from './image.js';
 export { alert } from './alert.js';
 export { toast, showToast } from './toast.js';
 export { tooltip } from './tooltip.js';

packages/skin/ui/src/types.ts

@@ -233,6 +233,13 @@ export interface TagProps {
   onClose?: () => void; // 关闭回调（调用方自行从数据源移除该项）
 }
 
+/*** 图片入参 ***/
+export interface ImageProps {
+  src: string;    // 图片地址（缩略图与大图共用）
+  alt?: string;   // 替代文本；缺省空串
+  width?: number; // 缩略图宽度像素，高度自适应；缺省走样式默认
+}
+
 /*** 提示条入参 ***/
 export interface AlertProps {
   message: string; // 提示内容

packages/skin/ui/ua.manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "@ui-arch/ui",
   "type": "skin-dom",
-  "description": "DOM 皮肤组件库：button / textField / textarea / slider / checkbox / switch / select / menu / radioGroup / accordion / breadcrumb / card / badge / tag / avatar / alert / toast / tooltip / popover / skeleton / spinner / progress / tabs / pagination / modal / drawer / form / formItem / dataTable，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌。",
+  "description": "DOM 皮肤组件库：button / textField / textarea / slider / checkbox / switch / select / menu / radioGroup / accordion / breadcrumb / card / badge / image / tag / avatar / alert / toast / tooltip / popover / skeleton / spinner / progress / tabs / pagination / modal / drawer / form / formItem / dataTable，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌。",
   "tags": [
     "components",
     "dom",
@@ -46,7 +46,8 @@
       "drawer(props, ...children)：抽屉，open 信号驱动侧滑面板，placement 左右可配、width 可调、footer 操作区，遮罩 / × / Esc 关闭",
       "form(props, items)：表单容器，布局 + 聚合校验，全部通过才触发 onSubmit",
       "formItem(props, control)：表单字段，label + 必填红星 + 规则校验 + 错误区，返回 { el, validate } 句柄",
-      "dataTable(props)：数据表格，粘性表头 / 行选择（全选三态）/ 排序 / 筛选 / 分页 / 空状态；loading 为真时数据行换骨架行且筛选/翻页禁用，内核为 table-core"
+      "dataTable(props)：数据表格，粘性表头 / 行选择（全选三态）/ 排序 / 筛选 / 分页 / 空状态；loading 为真时数据行换骨架行且筛选/翻页禁用，内核为 table-core",
+      "image(props)：图片，缩略图点击 / 回车开遮罩大图预览（Esc 或点击遮罩关闭），width 控制缩略宽"
     ],
     "keyTypes": [
       "ButtonProps",
@@ -103,6 +104,37 @@
       "读写状态：name() 读、name('张三') 写，界面自动同步，无需手动操作 DOM"
     ],
     "components": [
+      {
+        "id": "image",
+        "title": "图片 Image",
+        "demo": "sec-image",
+        "props": [
+          {
+            "n": "src",
+            "t": "string",
+            "r": 1,
+            "d": "图片地址（缩略图与大图共用）"
+          },
+          {
+            "n": "alt",
+            "t": "string",
+            "d": "替代文本；缺省空串",
+            "df": "''"
+          },
+          {
+            "n": "width",
+            "t": "number",
+            "d": "缩略图宽度像素，高度自适应；缺省走样式默认"
+          }
+        ],
+        "example": "image({ src: '/a.png', alt: '架构图', width: 160 })",
+        "steps": [
+          "基础用法只传 src：渲染缩略图，hover 上浮提亮，光标变放大镜",
+          "点击缩略图（或聚焦后回车）打开全屏遮罩大图，Esc 或点击遮罩任意处关闭，焦点归还缩略图",
+          "宽度用 width（像素）控制，高度按比例自适应，容器内不撑破 max-width",
+          "alt 尽量传有意义的描述，读屏与图片加载失败时都依赖它"
+        ]
+      },
       {
         "id": "button",
         "title": "按钮 Button",

packages/skin/ui/ui.css

@@ -1565,3 +1565,46 @@ button.ua-step-dot:hover {
     transition: none !important;
   }
 }
+
+/* ---- image 图片（缩略图 + 遮罩大图预览） ---- */
+.ua-image {
+  display: inline-block;
+  max-width: 100%;
+  border-radius: var(--ua-radius-md);
+  cursor: zoom-in;
+  transition: transform 0.15s ease, box-shadow 0.15s ease;
+}
+.ua-image:hover,
+.ua-image:focus-visible {
+  transform: translateY(-2px);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.14);
+  outline: none;
+}
+.ua-image-mask {
+  position: fixed;
+  inset: 0;
+  z-index: 1100;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(0, 0, 0, 0.6); /* 遮罩透明度叠加，非实体色 */
+  cursor: zoom-out;
+  animation: ua-image-in 0.18s ease;
+}
+.ua-image-full {
+  max-width: 90vw;
+  max-height: 90vh;
+  border-radius: var(--ua-radius-md);
+  box-shadow: 0 10px 28px rgba(0, 0, 0, 0.16);
+}
+@keyframes ua-image-in {
+  from { opacity: 0; transform: scale(0.96); }
+  to { opacity: 1; transform: scale(1); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .ua-image,
+  .ua-image-mask {
+    animation: none !important;
+    transition: none !important;
+  }
+}