60 lines
2.4 KiB
Markdown
60 lines
2.4 KiB
Markdown
|
---
|
|||
|
|
name: arco-vue-affix
|
|||
|
|
description: "Arco Design Vue 固钉 Affix 组件参考。用于 Vue 3、`@arco-design/web-vue`、`<a-affix>`、属性、事件、插槽、示例和实现细节。"
|
|||
|
|
user-invocable: false
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 固钉 Affix
|
|||
|
|
|
|||
|
|
## 简介
|
|||
|
|
|
|||
|
|
基本用法，不设置固定位置时，当页面滚动元素不可见时，元素固定在页面最顶部。
|
|||
|
|
|
|||
|
|
## 基本用法
|
|||
|
|
|
|||
|
|
```vue
|
|||
|
|
<template>
|
|||
|
|
<a-affix>
|
|||
|
|
<a-button type="primary">Affix Top</a-button>
|
|||
|
|
</a-affix>
|
|||
|
|
</template>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## API
|
|||
|
|
|
|||
|
|
### `<affix>` 属性
|
|||
|
|
|
|||
|
|
|参数名|描述|类型|默认值|
|
|||
|
|
|---|---|---|:---:|
|
|||
|
|
|offset-top|距离窗口顶部达到指定偏移量后触发|`number`|`0`|
|
|||
|
|
|offset-bottom|距离窗口底部达到指定偏移量后触发|`number`|`-`|
|
|||
|
|
|target|滚动容器，默认是 `window`|`string \| HTMLElement \| Window`|`-`|
|
|||
|
|
|target-container|`target`的外层滚动元素，默认是 `window`。`Affix `将会监听该元素的滚动事件，并实时更新固钉的位置。主要是为了解决 `target` 属性指定为非 `window` 元素时，如果外层元素滚动，可能会导致固钉跑出容器问题|`string \| HTMLElement \| Window`|`-`|
|
|||
|
|
|
|||
|
|
### `<affix>` 事件
|
|||
|
|
|
|||
|
|
|事件名|描述|参数|
|
|||
|
|
|---|---|---|
|
|||
|
|
|change|固定状态发生改变时触发|fixed: `boolean`|
|
|||
|
|
|
|||
|
|
### `<affix>` 方法
|
|||
|
|
|
|||
|
|
|方法名|描述|参数|返回值|
|
|||
|
|
|---|---|---|---|
|
|||
|
|
|updatePosition|更新位置|-|-|
|
|||
|
|
|
|||
|
|
## 常用模式
|
|||
|
|
|
|||
|
|
- **顶部固定**：当页面滚动或浏览器窗口改变时，元素向上滚动到距顶部一定距离时固定。
|
|||
|
|
- **底部固定**：当页面滚动或浏览器窗口改变时，元素向下滚动到距底部一定距离时固定。
|
|||
|
|
- **固定状态改变回调**：当固定状态发生改变时，会触发事件。
|
|||
|
|
- **滚动容器**：用 `target` 设置需要监听其滚动事件的元素，默认为 window。`target` 指定为非 window 容器时，可能会出现 `target`外层元素滚动，固钉元素跑出滚动容器的问题。这个时候可以通过传入`targetContainer`传入`target`外层的滚动元素。
|
|||
|
|
|
|||
|
|
## 最佳实践
|
|||
|
|
|
|||
|
|
- 新代码优先使用 Vue 3、Composition API 和 `<script setup lang="ts">`。
|
|||
|
|
- 模板属性使用 kebab-case，事件使用 `@event-name`，插槽使用 `#slot-name`。
|
|||
|
|
- 不要套用 React 专属 API，例如 JSX children、`Component.Sub` 或 `Form.useForm`。
|
|||
|
|
- 底层能力组件优先服务明确场景，避免为了样式效果直接暴露复杂配置。
|
|||
|
|
- 涉及滚动、弹层和 DOM 容器时，先确认挂载容器和边界行为。
|