This is a template post for image-heavy content. You can place text before and after each gallery block, and the text style matches the body size used in blog prose.
API 调用说明(先代码 / 后效果)
完整 API 参数说明(逐行注释)
// ===== 完整 API 调用参考(每行注释版)=====<ImageGalleryTemplaterowHeight="medium" // 全局基准高度: "low" | "medium" | "high"(默认 medium)portraitSpanRows // 开启后,竖图会按规则放大高度(默认 false)portraitRatioThreshold={1} // 低于该比例判定为竖图(默认 1)portraitSpanCount={2} // 竖图放大倍数(默认 2)className="my-6" // 外层容器自定义类名(可选)items={[ { src: "http://.../DSC05661.jpg", // 图片地址(可选;不传会显示占位块) alt: "Street photo", // 图片替代文本(必填) size: "high", // 单项高度,优先级高于 rowHeight(可选) caption: "override to high", // 图注(可选) ratio: "3:4", // 宽高比(可选;推荐 "3:4" 这种写法,缺省回退 4:3) id: "hero-photo", // 稳定 key(可选,建议列表动态场景使用) }, { kind: "placeholder", // 进阶项:占位块 fillAxis: "height", // "width" 横向补位 | "height" 纵向补位 fillRemaining: true, // 是否吃掉剩余空间(默认 true) ratio: "1:1", // 占位比例(可选) minRatio: "1:1", // 最小比例下限(可选) spanRows: 1, // 纵向占位行数(可选) heightOffset: -240, // 高度微调(可选,支持负数) reserveCaptionSpace: true, // 预留 caption 空间,便于和图片对齐(可选) size: "medium", // 占位块高度档位(可选,也支持 legacy: height) caption: "placeholder", // 占位块图注(可选) id: "ph-1", // 稳定 key(可选) },]}advancedItems={[ { kind: "text", // 进阶项:文字块 text: <>Custom text tile.</>, // 文字内容(ReactNode) ratio: "4:3", // 文本块比例(可选) minRatio: "4:3", // 文本块最小比例(可选) fillRemaining: true, // 是否填充剩余宽度(可选,默认 true) reserveCaptionSpace: true, // 无 caption 时也预留图注高度(可选) size: "low", // 文本块高度档位(可选,也支持 legacy: height) caption: "text tile", // 文本块图注(可选) id: "txt-1", // 稳定 key(可选) },]}/>// ===== 语法糖(简化批量图片输入)=====const items = withSize(fromImages([ "http://.../DSC05661.jpg", // 仅传字符串:自动生成 alt { src: "http://.../DSC05663.jpg", alt: "Manual alt", caption: "Optional caption" }, // 也可对象写法]),"medium", // 批量设置 size: "low" | "medium" | "high");1) 最简调用:批量图片 + 统一尺寸
<ImageGalleryTemplaterowHeight="medium"items={withSize( fromImages([ "http://.../DSC05663.jpg", ]), "medium",)}/>
2) 单项覆盖尺寸:全局 rowHeight + item size
<ImageGalleryTemplaterowHeight="medium"items={[ { alt: "Default medium", ratio: "3:4", caption: "inherits rowHeight" }, { alt: "Force high", ratio: "16:9", size: "high", caption: "item size: high" }, { alt: "Force low", ratio: "1:1", size: "low", caption: "item size: low" },]}/>3) 进阶调用:items + advancedItems
<ImageGalleryTemplaterowHeight="medium"portraitSpanRowsitems={[ { alt: "Photo A", ratio: "3:4", caption: "image item" }, { kind: "placeholder", ratio: "1:1", fillAxis: "width", spanRows: 1, heightOffset: -240, reserveCaptionSpace: true, }, { alt: "Photo B", ratio: "16:9", caption: "image item" },]}advancedItems={[ { kind: "text", ratio: "4:3", height: "low", caption: "text tile", text: <>Advanced text block.</>, },]}/>Mixed Example (2x Medium + Right Landscape)
Image + Text Box (Equal Height)
The text container is bottom-aligned, and the tile ratio is clamped to at least 4:3.
The text container is bottom-aligned, and the tile ratio is clamped to at least 4:3.
The text container is bottom-aligned, and the tile ratio is clamped to at least 4:3.
Mixed Height In One Row
Each item can override height independently via height: "low" | "medium" | "high", so mixed heights can appear in
the same wrapped row.
Portrait Span Two Rows (Experimental)
Low (320 -> 640)
Medium (480 -> 960)
High (540 -> 1080)
With portraitSpanRows, portrait images (ratio < 1) are scaled proportionally to 2x row height while landscape
images remain at the base row height.
Low Row Height
Low row height is good for overview sections with many images. It increases density while keeping captions readable.
Medium Row Height
Medium is a balanced default. If you do not have a strong reason, this is usually the best starting point.
High Row Height
High row height works for storytelling blocks where each image needs stronger visual impact.