iter(g58): 新增 affix 固钉组件

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T04:21:58.071Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T04:23:09.567Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -1442,6 +1442,29 @@ checkboxGroup({ value: permPick, min: 1, max: 3, checkAll: true, options: [{ val
 
 现场演示：apps/docs/demo.html#sec-checkgroup
 
+### affix — 固钉 Affix
+
+参数：
+
+- offset：number —— 距视口顶部多少像素后转为固定；缺省 0
+- target：HTMLElement | Window —— 监听的滚动容器；缺省 window（整页）
+- children：...unknown[] —— 被固定的内容，作为第二个及之后的实参传入
+
+示例：
+
+```
+affix({ offset: 8 }, card({ title: '滚动时我会贴顶' }, h('p', null, '正文')))
+```
+
+手把手：
+
+1. 把要贴住的内容作为实参传入；组件内部包两层：外层占位、内层负责 fixed
+2. 滚动到 offset 以内（默认贴视口顶）时内层转 fixed，外层同步撑出等高占位，页面不会塌跳
+3. 固定期间宽度与横向位置跟随占位容器，窗口缩放或父容器变宽都自动贴合
+4. 内滚容器场景把该元素传给 target，判定改为基于它的滚动位置
+
+现场演示：apps/docs/demo.html#sec-affix
+
 API 速览：
 
 - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交）
@@ -1500,6 +1523,7 @@ API 速览：
 - tour(props)：引导漫游，返回 { el, start, close } 句柄；聚光框按 target 选择器定位，卡片自动选方位，Esc / 跳过走 onClose
 - watermark(props, ...children)：内容容器 + 平铺水印覆盖层，canvas 生成单元、颜色取自令牌，覆盖层不挡交互
 - checkboxGroup(props)：多选组，value 为数组信号，min/max 用禁用边界项实现（不抛错），checkAll 支持半选且只统计未禁用项
+- affix(props, ...children)：固钉，滚过 offset 后内容转 fixed 贴顶、外层保留占位高度，固定后宽度随容器自适应
 
 一行用法：