@morehook/core/index.d.ts

关于vue的一些hooks，兼容vue2+vue3

import * as vue_demi from 'vue-demi';
import { Ref } from 'vue-demi';

/**
 * toggle: 快捷切换正反值
 * setTrue: 切换值为 true
 * setFalse: 切换值为 false
 */
interface Actions$4 {
    toggle: () => void;
    setTrue: () => void;
    setFalse: () => void;
}
/**
 * 优雅的管理 boolean 值
 * @param value 初始值 (默认为false)
 * @returns 返回数组，[0] 是返回值，[1]是各个操作方法
 */
declare function useBoolean(value?: boolean): [Ref<boolean>, Actions$4];

/**
 * watch: 是否监听返回值来更改 cookie 的值(默认 false)
 * defaultValue: 给返回值定义默认值
 * expires: 过期时间 (默认cookie有效期截止至用户退出浏览器)
 * path: 此cookie对哪个地址可见(默认为 /)
 * domain: 此cookie对哪个域名可见(默认为对创建此cookie的域名和子域名可见)
 * secure: cookie传输是否仅支持https (默认不支持)
 * sameSite: 限制第三方 cookie,减少安全风险(https://www.ruanyifeng.com/blog/2019/09/cookie-samesite.html)
 */
interface Options$8 {
    watch?: boolean;
    defaultValue?: string | undefined;
    expires?: number | Date;
    path?: string;
    domain?: string;
    secure?: boolean;
    sameSite?: 'strict' | 'lax' | 'none';
}
/**
 * 操作 cookie
 * @param key 获取 cookie 的 key
 * @param options 基础配置（见上面的 Options 接口）
 * @returns 返回 cookie 的值
 */
declare function useCookie(key: string, options?: Options$8): vue_demi.Ref<string | undefined>;

/**
 * onSuccess: 成功回调
 * onError: 失败回调
 */
interface Options$7 {
    onSuccess?: (str: Str) => void;
    onError?: (str: Str) => void;
}
declare type Str = undefined | string | number | boolean | object | (() => void);
/**
 * 控制 剪切板内容
 * 警告: 必须在网页聚焦时才能正常使用
 * @param str 剪切板初始化时的内容
 * @param options 如上 Options
 */
declare function useCopy(str?: Str, options?: Options$7): vue_demi.Ref<Str>;

declare type Value = string | number | Date;
/**
 * format: 针对日期格式化（默认 YYYY-MM-DD HH:mm:ss）
 * method: 获取时间的操作方法（默认 format）
 * methodParam: 针对获取到的时间 (例如 dayjs().hour(methodParam = 10) 就是将获取到的时间中小时时间设置为10)
 * 注意：比如说 method 设为 hour，methodParam 不设置时，dayjs返回的是当前小时数(比如当前是10点则返回10)
 */
interface Options$6 {
    format?: string;
    method?: 'format' | 'timestamp' | 'millisecond' | 'second' | 'minute' | 'hour' | 'date' | 'day' | 'month' | 'year';
    methodParam?: number;
}
/**
 * 操作时间（内部使用了 dayjs）
 * @param options
 * @param initialValue 初始时间
 */
declare function useDate(options?: Options$6, initialValue?: Value | undefined): {
    readonly data: any;
    refresh: (refreshValue?: Value) => void;
};

/**
 * 处理防抖值 - 连续触发只会更新一次值
 * @param fn 待执行函数
 * @param delay 防抖时间
 * @param firstTrigger 是否需要首次点击时立即触发(这里的首次指的并不是第一次，每当防抖时间过了都会刷新首次) (默认 false)
 * @returns
 */
declare function useDebounce<T>(value: Ref<T>, delay?: number, firstTrigger?: boolean): Ref<T>;

declare type Fn$3 = (...params: any[]) => any;
/**
 * 处理防抖函数
 * @param fn
 * @param delay 防抖间隔 (默认 1000)
 * @param firstTrigger 是否需要首次点击时立即触发(这里的首次指的并不是第一次，每当防抖时间过了都会刷新首次)
 * @returns
 */
declare function useDebounceFn(fn: Fn$3, delay?: number, firstTrigger?: boolean): {
    run: () => void;
};

/**
 * 获取页面是否隐藏
 * @returns
 */
declare function useDocumentHidden(): Ref<boolean>;

/**
 * 用于管理列表状态
 * @param initialValue 初始列表
 * @returns
 */
