Tham chiếu

Runtime API (pos)

Đối tượng pos trong extension và trang iframe: ngữ cảnh, gọi API, toast, điều hướng, sự kiện.

Xem Markdown

Á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): pos là 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ặc connect() của SDK) đưa pos cho trang (xem Trang iframe).

Type đầy đủ có trong gói @pancake-pos/ui-extensions (xem SDK & CLI).

Tổng quan

TypeScript
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.resource cho biết loại bản ghi (order, purchase…), pos.data.record là bản ghi đã lưu (records ở thanh thao tác hàng loạt), pos.data.draft là nội dung form chi tiết.
  • Trường bị ẩn bởi access.hidden_order_fields không có trong pos.data.
  • Với block, pos.data được cập nhật khi người dùng sửa form; nghe sự kiện data-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.

TypeScript
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>;
}
  • path phả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.methods củ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.

TypeScript
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).

TypeScript
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_entries hoặc total_pages thì các trang được tải song song, không có thì tải lần lượt đến trang thiếu.
  • truncated: true khi còn bản ghi sau maxItems: 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

TypeScript
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.

TypeScript
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.

TypeScript
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

TypeScript
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.

TypeScript
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.

TypeScript
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ằng pos.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 (PosProvider bá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 /, width lạ) ném lỗi invalid_argument; app không có trang iframe nào thì lỗi failed; app đang mở một modal/drawer khác thì lỗi busy (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 .xlsx hoặ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).
TypeScript
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, sheet sai dạng ném PosRuntimeError với code: '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.

TypeScript
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: true của cột pos-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.

TypeScript
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 });
  • resource mở 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); id là 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.

TypeScript
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)}`);
  • money nhậ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, PHP100 lưu theo 1/100 đơn vị).
  • pos.shop.currency có 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ố 100 và chia số tiền cho 100.
  • date nhận YYYY-MM-DD (ngày theo lịch, không lệch múi giờ), chuỗi ISO, số mili giây hoặc Date. 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

TypeScript
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:

TypeScript
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():

TypeScript
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:

TypeScript
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ủa setPrimaryAction), vẽ như nút của pos-page. Bấm nút phát header-action. heading được ưu tiên hơn setTitle; null trả về tiêu đề mặc định. Nút không có label lẫn icon, hay trùng id, bị bỏ. Trả false khi bản POS chưa hỗ trợ: trang tự vẽ tiêu đề (PosProvider làm sẵn). PosPage của @pancake-pos/ui tự gọi setHeader với heading, description và nút trong actions.
  • 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 (PosProvider tự 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át backdrop-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, usePosBackdrop của @pancake-pos/ui tự gọi. Trả false khi bản POS chưa hỗ trợ.
  • Đồng bộ URL: SDK theo dõi history.pushState, replaceState và popstate trong 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/drawer có pos.data.presentation, đóng bằng pos.close(result).
  • Giao diện: dùng @pancake-pos/ui: component cùng tên, thuộc tính với element pos-*, theme, font, token của POS. pos-app check cả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ữ: localStorage củ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/.

JSON
{ "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ả null thay 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 url là gốc của app. /shop/<id>/apps/<handle>/orders/5 trong POS tương ứng https://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.path là đườ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 url khi 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/pos thay url bằ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.body là 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 tool get_errors củ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áo standard_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 check khô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ụ selected của pos-tabs), null hay '' 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.