スクリプト API 付録

目的

サイトのページスクリプトと API インターセプトスクリプトで使用できる window.api の機能を説明します。設定読み取り、HTTP リクエスト、ユーザーデータ、DOM ツール、汎用ツール、リクエストヘッダーとレスポンスヘッダーの読み取りを含みます。

ページスクリプトと通常 API インターセプトスクリプトは window.api を使用できます。SSE スクリプトは data が渡されることだけが保証され、通常 window.api には依存しません。

interface Window {
  api: {
    user: UserApi;
    http: HttpApi;
    config: Record<string, unknown>;
    dom: DomApi;
    utils: UtilsApi;
    header(headerName: string, isRequestHeader: boolean): Promise<string | string[] | undefined>;
  };
}

`api.config`

サイトスクリプト環境のカスタム設定を読み取ります。

config: Record<string, unknown>

例:

const apiBase = api.config.apiBase;

`api.http`

api.http はユーザースクリプト向けの HTTP ヘルパーです。api.http.ajax はブラウザーのメインプロセス内で実際のリクエストを実行するため、ページの CORS ポリシーに制限されません。

`api.http.ajax(options)`

HTTP リクエストを送信します。

ajax(options: {
  url: string;
  method?: string;
  data?: any;
  headers?: Record<string, string>;
  timeout?: number;
  dataType?: 'json' | 'text' | 'html' | 'arrayBuffer';
  contentType?: string;
  processData?: boolean;
}): Promise<{
  ok: boolean;
  status: number;
  statusText: string;
  data?: any;
  error?: string;
  timeout?: boolean;
}>

オプション	型	既定値	説明
`url`	string	-	リクエスト URL。
`method`	string	`GET`	HTTP メソッド。
`data`	any	-	リクエストデータ。`GET` と `HEAD` ではクエリ文字列へシリアライズされ、それ以外のメソッドではリクエスト本文に書き込まれます。
`headers`	`Record<string, string>`	`{}`	リクエストヘッダー。
`timeout`	number	-	タイムアウト時間（ミリ秒）。`0` より大きい場合のみ有効です。
`dataType`	`'json' \| 'text' \| 'html' \| 'arrayBuffer'`	`json`	レスポンスの解析方式。
`contentType`	string	`application/x-www-form-urlencoded; charset=UTF-8`	リクエスト本文の Content-Type。
`processData`	boolean	`true`	`data` を自動的にシリアライズするかどうか。`false` にすると、`data` をそのままリクエスト本文として渡します。

戻り値：

フィールド	型	説明
`ok`	boolean	HTTP 2xx レスポンスでは `true`。解析エラー、HTTP エラー、タイムアウト、中止、ネットワークエラーでは `false`。
`status`	number	HTTP ステータスコード。`0` はタイムアウト、中止、またはネットワークレベルの失敗を示します。
`statusText`	string	HTTP ステータステキスト。HTTP 以外の失敗では `timeout`、`abort`、または `error`。
`data`	any	解析に成功したレスポンスデータ。
`error`	string	解析失敗または HTTP 以外の失敗時のエラーメッセージ。
`timeout`	boolean	設定されたタイムアウトによりリクエストが中止された場合は `true`。

例：

const ret = await api.http.ajax({
  url: 'https://example.com/api/profile',
  method: 'GET',
  dataType: 'json',
  timeout: 10000
});

if (ret.ok) {
  console.log(ret.data);
}

const ret = await api.http.ajax({
  url: 'https://example.com/api/items',
  method: 'POST',
  contentType: 'application/json',
  data: { name: 'demo' }
});

`api.user`

api.user は、スクリプト実行中のユーザー関連データを読み書きします。

共通パラメーター:

パラメーター	型	デフォルト	説明
`site`	boolean	`false`	サイト別に保存するかどうか。
`account`	boolean	`false`	アカウント別に保存するかどうか。
`did`	boolean	`false`	デバイス別に保存するかどうか。

`api.user.put(name, value, site, account, did)`

指定したキー値を保存します。

put(
  name: string,
  value: string,
  site?: boolean,
  account?: boolean,
  did?: boolean
): Promise<{ status: boolean }>

例:

await api.user.put('token', 'abc123');

`api.user.get(name, site, account, did)`

指定したキー値を読み取ります。

get(
  name: string,
  site?: boolean,
  account?: boolean,
  did?: boolean
): Promise<{ value: string | null, status: boolean }>

例:

const ret = await api.user.get('token');
console.log(ret.value);

`api.user.remove(name, site, account, did)`

指定したキー値を削除します。

remove(
  name: string,
  site?: boolean,
  account?: boolean,
  did?: boolean
): Promise<{ status: boolean }>

例:

await api.user.remove('token');

`api.user.incr(name, step, site, account, did)`

指定したキーの数値を step 分増やします。キーが存在しない場合は、値 step で作成します。

incr(
  name: string,
  step?: number,
  site?: boolean,
  account?: boolean,
  did?: boolean
): Promise<{ status: boolean, value: number | string }>

