Skip to content
ScriptCatScriptCat
首页
使用指南
开发指南
更新日志
关于我们
github icon
  • 开发指南

    • 简介
      • 后台脚本
        • 云端执行
          • 订阅模式
            • 用户配置
              • API 文档
                • 说明
                  • 定义
                    • GM_cookie
                      • GM_notification *
                        • GM_xmlhttpRequest *
                          • GM_log *
                            • GM_get/set/deleteValue
                              • GM_listValues
                                • GM_add/removeValueChangeListener *
                                  • GM_openInTab
                                    • GM_get/saveTab/GM_getTabs
                                      • GM_setClipboard
                                        • GM_addStyle
                                          • GM_registerMenuCommand
                                            • GM_unregisterMenuCommand
                                              • GM_getResourceText/GM_getResourceURL
                                                • GM_download
                                              • CatApi 文档
                                                • 描述文档

                                                API 文档

                                                calendar icon2021年5月26日timer icon大约 5 分钟

                                                此页内容
                                                • 说明
                                                • 定义
                                                  • GM_cookie
                                                  • GM_notification *
                                                  • GM_xmlhttpRequest *
                                                  • GM_log *
                                                  • GM_get/set/deleteValue
                                                  • GM_listValues
                                                  • GM_add/removeValueChangeListener *
                                                  • GM_openInTab
                                                  • GM_get/saveTab/GM_getTabs
                                                  • GM_setClipboard
                                                  • GM_addStyle
                                                  • GM_registerMenuCommand
                                                  • GM_unregisterMenuCommand
                                                  • GM_getResourceText/GM_getResourceURL
                                                  • GM_download

                                                # API 文档

                                                # 说明

                                                本扩展api定义参考tampermonkey文档open in new window,由于时间和精力问题,只实现了部分API,后续将继续迭代,本扩展进行扩充或者与原GM不同的API将在文档中特殊标注(使用*号).对于某些API还提供了同步函数,同步函数规则:GM.*,具体请看文档内容.

                                                API的详细定义,请看tempermonkey.d.ts或者内置编辑器提示,文档更新可能不会及时.对于本扩展特有的API请看CatApi文档

                                                # 定义

                                                # GM_cookie

                                                必须使用@connect声明操作的host,且经过用户授权才可使用.虽然兼容TM的GM_cookie.list操作,但是为了统一,不建议这样.

                                                declare function GM_cookie(action: GM_Types.CookieAction, details: GM_Types.CookieDetails, ondone: (cookie: GM_Types.Cookie[], error: any | undefined) => void): void;
                                                
                                                // store可通过tabid(前后端通信可能用到,ValueChangeListener会返回tabid),获取storeid,后台脚本用.
                                                declare namespace GM_Types {
                                                    type CookieAction = "list" | "delete" | "set" | "store";
                                                    interface CookieDetails {
                                                        url?: string
                                                        name: string
                                                        value?: string
                                                        domain?: string
                                                        path?: string
                                                        secure?: boolean
                                                        session?: boolean
                                                        storeId?: string;
                                                        httpOnly?: boolean
                                                        expirationDate?: number
                                                    }
                                                    interface Cookie {
                                                        domain: string;
                                                        name: string;
                                                        storeId: string;
                                                        value: string;
                                                        session: boolean;
                                                        hostOnly: boolean;
                                                        expirationDate?: number;
                                                        path: string;
                                                        httpOnly: boolean;
                                                        secure: boolean;
                                                    }
                                                }
                                                
                                                1
                                                2
                                                3
                                                4
                                                5
                                                6
                                                7
                                                8
                                                9
                                                10
                                                11
                                                12
                                                13
                                                14
                                                15
                                                16
                                                17
                                                18
                                                19
                                                20
                                                21
                                                22
                                                23
                                                24
                                                25
                                                26
                                                27
                                                28
                                                29
                                                30

                                                # GM_notification *

                                                发送消息通知,提供了progress和buttons的能力(Firefox不支持),可以显示进度条类型和按钮类型的通知,多提供了GM_closeNotification,GM_updateNotification(Firefox不支持)两个方法.

                                                demoopen in new window

                                                declare function GM_notification(details: GM_Types.NotificationDetails, ondone: Function): void;
                                                declare function GM_notification(text: string, title: string, image: string, onclick: Function): void;
                                                declare function GM_closeNotification(id: string): void;
                                                declare function GM_updateNotification(id: string, details: GM_Types.NotificationDetails): void;
                                                
                                                declare namespace GM_Types {
                                                
                                                    type NotificationOnClick = (this: NotificationThis, id: string, index?: number) => any;
                                                    type NotificationOnDone = (this: NotificationThis, clicked: boolean, id: string) => any;
                                                
                                                    interface NotificationButton {
                                                        title: string
                                                        iconUrl?: string
                                                    }
                                                
                                                    interface NotificationDetails {
                                                        text?: string
                                                        title?: string
                                                        image?: string
                                                        highlight?: boolean
                                                        silent?: boolean
                                                        timeout?: number
                                                        onclick?: NotificationOnClick
                                                        ondone?: NotificationOnDone
                                                        progress?: number
                                                        oncreate?: NotificationOnClick
                                                        // 只能存在2个
                                                        buttons?: NotificationButton[]
                                                    }
                                                
                                                }
                                                
                                                1
                                                2
                                                3
                                                4
                                                5
                                                6
                                                7
                                                8
                                                9
                                                10
                                                11
                                                12
                                                13
                                                14
                                                15
                                                16
                                                17
                                                18
                                                19
                                                20
                                                21
                                                22
                                                23
                                                24
                                                25
                                                26
                                                27
                                                28
                                                29
                                                30
                                                31

                                                # GM_xmlhttpRequest *

                                                部分功能缺失,cookie功能firefox暂不支持.需要用户授权才可正常访问,使用@connect描述的host可跳过用户授权,其它需要进行ajax操作的API同理.

                                                对于anonymous和cookie相比tm做了特殊处理,anonymous为true且cookie存在时,发送的cookie为设置的cookie不会带上其他cookie.

                                                特殊header也是支持的:

                                                • user-agent
                                                • origin,
                                                • referer
                                                • cookie
                                                • host
                                                • ...

                                                增加了maxRedirects参数,可控制请求的最大重定向次数,为0表示禁止重定向.

                                                declare function GM_xmlhttpRequest(details: GM_Types.XHRDetails): GM_Types.AbortHandle<void>;
                                                
                                                declare namespace GM_Types {
                                                    interface XHRResponse {
                                                        finalUrl?: string,
                                                        readyState?: 0 | 1 | 2 | 3 | 4,
                                                        responseHeaders?: string,
                                                        status?: number,
                                                        statusText?: string,
                                                        response?: any,
                                                        responseText?: string,
                                                        responseXML?: Document | null
                                                    }
                                                
                                                    interface XHRProgress extends XHRResponse {
                                                        done: number,
                                                        lengthComputable: boolean,
                                                        loaded: number,
                                                        position: number,
                                                        total: number,
                                                        totalSize: number
                                                    }
                                                
                                                    type Listener<OBJ> = (event: OBJ) => any;
                                                
                                                    interface XHRDetails {
                                                        method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS'
                                                        url: string
                                                        headers?: { [key: string]: string }
                                                        data?: string | FormData
                                                        cookie?: string
                                                        binary?: boolean
                                                        timeout?: number
                                                        responseType?: 'text' |'arraybuffer' | 'blob' | 'json'
                                                        overrideMimeType?: string,
                                                        anonymous?: boolean,
                                                        fetch?: boolean,
                                                        user?: string,
                                                        password?: string,
                                                        nocache?: boolean
                                                        maxRedirects?: number
                                                
                                                        onload?: Listener<XHRResponse>,
                                                        onloadstart?: Listener<XHRResponse>,
                                                        onloadend?: Listener<XHRResponse>,
                                                        onprogress?: Listener<XHRProgress>,
                                                        onreadystatechange?: Listener<XHRResponse>,
                                                        ontimeout?: () => void,
                                                    }
                                                }
                                                
                                                1
                                                2
                                                3
                                                4
                                                5
                                                6
                                                7
                                                8
                                                9
                                                10
                                                11
                                                12
                                                13
                                                14
                                                15
                                                16
                                                17
                                                18
                                                19
                                                20
                                                21
                                                22
                                                23
                                                24
                                                25
                                                26
                                                27
                                                28
                                                29
                                                30
                                                31
                                                32
                                                33
                                                34
                                                35
                                                36
                                                37
                                                38
                                                39
                                                40
                                                41
                                                42
                                                43
                                                44
                                                45
                                                46
                                                47
                                                48
                                                49
                                                50

                                                # GM_log *

                                                日志函数,后台脚本的日志将在控制面板的运行日志中看到(点击运行状态栏).相比于tm增加了一个日志的level.

                                                declare function GM_log(message: string, level?: GM_Types.LoggerLevel): any;
                                                declare namespace GM_Types {
                                                    type LoggerLevel = 'debug' | 'info' | 'warn' | 'error';
                                                }
                                                
                                                1
                                                2
                                                3
                                                4

                                                # GM_get/set/deleteValue

                                                从储存中获取或者设置值,数据在同一storageName中可以共享,且可以实时的同步.

                                                // 添加数据,请注意数据只能为bool;string;number;object四种类型,不能存储对象实例
                                                declare function GM_setValue(name: string, value: any): void;
                                                // 获取数据
                                                declare function GM_getValue(name: string, defaultValue?: any): any;
                                                // 删除数据,再获取会返回undefined或defaultValue
                                                declare function GM_deleteValue(name: string): void;
                                                
                                                1
                                                2
                                                3
                                                4
                                                5
                                                6

                                                # GM_listValues

                                                列出所有key

                                                declare function GM_listValues(): string[];
                                                
                                                1

                                                # GM_add/removeValueChangeListener *

                                                对值的监听操作,add会返回一个监听id,使用remove可以取消监听.后台脚本监听会返回tabid.可以使用这个方法实现一个简单的通信,使用storageName可以实现跨脚本通信.

                                                // tabid是只有后台脚本监听才有的参数,获得tabid后可以使用GM_cookie('store')获取页面的cookie储存空间
                                                type ValueChangeListener = (name: string, oldValue: any, newValue: any, remote: boolean, tabid?: number) => any;
                                                
                                                declare function GM_addValueChangeListener(name: string, listener: GM_Types.ValueChangeListener): number;
                                                
                                                declare function GM_removeValueChangeListener(listenerId: number): void;
                                                
                                                1
                                                2
                                                3
                                                4
                                                5
                                                6

                                                # GM_openInTab

                                                打开一个新窗口

                                                declare function GM_openInTab(url: string, options: GM_Types.OpenTabOptions): void;
                                                declare function GM_openInTab(url: string, loadInBackground: boolean): void;
                                                declare function GM_openInTab(url: string): void
                                                
                                                declare namespace GM_Types {
                                                    interface OpenTabOptions {
                                                        active?: boolean,
                                                        insert?: boolean,
                                                        setParent?: boolean
                                                    }
                                                }
                                                
                                                1
                                                2
                                                3
                                                4
                                                5
                                                6
                                                7
                                                8
                                                9
                                                10
                                                11

                                                # GM_get/saveTab/GM_getTabs

                                                类似GM_setValue的一个储存数据的方法,但是本方法的生命周期为一个浏览器页面窗口的打开->关闭,后台脚本中无法使用

                                                // 获取tab数据
                                                declare function GM_getTab(callback: (obj: object) => any): void;
                                                // 保存tab数据
                                                declare function GM_saveTab(obj: object): void;
                                                // 获取所有tab数据
                                                declare function GM_getTabs(callback: (objs: { [key: number]: object }) => any): void;
                                                
                                                1
                                                2
                                                3
                                                4
                                                5
                                                6

                                                # GM_setClipboard

                                                设置剪辑板

                                                declare function GM_setClipboard(data: string, info?: string | { type?: string, minetype?: string }): void;
                                                
                                                1

                                                # GM_addStyle

                                                添加样式到页面中,返回样式DOM

                                                declare function GM_addStyle(css: string): HTMLElement;
                                                
                                                1

                                                # GM_registerMenuCommand

                                                注册一个菜单选项到弹出页面中,点击时会调用listener方法,如果注册多个同名菜单,则只会第一个生效

                                                declare function GM_registerMenuCommand(name: string, listener: Function, accessKey?: string): number;
                                                
                                                1

                                                # GM_unregisterMenuCommand

                                                通过id删除一个已经注册了的菜单项

                                                declare function GM_unregisterMenuCommand(id: number): void;
                                                
                                                1

                                                # GM_getResourceText/GM_getResourceURL

                                                获取@resource声明的资源信息

                                                //GM_getResourceText 获取资源文本数据,image等byte类型的数据会返回空文本,需要使用GM_getResourceURL获取
                                                declare function GM_getResourceText(name: string): string | undefined;
                                                //GM_getResourceURL 获取经过base64后的数据
                                                declare function GM_getResourceURL(name: string): string | undefined
                                                
                                                1
                                                2
                                                3
                                                4

                                                # GM_download

                                                下载文件,可设置header等内容,相比tm多了cookie和anonymous的功能,如果为blob url,将会直接打开下载,只有onload事件,这是与tm不同的一个特性(为后台脚本无法创建下载而服务,可能会在一些生成报表的场景使用到)

                                                declare function GM_download(details: GM_Types.DownloadDetails): GM_Types.AbortHandle<boolean>;
                                                declare function GM_download(url: string, filename: string): GM_Types.AbortHandle<boolean>;
                                                
                                                declare namespace GM_Types {
                                                
                                                    interface DownloadError {
                                                        error: 'not_enabled' | 'not_whitelisted' | 'not_permitted' | 'not_supported' | 'not_succeeded' | 'unknown',
                                                        details?: string
                                                    }
                                                
                                                    interface DownloadDetails {
                                                        method?: 'GET' | 'POST'
                                                        url: string,
                                                        name: string,
                                                        headers?: { [key: string]: string }
                                                        saveAs?: boolean,
                                                        timeout?: number,
                                                        cookie?: string,
                                                        anonymous?: boolean
                                                
                                                        onerror?: Listener<DownloadError>,
                                                        ontimeout?: () => void,
                                                        onload?: Listener<object>,
                                                        onprogress?: Listener<XHRProgress<void>>
                                                    }
                                                
                                                }
                                                
                                                1
                                                2
                                                3
                                                4
                                                5
                                                6
                                                7
                                                8
                                                9
                                                10
                                                11
                                                12
                                                13
                                                14
                                                15
                                                16
                                                17
                                                18
                                                19
                                                20
                                                21
                                                22
                                                23
                                                24
                                                25
                                                26
                                                27
                                                edit icon编辑此页open in new window
                                                上次编辑于: 2022/4/16 05:35:31
                                                贡献者: CodFrm,CodFrm,Hangover1230,Junzhou Liu
                                                上一页
                                                用户配置
                                                下一页
                                                CatApi 文档
                                                Released under the MIT License Copyright © 2021-2022 ScriptCat 脚本猫