图片灯箱 Lightbox — Astryx v0.7.1 文档

图片灯箱用于浮层与提示场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

图片灯箱 · 综合展示 / 浅色 1：首先体验这个示例，再查看代码理解组件的组合方式。
图片灯箱 · 浅色 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
图片灯箱 · 浅色 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
图片灯箱 · 浅色 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

A fullscreen overlay for viewing images and videos at full resolution. Supports single-item and gallery modes with prev/next navigation, optional zoom and pan for images, and native video controls.

属性	类型	默认值	说明
isOpen *	boolean		灯箱是否打开。
onOpenChange *	(isOpen: boolean) => void		灯箱打开状态变化时的回调。
media *	LightboxMedia \| LightboxMedia[]		要显示的媒体。传入单个对象或数组（用于画廊模式的上一张/下一张导航）。每项为 {src, alt, caption?, type?: 'image' \| 'video'}；type 默认为 'image'，'video' 禁用缩放/平移。
index	number		画廊模式中当前索引。
onIndexChange	(index: number) => void		通过上一张/下一张导航更改画廊索引时的回调。
hasZoom	boolean	false	启用双击缩放（仅图片）。缩放后可拖动平移。
defaultIndex	number	0	Initial image index in gallery mode for uncontrolled usage.
hasAutoPlay	boolean	false	Automatically start video playback when a video media item is shown.
xstyle	StyleXStyles		用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。

使用建议

Always provide alt text for every image for screen reader accessibility.
Use gallery mode with onIndexChange for multi-image sets.
Enable hasZoom only when viewing high-resolution images that benefit from close inspection.
避免：Use the lightbox for non-image content; it is specialized for images.
避免：Nest interactive content inside captions; keep them plain text.

主题 API

{
  "targets": [
    {
      "className": "astryx-lightbox",
      "visualProps": []
    }
  ]
}

组件结构

Viewer overlay: Full-viewport dialog overlay that contains the active media and controls.
Media: Active image or video presented inside the viewer.
Close button: Button that closes the viewer.
Previous button: Gallery button that moves to the previous media item.
Next button: Gallery button that moves to the next media item.
Caption: Caller-provided caption displayed below the active media.
Counter: Current position and total shown in gallery mode.

图片灯箱

图片灯箱 · Lightbox