Áp dụng cho api_version: "2026-01".
Mọi extension nhận một đối tượng pos để đọc ngữ cảnh, gọi Open API và ra lệnh cho giao diện POS.
- Extension trong worker (block, action, hook, trang Worker UI):
poslà biến toàn cục do runtime POS nạp sẵn trước khi module chạy. - Trang iframe:
<PosProvider>của@pancake-pos/ui(hoặcconnect()của SDK) đưaposcho trang (xem Trang iframe).
Type đầy đủ có trong gói @pancake-pos/ui-extensions (xem SDK & CLI).
Tổng quan
interface Pos {
apiVersion: string; // ví dụ "2026-01"
target: string; // target của extension đang chạy
extensionId: string; // id khai trong manifest
app: { id: string; handle: string; version: string };
shop: { id: number; name: string; currency: string; country: string; timezone: string };
user: { id: string; name: string; locale: string };
data: unknown; // dữ liệu ngữ cảnh, schema theo target
api: PosApi; // gọi Open API
format: PosFormat; // định dạng số, tiền, ngày như màn hình POS
session: { getToken(): Promise<{ token: string; expiresAt: string }> };
toast: { show(message: string, options?: ToastOptions): void };
ui: {
confirm(options: ConfirmOptions): Promise<boolean>;
modal<T>(options: OverlayOptions): Promise<T | null>; // trang iframe của app trong modal của POS
drawer<T>(options: OverlayOptions): Promise<T | null>;
};
download(file: DownloadFile): Promise<void>;
clipboard: { copy(text: string): Promise<void> };
navigate(to: NavigateTarget): void;
refresh(): void;
close(result?: unknown): void;
on(event: PosEvent, handler: (payload: any) => void): () => void;
}Phạm vi khả dụng
| API | Block | Action headless | Action modal/fullscreen | Hook, should_render | Trang |
|---|---|---|---|---|---|
shop, user, app, data |
✓ | ✓ | ✓ | ✓ | ✓ |
api, session, format |
✓ | ✓ | ✓ | ✓ | ✓ |
toast, ui.confirm, download, clipboard |
✓ | ✓ | ✓ | ✓ | |
ui.modal, ui.drawer |
✓ | ✓ | ✓ | ✓ ¹ | |
navigate |
✓ | ✓ | ✓ | ✓ | |
refresh |
✓ | ✓ | ✓ | ||
close |
✓ | ² | |||
on('data-change') |
✓ | ✓ | ✓ | ||
page.setTitle, page.setPrimaryAction, on('primary-action') |
✓ ¹ | ||||
page.setHeader, page.setFrame, page.setBackdrop, on('header-action'), on('backdrop-dismiss') |
iframe ¹ |
¹ Trừ trang đang hiện trong modal/drawer của pos.ui.modal/drawer (một lớp, không có dòng tiêu đề của POS).
² Chỉ trang iframe đang hiện trong modal/drawer của pos.ui.modal/drawer.
Gọi API ngoài phạm vi sẽ ném lỗi PosRuntimeError với code: 'unavailable'.
pos.data
Dữ liệu ngữ cảnh của vị trí đang chạy, cũng là tham số của hàm export default. Schema từng target xem tại Extension point.
- Các target gắn với bản ghi POS dùng chung một dạng:
pos.data.resourcecho biết loại bản ghi (order,purchase…),pos.data.recordlà bản ghi đã lưu (recordsở thanh thao tác hàng loạt),pos.data.draftlà nội dung form chi tiết. - Trường bị ẩn bởi
access.hidden_order_fieldskhông có trongpos.data. - Với block,
pos.datađược cập nhật khi người dùng sửa form; nghe sự kiệndata-changeđể render lại.
pos.api
Gọi Open API bằng app token. SDK tự gắn token, tự gia hạn và thử lại một lần khi token hết hạn.
interface PosApi {
baseUrl: string; // gốc Open API, ví dụ "https://pos.pages.fm/api/v1"
request<T = any>(options: {
method: 'GET' | 'POST' | 'PUT' | 'DELETE';
path: string; // tương đối với baseUrl: /shops/{shop_id}/... hoặc /geo/...
query?: Record<string, unknown>;
body?: unknown; // gửi dạng JSON
signal?: AbortSignal;
}): Promise<T>;
get<T = any>(path: string, options?: { query?: Record<string, unknown>; signal?: AbortSignal; cache?: number }): Promise<T>;
paginate<T = any>(path: string, options?: PaginateOptions): Promise<{ items: T[]; total: number | null; truncated: boolean }>;
post<T = any>(path: string, body?: unknown, options?: { query?: Record<string, unknown>; signal?: AbortSignal }): Promise<T>;
put<T = any>(path: string, body?: unknown, options?: { query?: Record<string, unknown>; signal?: AbortSignal }): Promise<T>;
delete<T = any>(path: string, options?: { query?: Record<string, unknown>; signal?: AbortSignal }): Promise<T>;
}pathphải thuộc shop hiện tại (/shops/${pos.shop.id}/...). Gọi shop khác bị từ chối. Ngoại lệ duy nhất là danh mục địa chỉ:/geo/provinces,/geo/districts,/geo/communes.- Kết quả là JSON nguyên bản của Open API (thường có dạng
{ success, data, ... }). - Method phải nằm trong
access.methodscủa app; không thì ném lỗi trước khi gửi request.
Cache danh mục
get(path, { cache: giây }) giữ kết quả trong bộ nhớ của extension (tối đa 3600 giây), dùng cho danh mục ít đổi: ĐVVC (/partners), kho, thẻ, tỉnh/thành (/geo/provinces). Lần gọi sau cùng path và query không gửi request; mỗi lần nhận một bản sao nên sửa kết quả không ảnh hưởng lần sau. Một lệnh ghi (POST, PUT, DELETE) thành công xoá toàn bộ cache.
const { data: partners } = await pos.api.get(`/shops/${pos.shop.id}/partners`, { cache: 600 });Tải nhiều trang
paginate tải một danh sách Open API qua nhiều trang, vài trang cùng lúc, trong giới hạn tần suất. Gặp 429 thì tự đợi rồi thử lại (tối đa 3 lần).
type PaginateOptions = {
query?: Record<string, unknown>; // bộ lọc của endpoint; nên kèm fields[] để chỉ lấy trường cần
pageSize?: number; // mặc định 100, tối đa 200
maxItems?: number; // mặc định 2.000, tối đa 20.000
concurrency?: number; // số trang tải cùng lúc, mặc định 3, tối đa 5
pageParam?: 'page_number' | 'page'; // mặc định gửi cả hai (Open API dùng một trong hai tuỳ endpoint)
signal?: AbortSignal; // huỷ khi người dùng đổi bộ lọc
onProgress?: (progress: { loaded: number; total: number | null }) => void;
};
const controller = new AbortController();
const { items, total, truncated } = await pos.api.paginate(`/shops/${pos.shop.id}/orders`, {
query: { startDateTime, endDateTime },
maxItems: 5000,
signal: controller.signal,
onProgress: ({ loaded, total }) => setProgress(total ? (loaded / total) * 100 : 0),
});- Endpoint phải trả
{ data: [...] }; cótotal_entrieshoặctotal_pagesthì các trang được tải song song, không có thì tải lần lượt đến trang thiếu. truncated: truekhi còn bản ghi saumaxItems: báo người dùng thu hẹp bộ lọc.- Báo cáo trên khoảng lớn vẫn chậm vì phải tải từng bản ghi; chọn khoảng ngày mặc định ngắn (7 ngày) và hiện tiến độ bằng
pos-progress.
Lỗi
class PosApiError extends Error {
status: number; // HTTP status
code?: number | string; // error_code của Open API nếu có
body?: unknown; // body trả về
}SDK ném PosApiError khi HTTP status ≥ 400 hoặc body có success: false. Danh sách mã lỗi xem Truy cập dữ liệu › Mã lỗi.
try {
const { record } = pos.data; // order.details.action: record là OrderRef
const res = await pos.api.get(`/shops/${pos.shop.id}/orders/${record.system_id}`);
render(<OrderInfo order={res.data} />, document.body);
} catch (error) {
if (error.status === 403) pos.toast.show('Bạn không có quyền xem đơn này', { tone: 'error' });
else throw error;
}pos.session.getToken
Lấy app token hiện tại để tự gọi Open API bằng thư viện khác.
const { token, expiresAt } = await pos.session.getToken();
await fetch(`${pos.api.baseUrl}/shops/${pos.shop.id}/orders`, {
headers: { Authorization: `Bearer ${token}` },
});Không lưu token lâu dài, không gửi token cho hệ thống bên ngoài, trừ backend của trang tự host. Token hết hạn sau 15 phút; gọi lại getToken() để lấy token mới.
pos.toast.show
type ToastOptions = {
tone?: 'success' | 'error' | 'info' | 'warning'; // mặc định 'success'
duration?: number; // giây, mặc định 3, từ 1 đến 10
};Tối đa 3 toast mỗi 10 giây cho mỗi extension; vượt thì bị bỏ qua.
pos.ui.confirm
Hộp xác nhận do POS vẽ, phủ toàn màn hình.
type ConfirmOptions = {
title: string;
content?: string;
okText?: string; // mặc định "Đồng ý"
cancelText?: string; // mặc định "Huỷ"
danger?: boolean; // nút đồng ý màu đỏ
};
if (await pos.ui.confirm({ title: 'Đẩy đơn sang ERP?' })) {
// ...
}pos.ui.modal, pos.ui.drawer
Mở một trang iframe của app (app.page có render: "iframe") trong modal hoặc drawer của POS, phủ cả màn hình POS. Dùng cho màn hình phức tạp mở từ block, action hay trang: chọn sản phẩm, sửa thông tin giao hàng, xem chi tiết.
type OverlayOptions = {
page?: string; // id của app.page render "iframe"; mặc định trang iframe đầu tiên
path?: string; // đường dẫn trong trang, mặc định "/"
query?: Record<string, string>;
title?: string; // tiêu đề modal; POS ghi kèm tên app
width?: 'small' | 'medium' | 'large'; // modal 520/720/1000 px (mặc định small), drawer 400/560/800 px (mặc định medium)
};
const picked = await pos.ui.drawer<{ id: number }>({ path: '/pick-product', title: 'Chọn sản phẩm', width: 'large' });
if (picked) addProduct(picked.id);- Trang bên trong biết mình đang ở modal qua
pos.data.presentation('modal'hoặc'drawer'), đóng và trả kết quả bằngpos.close(result)(tối đa 256 KB). Người dùng bấm × thì kết quả lànull. - Modal cao theo nội dung trang (
PosProviderbáo chiều cao), không quá màn hình; phần còn lại cuộn trong iframe. Drawer cao hết màn hình. - Một lớp: trang đang ở modal/drawer không mở thêm modal/drawer và không có
pos.page.*. Chuyển sang trang khác của POS thì modal đóng. - Không có trong hook và
should_render. Tham số sai (đường dẫn không bắt đầu bằng/,widthlạ) ném lỗiinvalid_argument; app không có trang iframe nào thì lỗifailed; app đang mở một modal/drawer khác thì lỗibusy(mỗi app một modal cùng lúc). - Action headless đang chờ modal không bị tính vào giới hạn chạy 30 giây.
pos.download
Tải file về máy người dùng. Code chạy trong worker không tạo được link tải, nên POS tải hộ; trang iframe gọi được như vậy. Có hai cách:
- Bảng (
sheet): app truyền cột và dòng, POS dựng file.xlsxhoặc.csv. Số, tiền, phần trăm, ngày có định dạng như màn hình POS, hàng tiêu đề theo style file Excel của POS. App không cần thư viện Excel. - Nội dung (
content): app tự tạo file (chữ hoặc byte).
type SheetColumn = {
key: string; // trường của dòng, có thể là đường dẫn như customer.name
title: string;
format?: 'text' | 'number' | 'money' | 'percent' | 'date' | 'datetime' | 'badge' | 'link'; // badge, link xuất thành chữ
};
type DownloadFile =
| { filename: string; sheet: { name?: string; columns: SheetColumn[]; rows: object[] } } // .xlsx, .csv
| { filename: string; content: string | ArrayBuffer | ArrayBufferView; type?: string }; // .csv, .xlsx, .json, .txt, .pdf
// Dùng lại cột của pos-table và bản ghi Open API như đang hiển thị.
await pos.download({ filename: 'don-hang.xlsx', sheet: { name: 'Đơn hàng', columns, rows: orders } });
const csv = ['Mã đơn,Khách hàng,Tổng tiền', ...rows.map((r) => [r.id, r.name, r.total].join(','))].join('\n');
await pos.download({ filename: 'don-hang.csv', content: csv });sheet: tối đa 50 cột, 20.000 dòng. Giá trị là object hay mảng thì để trống ô; chuỗi bắt đầu bằng=,+,-,@được ghi là chữ, không thành công thức.- Tối đa 10 MB mỗi file. Loại khác, file quá lớn hoặc
content,sheetsai dạng némPosRuntimeErrorvớicode: 'invalid_download'. - File CSV được thêm BOM UTF-8 để Excel đọc đúng tiếng Việt.
- Không có trong hook và
should_render.
pos.clipboard.copy
Chép chữ (mã vận đơn, mã đơn, link) vào clipboard của người dùng. Worker không truy cập clipboard được nên POS chép hộ và hiện thông báo "Đã sao chép."; app không cần báo thêm.
await pos.clipboard.copy(order.partner.extend_code);- Tối đa 10.000 ký tự. Trình duyệt chặn (ví dụ trang không được focus) thì ném lỗi.
- Ô bảng chỉ cần chép giá trị: dùng
copyable: truecủa cộtpos-table, không cần gọi API này.
pos.navigate
Chuyển tới một trang của app, hoặc mở một bản ghi của POS.
type NavigateTarget =
| { page: string; path?: string; query?: Record<string, string> } // page: id extension app.page
| { resource: 'order'; id: number | string }; // id: system_id của đơn
pos.navigate({ page: 'home', path: '/returns', query: { order_id: String(pos.data.record.system_id) } });
pos.navigate({ resource: 'order', id: order.system_id });resourcemở chi tiết bản ghi trong POS ở tab mới, để trang báo cáo, danh sách của app giữ nguyên bộ lọc và vị trí. Hiện hỗ trợ đơn hàng (order);idlà mã dùng trong đường dẫn Open API (system_id).
Nếu đang ở modal, modal đóng trước khi chuyển trang. Nếu đang ở đúng trang đó, POS chỉ đổi URL và phát data-change với path, query mới, không tải lại trang.
pos.format
Định dạng như màn hình POS cho chuỗi app tự ghép (tiêu đề, mô tả, nội dung bản in). Cột bảng, pos-stat, pos-money đã được POS định dạng sẵn theo format, không cần gọi.
interface PosFormat {
number(value: number, digits?: number): string; // theo ngôn ngữ người dùng, tối đa 2 chữ số lẻ: 1.234,5
percent(value: number, digits?: number): string; // 12.5 → "12,5%"
money(value: number): string; // theo tiền tệ của shop: "916.460 ₫", "$ 12,345.67"
date(value: string | number | Date): string; // "01/10/2026"
datetime(value: string | number | Date): string; // "01/10/2026 08:05", theo giờ máy người dùng
}
pos.toast.show(`Đã đối soát ${pos.format.number(count)} đơn, lệch ${pos.format.money(diff)}`);moneynhận giá trị như Open API trả về và theo quy tắc tiền tệ của POS (ký hiệu, dấu thập phân; tiền tệ có phần lẻ như USD và mãVND100,PHP100lưu theo 1/100 đơn vị).pos.shop.currencycó thể làVND100,PHP100: mã nội bộ của POS cho đồng, peso lưu tới 2 số lẻ, không phải ISO 4217. Cần mã ISO (dịch vụ ngoài) thì bỏ hậu tố100và chia số tiền cho 100.datenhậnYYYY-MM-DD(ngày theo lịch, không lệch múi giờ), chuỗi ISO, số mili giây hoặcDate. Giá trị không hợp lệ trả''.
pos.refresh
Yêu cầu POS tải lại dữ liệu của màn hình hiện tại (ví dụ đơn hay phiếu nhập đang mở) sau khi app đã cập nhật qua Open API.
- POS tải lại danh sách đang xem và bản ghi đang mở. Thay đổi chưa lưu trên form của bản ghi đó bị thay bằng dữ liệu mới.
- Nhiều lần gọi liên tiếp được gộp lại: mỗi loại bản ghi tải lại tối đa 1 lần mỗi 3 giây.
pos.close
Đóng modal/fullscreen của action đang mở. Trang iframe đang hiện trong modal/drawer của pos.ui.modal truyền kèm kết quả cho bên đã mở: pos.close({ id: 5 }).
Sự kiện
const off = pos.on('data-change', (data) => {
// data có schema giống pos.data
});
off(); // huỷ đăng ký| Sự kiện | Phát khi | Payload |
|---|---|---|
data-change |
Dữ liệu ngữ cảnh thay đổi, ví dụ người dùng sửa form chi tiết (gom trong 300 ms) hoặc trang đổi đường dẫn | pos.data mới |
primary-action |
Người dùng bấm nút chính của trang (iframe hoặc Worker UI) | không có |
header-action |
Người dùng bấm nút trang iframe đặt bằng pos.page.setHeader |
{ id, item? } (item: mục của nút có danh sách) |
backdrop-dismiss |
Người dùng bấm vùng mờ của POS hoặc nhấn Esc khi trang iframe đã bật pos.page.setBackdrop |
{ via: 'click' | 'escape' } |
Trang Worker UI
Trang render: "worker" chạy trong worker như block: dùng biến pos toàn cục và element pos-* (xem Component › Trang Worker UI). pos.page có ở trang Worker UI như trang iframe:
pos.page.setTitle('Đối soát ngày 12/05');
pos.page.setPrimaryAction({ label: 'Xuất Excel', loading: false });
pos.on('primary-action', exportExcel);heading của pos-page (nếu có) hiện thay tiêu đề đặt bằng setTitle ở dòng tiêu đề; setTitle vẫn là tiêu đề của tab trình duyệt.
Với TypeScript, pos.page có kiểu tuỳ chọn vì chỉ trang mới có; trong module của trang dùng pos.page! hoặc (pos as PosPage).page.
Trang iframe
Trang render: "iframe" là một ứng dụng web bình thường, được phục vụ tại gốc domain sandbox của app. Mọi đường dẫn không phải file tĩnh đều trả về index.html, nên router dùng basename là /. Đường dẫn bắt đầu bằng /_pos/ dành riêng cho POS: không dùng làm route hay đường dẫn file.
Cách khuyến nghị là @pancake-pos/ui: <PosProvider> kết nối POS, áp theme, font, khung, rồi usePos() trả pos. Không dùng React thì gọi connect():
import { connect } from '@pancake-pos/ui-extensions/page';
const pos = await connect(); // chờ POS gửi ngữ cảnh và token
// pos.data: { path, query, presentation? }Ngoài các API ở trên, trang iframe có thêm:
interface PosPage {
setTitle(title: string): void;
setPrimaryAction(action: { label: string; disabled?: boolean; loading?: boolean } | null): void;
setHeader(header: { heading?: string; description?: string; actions?: HeaderAction[] } | null): Promise<boolean>;
setFrame(frame: { background: 'none' | 'card' }): Promise<boolean>; // false: POS chưa hỗ trợ
setBackdrop(on: boolean): Promise<boolean>;
}
type HeaderAction = {
id: string;
label?: string; // tối đa 40 ký tự; nút cần label hoặc icon
icon?: string; // như icon của pos-button
variant?: 'primary' | 'secondary' | 'tertiary' | 'danger';
tooltip?: string;
disabled?: boolean;
loading?: boolean;
items?: { id: string; label: string; danger?: boolean; disabled?: boolean }[]; // có items: nút mở danh sách
};
pos.page.setHeader({ heading: 'Công nợ', description: 'Theo khách hàng', actions: [{ id: 'export', label: 'Xuất', icon: 'download' }] });
pos.on('header-action', ({ id, item }) => id === 'export' && exportExcel());
pos.page.setFrame({ background: 'none' });- Dòng tiêu đề:
setHeaderđặt tiêu đề, mô tả và tối đa 5 nút trên dòng tiêu đề của POS (cạnh nút chính củasetPrimaryAction), vẽ như nút củapos-page. Bấm nút phátheader-action.headingđược ưu tiên hơnsetTitle;nulltrả về tiêu đề mặc định. Nút không cólabellẫnicon, hay trùngid, bị bỏ. Trảfalsekhi bản POS chưa hỗ trợ: trang tự vẽ tiêu đề (PosProviderlàm sẵn).PosPagecủa@pancake-pos/uitự gọisetHeadervớiheading,descriptionvà nút trongactions. - Khung: mặc định trang nằm trong thẻ trắng bo góc.
setFrame({ background: 'none' })bỏ thẻ, trang vẽ trên nền xám của POS như trang Worker UI (PosProvidertự gọi;<PosProvider frame="card">giữ thẻ trắng). - Lớp mờ: modal, drawer vẽ trong trang chỉ phủ được iframe. Gọi
setBackdrop(true)khi mở,setBackdrop(false)khi đóng: POS làm mờ phần ngoài iframe (dòng tiêu đề, menu, thanh trên); bấm vùng mờ hay nhấn Esc phátbackdrop-dismissđể trang đóng lớp trên cùng. Trang vẫn để mờ sau lần bấm đầu thì lần bấm thứ hai POS tự tắt lớp mờ.PosModal,PosDrawer,usePosBackdropcủa@pancake-pos/uitự gọi. Trảfalsekhi bản POS chưa hỗ trợ. - Đồng bộ URL: SDK theo dõi
history.pushState,replaceStatevàpopstatetrong iframe rồi cập nhật URL của POS. Khi mở link có sẵn, iframe được nạp đúng đường dẫn tương ứng. - Chiều cao: iframe chiếm toàn bộ vùng nội dung của POS; trang tự cuộn bên trong. Trong modal của
pos.ui.modal, modal cao theo nội dung trang. - Modal/drawer: trang mở bằng
pos.ui.modal/drawercópos.data.presentation, đóng bằngpos.close(result). - Giao diện: dùng
@pancake-pos/ui: component cùng tên, thuộc tính với elementpos-*, theme, font, token của POS.pos-app checkcảnh báo thư viện UI khác, màu ngoài bảng màu POS, tiền tự định dạng. - Lưu trữ:
localStoragecủa trang iframe thuộc riêng domain sandbox của app, không dùng chung với POS hay app khác.
Trang tự host
Khai url thay cho entry khi trang đã chạy trên máy chủ của bạn, ví dụ web ERP sẵn có. POS nhúng thẳng url vào iframe; gói không cần thư mục page/.
{ "target": "app.page", "id": "home", "title": "ERP", "render": "iframe", "url": "https://erp.example.com/pos" }- Kết nối: trang cài
@pancake-pos/ui(<PosProvider>) hoặc@pancake-pos/ui-extensions(connect()) như trang trong gói;pos.page,pos.api,pos.toast… dùng như nhau. - Mở ngoài POS:
<PosProvider standalone>vẫn vẽ trang khi mở thẳng trên trình duyệt (không có POS),usePosOptional()trảnull; không dùng React thìconnect({ optional: true })trảnullthay vì lỗi,isEmbedded()cho biết trang có nằm trong cửa sổ khác không. - Đường dẫn: phần đường dẫn của
urllà gốc của app./shop/<id>/apps/<handle>/orders/5trong POS tương ứnghttps://erp.example.com/pos/orders/5. Trang đi ra ngoài gốc này (ví dụ/login) thì URL của POS giữ nguyên.pos.data.pathlà đường dẫn thật của trang. - Cho phép POS nhúng: đặt header
Content-Security-Policy: frame-ancestors https://pos.pancake.vn https://pos.pages.fmđể chỉ POS nhúng được trang. Không dựa vào cookie đăng nhập của trang: trình duyệt có thể chặn cookie trong iframe khác domain (Safari chặn mặc định). - Gọi API từ máy chủ của bạn: gửi app token (
pos.session.getToken()) kèm request về backend, backend gọi Open API bằng token đó (Authorization: Bearer). Token hạn 15 phút và chỉ có quyền của app; không lưu token lâu dài. - Duyệt và thay đổi: quản trị viên thấy
urlkhi kích hoạt. Nội dung trang do máy chủ của bạn quyết định và đổi được bất cứ lúc nào mà không qua duyệt version, nên chỉ dùng máy chủ bạn kiểm soát. - Chạy thử:
pos-app dev --page-url http://localhost:3000/posthayurlbằng máy chủ trên máy bạn; hot reload của Vite hay Next vẫn chạy trong iframe.
Môi trường worker
Extension trong worker chỉ được bảo đảm có:
- Cú pháp và đối tượng chuẩn của JavaScript (ES2020).
fetch,Headers,Request,Response,AbortController,URL,URLSearchParams.setTimeout,clearTimeout,setInterval,clearInterval.console(chỉ xem được ở chế độ phát triển).- DOM tối giản do runtime POS cung cấp để Preact hoặc JS thuần dựng element
pos-*:document.createElement,document.createTextNode,append,appendChild,insertBefore,removeChild,remove,setAttribute,removeAttribute,textContent,addEventListener,removeEventListener,parentNode,childNodes,firstChild,nextSibling,CustomEvent.document.bodylà gốc giao diện của extension.
Không dùng: window, document.querySelector, localStorage, sessionStorage, canvas, đo kích thước DOM (getBoundingClientRect…), alert/confirm/prompt, nạp script từ CDN. Các API này có thể không tồn tại hoặc bị khoá bất kỳ lúc nào.
Nhật ký lỗi
- Chế độ phát triển: lỗi và
console.*hiện trong DevTools của trình duyệt; lỗi và cảnh báo của POS đọc được bằng toolget_errorscủa MCP. POS còn kiểm màn hình đang chạy theo Màn hình chuẩn và ghi cảnh báostandard_screen(emoji trong nhãn, section chỉ chứa số, bảng quá nhiều cột…), bắt được cả dữ liệu động màpos-app checkkhông thấy. - Thuộc tính sai kiểu hay element đặt sai chỗ không làm dừng extension: POS bỏ thuộc tính đó (dùng giá trị mặc định) hoặc không vẽ element đó, rồi ghi cảnh báo
invalid_prop,invalid_child,invalid_slot. Số được tự đổi thành chuỗi ở chỗ cần chuỗi (ví dụselectedcủapos-tabs),nullhay''coi như không đặt. - Version đang kích hoạt: lỗi chưa bắt (uncaught), lỗi render, timeout được ghi vào nhật ký lỗi của app, xem trong Nhật ký lỗi của trang quản lý ứng dụng tuỳ biến.
