Annexe API de script

Objectif

Décrit les capacités window.api disponibles pour les scripts de page de site et les scripts d’interception d’API, notamment la lecture de configuration, les requêtes HTTP, les données utilisateur, les outils DOM, les utilitaires généraux et la lecture des en-têtes de requête/réponse.

Les scripts de page et les scripts d’interception d’API normale peuvent utiliser window.api. Les scripts SSE garantissent seulement la transmission de data et ne dépendent généralement pas de 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`

Lire la configuration personnalisée dans l’environnement de script du site.

config: Record<string, unknown>

Exemple :

const apiBase = api.config.apiBase;

`api.http`

api.http fournit des helpers HTTP pour les scripts utilisateur. api.http.ajax exécute la requête réelle dans le processus principal du navigateur, elle n'est donc pas limitée par la politique CORS de la page.

`api.http.ajax(options)`

Envoie une requête 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;
}>

Option	Type	Valeur par défaut	Description
`url`	string	-	URL de la requête.
`method`	string	`GET`	Méthode HTTP.
`data`	any	-	Données de requête. Pour `GET` et `HEAD`, elles sont sérialisées dans la chaîne de requête. Pour les autres méthodes, elles sont écrites dans le corps de la requête.
`headers`	`Record<string, string>`	`{}`	En-têtes de requête.
`timeout`	number	-	Délai d'expiration en millisecondes. Il ne s'applique que s'il est supérieur à `0`.
`dataType`	`'json' \| 'text' \| 'html' \| 'arrayBuffer'`	`json`	Mode d'analyse de la réponse.
`contentType`	string	`application/x-www-form-urlencoded; charset=UTF-8`	Content-Type du corps de la requête.
`processData`	boolean	`true`	Indique si `data` est sérialisé automatiquement. Définissez `false` pour transmettre directement `data` comme corps de requête.

Valeur de retour :

Champ	Type	Description
`ok`	boolean	`true` pour les réponses HTTP 2xx ; `false` pour les erreurs d'analyse, erreurs HTTP, timeout, abort ou erreurs réseau.
`status`	number	Code d'état HTTP. `0` indique un timeout, un abort ou un échec au niveau réseau.
`statusText`	string	Texte d'état HTTP, ou `timeout`, `abort` ou `error` pour les échecs non HTTP.
`data`	any	Données de réponse analysées, présentes lorsque l'analyse réussit.
`error`	string	Message d'erreur, présent lors des échecs d'analyse ou des échecs non HTTP.
`timeout`	boolean	`true` lorsque la requête a été interrompue par le timeout configuré.

Exemples :

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 sert à lire et écrire les données associées à l’utilisateur pendant l’exécution du script.

Paramètres communs :

Paramètre	Type	Valeur par défaut	Description
`site`	boolean	`false`	Indique si le stockage est séparé par site.
`account`	boolean	`false`	Indique si le stockage est séparé par compte.
`did`	boolean	`false`	Indique si le stockage est séparé par appareil.

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

Enregistre la paire clé-valeur indiquée.

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

Exemple :

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

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

Lit la paire clé-valeur indiquée.

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

Exemple :

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

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

Supprime la paire clé-valeur indiquée.

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

Exemple :

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

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

Augmente la valeur numérique de la clé indiquée selon le pas. Si la clé n’existe pas, elle est créée avec la valeur step.

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

Exemple :

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

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

Diminue la valeur numérique de la clé indiquée selon le pas. Si la clé n’existe pas, elle est créée avec la valeur step * -1.

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

Exemple :

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

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

Recherche toutes les données dont le nom de clé commence par le préfixe indiqué.

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

Exemple :

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

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

Compte le nombre d’enregistrements pour le nom de clé indiqué.

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

Exemple :

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

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

Calcule la somme numérique des valeurs correspondant au nom de clé indiqué.

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

Exemple :

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

`api.dom`

api.dom fournit des requêtes DOM, des contrôles de visibilité, des écouteurs de connexion, des écouteurs de taille et la création d’overlays.

Sélecteurs pris en charge :

Écriture	Description
`.button.primary`	Sélecteur CSS.
`xpath://div[@id="app"]`	Sélecteur XPath.
`.dialog:p`	Retourne l’élément parent de l’élément correspondant.
`.dialog:p2`	Retourne le parent deux niveaux au-dessus de l’élément correspondant.
`.header:bottom`	Utilise la bordure inférieure de l’élément cible dans les méthodes de bordure d’overlay.
`.sidebar:right`	Utilise la bordure droite de l’élément cible dans les méthodes de bordure d’overlay.

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

Crée et met en cache un MutationObserver. Si ele[bindStr] existe déjà, l’observer existant est retourné directement.

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

Exemple :

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

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

Recherche le premier élément correspondant.

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

Exemple :

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

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

Recherche tous les éléments correspondants.

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

Exemple :

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

`api.dom.isVisible(ele)`

Détermine si l’élément se trouve dans une zone d’intersection visible.

isVisible(ele: HTMLElement): Promise<boolean>

Exemple :

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

`api.dom.getVisibleRect(ele)`

Obtient le rectangle visible actuel de l’élément.

getVisibleRect(ele: HTMLElement): Promise<DOMRectReadOnly>

Exemple :

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

`api.dom.getConnectListeners()`

Obtient la liste actuelle des écouteurs de connexion.

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

Exemple :

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

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

Écoute l’apparition ou la disparition de l’élément cible dans le document.

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

Exemple :

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

`api.dom.removeConnectListener(cssOrXPathSelectors)`

Supprime les écouteurs de connexion correspondant aux sélecteurs indiqués.

removeConnectListener(cssOrXPathSelectors: string[]): void

Exemple :

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

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

Écoute les changements de taille et de position de l’élément cible. Si l’élément n’existe pas, le callback reçoit new DOMRect(0, 0, 0, 0).

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

Exemple :

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

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

Crée un overlay en position fixed qui suit la zone visible de l’élément cible.

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

Exemple :

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)`

Crée un overlay en position fixed à partir de quatre bords. Chaque bord peut être une valeur numérique en pixels ou un sélecteur; les sélecteurs peuvent utiliser :top, :right, :bottom, :left.

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

Exemple :

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)`

Interroge jusqu’à ce que la fonction de condition retourne une valeur vraie.

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

Après expiration, l’erreur Error("Timeout: function did not return true in time.") est levée.

Exemple :

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

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

Exécute du code JavaScript dans la page actuelle.

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

Exemple :

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

`api.header(headerName, isRequestHeader)`

Lit les en-têtes de requête ou de réponse enregistrés par le navigateur distant.

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

Paramètre	Type	Description
`headerName`	string	Nom de l’en-tête de requête ou de réponse; il est converti en minuscules à la lecture.
`isRequestHeader`	boolean	`true` lit les en-têtes de requête, `false` lit les en-têtes de réponse.

Remarques :

Seuls les en-têtes ajoutés dans la configuration du site sont enregistrés.
Les en-têtes de requête proviennent des headers envoyés par le navigateur distant.
Les en-têtes de réponse proviennent des headers reçus par le navigateur distant.
Les en-têtes de réponse peuvent retourner des tableaux de chaînes.

Exemple :

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

Annexe API de script ​

Objectif ​

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) ​

Annexe API de script

Objectif

`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)`