OpenMax
免费试用

名片

用户点击消息区或单聊头部里的头像时,弹出名片浮层。

名片

profile-card-basic demo

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。

演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): profile-card-basic.tsx
"use client";

import { ChatHostProvider } from "@openmaxai/chat/host";
import { MessageThread } from "@openmaxai/chat/message-thread";
// 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 ProfileCardDemo() {
	// With the `profileCard` capability every avatar opens a profile card. Its buttons call
	// `openDirectMessage` / `openSelfSettings` / `openAgentManagement` on your host
	// (here they print the call at the bottom of the demo).
	const host = useDemoHost();
	const { conversations } = useDemoData();

	return (
		<ChatHostProvider host={host}>
			<div className="flex h-full flex-col bg-background text-foreground">
				<MessageThread conversation={conversations[0]} />
			</div>
		</ChatHostProvider>
	);
}

演示使用内存宿主(useDemoHost),下面的示例改用你自己的宿主。

何时使用

  • 让用户在聊天里查看某人是谁:点击消息上的头像,或单聊 ChatHeader 里对方的头像和名字。
  • 人员名片显示成员和他名下的 Agent;Agent 名片显示在线状态、主人和「复制 Agent ID」。点主人或 Agent 可在同一浮层内切换。
  • 不需要挂载组件:宿主提供 profileCard 能力后,MessageThread 和 ChatHeader 里的头像就能点开。用 createChatHost 时由 SDK 组出,见下文。

代码示例

用 createChatHost

用 createChatHost 建宿主时不用自己写 profileCard:适配器给出取数的 profiles,你在 profileCardActions 里给出「设置」和「管理」去哪,SDK 组出名片。「发送消息」默认由 SDK 找到或新建与对方的私聊,交给页面用 useChatSdkOpenConversation 挂的监听者。

host.ts

import { createChatHost } from "@openmaxai/chat-sdk/react";

export const host = createChatHost({
  adapter: createAcmeAdapter(), // 适配器上有 profiles: { loadProfile, listOwnedAgents }
  profileCardActions: {
    openSelfSettings: () => router.push("/settings"),
    openAgentManagement: (memberId) => router.push(`/agents?id=${memberId}`),
  },
});

名片打开的第一帧用成员数据里已有的名字和头像,其余等 loadProfile 回来。profiles 的形状见 ChatSdkAdapterProfiles,三个动作见 ChatSdkProfileCardActions。用 @openmaxai/chat-openmax 时适配器已经带 profiles,只要交 profileCardActions。

提供能力

profile-card.ts

import type { ChatProfileCardPort } from "@openmaxai/chat/host";

export const profileCard: ChatProfileCardPort = {
  async loadProfile(memberId) {
    const m = await api.getMember(memberId);
    if (!m) return undefined;
    return {
      memberId: m.id,
      displayName: m.name,
      avatarUrl: m.avatar,
      kind: m.isAgent ? "agent" : "human",
      subtitle: m.roleName ?? "成员",
      onlineStatus: m.status,
      ownerMemberId: m.ownerId,
      agentIdentityId: m.identityId,
    };
  },
  listOwnedAgents: async (memberId) => (await api.getOwnedAgents(memberId)).map(toProfileEntity),
  openDirectMessage: (memberId) => openDmWith(memberId),
  openSelfSettings: () => router.push("/settings"),
  openAgentManagement: (memberId) => router.push(`/agents/${memberId}`),
};

subtitle 是算好的字符串,比如成员的角色或 Agent 的模型。名片本身不查角色。

在 React 状态里处理跳转

openDirectMessage 通常要切换当前选中的会话。可以在 <ChatProvider> 里面嵌套一层 @openmaxai/chat/host 的 ChatHostProvider,在现有宿主上加 profileCard。ChatHostProvider 不是安装入口,只替换它下面这一块界面用到的能力。

profile-cards.tsx

import { ChatHostProvider, useChatHost } from "@openmaxai/chat/host";

export function ProfileCards({ onOpenConversation, children }: ProfileCardsProps) {
  const parent = useChatHost();
  const host = useMemo(
    () => ({
      ...parent,
      profileCard: {
        loadProfile,
        listOwnedAgents,
        openDirectMessage: (memberId: string) => openDmWith(memberId).then(onOpenConversation),
        openSelfSettings: () => router.push("/settings"),
      },
    }),
    [parent, onOpenConversation],
  );
  return <ChatHostProvider host={host}>{children}</ChatHostProvider>;
}

API

名片没有 props,由宿主提供 ChatProfileCardPort:

成员 类型 必填 说明
loadProfile (memberId: string) => Promise<ChatMemberProfile | undefined> 是 名片内容;找不到时返回 undefined
listOwnedAgents (memberId: string) => Promise<readonly ChatProfileEntity[]> 是 人员名片上的 Agent 列表;没有时返回 []
openDirectMessage (memberId: string) => void 是 他人名片上的「发消息」
openSelfSettings () => void 是 自己名片上的「设置」
openAgentManagement (memberId: string) => void 否 你名下 Agent 名片上的「管理」
peekProfile (memberId: string) => ChatMemberProfile | undefined 否 同步给出第一帧(已有的名字、头像),loadProfile 回来前先画;不给时先显示「加载中」

ChatProfileEntity 是 { memberId, displayName, avatarUrl?, kind?, subtitle? };ChatMemberProfile 另有 onlineStatus?、ownerMemberId?、agentIdentityId?。

依赖的能力

能力 缺了会怎样
profileCard 消息区和单聊头部的头像都不可点
profileCard(openAgentManagement) 没有「管理」

loadProfile 返回 undefined 时名片显示「加载失败」;ChatMemberProfile 没有 agentIdentityId 时没有「复制 Agent ID」。

名片与浮层上的每个词都逐个取宿主 i18n 能力:标签、「加载失败」按钮与「复制 Agent ID」的提示(profileCard.*、common.agentTag,ns 为 components)、在线状态(status.*,ns 为 agent)与「加载中」(loading,ns 为 common)。你的 i18n 认不得这些键(回原键、带命名空间前缀的原键或空串)时用英文。名片不读页面全局的 react-i18next 实例,页面不必为它包 I18nextProvider。名字与副标题是 loadProfile 给的,原样显示;用 createChatHost 时,SDK 补的缺省副标题、没有名字时的「未命名」,以及适配器给了 orgRole 时内置组织角色的名字(memberRow.member、memberDisplay.unnamed、rolePermissionMenu.roles.*.label,ns 为 components)按同一规则取词。

无障碍

  • 头像是原生 <button>,有可见焦点环。浮层是 Radix Popover,触发按钮带 aria-expanded / aria-haspopup,关闭后焦点回到头像。
  • 卡内图标为 aria-hidden,操作按钮以文字作标签。

常见问题

头像点不了。 宿主没有 profileCard 能力。用 createChatHost 时,适配器要有 profiles、参数里要有 profileCardActions,缺一样头像就不可点;自己写宿主时需要自己加。createChatHost 提供哪些见已知限制 · 默认宿主。

名片能显示成员的角色吗? 能。在 loadProfile 里算好,作为 subtitle 返回。