tiny-essentials
Version:
Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.
155 lines • 7.05 kB
text/typescript
export default TinyClipboard;
/**
* Utility class to handle clipboard operations for text and blob data.
* Supports modern Clipboard API, custom platform, and legacy execCommand fallback.
*/
declare class TinyClipboard {
/**
* Override the default text copy behavior.
* This allows you to provide your own clipboard implementation or
* integrate with external systems like Capacitor or Electron.
*
* @param {(text: string) => Promise<void>} callback - The function to use for copying text.
* @throws {TypeError} If the callback is not a function.
*/
setCopyText(callback: (text: string) => Promise<void>): void;
/**
* Override the default blob copy behavior.
* This allows you to provide a custom clipboard handling method for blob data.
*
* @param {(blob: Blob) => Promise<void>} callback - The function to use for copying blob data.
* @throws {TypeError} If the callback is not a function.
*/
setCopyBlob(callback: (blob: Blob) => Promise<void>): void;
/**
* Copy a plain text string to the clipboard.
* Uses modern or legacy fallback.
*
* @param {string} text - The text string to be copied.
* @returns {Promise<void>} A promise resolving when the text is copied or boolean for legacy.
*/
copyText(text: string): Promise<void>;
/**
* Copy a Blob (binary data) to the clipboard.
*
* @param {Blob} blob - The blob object to copy.
* @returns {Promise<void>} A promise that resolves when the blob is copied or null on fallback.
*/
copyBlob(blob: Blob): Promise<void>;
/**
* Internal: Handle getting blob data from a clipboard item.
*
* @private
* @param {string} type - The MIME type to fetch.
* @param {ClipboardItem} clipboardItem - Clipboard item instance.
* @returns {Promise<Blob>} A promise that resolves with the Blob.
*/
private _handleBlob;
/**
* Internal: Handle getting plain text from a clipboard item.
*
* @private
* @param {string} type - The MIME type (should be 'text/plain').
* @param {ClipboardItem} clipboardItem - Clipboard item instance.
* @returns {Promise<string>} A promise that resolves with the text content.
*/
private _handleText;
/**
* Read clipboard data based on filters like type, mime, index.
*
* @param {number|null} [index=0] - Item index or null for all.
* @param {'text'|'custom'|null} [type=null] - Data type to filter.
* @param {string|null} [mimeFormat=null] - MIME type or prefix.
* @param {boolean} [fixValue=false] - If true, exact match on MIME type.
* @returns {Promise<Blob|string|Array<Blob|string>|null>} A promise resolving with matching data.
*/
_readData(index?: number | null, type?: "text" | "custom" | null, mimeFormat?: string | null, fixValue?: boolean): Promise<Blob | string | Array<Blob | string> | null>;
/**
* Read plain text from the clipboard (single item by index).
*
* @param {number} [index=0] - The index of the clipboard item to read.
* @returns {Promise<string|null>} A promise that resolves to the clipboard text or null.
*/
readText(index?: number): Promise<string | null>;
/**
* Read custom clipboard data based on MIME type from a specific index.
*
* @param {string|null} [mimeFormat=null] - MIME prefix to match (e.g., "image/").
* @param {boolean} [fixValue=false] - If true, matches exact MIME instead of prefix.
* @param {number} [index=0] - Clipboard item index.
* @returns {Promise<Blob|null>} A promise resolving with a blob or null.
*/
readCustom(mimeFormat?: string | null, fixValue?: boolean, index?: number): Promise<Blob | null>;
/**
* Read all available plain text entries from the clipboard.
*
* @returns {Promise<string[]>} A promise resolving to an array of strings or null.
*/
readAllTexts(): Promise<string[]>;
/**
* Read all clipboard data matching a specific custom MIME type.
*
* @param {string|null} [mimeFormat=null] - MIME prefix or exact type.
* @param {boolean} [fixValue=false] - Match prefix or exact MIME.
* @returns {Promise<Blob[]>} A promise resolving with array of Blobs or null.
*/
readAllCustom(mimeFormat?: string | null, fixValue?: boolean): Promise<Blob[]>;
/**
* Read all clipboard data as Blob or text depending on type.
*
* @param {'text'|'custom'|null} [type=null] - The type of data to retrieve.
* @param {string|null} [mimeFormat=null] - The MIME type or prefix to match.
* @returns {Promise<Array<Blob|string>>} A promise resolving with matching data array.
*/
readAllData(type?: "text" | "custom" | null, mimeFormat?: string | null): Promise<Array<Blob | string>>;
/**
* Read clipboard data at a specific index or all if null.
*
* @param {number|null} index - Index of the item to retrieve or null to get all.
* @returns {Promise<ClipboardItem|ClipboardItems|null>} A promise resolving with a clipboard item or array of items.
*/
_read(index: number | null): Promise<ClipboardItem | ClipboardItems | null>;
/**
* Read clipboard data at a specific index.
*
* @param {number} index - Index of the item to retrieve
* @returns {Promise<ClipboardItem|null>} A promise resolving with a clipboard item.
*/
readIndex(index: number): Promise<ClipboardItem | null>;
/**
* Read all clipboard content without any filters.
*
* @returns {Promise<ClipboardItems>} A promise resolving with all clipboard items.
*/
readAll(): Promise<ClipboardItems>;
/**
* Returns whether the legacy `document.execCommand()` API is available.
* This can be used to determine if a fallback clipboard method is usable.
*
* @returns {boolean} True if `document.execCommand` is available.
*/
isExecCommandAvailable(): boolean;
/**
* Returns whether the modern Clipboard API (`navigator.clipboard`) is available.
* Useful to know if full clipboard features can be accessed.
*
* @returns {boolean} True if `navigator.clipboard` is available.
*/
isNavigatorClipboardAvailable(): boolean;
/**
* Returns the function used to copy plain text to the clipboard.
* This function may be built-in or set manually via `setCopyText`.
*
* @returns {((text: string) => Promise<void>) | null} The current text copy function or null if unavailable.
*/
getCopyTextFunc(): ((text: string) => Promise<void>) | null;
/**
* Returns the function used to copy Blob (binary data) to the clipboard.
* This function may be built-in or set manually via `setCopyBlob`.
*
* @returns {((blob: Blob) => Promise<void>) | null} The current blob copy function or null if unavailable.
*/
getCopyBlobFunc(): ((blob: Blob) => Promise<void>) | null;
#private;
}
//# sourceMappingURL=TinyClipboard.d.mts.map