Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Affix 固钉
页面滚动时,把一块内容固定在滚动区域的顶部或底部,不随内容滚走。
引入
import { NsAffix } from '@ns/ui'
基础用法
内容滚到离顶部 offset 像素的位置时固定住,固定后也停在离顶部 offset 像素处。固定期间原来的位置会保留同样高度的占位,下面的内容不会跳动。
不传 listen-to 时监听整个页面的滚动。为了方便看效果,本页的示例都放在一个固定高度的滚动容器里,用 listen-to 指向这个容器(用法见下面的“自定义滚动容器”)。在框里往下滚:
<script setup lang="ts">
import { NsAffix, NsButton } from '@ns/ui'
</script>
<template>
<div id="affix-demo-basic" class="box">
<p class="line">往下滚动</p>
<NsAffix listen-to="#affix-demo-basic" :offset="20">
<NsButton type="primary">距离顶部 20px 时固定</NsButton>
</NsAffix>
<p v-for="i in 20" :key="i" class="line">第 {{ i }} 行内容</p>
</div>
</template>
<style scoped>
.box {
height: 240px;
overflow: auto;
padding: 0 16px;
border: 1px solid var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
.line {
margin: 12px 0;
color: var(--ns-text-color-secondary);
}
</style>
固定在顶部或底部
position 可选 top(默认)和 bottom。position="bottom" 时,内容离滚动区域底部不到 offset 像素(包括还在可视范围下面)时固定在底部,往下滚到离底部超过 offset 后恢复原位。
下面左边是 top,右边是 bottom:右边的按钮原本在内容中间,一开始在可视范围下面,所以固定在底部,滚到它原来的位置后恢复原位。
<template>
<NsSpace wrap align="start">
<div id="affix-demo-top" class="box">
<p class="line">position="top"</p>
<NsAffix listen-to="#affix-demo-top" position="top" :offset="10">
<NsButton type="primary">固定在顶部(top)</NsButton>
</NsAffix>
<p v-for="i in 20" :key="i" class="line">第 {{ i }} 行内容</p>
</div>
<div id="affix-demo-bottom" class="box">
<p class="line">position="bottom"</p>
<p v-for="i in 10" :key="i" class="line">第 {{ i }} 行内容</p>
<NsAffix listen-to="#affix-demo-bottom" position="bottom" :offset="10">
<NsButton type="success">固定在底部(bottom)</NsButton>
</NsAffix>
<p v-for="i in 10" :key="i + 10" class="line">第 {{ i + 10 }} 行内容</p>
</div>
</NsSpace>
</template>
<style scoped>
.box {
width: 260px;
height: 240px;
overflow: auto;
padding: 0 16px;
border: 1px solid var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
.line {
margin: 12px 0;
color: var(--ns-text-color-secondary);
}
</style>
触发距离和固定位置分开设置
trigger-top 是触发固定的距离,top 是固定后离顶部的距离,可以不一样。trigger-bottom、bottom 对应固定在底部的情况。
只写其中一个时,另一个也用这个值;都不写时用 offset。具体的取值顺序:
- 触发距离:
triggerTop→top→offset(底部:triggerBottom→bottom→offset) - 固定位置:
top→triggerTop→offset(底部:bottom→triggerBottom→offset)
下面左边滚到离顶部 60px 时就固定,固定后贴到离顶部 10px 处,会往上“跳”一下;右边是底部的对应写法。
<template>
<NsSpace wrap align="start">
<div id="affix-demo-trigger-top" class="box">
<p v-for="i in 3" :key="i" class="line">第 {{ i }} 行内容</p>
<NsAffix listen-to="#affix-demo-trigger-top" :trigger-top="60" :top="10">
<div class="bar">离顶部 60px 时固定,固定后离顶部 10px</div>
</NsAffix>
<p v-for="i in 20" :key="i + 3" class="line">第 {{ i + 3 }} 行内容</p>
</div>
<div id="affix-demo-trigger-bottom" class="box">
<p v-for="i in 10" :key="i" class="line">第 {{ i }} 行内容</p>
<NsAffix
listen-to="#affix-demo-trigger-bottom"
position="bottom"
:trigger-bottom="60"
:bottom="10"
>
<div class="bar">离底部不到 60px 时固定,固定后离底部 10px</div>
</NsAffix>
<p v-for="i in 10" :key="i + 10" class="line">第 {{ i + 10 }} 行内容</p>
</div>
</NsSpace>
</template>
<style scoped>
.box {
width: 260px;
height: 240px;
overflow: auto;
padding: 0 16px;
border: 1px solid var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
.line {
margin: 12px 0;
color: var(--ns-text-color-secondary);
}
.bar {
padding: 8px 12px;
background-color: var(--ns-color-primary);
color: var(--ns-color-white);
border-radius: var(--ns-border-radius);
}
</style>
监听固定状态
固定状态变化时触发 change,参数是现在是否固定。每次重新计算位置时(挂载、滚动、窗口缩放、内容高度变化)触发 scroll,参数里有滚动距离 scrollTop 和是否固定 fixed。
<script setup lang="ts">
import { ref } from 'vue'
import { NsAffix } from '@ns/ui'
const fixed = ref(false)
const scrollTop = ref(0)
const changeCount = ref(0)
const handleChange = (value: boolean) => {
fixed.value = value
changeCount.value += 1
}
const handleScroll = (params: { scrollTop: number; fixed: boolean }) => {
scrollTop.value = params.scrollTop
}
</script>
<template>
<div id="affix-demo-change" class="box">
<p class="line">往下滚动</p>
<NsAffix
listen-to="#affix-demo-change"
:offset="0"
@change="handleChange"
@scroll="handleScroll"
>
<div
:style="{
padding: '12px',
backgroundColor: fixed ? 'var(--ns-color-primary)' : 'var(--ns-bg-color)',
color: fixed ? 'var(--ns-color-white)' : 'var(--ns-text-color)',
border: '1px solid var(--ns-border-color)'
}"
>
{{ fixed ? '已固定' : '未固定' }}
</div>
</NsAffix>
<p v-for="i in 20" :key="i" class="line">第 {{ i }} 行内容</p>
</div>
<p style="margin-top: 12px">
change 触发 {{ changeCount }} 次,当前 {{ fixed ? '已固定' : '未固定' }};scrollTop:{{
scrollTop
}}
</p>
</template>
<style scoped>
.box {
height: 240px;
overflow: auto;
padding: 0 16px;
border: 1px solid var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
.line {
margin: 12px 0;
color: var(--ns-text-color-secondary);
}
</style>
自定义滚动容器
内容在某个可以滚动的元素里时,用 listen-to 指定这个元素,可以传 CSS 选择器、元素,或者返回元素的函数。固定后的位置按这个容器计算:贴在容器顶部往下 offset 像素处,容器在页面里移动时固钉跟着它走。target 的作用和 listen-to 相同,listen-to 没传时才用它。
<script setup lang="ts">
import { NsAffix } from '@ns/ui'
</script>
<template>
<div
id="affix-demo-box"
style="height: 300px; overflow: auto; border: 1px solid var(--ns-border-color)"
>
<div style="height: 80px">上方内容</div>
<NsAffix listen-to="#affix-demo-box" :offset="10">
<div
style="padding: 12px; background-color: var(--ns-color-primary); color: var(--ns-color-white)"
>
滚到容器顶部时固定
</div>
</NsAffix>
<div style="height: 800px">下方内容</div>
</div>
</template>
用 ref 拿容器时,传一个函数:
<script setup lang="ts">
import { ref } from 'vue'
import { NsAffix } from '@ns/ui'
const boxRef = ref<HTMLElement>()
// 写成固定的函数,不要在模板里写箭头函数:每次渲染都是新函数,会让组件重新绑定监听
const getBox = () => boxRef.value!
</script>
<template>
<div ref="boxRef" style="height: 300px; overflow: auto; border: 1px solid var(--ns-border-color)">
<div style="height: 80px">上方内容</div>
<NsAffix :listen-to="getBox" :offset="10">
<div
style="padding: 12px; background-color: var(--ns-color-warning); color: var(--ns-color-white)"
>
固钉内容(listen-to 传函数)
</div>
</NsAffix>
<div style="height: 800px">内容</div>
</div>
</template>
用 target 传选择器,效果和 listen-to 一样:
<template>
<div
id="affix-demo-target"
style="height: 300px; overflow: auto; border: 1px solid var(--ns-border-color)"
>
<div style="height: 80px">上方内容</div>
<NsAffix target="#affix-demo-target" :offset="10">
<div
style="padding: 12px; background-color: var(--ns-color-info); color: var(--ns-color-white)"
>
用 target 指定容器
</div>
</NsAffix>
<div style="height: 800px">下方内容</div>
</div>
</template>
绝对定位
css-position 可选 fixed(默认)和 absolute。默认固定后用 position: fixed,上面的示例都是这种。css-position="absolute" 时改用 position: absolute,top / bottom 是相对最近的定位祖先算的。所以要这样写:最外层放一个 position: relative 的包裹元素,里面放滚动容器(滚动容器自己不要设 position),固钉放在滚动容器里,listen-to 指向滚动容器。这样固定后,固钉相对包裹元素定位,不会跟着内容滚走。
<script setup lang="ts">
import { NsAffix } from '@ns/ui'
</script>
<template>
<div style="position: relative">
<div
id="affix-absolute-box"
style="height: 300px; overflow: auto; border: 1px solid var(--ns-border-color)"
>
<div style="height: 80px">上方内容</div>
<NsAffix css-position="absolute" listen-to="#affix-absolute-box" :top="10" :trigger-top="10">
<div
style="padding: 12px; background-color: var(--ns-color-success); color: var(--ns-color-white)"
>
绝对定位的固钉
</div>
</NsAffix>
<div style="height: 800px">下方内容</div>
</div>
</div>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| position | 'top' | 'bottom' | 'top' | 固定在顶部还是底部 |
| offset | number | 0 | 触发距离和固定位置的默认值(px),top、bottom、triggerTop、triggerBottom 都没写时用它 |
| listenTo | string | HTMLElement | Document | Window | (() => HTMLElement | Document | Window) | - | 监听滚动的容器。字符串按 CSS 选择器查找,函数在挂载时调用。优先于 target。Document 当作 window |
| target | string | HTMLElement | Window | - | 监听滚动的容器,作用和 listenTo 相同,listenTo 没传时才用它。两个都没传时监听页面滚动(window) |
| zIndex | number | 100 | 固定后的层级 |
| cssPosition | 'fixed' | 'absolute' | 'fixed' | 固定后用的 CSS 定位方式。absolute 的用法见上面的示例 |
| top | number | - | 顶部固定后离顶部的距离(px)。不写时依次用 triggerTop、offset |
| bottom | number | - | 底部固定后离底部的距离(px)。不写时依次用 triggerBottom、offset |
| triggerTop | number | - | 离顶部多远时触发顶部固定(px)。不写时依次用 top、offset |
| triggerBottom | number | - | 离底部多远时触发底部固定(px)。不写时依次用 bottom、offset |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| change | (fixed: boolean) | 固定状态变化时触发 |
| scroll | (params: { scrollTop: number; fixed: boolean }) | 每次重新计算位置时触发:挂载时、容器或页面滚动时、窗口缩放时、内容高度变化时 |
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 要固定的内容 |
类型
import type {
AffixProps,
AffixEmits,
AffixPosition,
AffixCssPosition,
AffixListenTo,
AffixTarget
} from '@ns/ui'
type AffixPosition = 'top' | 'bottom'
type AffixCssPosition = 'fixed' | 'absolute'
type AffixListenTo =
| string
| HTMLElement
| Document
| Window
| (() => HTMLElement | Document | Window)
type AffixTarget = string | HTMLElement | Window
interface AffixProps {
position?: AffixPosition
offset?: number
target?: AffixTarget
zIndex?: number
cssPosition?: AffixCssPosition
listenTo?: AffixListenTo
top?: number
bottom?: number
triggerTop?: number
triggerBottom?: number
}
interface AffixEmits {
(e: 'change', fixed: boolean): void
(e: 'scroll', params: { scrollTop: number; fixed: boolean }): void
}
注意事项
- 组件渲染成两层:外层
.ns-affix一直留在原位置,固定时设成内容的高度充当占位;内层.ns-affix__content固定时带上is-fixed类和定位样式。写在NsAffix上的class、style落在外层。 - 固定后的宽度等于外层的宽度,窗口缩放、容器滚动时会重新计算宽度和位置。
- 挂载时如果已经超过触发距离,会立即固定。
- 选择器在挂载时查找,找不到时监听页面滚动。函数形式的
listenTo也是在挂载时调用,这时同一个模板里的 ref 已经可以用了。运行时修改listenTo或target,监听会跟着换。 listenTo和target意思相同,同时传时只用listenTo。- 监听自定义容器时,除了容器的滚动,还会监听页面滚动和窗口缩放,容器本身在页面里移动时固钉也会跟着更新。
cssPosition: 'absolute'必须配合position: relative的外层包裹元素,并且滚动容器自己不能是定位元素,否则固定后会跟着内容一起滚走。- 服务端渲染时不访问
window、document,滚动监听在挂载后才绑定,卸载时自动移除。