Lampiran API Skrip

Tujuan

Menjelaskan kemampuan window.api yang tersedia untuk skrip halaman situs dan skrip intersepsi API, termasuk pembacaan konfigurasi, request HTTP, data pengguna, alat DOM, utilitas umum, serta pembacaan header request/response.

Skrip halaman dan skrip intersepsi API normal dapat menggunakan window.api. Skrip SSE hanya menjamin data diteruskan dan biasanya tidak bergantung pada 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

Membaca konfigurasi kustom dari lingkungan skrip situs.

config: Record<string, unknown>

Contoh:

const apiBase = api.config.apiBase;

api.http

api.http menyediakan helper HTTP untuk skrip pengguna. api.http.ajax menjalankan request sebenarnya di proses utama browser, sehingga tidak dibatasi oleh kebijakan CORS halaman.

api.http.ajax(options)

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

Opsi	Tipe	Default	Deskripsi
url	string	-	URL request.
method	string	GET	Metode HTTP.
data	any	-	Data request. Untuk GET dan HEAD, data diserialisasi ke query string. Untuk metode lain, data ditulis ke body request.
headers	Record<string, string>	{}	Header request.
timeout	number	-	Timeout dalam milidetik. Hanya berlaku jika lebih besar dari 0.
dataType	'json' | 'text' | 'html' | 'arrayBuffer'	json	Mode parsing response.
contentType	string	application/x-www-form-urlencoded; charset=UTF-8	Content-Type body request.
processData	boolean	true	Apakah data diserialisasi otomatis. Set false untuk meneruskan data langsung sebagai body request.

Nilai balik:

Field	Tipe	Deskripsi
ok	boolean	true untuk response HTTP 2xx; false untuk error parsing, error HTTP, timeout, abort, atau error jaringan.
status	number	Kode status HTTP. 0 menunjukkan timeout, abort, atau kegagalan level jaringan.
statusText	string	Teks status HTTP, atau timeout, abort, atau error untuk kegagalan non-HTTP.
data	any	Data response yang sudah diparse, tersedia jika parsing berhasil.
error	string	Pesan error, tersedia untuk kegagalan parsing atau kegagalan non-HTTP.
timeout	boolean	true jika request dibatalkan oleh timeout yang dikonfigurasi.

Contoh:

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 digunakan untuk membaca dan menulis data terkait pengguna selama skrip berjalan.

Parameter umum:

Parameter	Tipe	Default	Deskripsi
site	boolean	false	Apakah penyimpanan dipisah per situs.
account	boolean	false	Apakah penyimpanan dipisah per akun.
did	boolean	false	Apakah penyimpanan dipisah per perangkat.

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

Menyimpan pasangan key-value tertentu.

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

Contoh:

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

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

Membaca pasangan key-value tertentu.

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

Contoh:

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

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

Menghapus pasangan key-value tertentu.

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

Contoh:

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

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

Menambah nilai numerik key tertentu sesuai step. Jika key belum ada, key dibuat dengan nilai step.

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

Contoh:

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

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

Mengurangi nilai numerik key tertentu sesuai step. Jika key belum ada, key dibuat dengan nilai step * -1.

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

Contoh:

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

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

Mencari semua data yang nama key-nya diawali prefix tertentu.

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

Contoh:

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

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

Menghitung jumlah record dengan nama key tertentu.

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

Contoh:

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

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

Menghitung jumlah numerik nilai untuk nama key tertentu.

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

Contoh:

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

api.dom

api.dom menyediakan query DOM, pengecekan visibilitas, listener koneksi, listener ukuran, dan pembuatan overlay.

Dukungan selector:

Pola	Deskripsi
.button.primary	Selector CSS.
xpath://div[@id="app"]	Selector XPath.
.dialog:p	Mengembalikan elemen induk dari elemen yang cocok.
.dialog:p2	Mengembalikan elemen induk dua level di atas elemen yang cocok.
.header:bottom	Menggunakan batas bawah elemen target pada metode batas overlay.
.sidebar:right	Menggunakan batas kanan elemen target pada metode batas overlay.

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

Membuat dan menyimpan MutationObserver di cache. Jika ele[bindStr] sudah ada, observer yang ada langsung dikembalikan.

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

Contoh:

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

api.dom.querySelector(doc, cssOrXPathSelector)

Mencari elemen pertama yang cocok.

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

Contoh:

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

api.dom.querySelectorAll(doc, cssOrXPathSelector)

Mencari semua elemen yang cocok.

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

Contoh:

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

api.dom.isVisible(ele)

Menentukan apakah elemen berada pada area perpotongan yang terlihat.

isVisible(ele: HTMLElement): Promise<boolean>

Contoh:

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

api.dom.getVisibleRect(ele)

Mengambil persegi panjang area terlihat saat ini dari elemen.

getVisibleRect(ele: HTMLElement): Promise<DOMRectReadOnly>

Contoh:

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

api.dom.getConnectListeners()

Mengambil daftar listener koneksi saat ini.

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

Contoh:

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

api.dom.addConnectListener(cssOrXPathSelector, callback)

Memantau apakah elemen target muncul di dokumen atau menghilang dari dokumen.

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

Contoh:

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

api.dom.removeConnectListener(cssOrXPathSelectors)

Menghapus listener koneksi untuk selector tertentu.

removeConnectListener(cssOrXPathSelectors: string[]): void

Contoh:

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

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

Memantau perubahan ukuran dan posisi elemen target. Jika elemen tidak ada, callback menerima new DOMRect(0, 0, 0, 0).

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

Contoh:

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

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

Membuat overlay fixed-position yang mengikuti area terlihat elemen target.

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

Contoh:

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)

Membuat overlay fixed-position dari empat sisi. Setiap sisi dapat berupa nilai piksel numerik atau selector; selector dapat memakai :top, :right, :bottom, :left.

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

Contoh:

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)

Melakukan polling sampai fungsi kondisi mengembalikan nilai truthy.

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

Setelah timeout, akan melempar Error("Timeout: function did not return true in time.").

Contoh:

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

api.utils.runScript(code, callback)

Menjalankan kode JavaScript di halaman saat ini.

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

Contoh:

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

api.header(headerName, isRequestHeader)

Membaca header request atau response yang dicatat browser jarak jauh.

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

Parameter	Tipe	Deskripsi
headerName	string	Nama header request atau response; dikonversi ke huruf kecil saat dibaca.
isRequestHeader	boolean	true membaca header request, false membaca header response.

Catatan:

• Hanya header yang ditambahkan di konfigurasi situs yang dicatat.
• Header request berasal dari header yang dikirim browser jarak jauh.
• Header response berasal dari header yang diterima browser jarak jauh.
• Header response dapat mengembalikan array string.

Contoh:

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