两种入口:独立页面与全站浮窗
结论
聊天需要两个入口:/chat 负责可分享、可深链接的完整页面;全站浮窗负责“读到这里,顺手问一句”的上下文入口。两者共用 ChatConversation 和 useChat(),但各自持有独立会话。
入口层不处理协议,只处理“什么时候出现、打开后焦点去哪、关闭后回到哪”。
问题与设计
只做浮窗,用户无法直接分享一次对话入口;只做独立页,读者在笔记详情里想问一句时必须离开当前页面。两个入口解决的是不同场景,不应该复制聊天逻辑。
结构上:
app/layouts/default.vue
└── ChatAssistantFeature
└── ChatLauncher(全站浮窗)
app/pages/chat.vue
└── ChatConversation(独立页面)
ChatLauncher 自己调用 useChat(),/chat 页面也调用一次。两个实例互不影响:页面里的对话不会出现在浮窗里,反之亦然。这是有意的隔离,避免用户在一个入口的临时提问污染另一个入口。
浮窗在 /chat 页面隐藏:
const isChatPage = computed(() => route.path === '/chat')
独立页已经有完整输入区,再显示一个浮窗会让用户面对两个输入框。这里用精确路径判断,不做前缀匹配,避免未来 /chat/xxx 子路由被误伤。
功能开关分两层:
// nuxt.config.ts
runtimeConfig: {
assistantEnabled: false,
assistantBackendUrl: '',
public: {
assistantEnabled: process.env.NUXT_PUBLIC_ASSISTANT_ENABLED === 'true',
},
}
public.assistantEnabled只控制是否渲染浮窗入口,会进入客户端 bundle,不能放密钥。assistantEnabled与assistantBackendUrl是服务端运行时配置,供 Nitro 代理使用。- 生产环境的代理还有独立的 fail-closed 判断,不能靠打开
NUXT_PUBLIC_ASSISTANT_ENABLED绕过。
浮窗的核心生命周期是“打开时把焦点送进去,关闭时把焦点还回去”:
function openDialog() {
open.value = true
lockBodyScroll()
void nextTick(() => {
dialog.value?.querySelector<HTMLTextAreaElement>('textarea')?.focus()
})
}
function closeDialog() {
if (isStreaming.value) stop()
open.value = false
unlockBodyScroll()
void nextTick(() => launcher.value?.focus())
}
nextTick 不是装饰:open 变为 true 之前,Teleport 里的对话框还没挂载,直接查询 textarea 会得到 null。关闭同理,浮窗按钮在对话框卸载后才适合重新获得焦点。
对话框使用 role="dialog"、aria-modal="true" 和 aria-labelledby,并在内部处理 Escape 与 Tab 循环:
const focusableSelector =
'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), [tabindex]:not([tabindex="-1"])'
if (event.key === 'Escape') {
closeDialog()
return
}
const items = [...dialog.value.querySelectorAll<HTMLElement>(focusableSelector)]
if (!items.length) {
event.preventDefault()
dialog.value.focus()
return
}
const first = items[0]
const last = items[items.length - 1]
if (
event.shiftKey &&
(document.activeElement === first || document.activeElement === dialog.value)
) {
event.preventDefault()
last?.focus()
} else if (!event.shiftKey && document.activeElement === last) {
event.preventDefault()
first?.focus()
}
没有引入弹窗库,是因为这里的交互面很小:一个对话框、一个关闭按钮、一个输入区。代价是焦点陷阱、滚动锁定和焦点恢复都要自己实现并测试。
滚动锁定除了 overflow: hidden,还要补偿滚动条宽度:
const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth
body.style.overflow = 'hidden'
if (scrollbarWidth > 0) body.style.paddingRight = `${scrollbarWidth}px`
如果不补偿,桌面端打开浮窗时页面会因为滚动条消失而横向跳一下。关闭时要恢复原来的 overflow 和 paddingRight,不能在卸载时留下全局样式。
移动端把对话框变成底部抽屉:
@media (max-width: (tokens.$breakpoint-tablet - 1px)) {
.dialog {
width: 100%;
height: min(92dvh, 760px);
border-radius: tokens.$radius-8 tokens.$radius-8 0 0;
}
}
dvh 比 vh 更贴近移动浏览器的可视区域,避免地址栏收起时底部被裁掉。
验证
端到端测试覆盖入口的关键路径:
/chat页面显示一级标题,默认布局仍在,且不出现浮窗按钮。- 在首页用键盘聚焦浮窗按钮,按 Enter 打开;焦点进入输入框;按 Escape 关闭;焦点回到按钮。
- 在笔记详情页打开浮窗,页面 URL 不变,阅读上下文没有被路由切换打断。
- 在 390、768、1440 三个宽度打开浮窗,页面不产生横向滚动。
cd frontend
npx playwright test e2e/site.spec.ts
边界
- 两个入口的会话不共享,也没有跨刷新持久化;用户从浮窗切到
/chat会看到一段空对话。 - 浮窗的打开状态没有写进 URL,不能通过链接直接打开某个浮窗对话。
- 背景内容没有加
inert;焦点陷阱只覆盖 Tab 路径,读屏的虚拟光标仍可能浏览到背景。更严格的模态实现需要补inert或焦点哨兵。 - 焦点选择器没有包含
select、contenteditable等元素;当前对话框里没有这类控件,增加后要同步维护。 - 移动端抽屉的
dvh行为和软键盘弹出仍需真机验证,自动化测试不能完全替代。
下一篇把同源代理接上:浏览器只请求自己的域名,后端地址和流式转发留在 Nitro。