declare function useDynamicList<T = any>(initialValue: Ref<T[]>): {
    list: Ref<T[]>;
    resetList: (resetList: Ref<T[]> | T[]) => void;
    insert: (index: number, ...obj: any[] | any[][]) => void;
    replace: (index: number, obj: T) => void;
    remove: (index: number) => void;
    move: (oldIndex: number, newIndex: number) => void;
    push: (obj: T) => void;
    pop: () => void;
    unshift: (obj: T) => void;
    shift: () => void;
    getKey: (index: number) => string;
    getIndex: (key: string) => number;
};

declare type Elements = HTMLScriptElement | HTMLLinkElement | HTMLImageElement;
/**
 * manual: 是否手动下载 (默认 false)
 * async: script 标签属性
 * crossOrigin: script 标签属性
 * referrerPolicy: script 标签属性
 * noModule: script 标签属性
 * defer: script 标签属性
 * media: link 标签属性 (默认 all)
 * target: 资源挂载在哪 (默认 document.body)
 */
interface Options$5 {
    manual?: boolean;
    async?: boolean;
    crossOrigin?: 'anonymous' | 'use-credentials';
    referrerPolicy?: 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url';
    noModule?: boolean;
    defer?: boolean;
    media?: string;
    target?: HTMLElement | Ref<HTMLElement> | undefined;
}
/**
 * 用于动态地向页面加载或卸载外部资源（js，图片，css）
 * @param src 下载地址
 * @param onLoaded 下载成功回调
 * @param options
 * @remark 图片需要手动控制下载，否则可能会出现没有及时拿到外部 target 元素
 */
declare function useExternal(src: string | Ref<string>, onLoaded?: (el: Elements) => void, options?: Options$5): {
    resources: Ref<Elements | null>;
    load: () => Promise<unknown>;
    unload: () => void;
};

/**
 * onFull: 全屏钩子
 * onExitFull: 退出全屏钩子
 */
interface Options$4 {
    onFull?: () => void;
    onExitFull?: () => void;
}
/**
 * setFull: 设置全屏
 * exitFull: 退出全屏
 * toggle: 切换是否全屏
 */
interface Actions$3 {
    setFull: () => void;
    exitFull: () => void;
    toggle: () => void;
}
declare type Target$1 = HTMLElement | (() => HTMLElement) | Ref<HTMLElement>;
/**
 * 控制元素全屏
 * @param target 需要全屏的元素(默认 document.body)
 * @param options
 * @returns isFullscreen: 是否全屏状态， actions: 操控是否全屏
 */
declare function useFullscreen(target?: Target$1, options?: Options$4): [isFullscreen: Ref<boolean>, actions: Actions$3];

/**
 * watch: 是否监听返回出去的值，当此值变化时同时更改 localStorage
 */
interface Options$3 {
    watch: boolean;
}
/**
 * 管理 localStorage
 * @param key 键
 * @param initialValue 初始值
 * @param options
 * @returns 返回取到的值
 */
declare function useLocalStorage<T = any>(key: string, initialValue?: T | Ref<T>, options?: Options$3): Ref<T | null | undefined>;

declare type ArgsAny = any[];
declare type Fn$2 = (...args: ArgsAny) => Promise<any> | void;
/**
 * 给函数设置单行道，只有此函数执行完毕才能执行下一个
 * @param fn 需要执行的函数
 * @returns 返回待执行函数
 */
declare function useLockFn(fn: Fn$2): (...args: ArgsAny) => Promise<any>;

declare type MapValue = readonly (readonly [any, any])[];
/**
 * set: 新增数据
 * get: 获取数据
 * remove: 删除数据
 * has: 判断是否有某条数据
 * clear: 清除某条数据
 * setAll: 设置所有数据
 * reset: 清除所有数据
 */
interface Actions$2<T> {
    set: (key: string, value: T) => void;
    get: (key: string) => T;
    remove: (key: string) => void;
    has: (key: string) => boolean;
    clear: () => void;
    setAll: (newMap: MapValue) => void;
    reset: () => void;
}
/**
 * 操作 Map
 * @param initialValue map 初始值
 * @returns state: map源数据，actions: Actions
 */
declare function useMap<T = any>(initialValue?: MapValue): [state: Ref<Map<any, any>>, actions: Actions$2<T>];

/**
 * 监听 mediaQuery 状态
 * 此 hook 只针对单个监听，useMediaQueryS支持多个
 * @param query 需要监听的阈值
 * @returns 返回是否满足设定值
 */
declare function useMediaQuery(query: string): vue_demi.Ref<boolean>;

declare type queryType = {
    [key: string]: string;
};
/**
 * 监听多个 mediaQuery 状态
 * @param query 需要监听的阈值对象
 * @returns 返回当前满足value设定的 key
 */
