FloatyJS

FloatyJS 是一个原生 JavaScript 浮窗工具，用于在宿主页面中嵌入 iframe 浮窗，并让 iframe 页面获取宿主页面上下文。

它主要服务 AI 助手类场景：宿主页面提供按钮和页面信息，iframe 中的助手页面可以请求页面文本、焦点元素、鼠标所在元素、截图和组合快照。

适用场景

FloatyJS 适合：

• 在任意页面右下角挂一个 AI 助手按钮
• 用 iframe 承载助手页面或客服页面
• 让助手获取当前页面摘要和用户所在位置
• 在不改造宿主业务框架的情况下接入浮窗
• 为 AI 工具提供页面上下文和截图

不适合：

• 复杂后台布局系统
• 需要深度接管宿主页面路由的场景
• 需要跨域读取敏感表单值的场景
• 替代完整前端应用框架

文件说明

• floaty-main.js：宿主页面入口，负责悬浮按钮、iframe 浮窗、页面上下文采集、截图和通信
• floaty-slave.js：iframe 页面入口，负责向宿主页面请求上下文
• floaty.js：兼容入口，转发到主入口
• index.html：宿主页演示台
• iframe.html：从页演示台
• serve.py：本地静态服务器脚本

新接入优先使用 floaty-main.js 和 floaty-slave.js。floaty.js 只用于兼容旧入口。

快速接入

宿主页面添加：

<script
  type="module"
  src="./floaty-main.js"
  data-theme-color="#111827"
  data-button-text="AI"
  data-tooltip-text="点击打开 AI 浮窗"
  data-window-width="1000px"
  data-window-height="800px"
  data-window-title="AI 助手"
  data-target-link="./iframe.html"
  data-position="bottom-right"
  data-close-on-outside-click="true"
  defer
></script>

iframe 页面添加：

<script type="module" src="./floaty-slave.js"></script>

接入后，宿主页面会出现一个浮动按钮。点击按钮会打开 iframe 浮窗。

宿主侧配置

常用配置：

• data-theme-color：悬浮按钮颜色
• data-button-text：按钮文本
• data-tooltip-text：按钮提示
• data-window-width：浮窗宽度
• data-window-height：浮窗高度
• data-window-title：浮窗标题
• data-target-link：iframe 地址
• data-position：按钮位置，支持 bottom-right、bottom-left、top-right、top-left
• data-dark：是否启用暗色浮窗
• data-close-on-outside-click：点击外部是否关闭
• data-page-info：宿主页面提供的补充说明
• data-screenshot-library-url：截图依赖地址

data-page-info 很适合放页面业务摘要，例如“用户正在查看订单详情”或“当前页面是商品套餐对比页”。不要放密钥、token、身份证号、手机号完整值等敏感信息。

宿主侧 API

宿主页面加载后会暴露：

window.FloatyMain
window.floaty

常用方法：

window.FloatyMain.open()
window.FloatyMain.close()
window.FloatyMain.toggle()
window.FloatyMain.setPageInfo("用户正在查看订单详情")
window.FloatyMain.getPageInfo()
window.FloatyMain.syncPageText()
window.FloatyMain.getState()
window.FloatyMain.destroy()

如果宿主页面内容发生变化，可以调用 setPageInfo() 或 syncPageText() 让 iframe 获取最新上下文。

iframe 侧 API

iframe 页面加载后会暴露：

window.FloatySlave

常用方法：

await window.FloatySlave.getPageText()
await window.FloatySlave.getFocusContext({ depth: 5 })
await window.FloatySlave.getPointerContext({ depth: 5 })
await window.FloatySlave.getInteractionContext({ depth: 5 })
await window.FloatySlave.captureScreenshot({ includePointer: true })
await window.FloatySlave.getAISnapshot({ depth: 5, includeScreenshot: true })

AI 助手通常优先使用 getAISnapshot()，它会组合页面文本、焦点上下文、鼠标上下文和可选截图。

页面上下文

FloatyJS 可以采集：

• 当前页面纯文本
• 当前页面标题和 URL
• 当前焦点元素及祖先链
• 当前鼠标位置元素及祖先链
• 页面截图
• 宿主页面补充说明

上下文采集应服务于明确的用户需求。不要为了“信息更全”无差别传递敏感内容。

截图能力

iframe 可以请求宿主页面截图：

const screenshot = await window.FloatySlave.captureScreenshot({
  includePointer: true,
  fullPage: false,
  format: "image/png",
  scale: 1
})

浏览器没有稳定 API 能直接把系统鼠标指针截进 DOM 截图。includePointer: true 时，FloatyJS 会根据最近一次鼠标位置叠加模拟指针。

截图可能包含用户正在查看的页面内容。调用前应确认场景确实需要截图，且不要把截图发送到无关第三方。

消息协议

主从页面通过 postMessage 通信，统一 envelope：

{
  "namespace": "floatyjs",
  "version": "2.0.0",
  "source": "floaty-main",
  "target": "floaty-slave",
  "type": "request",
  "action": "page:getScreenshot",
  "requestId": "1711111111111-abcd1234",
  "payload": {},
  "success": true,
  "error": null,
  "sentAt": "2026-03-22T12:34:56.000Z"
}

调用方应通过 requestId 关联请求和响应，不要依赖消息顺序。

本地预览

运行：

python serve.py

打开：

http://127.0.0.1:8000/index.html

演示页包含宿主控制台、iframe 控制台、截图预览和 AI Snapshot 演示。

安全建议

• iframe 地址应来自可信来源
• 不要把敏感表单值写入 data-page-info
• 跨域使用时要明确允许的消息来源
• 截图和页面文本可能包含隐私信息
• 销毁浮窗时调用 destroy() 清理事件监听

FloatyJS 提供的是上下文桥，不是权限隔离层。真正的权限控制仍应由宿主系统和后端服务负责。