API 文档
说明
本扩展 api 定义参考tampermonkey 文档,由于时间和精力问题,只实现了部分 API,后续将继续迭代,本扩展进行扩充或者与原 GM 不同的 API 将在文档中特殊标注(使用*号).对于某些 API 还提供了同步函数,同步函数规则:GM.*,具体请看文档内容.
API 的详细定义,请看tempermonkey.d.ts
或者内置编辑器提示,文档更新可能不会及时.对于本扩展特有的 API
请看CatApi 文档
另外可以在example查看相关示例
定义
GM_info
获取脚本相关信息(参考tempermonkey.d.ts
且并不完全)
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
不支持)两个方法.
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;