@yiero/gmlib/dist/UserInteraction/gmMenuCommand.d.ts

GM Lib for Tampermonkey/ScriptCat

/**
 * 菜单命令对象接口
 */
export interface MenuCommand {
    /** 菜单项显示文本 */
    title: string;
    /** 点击菜单项时的回调函数 */
    onClick: () => void;
    /** 是否激活状态（显示） */
    isActive: boolean;
    /** GM_registerMenuCommand 返回的 ID */
    id: number;
}
/**
 * 用户脚本菜单命令管理器
 *
 * 提供 Tampermonkey/ScriptCat 菜单命令的高级管理功能，
 * 支持链式调用、状态切换菜单、模拟点击等。
 *
 * @warn 需要授权函数 `GM_registerMenuCommand`、`GM_unregisterMenuCommand`
 *
 * @example
 * ```ts
 * // 创建简单菜单
 * gmMenuCommand
 *   .create('刷新数据', () => location.reload())
 *   .render();
 *
 * // 创建状态切换菜单
 * gmMenuCommand.createToggle({
 *   active: { title: '🔴 停止监控', onClick: stopMonitoring },
 *   inactive: { title: '🟢 开始监控', onClick: startMonitoring }
 * }).render();
 * ```
 */
declare class gmMenuCommand {
    /**
     * 菜单按钮列表
     * */
    static list: MenuCommand[];
    /**
     * 是否暂停渲染（用于 batch 批量操作）
     * */
    private static _renderSuspended;
    private constructor();
    /**
     * 获取菜单按钮详情
     *
     * @param title 菜单项标题
     * @returns MenuCommand 对象
     * @throws 菜单按钮不存在时抛出错误
     */
    static get(title: string): MenuCommand;
    /**
     * 创建状态切换菜单
     *
     * 创建一对关联的菜单项，用于表示功能的开启/关闭状态。
     * 点击激活态菜单时执行回调并切换到未激活态，反之亦然。
     *
     * @param details 状态配置对象，包含 active 和 inactive 两个状态
     * @param defaultState 默认状态
     * @returns gmMenuCommand 实例（支持链式调用）
     */
    static createToggle(details: {
        active: Omit<MenuCommand, 'id' | 'isActive'>;
        inactive: Omit<MenuCommand, 'id' | 'isActive'>;
    }, defaultState?: 'active' | 'inactive'): typeof gmMenuCommand;
    /**
     * 模拟点击菜单命令
     *
     * 无需用户操作，直接触发菜单项的回调函数
     *
     * @param title 菜单项标题
     * @returns gmMenuCommand 实例（支持链式调用）
     */
    static click(title: string): typeof gmMenuCommand;
    /**
     * 创建标准菜单命令
     *
     * @param title 菜单项文本
     * @param onClick 点击回调函数
     * @param isActive 初始激活状态，默认为 true
     * @returns gmMenuCommand 实例（支持链式调用）
     * @throws 菜单按钮已存在时抛出错误
     */
    static create(title: string, onClick: () => void, isActive?: boolean): typeof gmMenuCommand;
    /**
     * 删除菜单命令
     *
     * @param title 菜单项标题
     * @returns gmMenuCommand 实例（支持链式调用）
     */
    static remove(title: string): typeof gmMenuCommand;
    /**
     * 清空所有菜单按钮
     */
    static reset(): typeof gmMenuCommand;
    /**
     * 批量操作菜单命令
     *
     * 在回调函数中进行的所有菜单操作不会触发多次渲染，
     * 而是在回调结束后统一渲染一次。
     *
     * @param callback 批量操作回调
     * @returns gmMenuCommand 实例（支持链式调用）
     *
     * @example
     * ```ts
     * gmMenuCommand.batch(() => {
     *   gmMenuCommand.create('菜单1', () => {});
     *   gmMenuCommand.create('菜单2', () => {});
     *   gmMenuCommand.create('菜单3', () => {});
     * });
     * // 只会在最后渲染一次
     * ```
     */
    static batch(callback: () => void): typeof gmMenuCommand;
    /**
     * 修改两个菜单按钮的顺序
     */
    static swap(title1: string, title2: string): typeof gmMenuCommand;
    /**
     * 修改一个菜单按钮
     */
    static modify(title: string, details: Partial<Omit<MenuCommand, 'title' | 'id'>>): typeof gmMenuCommand;
    /**
     * 切换菜单按钮激活状态
     */
    static toggleActive(title: string): typeof gmMenuCommand;
    /**
     * 渲染所有激活的菜单按钮
     */
    static render(): typeof gmMenuCommand;
    /**
     * 清除指定 id 的绑定状态
     */
    private static unregisterMenuCommand;
}
export { gmMenuCommand };