declare function useMediaQueryS(query: queryType): vue_demi.Ref<string | undefined>;

/**
 * type: click(点击触发) move(移动触发) (默认 click)
 * target: 触发的元素 (默认 document.body)
 */
interface Options$2 {
    type?: 'click' | 'move';
    target?: HTMLElement | Ref<HTMLElement>;
    onSuccess?: () => void;
}
/**
 * 捕捉鼠标方位
 * 分两种 1.点击触发 2.移动触发
 * 也分为全局触发和某个元素触发
 * @param options Options
 * @return clickX: x坐标 clickY: y坐标
 */
declare function useMousePosition(options?: Options$2): {
    clickX: Ref<number>;
    clickY: Ref<number>;
};

/**
 * since: 在线与不在线最后改变时间
 * online: 网络是否为在线
 * rtt: 当前连接下评估的往返时延
 * type: 设备使用与所述网络进行通信的连接的类型
 * downlink: 有效带宽估算（单位：兆比特/秒）
 * downlinkMax: 最大下行速度（单位：兆比特/秒）
 * saveData: 用户代理是否设置了减少数据使用的选项
 * effectiveType: 网络连接的类型
 */
interface NetworkState {
    since?: number | Date;
    online?: boolean;
    rtt?: number;
    type?: string;
    downlink?: number;
    saveData?: boolean;
    downlinkMax?: number;
    effectiveType?: string;
}
/**
 * 获取当前网络状态
 * @returns NetworkState
 */
declare function useNetwork(): {};

declare type Text = Ref<string> | string;
/**
 * onRenderingStart: 开始渲染钩子
 * onRenderingEnd: 渲染结束钩子
 */
interface useQRCodeOptions {
    onRenderingStart?: (qrCodeOptions: any) => void;
    onRenderingEnd?: (qrCodeOptions: any, dataURL: string) => void;
    [key: string]: any;
}
/**
 * 根据字符串生成二维码
 * @param text 二维码字符串内容
 * @param options useQRCodeOptions
 * @returns base64 格式的二维码内容
 */
declare function useQRCode(text: Text, options?: useQRCodeOptions): Ref<string | undefined>;

/**
 * target: 需要获取滚动量的元素 (默认 )
 */
interface Options$1 {
    target?: HTMLElement | Ref<HTMLElement>;
}
/**
 * 获取scroll 的Y轴滚动量
 * 分为全局触发和某个元素触发
 * @param options Options
 * @return scrollY: 当更改此值时会直接滚动到目标区域
 */
declare function useScrollPosition(options?: Options$1): {
    scrollY: Ref<number>;
};

/**
 * watch: 是否监听返回值，当返回值更改时也会同步到 sessionStorage (默认 true)
 */
interface Options {
    watch: boolean;
}
/**
 * 优雅操作 sessionStorage 存储
 * @param key 键值
 * @param initialValue 初始值
 * @param options watch: 是否监听返回值，当返回值更改时也会同步到 sessionStorage
 * @returns key代表的值 (默认为初始值)
 */
declare function useSessionStorage<T = any>(key: string, initialValue?: T | Ref<T>, options?: Options): Ref<T | null | undefined>;

/**
 * add: 添加值
 * remove: 删除某个值
 * has: 判断是否存在
 * clear: 清除全部
 * reset: 重置 set
 */
interface Actions$1<T> {
    add: (value: T) => void;
    remove: (value: T) => void;
    has: (value: T) => boolean;
    clear: () => void;
    reset: (value: T[]) => void;
}
/**
 * 操作 Set 数据结构
 * @param initialValue 初始值 - 当传入的初始值发生改变时 Set数据也会变
 * @return [0]: 生成的 set 结构， [1]: 快捷操作 set 结构的函数，参照Actions
 */
declare function useSet<T = any>(initialValue?: T[]): [state: Ref<Set<any>>, actions: Actions$1<T>];

/**
 * 暂停程序 - 在设定时间后继续执行
 * @param time 暂停的时间
 * @param type 暂停方式 while:整个程序暂停  await:暂停某一块逻辑 (默认 await)
 * @returns 如果是 await 方式则返回promise对象，外层直接await
 * @tips 谨慎选择 while暂停方式，其原理是跑满cpu以至于不能执行其他程序，这意味着你点击其他菜单都不会做出反应
 */
declare function useSleep(time: number, type?: 'while' | 'await'): Promise<unknown> | undefined;

