Áp dụng cho api_version: "2026-01", gói @pancake-pos/ui từ bản 2026.1.11.
Trang iframe (app.page có render: "iframe") là ứng dụng web tự do: dùng được React, router, thư viện bất kỳ. Để trang nhìn và dùng như các màn hình khác của POS, gói @pancake-pos/ui có:
- Component cùng bộ với Worker UI: mỗi element
pos-*trong Component giao diện có component React cùng tên viết hoa (pos-table→PosTable), cùng thuộc tính và sự kiện. POS cũng vẽ element của Worker UI bằng chính các component này, nên hai kiểu trang giống nhau tới từng điểm ảnh. PosProvider: kết nối POS, áp theme antd, font Inter, ngôn ngữ của người dùng, đưa tiêu đề và nút của trang lên dòng tiêu đề của POS, bỏ thẻ trắng để trang nằm trên nền xám như trang của POS.- Token: màu, chữ, khoảng cách của POS dạng JS, biến CSS và preset Tailwind cho phần tự vẽ.
Ảnh trên là ví dụ iframe-report (lệnh get_example của MCP) với dữ liệu mẫu.
Cài đặt
Dự án tạo bằng create-pos-app đã có sẵn. Thêm vào dự án có sẵn:
npm install @pancake-pos/ui @pancake-pos/ui-extensions antd react react-dom
npm install recharts@2 # chỉ khi dùng PosChartPosProvider
Bọc cả trang trong PosProvider, lấy pos bằng usePos():
import { useState } from 'react';
import { createRoot } from 'react-dom/client';
import { PosFilterBar, PosPage, PosProvider, PosSection, PosTable, PosTextField, PosButton, usePos } from '@pancake-pos/ui';
function App() {
const pos = usePos();
const [search, setSearch] = useState('');
return (
<PosPage heading="Công nợ" description={pos.shop.name} actions={<PosButton icon="download" onClick={exportFile}>Xuất</PosButton>}>
<PosFilterBar>
<PosTextField label="Tìm khách" value={search} onChange={(event) => setSearch(event.detail)} />
</PosFilterBar>
<PosSection>
<PosTable rows={rows} columns={[{ key: 'name', title: 'Khách hàng' }, { key: 'debt', title: 'Còn nợ', format: 'money', align: 'right' }]} />
</PosSection>
</PosPage>
);
}
createRoot(document.getElementById('root')!).render(
<PosProvider>
<App />
</PosProvider>,
);| Thuộc tính | Mặc định | Ý nghĩa |
|---|---|---|
frame |
'plain' |
plain: POS bỏ thẻ trắng quanh iframe, trang vẽ trên nền xám, PosSection là thẻ trắng. card: giữ thẻ trắng, khối có viền |
standalone |
không | Trang tự host mở được cả ngoài POS: true hoặc { locale, currency } cho ngôn ngữ, tiền tệ khi ngoài POS |
font |
true |
Nạp font Inter kèm gói (không tải từ Google Fonts, vì CSP của sandbox chặn font ngoài) |
timeout |
10 giây | Thời gian chờ POS |
fallback |
Spin |
Hiện trong lúc chờ POS |
usePos()trảposnhư Runtime API; ngoàiPosProviderhoặc ngoài POS thì ném lỗi.usePosOptional()trảnullthay vì lỗi.PosPageđưaheading,descriptionvà nút trongactions(PosButton,PosMenuButton) lên dòng tiêu đề của POS quapos.page.setHeader; bấm nút gọi đúngonClick/onSelectcủa nút trong trang. Nút cần chữ thuần hoặcicon; con khác trongactionskhông lên được dòng tiêu đề (console cảnh báo). Trang không dùngPosPagetự gọipos.page.setHeaderđược,PosProviderkhông ghi đè.- Ngôn ngữ của antd (DatePicker, Table, Pagination…) theo ngôn ngữ người dùng: vi, en, th, id, es, pt, lo.
- App đã build bằng SDK trước 2026.1.11 giữ nguyên khung trắng và tiêu đề cũ. Lên SDK mới thì trang chuyển sang nền xám; trang đang tự vẽ nền trắng toàn trang dùng
<PosProvider frame="card">để giữ như cũ. Mở trên bản POS chưa hỗ trợ dòng tiêu đề (POS cũ),PosPagetự vẽ tiêu đề và nút trong trang, trang giữ thẻ trắng.
Component
Viết như element pos-* của Worker UI, đổi tên thẻ:
| Worker UI | Trang iframe |
|---|---|
<pos-stat label="Đơn" value={n} /> |
<PosStat label="Đơn" value={n} /> |
Sự kiện onChange={(e) => set(e.detail)} |
Giống hệt: onChange={(e) => set(e.detail)} |
Slot: <pos-button slot="actions">Xuất</pos-button> |
Thuộc tính: actions={<PosButton>Xuất</PosButton>} (footer của PosModal, PosDrawer cũng vậy) |
Biến toàn cục pos |
const pos = usePos() |
element.focus() qua ref |
ref trỏ vào phần tử DOM của component |
Thuộc tính, giá trị enum, giới hạn xem từng element trong Component giao diện. Component nhận value/checked/selected từ state của bạn (controlled); bỏ trống thì component tự giữ giá trị.
| Nhóm | Component |
|---|---|
| Bố cục | PosStack, PosGrid, PosSection, PosDivider |
| Hiển thị | PosText, PosHeading, PosBadge, PosMoney, PosLink, PosImage, PosDescriptionList, PosTimeline |
| Nhập liệu | PosTextField, PosNumberField, PosSelect, PosCheckbox, PosDatePicker, PosTimePicker, PosDateRange, PosSwitch, PosRadioGroup, PosFileInput |
| Phản hồi | PosBanner, PosSpinner, PosProgress, PosEmpty |
| Dữ liệu và thao tác | PosButton, PosMenuButton, PosTable, PosModal, PosDrawer |
| Trang | PosPage, PosTabs, PosFilterBar, PosStat, PosChart |
PosChartnằm ở@pancake-pos/ui/chartvà cầnrecharts:import { PosChart } from '@pancake-pos/ui/chart'.PosMoney, cộtformat: 'money',PosStat format="money"định dạng theo tiền tệ và quy tắc của shop như màn hình POS; không tự định dạng bằngtoLocaleString.- Vẫn dùng được component antd khác (
Tree,Steps…):PosProviderđã áp theme của POS.
Modal và drawer phủ cả POS
Trang iframe mở modal, drawer theo hai cách:
PosModal, PosDrawer |
pos.ui.modal, pos.ui.drawer |
|
|---|---|---|
| Nội dung | Vẽ trong trang, dùng state của trang | Một trang iframe khác của app, nhận path, query, trả kết quả qua pos.close(result) |
| Cỡ | Cao, rộng tối đa bằng iframe; POS làm mờ phần ngoài iframe | Modal, drawer của POS, cao hết màn hình |
| Mở từ | Trang iframe | Block, action, trang |
| Hợp với | Hộp xác nhận, form ngắn | Panel chi tiết, form rộng |
PosModal, PosDrawer
Modal, drawer vẽ trong iframe chỉ phủ được iframe. Khi PosModal, PosDrawer mở, POS làm mờ dòng tiêu đề, menu và thanh trên quanh iframe như khi POS tự mở modal (pos.page.setBackdrop). Bấm vùng mờ hay nhấn Esc gọi onClose của lớp mở sau cùng, như bấm nền mờ trong trang.
Modal, Drawer của antd hay thư viện khác thì gọi usePosBackdrop để POS làm mờ như vậy:
import { Drawer } from 'antd';
import { usePosBackdrop } from '@pancake-pos/ui';
function Detail({ open, onClose }: { open: boolean; onClose: () => void }) {
usePosBackdrop(open, onClose);
return <Drawer open={open} onClose={onClose}>…</Drawer>;
}Cần gói từ bản 2026.1.12 và bản POS có lệnh này; POS cũ chỉ làm mờ trong iframe như trước.
pos.ui.modal, pos.ui.drawer
Modal, drawer của POS (cao hết màn hình, mở được cả từ block, action) mở một trang iframe của app bằng pos.ui.modal/drawer:
// Trang đang mở: mở chính trang này ở /pick trong drawer của POS.
const picked = await pos.ui.drawer<{ id: number }>({ path: '/pick', title: 'Chọn sản phẩm', width: 'large' });
// Trang ở /pick: biết mình đang ở drawer, nút của PosPage nằm ở chân.
function Pick() {
const pos = usePos();
return (
<PosPage actions={<PosButton variant="primary" onClick={() => pos.close({ id: selected })}>Chọn</PosButton>}>
…
</PosPage>
);
}
const App = () => (usePos().data.presentation === 'drawer' ? <Pick /> : <Report />);Trong modal/drawer, PosPage không có dòng tiêu đề (tiêu đề là title của pos.ui.modal), nút trong actions dính ở đáy như chân modal của POS; modal cao theo nội dung.
Màu, chữ, Tailwind
Phần trang tự vẽ (HTML, CSS riêng) dùng token của POS thay vì mã màu tự chọn; pos-app check cảnh báo màu ngoài bảng màu POS.
import { tokens } from '@pancake-pos/ui';
tokens.color.primary; // '#0050B3'
tokens.color.bgLayout; // nền trang '#EAECF0'
tokens.chart; // màu biểu đồ theo thứ tự series@import '@pancake-pos/ui/tokens.css'; /* biến CSS --pos-color-*, --pos-space-*, --pos-radius-* */
.note { color: var(--pos-color-text-secondary); padding: var(--pos-space-md); }- Tailwind 4:
@import "tailwindcss"; @import "@pancake-pos/ui/tailwind.css";cho classbg-pos-layout,text-pos-secondary,border-pos-border,rounded-pos-card,p-pos-lg,text-pos-body. - Tailwind 3:
import posPreset from '@pancake-pos/ui/tailwind-preset', thêmpresets: [posPreset]vàotailwind.config.js. - Không dùng React:
@pancake-pos/ui/fonts.css(font Inter kèm gói) vàtokens.css; kết nối POS bằngconnect()(xem Runtime API › Trang iframe).
Trang tự host mở ngoài POS
Trang tự host (url) có thể là web dùng riêng, mở thẳng trên trình duyệt. PosProvider standalone vẽ trang với cùng component và nền xám khi không có POS:
<PosProvider standalone={{ locale: 'vi', currency: 'VND' }}>
<App />
</PosProvider>
function App() {
const pos = usePosOptional(); // null khi mở ngoài POS
…
}PosPage ngoài POS tự vẽ dòng tiêu đề trong trang bằng cùng style. Cấu hình máy chủ (frame-ancestors, gửi app token về backend) xem Trang tự host. Ví dụ đầy đủ: get_example với iframe-report và self-hosted trong MCP.
Kiểm tra
pos-app check và npx eslint . có luật cho page/: cảnh báo thư viện UI khác (@mui/*, @chakra-ui/*, bootstrap…), màu ngoài bảng màu POS, tiền tự định dạng, file vào của trang không dùng PosProvider/connect(), Modal, Drawer, Modal.confirm của antd (dùng PosModal/PosDrawer, pos.ui.*); báo lỗi <link>, @import, @font-face trỏ ra ngoài gói.



