iter(g51): 新增 backTop 返回顶部按钮

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T04:13:49.611Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T04:14:40.933Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -1311,6 +1311,30 @@ datePicker({ value: dateVal, min: '2026-10-20', max: '2026-10-31', onChange: (d)
 
 现场演示：apps/docs/demo.html#sec-datepicker
 
+### backTop — 返回顶部 BackTop
+
+参数：
+
+- target：HTMLElement | Window —— 监听的滚动容器；缺省 window（整页）
+- threshold：number —— 滚动超过多少像素才浮现；缺省 300
+- progress：boolean —— 是否显示滚动进度环；缺省 true
+- onClick：() => void —— 回顶之后的回调（适合埋点）
+
+示例：
+
+```
+backTop({ threshold: 300, onClick: () => toast.info('已回到顶部') })
+```
+
+手把手：
+
+1. 把返回的元素挂到页面任意位置即可，组件自身 position: fixed 定位在右下角
+2. 滚动越过 threshold 才浮现（淡入 + 上移微动画），回到阈值内自动隐藏
+3. progress 为 true 时外环弧长等于已滚比例；内滚容器用 target 传入该元素
+4. 点击平滑回顶；系统开启「减少动效」时改为瞬间跳转
+
+现场演示：apps/docs/demo.html#sec-backtop
+
 API 速览：
 
 - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交）
@@ -1364,6 +1388,7 @@ API 速览：
 - splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号
 - autoComplete(props)：输入联想，输入即过滤候选、↑↓ 环形高亮 / Enter 选中 / Esc 收起，options 可传函数做远程联想
 - datePicker(props)：日期选择，单月网格 + 翻月 / 今天快捷键，value 为 YYYY-MM-DD 信号，min/max 闭区间限制，方向键逐日逐周可导航
+- backTop(props)：返回顶部悬浮按钮，越过阈值才浮现，外环 conic-gradient 显示已滚比例，点击平滑回顶
 
 一行用法：