组件 · 数据展示

Image 图片

图片展示组件，含加载与失败态相关能力（以类型声明为准）。

入口 @selrux/ui/image · 源码 src/components/image/index.ts · 3 个组件 · 发布状态 preview

使用建议

避免：杜撰 lazy 以外的未导出属性
限制：属性与导出以 @selrux/ui 对应子路径 d.ts/源码为准，禁止臆造

引入

tsx

12345678import {
  Image,
  ImagePreview,
  ImagePreviewGroup,
  createDefaultImagePreviewIcons,
  mergeImagePreviewIcons,
  resolveImageSize,
} from '@selrux/ui/image';

演练场

调节下方可实现的字面量属性，实时预览真实组件。函数、Portal、样式逃生口等见代码演示与 API 表。

预览

代码演示

基础用法

点击图片打开预览（默认 preview 开启）。

预览

加载失败

fallback 指定兜底图片。

预览

预览组

Image.PreviewGroup 内的图片可左右切换。

预览

尺寸、占位与预览配置

size；placeholder 加载占位（节点或 { progress }）；preview={false} 关闭点击预览，或传配置对象。

加载中…

预览

独立预览

ImagePreview 受控打开（defaultOpen / onOpenChange）；minScale / maxScale / scaleStep 缩放，movable 拖动，wheel 滚轮缩放，focusTrap 焦点约束；mask 遮罩、closeIcon、cover；countRender、current / total；toolbarRender / actionsRender / imageRender / icons 自定义渲染；imageInfo 原始尺寸；fallback 兜底图。

open = false

预览组配置

ImagePreviewGroup 的 items 声明图片列表、fallback 兜底、preview 配置。

预览

API

属性覆盖：示例用到 27 / 27 个自有属性（100%）

由 scripts/demo-coverage.mjs 统计，不含 className / style / 原生透传属性与纯转发事件。

ImagePreview.getContainer：Portal 挂载目标，默认 body；文档页无需更换挂载点

Image

带静态挂载的 Image。

静态成员：Image.Preview Image.PreviewGroup

属性	说明	类型	默认值
`size`	-	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	-
`placeholder`	-	`ImagePlaceholder`	-
`fallback`	-	`string`	-
`preview`	-	`boolean \| ImagePreviewConfig`	-
`wrapperClassName`	-	`string`	-
`wrapperStyle`	-	`CSSProperties`	-
`data-size`	UI 尺寸档，落到包装根 data-size。	`string`	-

另有 292 项原生属性与事件继承自 HTMLAttributes / ImgHTMLAttributes，原样透传。

ImagePreview

主题化独立预览层。

属性	说明	类型	默认值
`defaultOpen`	-	`boolean`	-
`onOpenChange`	-	`((open: boolean) => void)`	-
`fallback`	-	`string`	-
`cover`	-	`ImageCoverConfig`	-
`closeIcon`	-	`ReactNode`	-
`mask`	-	`ImagePreviewMask`	-
`getContainer`	false 表示就地挂载（不 Portal）。	`false \| PortalContainerInput`	-
`minScale`	-	`number`	-
`maxScale`	-	`number`	-
`scaleStep`	-	`number`	-
`movable`	-	`boolean`	-
`wheel`	-	`boolean`	-
`focusTrap`	-	`boolean`	-
`onTransform`	-	`((info: { transform: ImageTransform; action: ImageTransformAction; }) => void)`	-
`actionsRender`	-	`ImageActionsRender`	-
`toolbarRender`	-	`ImageActionsRender`	-
`imageRender`	-	`ImageContentRender`	-
`countRender`	-	`((current: number, total: number) => ReactNode)`	-
`current`	-	`number`	-
`total`	-	`number`	-
`onActive`	-	`((offset: number) => void)`	-
`icons`	-	`Partial<ImageToolbarIcons>`	-
`imageInfo`	-	`Pick<ImageInfo, "width" \| "height">`	-

另有 281 项原生属性与事件继承自 HTMLAttributes，原样透传。

ImagePreviewGroup

主题化预览组。

属性	说明	类型	默认值
`items`	-	`(string \| ImagePreviewItem)[]`	-
`fallback`	-	`string`	-
`preview`	-	`boolean \| ImagePreviewConfig`	-

另有 277 项原生属性与事件继承自 HTMLAttributes，原样透传。

导出类型：ImageActionsRender、ImageContentRender、ImageCoverConfig、ImageInfo、ImagePlaceholder、ImagePreviewConfig、ImagePreviewGroupProps、ImagePreviewItem、ImagePreviewMask、ImagePreviewProps、ImageProgressConfig、ImageProps、ImageSize、ImageToolbarActions、ImageToolbarIcons、ImageToolbarRenderInfo、ImageTransform、ImageTransformAction

函数与常量

名称	说明	签名 / 类型
`createDefaultImagePreviewIcons`	默认预览工具栏图标集。	`() => ImageToolbarIcons`
`mergeImagePreviewIcons`	合并调用方 icons 与默认图标。	`(icons?: Partial<ImageToolbarIcons>) => ImageToolbarIcons`
`resolveImageSize`	解析 Image size：prop → Provider → md。	`(size: ImageSize \| undefined, configured: ControlSize \| undefined) => ImageSize`