例:

const ret = await api.user.incr('count', 1);
console.log(ret.value);

`api.user.decr(name, step, site, account, did)`

指定したキーの数値を step 分減らします。キーが存在しない場合は、値 step * -1 で作成します。

decr(
  name: string,
  step?: number,
  site?: boolean,
  account?: boolean,
  did?: boolean
): Promise<{ status: boolean, value: number | string }>

例:

const ret = await api.user.decr('count', 1);
console.log(ret.value);

`api.user.startsWith(prefix, site, account, did)`

キー名が指定したプレフィックスで始まるすべてのデータを検索します。

startsWith(
  prefix: string,
  site?: boolean,
  account?: boolean,
  did?: boolean
): Promise<Array<{ name: string, value: string }>>

例:

const items = await api.user.startsWith('cache:');

`api.user.countAll(name, site, account)`

指定したキー名のレコード数を集計します。

countAll(
  name: string,
  site?: boolean,
  account?: boolean
): Promise<{ value: number, status: boolean }>

例:

const ret = await api.user.countAll('token');
console.log(ret.value);

`api.user.sumAll(name, site, account)`

指定したキー名に対応する値の数値合計を集計します。

sumAll(
  name: string,
  site?: boolean,
  account?: boolean
): Promise<{ value: number, status: boolean }>

例:

const ret = await api.user.sumAll('score');
console.log(ret.value);

`api.dom`

api.dom は DOM クエリ、可視性判定、接続リスナー、サイズリスナー、オーバーレイ作成機能を提供します。

セレクター対応:

書式	説明
`.button.primary`	CSS セレクター。
`xpath://div[@id="app"]`	XPath セレクター。
`.dialog:p`	一致した要素の親要素を返します。
`.dialog:p2`	一致した要素の 2 階層上の親要素を返します。
`.header:bottom`	オーバーレイ境界メソッドで対象要素の下端を使用します。
`.sidebar:right`	オーバーレイ境界メソッドで対象要素の右端を使用します。

`api.dom.createMutationObserver(ele, bindStr, childList, subtree, attributes, characterData, fn)`

MutationObserver を作成してキャッシュします。ele[bindStr] が既に存在する場合は、既存の observer を直接返します。

createMutationObserver(
  ele: Element,
  bindStr: string,
  childList: boolean,
  subtree: boolean,
  attributes: boolean,
  characterData: boolean,
  fn: (mutations: MutationRecord[]) => void
): MutationObserver

例:

api.dom.createMutationObserver(
  document.body,
  '__bodyObserver__',
  true,
  true,
  false,
  false,
  (mutations) => console.log(mutations)
);

`api.dom.querySelector(doc, cssOrXPathSelector)`

最初に一致する要素を検索します。

querySelector(doc: Document, cssOrXPathSelector: string): HTMLElement | null

例:

const el = api.dom.querySelector(document, 'xpath://button[contains(.,"Submit")]');

`api.dom.querySelectorAll(doc, cssOrXPathSelector)`

一致するすべての要素を検索します。

querySelectorAll(doc: Document, cssOrXPathSelector: string): HTMLElement[]

例:

const buttons = api.dom.querySelectorAll(document, 'button.primary');

`api.dom.isVisible(ele)`

要素が可視の交差領域にあるか判定します。

isVisible(ele: HTMLElement): Promise<boolean>

例:

if (await api.dom.isVisible(el)) {
  console.log('visible');
}

`api.dom.getVisibleRect(ele)`

要素の現在の可視領域の矩形を取得します。

getVisibleRect(ele: HTMLElement): Promise<DOMRectReadOnly>

例:

const rect = await api.dom.getVisibleRect(el);
console.log(rect.left, rect.top, rect.width, rect.height);

`api.dom.getConnectListeners()`

現在の接続リスナー一覧を取得します。

getConnectListeners(): Array<{
  querySelector: string;
  callback: (isConnected: boolean) => void;
  isConnected?: boolean;
}>

例:

api.dom.addConnectListener('.modal', () => {});
console.log(api.dom.getConnectListeners());

`api.dom.addConnectListener(cssOrXPathSelector, callback)`

対象要素がドキュメントに現れる、またはドキュメントから消えるかを監視します。

addConnectListener(
  cssOrXPathSelector: string,
  callback: (isConnected: boolean) => void
): void

例:

api.dom.addConnectListener('.dialog', (isConnected) => {
  console.log('dialog:', isConnected);
});

`api.dom.removeConnectListener(cssOrXPathSelectors)`

指定したセレクターに対応する接続リスナーを削除します。

removeConnectListener(cssOrXPathSelectors: string[]): void

例:

api.dom.removeConnectListener(['.dialog', '.toast']);

`api.dom.addResizeListener(cssOrXPathSelector, bindWindowStr, callback, createObserver, delayTime)`

対象要素のサイズと位置の変化を監視します。要素が存在しない場合、コールバックは new DOMRect(0, 0, 0, 0) を受け取ります。

