跳到主要内容
Ed. notes

两种入口:独立页面与全站浮窗

长文 · 2026-11-12 · 合集第 7 / 10 篇

  • Vue
  • 交互设计
  • 响应式
第 7 / 10 篇 · 查看全部章节 → 当前:两种入口:独立页面与全站浮窗

结论

聊天需要两个入口:/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。