大图查看器
用户点击消息里的图片,在全屏查看器里打开。
大图查看器

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。
演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): image-viewer-basic.tsx
"use client";
import { ChatHostProvider } from "@openmaxai/chat/host";
import { MessageThread } from "@openmaxai/chat/message-thread";
import {
ChatImageLightbox,
type ChatImageSlide,
} from "@openmaxai/chat-sdk/react";
import { useMemo, useState } from "react";
// Docs helpers: useDemoHost() is an in-memory host with sample data (no backend).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import { useDemoData, useDemoHost } from "./kit";
export default function ImageViewerDemo() {
const [viewer, setViewer] = useState({
slides: [] as ChatImageSlide[],
index: 0,
open: false,
});
// The `mediaViewer` capability: the thread calls `open` when an image is clicked.
// Keep it stable so the host is not rebuilt on every render.
const mediaViewer = useMemo(
() => ({
open: (slides: readonly ChatImageSlide[], index: number) =>
setViewer({ slides: [...slides], index, open: true }),
}),
[],
);
const host = useDemoHost({ mediaViewer });
const { conversations } = useDemoData();
const design = conversations.find((c) => c.id === "design") ?? null;
return (
<ChatHostProvider host={host}>
<div className="flex h-full flex-col bg-background text-foreground">
<MessageThread conversation={design} />
</div>
<ChatImageLightbox
slides={viewer.slides}
open={viewer.open}
index={viewer.index}
onClose={() => setViewer((v) => ({ ...v, open: false }))}
/>
</ChatHostProvider>
);
}
演示使用内存宿主(useDemoHost),下面的示例改用你自己的宿主。
何时使用
- 让用户放大查看消息里的图片。宿主不提供
mediaViewer能力时,图片不可点。触屏输入时同样轻点图片打开查看器;长按图片叫出这条消息的操作栏(见响应式)。 MessageThread收集已加载部分的全部图片,从被点的那张开始交给你的查看器。- 用
@openmaxai/chat-sdk的createChatHost时不用写任何查看器代码:不给ports.mediaViewer,SDK 自带一个(ChatImageLightbox),由ChatProvider画。要用自己的查看器,传ports.mediaViewer整项替换,SDK 就不画它自己的。不要看大图时传ports.mediaViewer: null。 - 手写宿主时查看器由你渲染,也可以直接用
@openmaxai/chat-sdk/react的ChatImageLightbox。
代码示例
使用 ChatImageLightbox
app.tsx
import {
ChatImageLightbox,
type ChatImageSlide,
ChatProvider,
} from "@openmaxai/chat-sdk/react";
import { useMemo, useState } from "react";
export function App() {
const [viewer, setViewer] = useState({
slides: [] as ChatImageSlide[],
index: 0,
open: false,
});
const mediaViewer = useMemo(
() => ({
open: (slides: readonly ChatImageSlide[], index: number) =>
setViewer({ slides: [...slides], index, open: true }),
}),
[],
);
const host = useMemo(() => ({ ...baseHost, mediaViewer }), [mediaViewer]);
return (
<ChatProvider host={host}>
{/* ConversationList、MessageThread …… */}
<ChatImageLightbox
slides={viewer.slides}
open={viewer.open}
index={viewer.index}
onClose={() => setViewer((v) => ({ ...v, open: false }))}
/>
</ChatProvider>
);
}
ChatImageLightbox 的按钮文案从 react-i18next 取(components 命名空间),所以要放在 I18nextProvider 之内,实例用 createChatI18n 建,见国际化。
搭配 createChatHost(默认内置)
什么都不用传:createChatHost 没收到 ports.mediaViewer 时自带一个查看器,状态在宿主里,ChatProvider 在聊天旁边画它。点消息里的图、Agent 回复里的图都在它里面打开,左右切换这条会话已加载部分的全部图片。
- 按钮文案逐个取宿主
i18n能力的chatImageLightbox.*(ns为components);你的i18n认不得这些键(回原键或空串)时用英文。页面不必为它包I18nextProvider。 - 查看器原地渲染(
position: fixed):ChatProvider外层有transform或filter时会被困在那一层里。 - 查看器开着时图片地址过期不会换新,关掉再点一次才重新换地址(见已知缺口)。
要替换自带的查看器,用下面的 ports.mediaViewer。ChatImageLightbox 另外单独导出,给手写宿主用,或在聊天之外看图用。
换成你自己的查看器(ports.mediaViewer)
createChatHost 收到 ports.mediaViewer 就整项用它,SDK 不画自己的查看器。宿主一般在模块顶层创建,灯箱状态却在 React 里:要么在组件里用 useMemo 建宿主,要么让 open 写入一个外部 store,灯箱从中读取。
import { createChatHost } from "@openmaxai/chat-sdk/react";
export const host = createChatHost({
adapter,
ports: { mediaViewer: { open: (slides, index) => viewerStore.open(slides, index) } },
});
关掉看大图(ports.mediaViewer: null)
ports.mediaViewer 有三种取值:不给是 SDK 自带的查看器;给一个端口是用你的;给 null 是关掉。
import { createChatHost } from "@openmaxai/chat-sdk/react";
export const host = createChatHost({
adapter,
ports: { mediaViewer: null },
});
关掉之后 SDK 不画查看器,宿主上没有 mediaViewer:消息里的图片格不可点(没有手型、没有 role="button"),Agent 回复里的图在默认渲染下也不可点。你给了 markdown.openImageViewer 或 markdown.renderImageViewer 时,Agent 回复里的图照旧走它们。
手写宿主上的 ChatMediaViewerPort
import type { ChatMediaViewerPort } from "@openmaxai/chat/host";
const mediaViewer: ChatMediaViewerPort = {
open(slides, index) {
myLightbox.show(slides.map((s) => ({ url: s.src, caption: s.description })), index);
},
};
API
ChatMediaViewerPort
| 成员 | 类型 | 说明 |
|---|---|---|
open |
(slides: readonly ChatImageViewerSlide[], index: number) => void |
从 slides[index] 开始打开查看器 |
每张图是 { src, alt?, description?, messageId, attachmentIndex, resolveDownloadUrl? }。description 是消息说明文字;attachmentIndex 按这条消息的全部附件计数,不只数图片。
src 是打开查看器时换来的预览地址,查看器开着久了可能过期。宿主的附件端口有 resolveDownloadUrl 时(createChatHost 里即适配器的 uploads.resolveDownloadUrl),服务端附件的切片带 resolveDownloadUrl():用户点下载时调它、从它给的地址下载;取不到或失败时什么也不下载,不要回退到 src。ChatImageLightbox 已经这样做。还在发送中的图 src 是本地地址,不带 resolveDownloadUrl。ChatImageViewerSlide(@openmaxai/chat/host)和 ChatImageSlide(@openmaxai/chat-sdk/react)字段相同,可以直接互传,所以上面的示例用 ChatImageSlide 写 open。
ChatImageLightbox
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
slides |
ChatImageSlide[] |
必填 | 图片列表 |
open |
boolean |
必填 | 是否打开 |
index |
number |
必填 | 打开时显示第几张 |
onClose |
() => void |
必填 | 用户关闭时调用 |
依赖的能力
| 能力 | 缺了会怎样 |
|---|---|
mediaViewer |
图片不可点(createChatHost 造的宿主默认有这一项:没给 ports.mediaViewer 时是 SDK 自带的;传 null 时没有) |
attachments(resolveUrls) |
收到的图片显示「不可用」,无法打开 |
上传中的图片不可点。被点的图片解析不出地址时,查看器不打开。
无障碍
- 有查看器时,图片是
role="button",标签「查看图片」,Enter或空格打开。 ChatImageLightbox是带标签的模态role="dialog":方向键切换,Escape关闭,按钮都有标签,当前缩略图带aria-current。
常见问题
消息区里的图片点不开。
手写宿主没有 mediaViewer,按上面的方式加一个;createChatHost 造的宿主自带查看器,点不开先看是不是传了 ports.mediaViewer: null。