addResizeListener(
  cssOrXPathSelector: string,
  bindWindowStr: string,
  callback: (rect: DOMRect) => void,
  createObserver?: boolean,
  delayTime?: number
): ResizeObserver | (() => void)

例:

api.dom.addResizeListener('.target', '__targetResize__', (rect) => {
  console.log(rect.width, rect.height);
});

`api.dom.createOverlayBy(cssOrXPathSelector, bindWindowStr, createObserver, delayTime, fn)`

対象要素の可視領域に追従する fixed 配置のオーバーレイを作成します。

createOverlayBy(
  cssOrXPathSelector: string,
  bindWindowStr: string,
  createObserver?: boolean,
  delayTime?: number,
  fn?: (rect: DOMRectReadOnly) => void
): HTMLElement

例:

const overlay = api.dom.createOverlayBy('.target', '__overlay__');
overlay.style.border = '2px solid #f00';
overlay.style.pointerEvents = 'none';
overlay.style.zIndex = '999999';

`api.dom.createOverlayByBorder(bindWindowStr, top, right, bottom, left, createObserver, delayTime)`

4 つの辺から fixed 配置のオーバーレイを作成します。各辺は数値ピクセル値またはセレクターにできます。セレクター境界では :top、:right、:bottom、:left を使用できます。

createOverlayByBorder(
  bindWindowStr: string,
  top: string | number,
  right: string | number,
  bottom: string | number,
  left: string | number,
  createObserver?: boolean,
  delayTime?: number
): HTMLElement

例:

const panel = api.dom.createOverlayByBorder(
  '__centerPanel__',
  'header:bottom',
  20,
  'footer:top',
  '.sidebar:right'
);
panel.style.background = 'rgba(0,0,0,.08)';

`api.utils`

`api.utils.wait(fn, timeoutMs, intervalMs)`

条件関数が真値を返すまでポーリングします。

wait(
  fn: () => boolean,
  timeoutMs: number,
  intervalMs?: number
): Promise<void>

タイムアウト後は Error("Timeout: function did not return true in time.") を投げます。

例:

await api.utils.wait(
  () => !!api.dom.querySelector(document, '.ready'),
  10000,
  200
);

`api.utils.runScript(code, callback)`

現在のページで JavaScript コードを実行します。

runScript(
  code: string,
  callback?: (result: any, error: Error) => void
): Promise<any>

例:

const title = await api.utils.runScript('document.title');
console.log(title);

`api.header(headerName, isRequestHeader)`

リモートブラウザーが記録したリクエストヘッダーまたはレスポンスヘッダーを読み取ります。

header(
  headerName: string,
  isRequestHeader: boolean
): Promise<string | string[] | undefined>

パラメーター	型	説明
`headerName`	string	リクエストヘッダーまたはレスポンスヘッダー名。読み取り時に小文字へ変換されます。
`isRequestHeader`	boolean	`true` はリクエストヘッダー、`false` はレスポンスヘッダーを読み取ります。

注意:

サイト設定に追加されたリクエストヘッダーまたはレスポンスヘッダーのみ記録されます。
リクエストヘッダーは、リモートブラウザーがリクエスト送信時に送った header です。
レスポンスヘッダーは、リモートブラウザーがレスポンス受信時に受け取った header です。
レスポンスヘッダーは文字列配列を返す場合があります。

例:

const cookie = await api.header('cookie', true);
const setCookie = await api.header('set-cookie', false);

スクリプト API 付録 ​

目的 ​

api.config ​

api.http ​

api.http.ajax(options) ​

api.user ​

api.user.put(name, value, site, account, did) ​

api.user.get(name, site, account, did) ​

api.user.remove(name, site, account, did) ​

api.user.incr(name, step, site, account, did) ​

api.user.decr(name, step, site, account, did) ​

api.user.startsWith(prefix, site, account, did) ​

api.user.countAll(name, site, account) ​

api.user.sumAll(name, site, account) ​

api.dom ​

api.dom.createMutationObserver(ele, bindStr, childList, subtree, attributes, characterData, fn) ​

api.dom.querySelector(doc, cssOrXPathSelector) ​

api.dom.querySelectorAll(doc, cssOrXPathSelector) ​

api.dom.isVisible(ele) ​

api.dom.getVisibleRect(ele) ​

api.dom.getConnectListeners() ​

api.dom.addConnectListener(cssOrXPathSelector, callback) ​

api.dom.removeConnectListener(cssOrXPathSelectors) ​

api.dom.addResizeListener(cssOrXPathSelector, bindWindowStr, callback, createObserver, delayTime) ​

api.dom.createOverlayBy(cssOrXPathSelector, bindWindowStr, createObserver, delayTime, fn) ​

api.dom.createOverlayByBorder(bindWindowStr, top, right, bottom, left, createObserver, delayTime) ​

api.utils ​

api.utils.wait(fn, timeoutMs, intervalMs) ​

api.utils.runScript(code, callback) ​

api.header(headerName, isRequestHeader) ​