feat(useElementOverflow): new function

vueuse · inside5545 · Jul 11, 2024 · Jul 11, 2024 · Jul 23, 2024 · Jul 23, 2024
commit ba3143c6db01c86cdaaed26b6757414cdad8050d
diff --git a/packages/components/index.ts b/packages/components/index.ts
@@ -17,6 +17,8 @@ export * from '../core/useDocumentVisibility/component'
 export * from '../core/useDraggable/component'
 export * from '../core/useElementBounding/component'
 export * from '../core/useElementHover/directive'
+export * from '../core/useElementOverflow/component'
+export * from '../core/useElementOverflow/directive'
 export * from '../core/useElementSize/component'
 export * from '../core/useElementSize/directive'
 export * from '../core/useElementVisibility/component'

diff --git a/packages/core/index.ts b/packages/core/index.ts
@@ -41,6 +41,7 @@ export * from './useDropZone'
 export * from './useElementBounding'
 export * from './useElementByPoint'
 export * from './useElementHover'
+export * from './useElementOverflow'
 export * from './useElementSize'
 export * from './useElementVisibility'
 export * from './useEventBus'

diff --git a/packages/core/useElementOverflow/component.ts b/packages/core/useElementOverflow/component.ts
@@ -0,0 +1,19 @@
+import { defineComponent, h, reactive, ref } from 'vue-demi'
+import { type RenderableComponent, type UseElementOverflowOptions, useElementOverflow } from '@vueuse/core'
+
+export const UseElementOverflow = /* #__PURE__ */ defineComponent<UseElementOverflowOptions & RenderableComponent>({
+  name: 'UseElementOverflow',
+  props: ['observeMutation', 'as'] as unknown as undefined,
+  emits: ['update'],
+  setup(props, { slots, attrs, emit }) {
+    const target = ref()
+    const info = reactive(useElementOverflow(target, {
+      observeMutation: props.observeMutation,
+      onUpdated: (...args: any[]) => { emit('update', ...args) },
+    }))
+    return () => {
+      if (slots.default)
+        return h(props.as || 'div', { ref: target, ...attrs }, slots.default(info))
+    }
+  },
+})
diff --git a/packages/core/useElementOverflow/demo.vue b/packages/core/useElementOverflow/demo.vue
@@ -0,0 +1,28 @@
+<script setup lang="ts">
+import { ref } from 'vue-demi'
+import { useElementOverflow } from './index'
+
+const overflowRef = ref()
+const { isXOverflowed } = useElementOverflow(overflowRef, { observeMutation: true })
+const input = ref('some words here')
+const width = ref(200)
+</script>
+
+<template>
+  <div>
+    <div>content:</div>
+    <input v-model="input" type="text">
+    <div>width:</div>
+    <input v-model.number="width" type="range" min="0" step="1" max="200">
+    <div>display:</div>
+    <div ref="overflowRef" :style="`width: ${width}px;overflow: hidden;text-overflow: ellipsis;white-space: nowrap;`">
+      <b>{{ input }}</b>
+    </div>
+    <br>
+    <div>
+      isOverflowed: <boolean-display :value="isXOverflowed">
+        {{ isXOverflowed }}
+      </boolean-display>
+    </div>
+  </div>
+</template>
diff --git a/packages/core/useElementOverflow/directive.ts b/packages/core/useElementOverflow/directive.ts
@@ -0,0 +1,19 @@
+import { watch } from 'vue-demi'
+import { directiveHooks } from '@vueuse/shared'
+import type { ObjectDirective } from 'vue-demi'
+import { type UseElementOverflowOptions, type UseElementOverflowReturn, useElementOverflow } from '.'
+
+type VElementOverflowHandler = (info: UseElementOverflowReturn) => void
+
+export const vElementOverflow: ObjectDirective<
+  HTMLElement,
+  VElementOverflowHandler | [VElementOverflowHandler, UseElementOverflowOptions]
+> = {
+  [directiveHooks.mounted](el, binding) {
+    const bindingValue = typeof binding.value === 'function' ? [binding.value] as [VElementOverflowHandler] : binding.value
+    const [handler, options] = bindingValue
+    const info = useElementOverflow(el, options)
+    const { isXOverflowed, isYOverflowed } = info
+    watch([isXOverflowed, isYOverflowed], () => handler(info), { immediate: true })
+  },
+}
diff --git a/packages/core/useElementOverflow/index.md b/packages/core/useElementOverflow/index.md
@@ -0,0 +1,77 @@
+---
+category: Elements
+---
+
+# useElementOverflow
+
+Reactive element's overflow state.
+
+## Usage
+
+```vue
+<script>
+import { ref } from 'vue'
+import { useElementOverflow } from '@vueuse/core'
+
+export default {
+  setup() {
+    const el = ref()
+    const { isXOverflowed } = useElementOverflow(el)
+    return {
+      isXOverflowed
+    }
+  },
+}
+</script>
+
+<template>
+  <div ref="el" style="width: 100px;overflow: hidden;">
+    <button v-if="isXOverflowed">
+      show more
+    </button>
+    <span v-else>some words may be too long to show here</span>
+  </div>
+</template>
+```
+
+## Component Usage
+
+```vue
+<template>
+  <UseElementOverflow v-slot="{ isXOverflowed }" style="width: 100px;overflow: hidden;">
+    <button v-if="isXOverflowed">
+      show more
+    </button>
+    <span v-else>some words may be too long to show here</span>
+  </UseElementOverflow>
+</template>
+```
+
+## Directive Usage
+
+```vue
+<script>
+import { ref } from 'vue'
+
+export default {
+  setup() {
+    const isXOverflowed = ref(false)
+    function onXOverflowChanged(info) {
+      isXOverflowed.value = info.isXOverflowed
+    }
+    return {
+      isXOverflowed
+    }
+  },
+}
+</script>
+
+<template>
+  <div v-element-overflow="onXOverflowChanged" style="width: 100px;overflow: hidden;">
+    <button v-if="isXOverflowed">
+      show more
+    </button>
+    <span v-else>some words may be too long to show here</span>
+  </div>
+</template>
+```
diff --git a/packages/core/useElementOverflow/index.ts b/packages/core/useElementOverflow/index.ts
@@ -0,0 +1,80 @@
+import { effectScope, ref } from 'vue-demi'
+import {
+  tryOnMounted,
+  tryOnUnmounted,
+} from '@vueuse/shared'
+import type { ConfigurableWindow } from '@vueuse/core/_configurable'
+import { type MaybeComputedElementRef, unrefElement } from '../unrefElement'
+import type { ResizeObserverCallback } from '../useResizeObserver'
+import { useMutationObserver } from '../useMutationObserver'
+import { useResizeObserver } from '../useResizeObserver'
+import { defaultWindow } from '../_configurable'
+
+export interface UseElementOverflowOptions extends ConfigurableWindow {
+  observeMutation?: boolean | MutationObserverInit
+  onUpdated?: ResizeObserverCallback | MutationCallback
+}
+
+export function useElementOverflow(target: MaybeComputedElementRef, option: UseElementOverflowOptions = {}) {
+  const { observeMutation, onUpdated, window = defaultWindow } = option
+  const isXOverflowed = ref(false)
+  const isYOverflowed = ref(false)
+
+  const scope = effectScope()
+
+  function update(htmlEl: HTMLElement) {
+    isXOverflowed.value = htmlEl.scrollWidth > htmlEl.offsetWidth
+    isYOverflowed.value = htmlEl.scrollHeight > htmlEl.offsetHeight
+  }
+
+  function stop() {
+    scope.stop()
+  }
+
+  tryOnMounted(() => {
+    const el = unrefElement(target)
+    if (!el || el instanceof SVGElement || !window) {
+      return
+    }
+    scope.run(() => {
+      if (!el || el instanceof SVGElement) {
+        return
+      }
+      const childEls = Array.from(el.children).filter(i => i instanceof HTMLElement)
+      useResizeObserver([el, ...childEls], (entries, observer) => {
+        update(el);
+        (onUpdated as ResizeObserverCallback)?.(entries, observer)
+      })
+      if (observeMutation) {
+        useMutationObserver(
+          [el, ...childEls],
+          (entries, observer) => {
+            update(el);
+            (onUpdated as MutationCallback)?.(entries, observer)
+          },
+          observeMutation === true
+            ? {
+                childList: true,
+                subtree: true,
+                characterData: true,
+              }
+            : observeMutation,
+        )
+      }
+    })
+  })
+  tryOnUnmounted(stop)
+  return {
+    isXOverflowed,
+    isYOverflowed,
+    stop,
+    update: () => {
+      const el = unrefElement(target)
+      if (el instanceof HTMLElement && window) {
+        update(el)
+      }
+    },
+  }
+}
+
+export type UseElementOverflowReturn = ReturnType<typeof useElementOverflow>