OpenMax
免费试用

大图查看器

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

大图查看器

image-viewer-basic demo

演示截图。演示跑在内存里的示例 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。