@yafh/use-tinykeys/dist/index.d.ts

Vue composition API for listen keyboard event.

import { Ref } from 'vue';

/** 键盘事件监听器 */
type KeyboardEventListener = (event: KeyboardEvent) => void | ((event: KeyboardEvent) => Promise<void>);
/**
 * 键盘事件监听目标
 */
type KeyboardTarget = Window | HTMLElement;
/**
 * 键盘事件类型
 */
type KeyboardEventType = 'keydown' | 'keyup' | /** @deprecated */ 'keypress';
/**
 * 键盘事件处理器对象
 */
interface KeyboardEventListenerOption {
    keyup?: KeyboardEventListener;
    keydown?: KeyboardEventListener;
    /** @deprecated */
    keypress?: KeyboardEventListener;
}
/**
 * 键盘事件选项
 */
interface KeyStrokeOption {
    /**
     * 需要监听的DOM元素
     * @default window
     */
    target?: KeyboardTarget;
    /**
     * 键盘事件类型
     * @default 'keydown'
     */
    eventType?: KeyboardEventType | KeyboardEventType[];
    /**
     * 连键超时时间(毫秒)
     * @default 300
     */
    timeout?: number;
    /**
     * 在组件不激活时是否仍然监听键盘事件
     */
    listenOnkeepAlive?: boolean;
    /**
     * 用户自定义的键盘事件控制值。如果传入该值，返回结果中的enable与这个值完全一致
     * - 组件切换激活状态时不会对该值进行修改
     */
    customEnable?: Ref<boolean>;
}
/**
 * 键盘值可选平台
 */
type KeyStrokePlatform = 'windows' | 'mac';
/**
 * 返回内容
 */
interface KeyStrokeResult {
    /** 当前按键事件控制值 */
    enable: Ref<boolean>;
    /** 实例作用域按键事件控制值 */
    enableInstance: Ref<boolean>;
    /** 注销键盘监听事件 */
    clearup: () => void;
}
/**
 * 键盘事件组合式API
 * @param key 键盘值
 * @param handler 键盘事件处理器
 * @param option 键盘事件选项
 *
 * 按键key说明：
 * 1. 'a' - 按下a键
 * 2. 'Control+a' - 按下ctrl+a键
 * 3. 'a b c d' - 依次按下a、b、c、d键
 *
 * 预设键值[点击查看](https://developer.mozilla.org/zh-CN/docs/Web/API/UI_Events/Keyboard_event_key_values#special_values)
 *
 *
 * @example
 * ```ts
 * // 监听单个键盘值
 * const { enable } = useKeyStroke('Control+s', (event) => {
 *  console.log(event)
 * })
 *
 * // 监听多个键盘值
 * const { enable } = useKeyStroke(['Control+s', 'Control+Shift+s'], (event) => {
 *  console.log(event)
 * })
 *
 * // 同时监听多个键盘事件
 * const { enable } = useKeyStroke('Control+s', (event) => {
 *  console.log(event)
 * },{
 *   eventType: ['keydown', 'keyup']
 * })
 *
 * // 分别监听多个键盘事件
 * const { enable } = useKeyStroke('Control+s', {
 *   keydown: (event) => {
 *     console.log(event)
 *   },
 *   keyup: (event) => {
 *     console.log(event)
 *   }
 * })
 *
 * // 针对不同平台监听不同键盘值
 * const { enable } = useKeyStroke({
 *    windows: 'Control+s',
 *    mac: ['Command+s', 'Command+Shift+s']
 *  }, (event) => {
 *    console.log(event)
 *  })
 *
 * // 更换监听目标
 * const { enable } = useKeyStroke('Control+s', (event) => {
 *   console.log(event)
 * }, {
 *   target: document.body
 * })
 *
 * // 组件在销毁时会自动注销键盘监听事件，如果需要手动注销，可以调用clearup方法
 * const { enable, clearup } = useKeyStroke('Control+s', (event) => {
 *  console.log(event)
 * })
 *
 * clearup() // 手动注销
 *
 * // 传入一个已存在的响应式变量控制键盘监听事件
 * const customEnable = ref(true)
 * const { enable } = useKeyStroke('Control+s', (event) => {
 *   console.log(event)
 * }, {
 *   customEnable
 * })
 * enable === customEnable // true
 *
 *
 * ```
 *
 * @returns enable：当前按键事件控制值 enableInstance：实例作用域按键事件控制值
 */
declare function useKeyStroke(key: string | string[] | Partial<Record<KeyStrokePlatform, string | string[]>>, handler: KeyboardEventListener | KeyboardEventListenerOption, option?: KeyStrokeOption): KeyStrokeResult;
/**
 * 包装键盘事件处理器，与keybinding进行匹配
 * @param handler 键盘事件处理器
 * @param key 键盘按键
 * @param timeout 连键超时时间
 * @returns
 */
declare function wrapKeyBindingHandler(handler: KeyboardEventListener, key: string[], timeout?: number): EventListener;

export { KeyStrokeOption, KeyStrokePlatform, KeyboardEventListener, KeyboardEventListenerOption, KeyboardEventType, KeyboardTarget, useKeyStroke, wrapKeyBindingHandler };