declare type Target = HTMLElement | Ref<HTMLElement> | (() => HTMLElement) | Document;
/**
 * 获取用户选中的字符串
 * @param target 指定在哪个元素下的选中
 * @returns text: 选中的内容字符串 rect: 参照 https://developer.mozilla.org/zh-CN/docs/Web/API/Element/getBoundingClientRect
 * @tips 获取到的 数据是相对于视图的左上角计算的(除 height，width外)
 */
declare function useTextSelection(target?: Target): vue_demi.ToRefs<{
    text: string;
    rect: {
        left: number;
        right: number;
        top: number;
        bottom: number;
        height: number;
        width: number;
    };
}>;

/**
 * 处理节流值
 * 不同于 useThrottleFn,此函数专门用来对某个值的节流变化
 * @param value 监听的源数据
 * @param delay 节流设定时间 (默认 1000)
 * @returns
 */
declare function useThrottle<T>(value: Ref<T>, delay?: number): Ref<T>;

declare type Fn$1 = (...params: any[]) => any;
/**
 * 处理节流函数
 * @param fn 待执行函数
 * @param delay 节流设定时间 (默认 1000)
 * @param runLastFn 是否在节流过期时执行最后一次被拦住的方法
 * @returns 包装后的函数
 */
declare function useThrottleFn(fn: Fn$1, delay?: number, runLastFn?: boolean): {
    run: () => void;
};

declare type State = string | number | boolean | undefined;
declare type RefState = Ref<State>;
declare type Fn = (v?: any) => void;
declare type Actions = Fn[];
/**
 * 用于在N个状态值间切换
 * @param args 多个数据源
 * @return [0]: 当前选中值  [1]: [toggle(), ...activeState()] (操作当前值)
 */
declare function useToggle<T extends State, U extends RefState>(...args: (T | U)[]): [U, Actions];

/**
 * itemHeight: 列表中子项的高度
 * overscan: 滚动列表时为了让视图正常设置的偏差值 (默认为5,一般情况下不需要特殊设置)
 */
interface Option {
    itemHeight: number | ((index: number) => number);
    overscan?: number;
}
/**
 * 虚拟列表
 * @param state 源数据
 * @param options Option
 * @returns
 * list: 当前视图显示的数据
 * wrapperStyle: 包装列表的容器样式
 * containerProps: 最外层容器的ref以及scroll事件绑定
 */
declare function useVirtualList<T = any>(state: T[], options: Option): {
    list: Ref<T[]>;
    wrapperStyle: {
        width: string;
        height: string;
        marginTop: string;
    };
    containerProps: {
        ref: (ele: any) => void;
        onScroll: (e: any) => void;
        style: {
            overflowY: "auto";
        };
    };
    scrollTo: (index: number) => void;
};

/**
 * manual: 是否手动连接 (默认false)
 * reconnectLimit: 重连数
 * reconnectInterval: 重连间隔时间
 * onOpen: 打开连接回调
 * onClose: 关闭连接回调
 * onMessage: 发送消息回调
 * onError: 连接报错回调
 */
interface UseWebSocketOptions {
    manual?: boolean;
    reconnectLimit?: number;
    reconnectInterval?: number;
    onOpen?: (event: WebSocketEventMap['open']) => void;
    onClose?: (event: WebSocketEventMap['close']) => void;
    onMessage?: (event: WebSocketEventMap['message']) => void;
    onError?: (event: WebSocketEventMap['error']) => void;
}
declare enum ReadyState {
    Connecting = 0,
    Open = 1,
    Closing = 2,
    Closed = 3
}
/**
 * connect: 连接方法
 * disconnect: 关闭连接方法
 * sendMessage: 发送消息方法
 * readyState: 当前连接状态
 * latestMessage: 最后返回的消息
 * webSocketIns: 连接实例
 */
interface Result {
    connect: () => void;
    disconnect: () => void;
    sendMessage: WebSocket['send'];
    readyState: Ref<ReadyState>;
    latestMessage: Ref<WebSocketEventMap['message'] | undefined>;
    webSocketIns: Ref<WebSocket | undefined>;
}
/**
 * 管理 websocket
 * @param socketUrl 连接地址
 * @param options UseWebSocketOptions
 * @return Result
 */
declare function useWebSocket(socketUrl: string, options?: UseWebSocketOptions): Result;

export { NetworkState, Option, useBoolean, useCookie, useCopy, useDate, useDebounce, useDebounceFn, useDocumentHidden, useDynamicList, useExternal, useFullscreen, useLocalStorage, useLockFn, useMap, useMediaQuery, useMediaQueryS, useMousePosition, useNetwork, useQRCode, useScrollPosition, useSessionStorage, useSet, useSleep, useTextSelection, useThrottle, useThrottleFn, useToggle, useVirtualList, useWebSocket };