n-sticky 粘性布局
滚过组件所在位置后吸附，向下回滚自动还原。默认只提供属性和插槽：Web、微信使用原生 sticky；App 在组件内部接入页面或指定容器的滚动事件。没有页面级测量、占位或偏移计算。
普通模式将 default 与 content 一起吸附。开启 bounded 后，仅 default 吸附，content 保持常流，在分组结束时推动标题让位；没有 content 时没有持续吸附的距离。修改 bounded 会重新装配插槽，滚动过程保留插槽实例。
平台兼容性
最低 HBuilderX 5.26。实现覆盖 Android、iOS、鸿蒙、Web 和微信小程序。编译检查与交互验证分别记录，编译通过不代表对应真机验收完成。
| Android | iOS | 鸿蒙 | Web | 微信小程序 |
|---|---|---|---|---|
| 事件定位 | 事件定位 | 事件定位 | 原生 sticky | 原生 sticky |
API
属性
| 参数 | 说明 | 类型 | 默认值 | 可选值 |
|---|---|---|---|---|
| scrollTop | 可选显式滚动位置，px；null 自动定位，传数值时由该值驱动吸附，有限负数可表示回弹 | Number / null | null | 有限数 |
| scrollViewId | 所在原生 scroll-view 的 ID；空为页面滚动，默认无需转发事件 | String | "" | - |
| offsetTop | 距页面或滚动容器顶部的吸附偏移，px，允许负数 | Number | 0 | 有限数 |
| bounded | 仅吸附 default，content 为范围正文；关闭时两插槽一起吸附，无正文时无持续吸附区间 | Boolean | false | - |
| disabled | 禁用吸附并保持文档流内容；重新启用自动测量 | Boolean | false | - |
| zIndex | -1 使用主题层级，非负整数显式覆盖 | Number | -1 | -1 / 非负整数 |
| headStyle | default 内容层行内样式，支持背景、margin、padding 和高度 | String | "" | - |
| customClass | 根节点额外类，须在组件样式表内定义 | String | "" | - |
| customStyle | 根节点行内样式 | String | "" | - |
事件
| 事件名 | 说明 |
|---|---|
| change | 检测到吸附状态变化时触发，参数 Boolean；同一状态不重复派发 |
| error | 配置或测量错误，参数 NStickyError：{prop: string, message: string}；停止吸附并保留内容，修正后自动恢复 |
插槽
| 插槽名 | 说明 |
|---|---|
| default | 吸附内容；提供 isSticky（Boolean） |
| content | 普通模式随组件吸附，bounded 模式作为常流范围正文；提供 isSticky（Boolean） |
方法
| 方法名 | 说明 |
|---|---|
| measure | 请求重新测量；常规布局与尺寸变化由组件检测 |
样式令牌
| CSS 变量 | 默认值 | 作用 |
|---|---|---|
| --n-sticky-z-index | 900 | 吸附层级 |
实现说明
| 能力 | 常见做法 | 本组件做法与取舍 |
|---|---|---|
| 自动吸附 | 原生 sticky，或事件驱动 fixed 与占位 | Web / 微信自动滚动采用原生 sticky，App 采用事件定位；不通过定时查询补偿滚动位移 |
| 普通与范围模式 | 普通模式吸附外层，范围模式只吸附标题 | 两种模式的插槽含义全端一致，bounded 修改时重新装配，滚动时不重建插槽 |
| 显式滚动输入 | scrollTop 驱动状态与定位 | 保留既有显式输入能力；传入数值时使用事件定位，不增加公开模式开关 |
| 几何与占位 | 首次测量标题，滚动时保留占位 | 常驻区间、标题、根节点与容器来自同批查询；事件定位按包含 margin 的完整标题壳占位，避免锚点漂移 |
| 局部滚动 | 原生 sticky，或原生 scroll 驱动位移 | 原生定位跟随滚动祖先；App 订阅指定容器，显式 scrollTop 可用于自有滚动来源 |
| 导航偏移 | 手动传入导航栏高度参与计算 | Web 自动读取窗口顶偏移并入 offsetTop；App 页面内无内嵌导航栏，自定义导航场景由 offsetTop 直接表达 |
| 状态回报 | 显式滚动值或实际节点位置，或事件附带回执参数 | 事件定位即时计算状态；原生定位根据实际贴附位置回报 change / isSticky，检测结果不驱动视觉位置；事件直接绑定组件实例，不引入回执参数 |
| 样式与异常 | 节点样式定制、错误事件 | 保留主题令牌、根节点及标题内容层通道；非法参数、缺失节点和无效测量通过 error 回报并可恢复 |
几何与原生状态回报共享 100ms 检测时钟。原生吸附由平台逐帧完成，change 与 isSticky 为异步检测结果，不能用作逐帧滚动数据。显式 scrollTop 或 App 的滚动事件不逐次查询布局。隐藏、禁用、卸载时停止检测并注销监听，恢复后重新测量。