iter(g131): 新增悬浮操作按钮 floatButton

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T07:19:51.268Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T07:21:05.139Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -1729,6 +1729,35 @@ grid({ columns: 3, gutter: 'md' }, card({ title: '实例数' }, statistic({ valu
 
 现场演示：apps/docs/demo.html#sec-grid
 
+### floatButton — 悬浮操作按钮 FloatButton
+
+参数：
+
+- icon：string | Node —— 图标：字符串按字符（emoji / 符号）渲染，传 DOM 原样插入
+- label：string —— 文字标签；给了就出「图标 + 文字」胶囊，缺省为纯图标圆形
+- badge：string | number —— 角标（数字或短文案，如 3 / '新'）；缺省不渲染
+- tooltip：string —— 悬停提示，同时用作 aria-label；纯图标时必传，否则读屏听到默认「快捷操作」
+- position（默认 right-bottom）：'right-bottom' | 'left-bottom' —— 停靠角落；右下与 backTop 同侧，需同时出现时错开一左一右
+- offset（默认 24）：number —— 距边距离（px）；同角落堆叠多个时按倍数递增
+- onClick（回调）：() => void —— 点击回调
+
+示例：
+
+```
+document.body.append(floatButton({ icon: '+', label: '新建工单', position: 'left-bottom', onClick: () => toast.success('已新建') })); document.body.append(floatButton({ icon: '?', tooltip: '帮助中心', badge: 3 }))
+```
+
+手把手：
+
+1. 把返回节点挂到 document.body（不是页面容器内）：它是 fixed 定位，挂在容器里会被 overflow: hidden 裁剪
+2. 只有图标时务必传 tooltip：它同时是 aria-label，读屏用户靠它知道按钮干什么；有 label 时 tooltip 可省
+3. label 存在即「图标 + 文字」胶囊，只有图标即 44px 圆形；两种形态都保证触摸目标不小于 44px
+4. 同一角落要放多个按钮时递增 offset（如 24 / 80），或把它们并进同一个 flex 容器统一排布——组件自身不做堆叠计算
+5. 右下角已被 backTop 占用，页面同时有返回顶部时用 position: 'left-bottom'
+6. 纯展示 + 单回调，没有选中态与开合状态；需要多级操作请用 menu / popover 挂在 onClick 上
+
+现场演示：apps/docs/demo.html#sec-floatbutton
+
 API 速览：
 
 - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交）
@@ -1795,6 +1824,7 @@ API 速览：
 - calendar(props)：月历，整月网格内嵌页面（排期 / 值班 / 日程），每日可带 marker 标记文案，方向键漫游 + Enter 选中，翻月走 onMonthChange
 - typography(props)：排版文本，variant 决定语义（标题出 h1-h5 / 段落出 p / 行内出 span），支持语义色、装饰位、对齐、多行截断与复制按钮
 - grid(props, ...children)：栅格容器，columns 固定列数或 min 走 auto-fit 自适应列宽，gutter 统一列间距，窄屏自动降为单列
+- floatButton(props)：悬浮操作按钮，固定停靠左下 / 右下角，label 缺省为纯图标圆形，badge 走角标，tooltip 兼作 aria-label
 
 一行用法：