Apéndice de API de scripts

Objetivo

Describe las capacidades de window.api disponibles para scripts de página del sitio y scripts de interceptación de API, incluidas lectura de configuración, solicitudes HTTP, datos de usuario, herramientas DOM, utilidades generales y lectura de encabezados de solicitud/respuesta.

Los scripts de página y los scripts de interceptación de API normal pueden usar window.api. Los scripts SSE solo garantizan que se pase data y normalmente no dependen 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

Lee la configuración personalizada del entorno de scripts del sitio.

config: Record<string, unknown>

Ejemplo:

const apiBase = api.config.apiBase;

api.http

api.http proporciona helpers HTTP para scripts de usuario. api.http.ajax ejecuta la solicitud real en el proceso principal del navegador, por lo que no está restringido por la política CORS de la página.

api.http.ajax(options)

Envía una solicitud 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;
}>

Opción	Tipo	Valor predeterminado	Descripción
url	string	-	URL de la solicitud.
method	string	GET	Método HTTP.
data	any	-	Datos de la solicitud. Para GET y HEAD, se serializa en la cadena de consulta. Para otros métodos, se escribe en el cuerpo de la solicitud.
headers	Record<string, string>	{}	Encabezados de la solicitud.
timeout	number	-	Tiempo de espera en milisegundos. Solo se aplica cuando es mayor que 0.
dataType	'json' | 'text' | 'html' | 'arrayBuffer'	json	Modo de análisis de la respuesta.
contentType	string	application/x-www-form-urlencoded; charset=UTF-8	Content-Type del cuerpo de la solicitud.
processData	boolean	true	Si se serializa automáticamente data. Use false para pasar data directamente como cuerpo de la solicitud.

Valor devuelto:

Campo	Tipo	Descripción
ok	boolean	true para respuestas HTTP 2xx; false para errores de análisis, errores HTTP, timeout, abort o errores de red.
status	number	Código de estado HTTP. 0 indica timeout, abort o fallo de nivel de red.
statusText	string	Texto de estado HTTP, o timeout, abort o error para fallos no HTTP.
data	any	Datos de respuesta analizados, presentes cuando el análisis tiene éxito.
error	string	Mensaje de error, presente en fallos de análisis o fallos no HTTP.
timeout	boolean	true cuando la solicitud fue abortada por el timeout configurado.

Ejemplos:

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 se usa para leer y escribir datos asociados al usuario durante la ejecución del script.

Parámetros comunes:

Parámetro	Tipo	Valor predeterminado	Descripción
site	boolean	false	Si se almacena por sitio.
account	boolean	false	Si se almacena por cuenta.
did	boolean	false	Si se almacena por dispositivo.

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

Guarda el par clave-valor especificado.

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

Ejemplo:

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

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

Lee el par clave-valor especificado.

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

Ejemplo:

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

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

Elimina el par clave-valor especificado.

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

Ejemplo:

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

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

Aumenta el valor numérico de la clave por el paso. Si no existe, se crea con step.

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

Ejemplo:

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

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

Disminuye el valor numérico de la clave por el paso. Si no existe, se crea con step * -1.

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

Ejemplo:

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

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

Busca todos los datos cuyo nombre de clave empieza con el prefijo especificado.

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

Ejemplo:

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

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

Cuenta registros con el nombre de clave especificado.

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

Ejemplo:

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

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

Calcula la suma numérica de los valores del nombre de clave especificado.

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

Ejemplo:

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

api.dom

api.dom ofrece consultas DOM, comprobación de visibilidad, listeners de conexión, listeners de tamaño y creación de overlays.

Selectores admitidos:

Formato	Descripción
.button.primary	Selector CSS.
xpath://div[@id="app"]	Selector XPath.
.dialog:p	Devuelve el elemento padre del elemento coincidente.
.dialog:p2	Devuelve el padre dos niveles por encima del elemento coincidente.
.header:bottom	Usa el borde inferior del elemento objetivo en métodos de borde de overlay.
.sidebar:right	Usa el borde derecho del elemento objetivo en métodos de borde de overlay.

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

Crea y almacena en caché un MutationObserver. Si ele[bindStr] ya existe, devuelve directamente el observer existente.

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

Ejemplo:

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

api.dom.querySelector(doc, cssOrXPathSelector)

Consulta el primer elemento coincidente.

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

Ejemplo:

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

api.dom.querySelectorAll(doc, cssOrXPathSelector)

Consulta todos los elementos coincidentes.

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

Ejemplo:

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

api.dom.isVisible(ele)

Determina si el elemento está en un área de intersección visible.

isVisible(ele: HTMLElement): Promise<boolean>

Ejemplo:

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

api.dom.getVisibleRect(ele)

Obtiene el rectángulo visible actual del elemento.

getVisibleRect(ele: HTMLElement): Promise<DOMRectReadOnly>

Ejemplo:

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

api.dom.getConnectListeners()

Obtiene la lista actual de listeners de conexión.

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

Ejemplo:

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

api.dom.addConnectListener(cssOrXPathSelector, callback)

Escucha si el elemento objetivo aparece en el documento o desaparece de él.

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

Ejemplo:

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

api.dom.removeConnectListener(cssOrXPathSelectors)

Elimina listeners de conexión para los selectores especificados.

removeConnectListener(cssOrXPathSelectors: string[]): void

Ejemplo:

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

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

Escucha cambios de tamaño y posición del elemento objetivo. Si el elemento no existe, el callback recibe new DOMRect(0, 0, 0, 0).

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

Ejemplo:

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

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

Crea un overlay de posición fija que sigue el área visible del elemento objetivo.

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

Ejemplo:

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)

Crea un overlay de posición fija mediante cuatro bordes. Cada borde puede ser un valor numérico en píxeles o un selector; los selectores pueden usar :top, :right, :bottom, :left.

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

Ejemplo:

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)

Hace polling hasta que la función de condición devuelve un valor verdadero.

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

Al expirar, lanza Error("Timeout: function did not return true in time.").

Ejemplo:

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

api.utils.runScript(code, callback)

Ejecuta código JavaScript en la página actual.

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

Ejemplo:

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

api.header(headerName, isRequestHeader)

Lee encabezados de solicitud o respuesta registrados por el navegador remoto.

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

Parámetro	Tipo	Descripción
headerName	string	Nombre de encabezado de solicitud o respuesta; se convierte a minúsculas al leerse.
isRequestHeader	boolean	true lee encabezados de solicitud; false lee encabezados de respuesta.

Notas:

• Solo se registran encabezados agregados en la configuración del sitio.
• Los encabezados de solicitud provienen de los headers enviados por el navegador remoto.
• Los encabezados de respuesta provienen de los headers recibidos por el navegador remoto.
• Los encabezados de respuesta pueden devolver arrays de cadenas.

Ejemplo:

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