# exposure-vue

**Repository Path**: wyzhgx/exposure-vue

## Basic Information

- **Project Name**: exposure-vue
- **Description**: 插件基于Intersection Observer API实现，适用于SPA应用、广告统计及懒加载场景。提供元素曝光检测、滚动监听、比例计算功能，支持多阈值触发、根元素限定、边距调节等配置，具备自动实例管理和内存回收机制。支持Vue2/Vue3项目指令式集成，适用于电商大屏、长列表渲染等需要精准监测元素可见性的业务场景，有效降低性能消耗，确保高精度曝光事件追踪。
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-16
- **Last Updated**: 2025-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# exposure-vue

## 介绍

插件基于 Intersection Observer API 实现，适用于 SPA 应用中广告统计及懒加载场景。提供元素曝光检测，支持多阈值触发、根元素限定、边距调节、展示时长限制等配置，具备自动实例管理和内存回收机制。支持 Vue2/Vue3 项目指令式集成，适用于电商大屏、长列表渲染等需要精准监测元素可见性的业务场景，有效降低性能消耗，确保高精度曝光事件追踪。

## 安装教程

```javascript
npm install exposure-vue
```

## 使用说明

### 属性说明

1. 原生属性（root、rootMargin、threshold）

   - root：用作视口的元素，用于检查目标的可见性。必须是观察目标的祖先。如果未指定或为 null，则默认为浏览器视口。
   - rootMargin：根周围的边距。其值可以类似于 CSS margin 属性，例如 "10px 20px 30px 40px"（上、右、下、左）。这些值可以是百分比。在计算交叉点之前，这组值用于增大或缩小根元素边框的每一侧。默认值为全零。
   - threshold：一个数字或一个数字数组，表示观察目标可见度达到多少百分比时，观察器的回调就应该执行。

2. 自定义属性（once、exposureThreshold、callback）

   - once：是否只触发一次，默认值为 false；当观察目标可见度第一次达到阈值时会触发回调，然后直接取消对该观察目标的监听
   - exposureThreshold：曝光时长阈值，单位为毫秒，用来指定观察目标可见度达到触发阈值标准，且持续时间需满足该字段配置的时长，默认值为 0，即观察目标可见度达到触发阈值就触发回调函数
   - callback：回调函数，用来指定观察目标可见度达到触发阈值时触发的回调函数，默认值为 null，即不触发回调函数

     1. callback 接收两个参数：visible（一个布尔值，用于确定观察目标与指定视口区域是否交叉）、entry（一个描述观察目标与指定视口区域的交叉状态的对象）

### 使用须知

1. Intersection Observer API 原有可配置属性 threshold 支持配置阈值列表，callback 将在目标可见度达到不同阈值时触发；这种场景下 exposureThreshold 配置可能导致触发时机与预期不一致
2. 插件会自动实例化 Intersection Observer API；对每个观察目标的监听，实例都会在其销毁时取消；必要时可以调用 this.$Exposure.disconnect() 取消当前所有观察目标的监听

### 使用示例

```javascript
import { createApp } from "vue";
import App from "./App.vue";
import exposureVue from "exposure-vue";

const app = createApp(App);
// 无自定义配置
// app.use(exposureVue)

// 有自定义配置
// Intersection Observer API
app.use(exposureVue, {
	root: document.body,
	rootMargin: "0px",
	threshold: 0.5,
	once: true,
	exposureThreshold: 300,
});
app.mount("#app");
```

```javascript
<template>
	<div v-exposure></div>
	<div v-exposure.once></div>
	<div v-exposure="callback"></div>
	<div v-exposure.once="callback"></div>
	<div v-exposure="{once:true,callback:callback,exposureThreshold:300}"></div>
</template>
<script setup>
  const callback = (visible, observe)=>{
    if(visible){
      console.log('曝光了')
    }else{
      console.log('隐藏了')
    }
  }
</script>
```