onClickOutside

类别

Sensors

导出大小

1.25 kB

最近修改

2 days ago

监听元素外的点击事件。适用于模态框或下拉菜单。

🌐 Listen for clicks outside of an element. Useful for modals or dropdowns.

示例

源代码在线运行

用法

🌐 Usage

<script setup lang="ts">
import { onClickOutside } from '@vueuse/core'
import { useTemplateRef } from 'vue'

const target = useTemplateRef('target')

onClickOutside(target, event => console.log(event))
</script>

<template>
  <div ref="target">
    Hello world
  </div>
  <div>Outside element</div>
</template>

返回值

🌐 Return Value

默认情况下，onClickOutside 会返回一个 stop 函数来移除事件监听器。

🌐 By default, onClickOutside returns a stop function to remove the event listeners.

const stop = onClickOutside(target, handler)

// Later, stop listening
stop()

控制

🌐 Controls

如果你需要对触发处理程序有更多控制，可以使用 controls 选项。这会返回一个包含 stop、cancel 和 trigger 函数的对象。

🌐 If you need more control over triggering the handler, you can use the controls option. This returns an object with stop, cancel, and trigger functions.

const { stop, cancel, trigger } = onClickOutside(
  modalRef,
  (event) => {
    modal.value = false
  },
  { controls: true },
)

// cancel prevents the next click from triggering the handler
cancel()

// trigger manually fires the handler
trigger(event)

// stop removes all event listeners
stop()

忽略元素

🌐 Ignore Elements

使用 ignore 选项可以防止某些元素触发处理器。将元素作为 Refs 或 CSS 选择器的数组提供。

🌐 Use the ignore option to prevent certain elements from triggering the handler. Provide elements as an array of Refs or CSS selectors.

const ignoreElRef = useTemplateRef('ignoreEl')

onClickOutside(
  target,
  event => console.log(event),
  { ignore: [ignoreElRef, '.ignore-class', '#ignore-id'] },
)

捕获阶段

🌐 Capture Phase

默认情况下，事件监听器使用捕获阶段（capture: true）。设置 capture: false 以改用冒泡阶段。

🌐 By default, the event listener uses the capture phase (capture: true). Set capture: false to use the bubbling phase instead.

onClickOutside(target, handler, { capture: false })

检测 iframe 点击

🌐 Detect Iframe Clicks

默认情况下，iframe 内的点击不会被检测到。启用 detectIframe 可以在焦点移动到 iframe 时也触发处理程序。

🌐 Clicks inside an iframe are not detected by default. Enable detectIframe to also trigger the handler when focus moves to an iframe.

onClickOutside(target, handler, { detectIframe: true })

组件用法

🌐 Component Usage

<template>
  <OnClickOutside :options="{ ignore: [/* ... */] }" @trigger="count++">
    <div>
      Click Outside of Me
    </div>
  </OnClickOutside>
</template>

指令用法

🌐 Directive Usage

<script setup lang="ts">
import { vOnClickOutside } from '@vueuse/components'
import { shallowRef } from 'vue'

const modal = shallowRef(false)
function closeModal() {
  modal.value = false
}
</script>

<template>
  <button @click="modal = true">
    Open Modal
  </button>
  <div v-if="modal" v-on-click-outside="closeModal">
    Hello World
  </div>
</template>

还可以将 handler 设置为数组来设置指令的配置项。

🌐 You can also set the handler as an array to set the configuration items of the instruction.

<script setup lang="ts">
import { vOnClickOutside } from '@vueuse/components'
import { shallowRef, useTemplateRef } from 'vue'

const modal = shallowRef(false)

const ignoreElRef = useTemplateRef('ignoreEl')

const onClickOutsideHandler = [
  (ev) => {
    console.log(ev)
    modal.value = false
  },
  { ignore: [ignoreElRef] },
]
</script>

<template>
  <button @click="modal = true">
    Open Modal
  </button>

  <div ref="ignoreElRef">
    click outside ignore element
  </div>

  <div v-if="modal" v-on-click-outside="onClickOutsideHandler">
    Hello World
  </div>
</template>