@tanzhenxing/zx-affix NPM

zx-affix 固钉组件

将页面元素固定在特定可视区域，参考 Element Plus Affix 组件优化实现。

特性

🎯 支持顶部和底部固定
📦 可指定容器范围
🎨 平滑的过渡动画
📱 响应式支持
🔧 完整的 API 接口
💪 TypeScript 友好

基础用法

<template>
  <zx-affix :offset="120">
    <button>固定按钮</button>
  </zx-affix>
</template>

指定容器

<template>
  <view class="container" id="myContainer">
    <zx-affix target="#myContainer" :offset="80">
      <button>容器固钉</button>
    </zx-affix>
  </view>
</template>

底部固定

<template>
  <zx-affix position="bottom" :offset="20">
    <button>底部固定</button>
  </zx-affix>
</template>

API

Props

参数	说明	类型	默认值
offset	偏移距离	`number`	0
position	固钉位置	`'top' \\| 'bottom'`	'top'
target	指定容器（CSS 选择器）	`string`	''
zIndex	层级	`number`	100
customClass	自定义类名	`string`	''

Events

事件名	说明	回调参数
change	固钉状态改变时触发	`(fixed: boolean) => void`
scroll	滚动时触发	`(info: ScrollInfo) => void`

Methods

通过 ref 可以调用以下方法：

方法名	说明	参数
update	手动更新固钉状态	-
updateRoot	手动更新根元素的盒模型信息	-

ScrollInfo

interface ScrollInfo {
  scrollTop: number;  // 滚动距离
  fixed: boolean;     // 是否固定
  rect: DOMRect;      // 元素位置信息
}

示例

完整示例

<template>
  <view class="demo">
    <!-- 基础用法 -->
    <zx-affix 
      :offset="120" 
      @change="handleChange"
      @scroll="handleScroll"
    >
      <view class="affix-button">
        固定按钮
      </view>
    </zx-affix>

    <!-- 指定容器 -->
    <view class="container" id="container">
      <zx-affix target="#container" :offset="80">
        <view class="affix-button">
          容器固钉
        </view>
      </zx-affix>
    </view>

    <!-- 底部固定 -->
    <zx-affix position="bottom" :offset="20">
      <view class="affix-button">
        底部固定
      </view>
    </zx-affix>
  </view>
</template>

<script setup>
const handleChange = (fixed) => {
  console.log('固钉状态:', fixed);
};

const handleScroll = (info) => {
  console.log('滚动信息:', info);
};
</script>

<style>
.affix-button {
  padding: 12px 24px;
  background: #409eff;
  color: white;
  border-radius: 4px;
  text-align: center;
}

.container {
  height: 400px;
  background: #f5f5f5;
  position: relative;
  overflow: hidden;
}
</style>