API 文档

说明

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

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

另外可以在example查看相关示例

定义

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;
  }
}

GM_notification *

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

demo

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[];
  }
}

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"
      | "document"
      | "stream"; // stream 在当前版本是一个较为简陋的实现
    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;
    onabort?: () => void;
    onerror?: (err: string) => void;
  }
}

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";
}

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;

GM_listValues

列出所有 key

declare function GM_listValues(): string[];

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;

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;
  }
}

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;

GM_setClipboard

设置剪辑板

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

GM_addStyle

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

declare function GM_addStyle(css: string): HTMLElement;

GM_registerMenuCommand

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

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

GM_unregisterMenuCommand

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

declare function GM_unregisterMenuCommand(id: number): void;

GM_getResourceText/GM_getResourceURL

获取@resource声明的资源信息

//GM_getResourceText 获取资源文本数据,image等byte类型的数据会返回空文本,需要使用GM_getResourceURL获取
declare function GM_getResourceText(name: string): string | undefined;
//GM_getResourceURL 获取经过base64后的数据,也可以通过第二个参数获取blob url
declare function GM_getResourceURL(
  name: string,
  isBlobUrl?: boolean = false
): string | undefined;

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>>;
  }
}

GM_addElement

在页面中插入元素,可以绕过CSP限制

declare function GM_addElement(tag: string, attribubutes: any);
declare function GM_addElement(parentNode: Element, tag: string, attrs: any);

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​

GM_addElement​

说明

定义