AI助手与对话
AssistantHistoryMenu
@mox-hub/patterns · AI · 助手与对话 · canonical
assistant-history-menu@mox-hub/patternsAI Executioncanonicalsrc/components/assistant-history-menu.tsx变体演示assistant-history-menu
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| conversations* | AssistantConversationSummary[] | — | — |
| isLoading* | boolean | — | — |
| activeConversationId* | string | — | — |
| currentConversationId* | string | — | — |
| onSelect* | (id: string) => void | — | — |
| onCreate* | () => void | — | — |
| labels* | Partial<AssistantHistoryLabels> | — | — |
| formatUpdatedAt* | (updatedAt: string) => string | — | — |
源码
/**
* 历史对话菜单 —— 头部时钟按钮弹出:新建对话 + 历史会话列表(相对时间,
* 当前会话高亮;点选切换、空会话显示「新对话」占位)。
* AssistantHistoryList 独立导出便于测试。
*
* 库内不依赖 ordo API 类型/i18n:会话摘要与文案均由 props 注入。
*/
import { History, SquarePen } from 'lucide-react'
import { cn } from '@mox-hub/ui'
import { Button } from '@mox-hub/ui/components/button'
import {
Popover,
PopoverContent,
PopoverTrigger,
} from '@mox-hub/ui/components/popover'
import { ScrollArea } from '@mox-hub/ui/components/scroll-area'
import { HeaderActionButton } from './header-action-button'
import { formatRelative } from '@mox-hub/ui/format'
import { useFormatters, useI18n } from '@mox-hub/ui/i18n'
import { usePatternLabels } from '../lib/i18n'
/** 历史会话摘要(与 ordo AssistantConversationSummary 结构兼容) */
export interface AssistantConversationSummary {
id: string
title?: string | null
projectId?: string | null
messageCount: number
createdAt: string
updatedAt: string
}
/** 组件内文案缺省(中文常量;消费方经 labels 覆写接入 i18n)。 */
export interface AssistantHistoryLabels {
new: string
empty: string
untitled: string
open: string
}
export const ASSISTANT_HISTORY_DEFAULT_LABELS: AssistantHistoryLabels = {
new: '新建对话',
empty: '还没有历史对话',
untitled: '新对话',
open: '历史对话',
}
export function AssistantHistoryList({
conversations,
isLoading,
activeConversationId,
currentConversationId,
onSelect,
onCreate,
labels,
formatUpdatedAt,
}: {
conversations: AssistantConversationSummary[]
isLoading?: boolean
/** 菜单持有者当前展示的会话(跟随模式为 currentConversationId) */
activeConversationId: string | null
/** 服务端「当前会话」(最新 updatedAt),空会话占位与高亮用它兜底 */
currentConversationId: string | null
onSelect: (id: string) => void
onCreate: () => void
/** 文案覆写(默认 zh-CN;主仓 i18n 适配层集中传入 t() 结果)。 */
labels?: Partial<AssistantHistoryLabels>
/** 更新时间格式化器:主仓传 i18n 相对时间;缺省 formatRelative(跟随默认语言)。 */
formatUpdatedAt?: (updatedAt: string) => string
}) {
const D = usePatternLabels('assistantHistory', ASSISTANT_HISTORY_DEFAULT_LABELS)
const F = useFormatters()
const { locale } = useI18n()
const text = {
new: labels?.new ?? D.new,
empty: labels?.empty ?? D.empty,
untitled: labels?.untitled ?? D.untitled,
}
const format =
formatUpdatedAt ?? ((updatedAt: string) => formatRelative(updatedAt, { locale }))
return (
<div className="flex flex-col gap-1" data-ai-component="assistant.history-list">
<Button
type="button"
variant="outline"
disabled={isLoading}
onClick={onCreate}
className="h-8 justify-start gap-2 text-xs"
data-ai-action="assistant.history.new.click"
>
<SquarePen className="size-3.5" />
{text.new}
</Button>
{isLoading ? null : conversations.length === 0 ? (
<p className="px-2 py-3 text-2xs text-content-text-muted">{text.empty}</p>
) : (
// overlay 细滚动条:不占列表内容宽度(max-h 约束落在 viewport,Root 随内容自适应)
<ScrollArea
overscrollContain
className="[&_[data-slot=scroll-area-viewport]]:max-h-100"
contentClassName="pe-2"
>
{conversations.map((conversation) => {
const isActive = conversation.id === (activeConversationId ?? currentConversationId)
const title =
conversation.messageCount > 0 && conversation.title
? conversation.title
: text.untitled
const relative = format(conversation.updatedAt)
return (
<Button
key={conversation.id}
type="button"
variant="ghost"
onClick={() => onSelect(conversation.id)}
aria-current={isActive ? 'true' : undefined}
className={cn(
'h-auto w-full justify-between gap-2 px-2 py-1.5 text-start font-normal',
isActive && 'bg-accent',
)}
>
<span
className="min-w-0 flex-1 truncate text-label text-content-text"
title={title}
>
{title}
</span>
<span className="shrink-0 text-caption whitespace-nowrap text-content-text-muted">
{relative || F.date(conversation.updatedAt)}
</span>
</Button>
)
})}
</ScrollArea>
)}
</div>
)
}
export function AssistantHistoryMenu({
conversations,
isLoading,
activeConversationId,
currentConversationId,
onSelect,
onCreate,
labels,
formatUpdatedAt,
}: {
conversations: AssistantConversationSummary[]
isLoading?: boolean
activeConversationId: string | null
currentConversationId: string | null
onSelect: (id: string) => void
onCreate: () => void
/** 文案覆写(默认 zh-CN;主仓 i18n 适配层集中传入 t() 结果)。 */
labels?: Partial<AssistantHistoryLabels>
/** 更新时间格式化器:主仓传 i18n 相对时间;缺省 formatRelative(跟随默认语言)。 */
formatUpdatedAt?: (updatedAt: string) => string
}) {
const D = usePatternLabels('assistantHistory', ASSISTANT_HISTORY_DEFAULT_LABELS)
const openLabel = labels?.open ?? D.open
return (
<Popover>
<PopoverTrigger
render={<HeaderActionButton icon={History} label={openLabel} />}
/>
<PopoverContent align="end" className="w-72 p-2">
<AssistantHistoryList
conversations={conversations}
isLoading={isLoading}
activeConversationId={activeConversationId}
formatUpdatedAt={formatUpdatedAt}
currentConversationId={currentConversationId}
onSelect={onSelect}
onCreate={onCreate}
labels={labels}
/>
</PopoverContent>
</Popover>
)
}
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
历史对话菜单:新建 + 会话列表(相对时间/高亮/空态);会话摘要与 labels 由 props 注入,不依赖 API 或 i18n。