Skip to Content

Sổ tay giao diện

Sổ tay giao diện chỉ cách làm màn hình app Manh trông như sản phẩm thật: chọn đúng component Pro cho từng việc và theo sáu quy tắc chung.

Mỗi trang là một loại màn hình: khung app, danh sách, dashboard, form, trang chi tiết. Agent cũng đọc nội dung này qua MCP (framework_docs("pro")), nên bạn và agent dựng giao diện theo cùng một cách. App mẫu để đối chiếu là template Duyệt mua sắm (templates/purchase-requests/), đang chạy ở duyet-mua-sam.manh.run.

Nên đọc trước

  1. Màn hình nghiệp vụ — năm màn hình nghiệp vụ hoàn chỉnh chạy ngay trong docs.
  2. Chọn component theo việc — người dùng làm gì thì dùng component nào.
  3. Khung app và đầu trang — AppShell và PageContainer.
  4. Trang danh sách — ProTable có tìm, tab và chọn nhiều.
  5. Dashboard — số KPI, việc cần làm, biểu đồ.
  6. Form — form trong Drawer, form nhiều bước, dòng hàng.
  7. Trang chi tiết — xem một bản ghi và duyệt.
  8. Đăng nhập và đăng ký — LoginForm.
  9. Công thức trang — bố cục các trang thường gặp.
  10. Sơ đồ, kanban, AI chat — khi cần thêm thư viện ngoài bảng và form.
  11. API cần biết — prop của ProTable, form và valueType.

Muốn thử sửa một mẫu và lấy prompt cho agent, mở Playground.

App trông như bản demo: nguyên nhân và cách sửa

App trông như bản demo khi từng phần được tự ghép từ các component nhỏ:

  • Khung tự ghép từ Layout + Menu.
  • Dashboard là Card + Statistic trơn, số không có dòng phụ.
  • Table không có ô tìm, tab trạng thái hay Badge.
  • Form đặt trong một Modal trơn.
  • Màn hình nào cũng là một hộp xám giống nhau.

Thêm CSS không sửa được chuyện này. Hãy dùng component Pro có sẵn bố cục hoàn chỉnh và điền đủ các prop hiển thị nội dung của nó.

Trang chi tiết + duyệtTrang chi tiết: PageContainer (breadcrumb, tag, tóm tắt, số chính) + Steps tiến trình + Info + Timeline + nút quyết định cố định ở chân.
ví-dụ.manh.run · dữ liệu mẫuMở để sửa ↗
Ví dụ chạy khi bạn cuộn tới

Sáu quy tắc cho mọi màn hình

  1. Chọn component theo việc. Khung app → AppShell; đầu trang → PageContainer; danh sách → ResourceList hoặc ProTable; thẻ hoặc dòng tin → ProList; số KPI → StatRow; lịch sử → ActivityLog; một bản ghi chỉ xem → ProDescriptions; form → ProForm, DrawerForm, ModalForm, StepsForm; đăng nhập → LoginForm; trạng thái rỗng, xong, lỗi → Result.
  2. Điền đủ các prop hiển thị nội dung. title, subTitle, tooltip, headerBordered, extra, content, extraContent, valueEnum có status, valueType="money", showTotal, số đếm trên tab, nút ở footer. Thiếu những prop này, màn hình trông như làm dở.
  3. Khoảng cách đều nhau. 24px giữa các khối (<Flex vertical gap={16|24}>), 16px ở những hàng xếp sát. Mọi thẻ trên trang thẳng hàng ở mép trái và mép phải: chia cột bằng Row gutter={[16, 16]} + Col, không dùng ProCard gutter.
  4. Màu chỉ lấy từ token. Đặt màu thương hiệu một lần trong app/theme.tsx, đọc màu bằng theme.useToken(). Không tự gõ mã hex.
  5. Trạng thái luôn là Badge. Bảng, danh sách và trang chi tiết dùng chung một bảng valueEnum: { text, status: "Success" | "Error" | "Processing" | "Warning" | "Default" }.
  6. Không dùng onBack trên PageContainer hay PageHeader vì trang sẽ sập. Dùng header.breadcrumb.

Cần biết

  • ProCard gutter làm các thẻ thụt vào khoảng 8px so với thẻ rộng ở trên và dưới.
  • check cảnh báo code.hardcoded-color khi gặp mã màu gõ tay (trừ lớp phủ trắng / đen trên ảnh nền), và chặn code.no-pagecontainer-onback.

Kiểm tra trước khi deploy

  • Khung là AppShell, menu theo vai trò, mục đang chọn vẫn sáng khi mở trang chi tiết.
  • Mỗi danh sách: chỉ bật ô tìm kiếm cho những cột cần tìm, trạng thái là Badge, tiền canh phải và có định dạng, tab trạng thái chính có số đếm, danh sách rỗng thì có câu hướng dẫn làm gì tiếp.
  • Mỗi số trên dashboard có dòng phụ. Việc cần làm của người đang đăng nhập nằm trên cùng.
  • Từ trên xuống, mọi thẻ thẳng hàng ở mép trái và mép phải.
  • Trang chi tiết: tóm tắt ở đầu trang, số chính ở extraContent, tiến trình bằng Steps, lịch sử bằng ActivityLog, nút chuyển trạng thái bằng FlowActions.
  • Form nằm trong Drawer hoặc Modal, chữ trên nút dùng đúng từ người dùng hay nói, trường khó hiểu có tooltip, tiền và ngày theo định dạng Việt Nam.
  • Trước khi báo xong, đi hết luồng chính của từng vai trò trên bản đã deploy, rồi nhờ chủ app mở từng màn hình chính trên điện thoại và máy tính.

Bước tiếp theo

Cập nhật