---
title: "useScriptTriggerElement()"
description: "响应元素事件或可见性变化加载脚本。"
canonical_url: "https://nuxt-scripts.zhcndoc.com/docs/api/use-script-trigger-element"
last_updated: "2026-08-11T09:33:15.317Z"
---

当元素变为可见或接收到配置的事件之一时加载脚本。

## 签名

```ts
function useScriptTriggerElement(options: ElementScriptTriggerOptions): (Promise<boolean> & { ssrAttrs?: Record<string, string> }) | 'onNuxtReady'
```

## 参数

```ts
export interface ElementScriptTriggerOptions {
  /**
   * 触发脚本加载的事件。
   *
   * 接受与 addEventListener 一起使用的事件名称，例如 `mousedown`、`mouseenter` 和 `scroll`。
   * `visible` 和 `visibility` 则使用 IntersectionObserver。
   */
  trigger?: 'immediate' | 'visible' | string | string[] | false | undefined
  /**
   * 用于监听触发事件的元素。
   * 事件触发器默认为 document.body。可见性触发器需要指定元素。
   */
  el?: MaybeComputedElementRef<MaybeElement>
}
```

## 返回值

当配置的元素事件或可见性条件发生时，promise 将解析。随后，`useScript()` 开始加载脚本。省略触发器、`false`、`'immediate'` 或 `'onNuxtReady'` 触发器会返回 `'onNuxtReady'` 哨兵值。

如果所属的 Vue 作用域在事件发生前被释放，promise 将解析为 `false`；`useScript()` 不会加载脚本。

可见性触发器使用阈值为 `0`、`rootMargin: '30px 0px 0px 0px'` 的 `IntersectionObserver`。当元素与调整后的根相交时，promise 将解析；该根在元素顶部边缘之外额外包含 30 个像素。

## 处理预水合事件

用户可以在水合为元素附加事件监听器之前与该元素交互。将 `ssrAttrs` 绑定到该元素，以便水合前的事件（例如 `mousedown`）仍能启动脚本。在读取 `ssrAttrs` 之前，检查触发器是否返回了一个 promise。

```vue
<script setup lang="ts">
import { ref, useScriptTriggerElement } from '#imports'

const el = ref<HTMLElement>()
const trigger = useScriptTriggerElement({
  trigger: 'mousedown',
  el,
})

const elAttrs = computed(() => {
  return {
    ...(trigger instanceof Promise ? trigger.ssrAttrs : {}),
  }
})
</script>

<template>
  <div ref="el" v-bind="elAttrs">
    点击我以加载脚本
  </div>
</template>
```

## 示例

### 当元素变为可见时

```vue
<script setup lang="ts">
const el = ref<HTMLElement>()
useScript('/script.js', {
  trigger: useScriptTriggerElement({
    trigger: 'visible',
    el,
  })
})
</script>

<template>
  <div style="height: 100vh;">
    <h1>向下滚动以加载脚本</h1>
  </div>
  <div ref="el">
    <h1>脚本已加载！</h1>
  </div>
</template>
```

### 悬停时

```vue
<script setup lang="ts">
const el = ref<HTMLElement>()
useScript('/script.js', {
  trigger: useScriptTriggerElement({
    trigger: 'mouseenter',
    el,
  })
})
</script>

<template>
  <div ref="el">
    <h1>将鼠标悬停在此处以加载脚本</h1>
  </div>
</template>
```