feat(useClipboardItems): new function (#3477)

Doctor-wu · antfu · web-flow · commit 1aa50f825a24 · 2023-11-09T17:08:59.000Z
Co-authored-by: Anthony Fu &lt;anthonyfu117@hotmail.com&gt;
diff --git a/packages/core/index.ts b/packages/core/index.ts
@@ -21,6 +21,7 @@ export * from './useBroadcastChannel'
 export * from './useBrowserLocation'
 export * from './useCached'
 export * from './useClipboard'
+export * from './useClipboardItems'
 export * from './useCloned'
 export * from './useColorMode'
 export * from './useConfirmDialog'
diff --git a/packages/core/useClipboardItems/demo.vue b/packages/core/useClipboardItems/demo.vue
@@ -0,0 +1,51 @@
+<script setup lang="ts">
+import { effect, ref } from 'vue'
+import { useClipboardItems, usePermission } from '@vueuse/core'
+
+const input = ref('')
+
+const { content, isSupported, copy } = useClipboardItems()
+const computedText = ref('')
+effect(() => {
+  Promise.all(content.value.map(item => item.getType('text/html')))
+    .then((blobs) => {
+      return Promise.all(blobs.map(blob => blob.text()))
+    })
+    .then((texts) => {
+      computedText.value = texts.join('')
+    })
+})
+const permissionRead = usePermission('clipboard-read')
+const permissionWrite = usePermission('clipboard-write')
+
+function createClipboardItems(text: string) {
+  const mime = 'text/html'
+  const blob = new Blob([text], { type: mime })
+  return new ClipboardItem({
+    [mime]: blob,
+  })
+}
+</script>
+
+<template>
+  <div v-if="isSupported">
+    <note>
+      Clipboard Permission: read <b>{{ permissionRead }}</b> | write
+      <b>{{ permissionWrite }}</b>
+    </note>
+    <p>
+      Current copied: <code>{{ (computedText && `${computedText} (mime: text/html)`) || "none" }}</code>
+    </p>
+    <input v-model="input" type="text">
+    <button
+      @click="
+        copy([createClipboardItems(input)])
+      "
+    >
+      Copy
+    </button>
+  </div>
+  <p v-else>
+    Your browser does not support Clipboard API
+  </p>
+</template>
diff --git a/packages/core/useClipboardItems/index.md b/packages/core/useClipboardItems/index.md
@@ -0,0 +1,44 @@
+---
+category: Browser
+related:
+  - useClipboard
+---
+
+# useClipboardItems
+
+Reactive [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API). Provides the ability to respond to clipboard commands (cut, copy, and paste) as well as to asynchronously read from and write to the system clipboard. Access to the contents of the clipboard is gated behind the [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API). Without user permission, reading or altering the clipboard contents is not permitted.
+
+## Difference from `useClipboard`
+
+`useClipboard` is a "text-only" function, while `useClipboardItems` is a [ClipboardItem](https://developer.mozilla.org/en-US/docs/Web/API/ClipboardItem) based function. You can use `useClipboardItems` to copy any content supported by [ClipboardItem](https://developer.mozilla.org/en-US/docs/Web/API/ClipboardItem).
+
+## Usage
+
+```js
+import { useClipboardItems } from '@vueuse/core'
+
+const mime = 'text/html'
+const source = ref([
+  new ClipboardItem({
+    [mime]: new Blob(['\'<b>HTML content</b>\'', { type: mime }]),
+  })
+])
+
+const { content, copy, copied, isSupported } = useClipboardItems({ source })
+```
+
+```html
+<div v-if="isSupported">
+  <button @click='copy(source)'>
+    <!-- by default, `copied` will be reset in 1.5s -->
+    <span v-if='!copied'>Copy</span>
+    <span v-else>Copied!</span>
+  </button>
+  <p>
+    Current copied: <code>{{ text || 'none' }}</code>
+  </p>
+</div>
+<p v-else>
+  Your browser does not support Clipboard API
+</p>
+```
diff --git a/packages/core/useClipboardItems/index.ts b/packages/core/useClipboardItems/index.ts
@@ -0,0 +1,86 @@
+import type { MaybeRefOrGetter } from '@vueuse/shared'
+import { toValue, useTimeoutFn } from '@vueuse/shared'
+import type { ComputedRef, Ref } from 'vue-demi'
+import { ref } from 'vue-demi'
+import { useEventListener } from '../useEventListener'
+import { useSupported } from '../useSupported'
+import type { ConfigurableNavigator } from '../_configurable'
+import { defaultNavigator } from '../_configurable'
+
+export interface UseClipboardItemsOptions<Source> extends ConfigurableNavigator {
+  /**
+   * Enabled reading for clipboard
+   *
+   * @default false
+   */
+  read?: boolean
+
+  /**
+   * Copy source
+   */
+  source?: Source
+
+  /**
+   * Milliseconds to reset state of `copied` ref
+   *
+   * @default 1500
+   */
+  copiedDuring?: number
+}
+
+export interface UseClipboardItemsReturn<Optional> {
+  isSupported: Ref<boolean>
+  content: ComputedRef<ClipboardItems>
+  copied: ComputedRef<boolean>
+  copy: Optional extends true ? (content?: ClipboardItems) => Promise<void> : (text: ClipboardItems) => Promise<void>
+}
+
+/**
+ * Reactive Clipboard API.
+ *
+ * @see https://vueuse.org/useClipboardItems
+ * @param options
+ */
+export function useClipboardItems(options?: UseClipboardItemsOptions<undefined>): UseClipboardItemsReturn<false>
+export function useClipboardItems(options: UseClipboardItemsOptions<MaybeRefOrGetter<ClipboardItems>>): UseClipboardItemsReturn<true>
+export function useClipboardItems(options: UseClipboardItemsOptions<MaybeRefOrGetter<ClipboardItems> | undefined> = {}): UseClipboardItemsReturn<boolean> {
+  const {
+    navigator = defaultNavigator,
+    read = false,
+    source,
+    copiedDuring = 1500,
+  } = options
+
+  const isSupported = useSupported(() => (navigator && 'clipboard' in navigator))
+  const content = ref<ClipboardItems>([])
+  const copied = ref(false)
+  const timeout = useTimeoutFn(() => copied.value = false, copiedDuring)
+
+  function updateContent() {
+    if (isSupported.value) {
+      navigator!.clipboard.read().then((items) => {
+        content.value = items
+      })
+    }
+  }
+
+  if (isSupported.value && read)
+    useEventListener(['copy', 'cut'], updateContent)
+
+  async function copy(value = toValue(source)) {
+    if (isSupported.value && value != null) {
+      await navigator!.clipboard.write(value)
+
+      content.value = value
+      copied.value = true
+      timeout.start()
+    }
+  }
+
+  return {
+    isSupported,
+    content: content as ComputedRef<ClipboardItems>,
+    copied: copied as ComputedRef<boolean>,
+    copy,
+  }
+}
