Affix 固钉
uni-appH5微信小程序App
固钉。内容滚动到距离视口顶部指定位置时固定(position: fixed),滚回后还原。跨端限制:组件无法自行监听页面滚动,需由页面在 onPageScroll 中把 scrollTop 传入;元素测量通过 uni.createSelectorQuery 完成(替代 Web 版 getBoundingClientRect),首次测量发生在 onMounted 之后,内容上方布局变化时需调用 update() 重新测量。
何时使用
页面滚动时需要常驻的操作按钮、导航条、筛选栏。
何时不使用
需要底部吸附或复杂吸顶分组(如通讯录字母索引)的场景;scroll-view 内部滚动需自行监听其 @scroll 并传 scrollTop。
本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。
Props
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
scrollTop | number | 0 | 页面当前滚动位置(px),由页面的 onPageScroll 传入(跨端替代 Web 版的 window 滚动监听) |
offsetTop | number | 0 | 内容顶部距视口顶部多少像素时吸顶 |
Events
| 名称 | 载荷 | 说明 |
|---|---|---|
change | boolean | 吸顶状态切换时触发,参数为当前是否吸顶 |
Slots
| 名称 | 说明 |
|---|---|
default | 需要吸顶的内容 |
Methods
| 名称 | 签名 | 说明 |
|---|---|---|
update | update(): void | 强制重新测量位置与尺寸(内容上方布局变化后调用) |
fixed | Ref<boolean> | 当前是否处于吸顶状态的响应式引用(配合 ref 读取) |
示例
基础吸顶
vue
<Affix :offset-top="8">
<Tag variant="primary">吸顶内容</Tag>
</Affix>吸顶搜索栏
vue
<Affix :offset-top="0">
<Search v-model="kw" placeholder="吸顶后保持可见" />
</Affix>更大吸顶偏移
vue
<Affix :offset-top="60">
<Tag variant="primary">偏移 60px 吸顶</Tag>
</Affix>