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
- 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.
- Chọn component theo việc — người dùng làm gì thì dùng component nào.
- Khung app và đầu trang —
AppShellvàPageContainer. - Trang danh sách —
ProTablecó tìm, tab và chọn nhiều. - Dashboard — số KPI, việc cần làm, biểu đồ.
- Form — form trong Drawer, form nhiều bước, dòng hàng.
- Trang chi tiết — xem một bản ghi và duyệt.
- Đăng nhập và đăng ký —
LoginForm. - Công thức trang — bố cục các trang thường gặp.
- Sơ đồ, kanban, AI chat — khi cần thêm thư viện ngoài bảng và form.
- 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+Statistictrơn, số không có dòng phụ. Tablekhông có ô tìm, tab trạng thái hay Badge.- Form đặt trong một
Modaltrơ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ụ chạy khi bạn cuộn tới
app/page.tsx
// Trang 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.
// Không dùng PageContainer onBack (làm sập trang trên runtime này) — dùng breadcrumb.
import { useState } from "react";
import { ModalForm, PageContainer, ProCard, ProDescriptions, ProFormTextArea } from "@ant-design/pro-components";
import { Alert, App, Button, Col, Flex, Row, Space, Steps, Tag, Timeline, Typography } from "antd";
import { CheckOutlined, CloseOutlined } from "@ant-design/icons";
export default function Page() {
const { message } = App.useApp();
const [status, setStatus] = useState<"pending" | "approved" | "rejected">("pending");
const [note, setNote] = useState<string | null>(null);
const events = [
{ color: "blue", text: <><b>Trần Thị Lan</b> tạo đề xuất</>, at: "12:52 10/11/2026" },
...(status !== "pending" ? [{ color: status === "approved" ? "green" : "red", text: <><b>Nguyễn Thu Hà</b> {status === "approved" ? "duyệt" : "từ chối"}{note ? <> — <i>“{note}”</i></> : null}</>, at: "vừa xong" }] : []),
];
const decide = (to: "approved" | "rejected") => async (v: { note?: string }) => {
setStatus(to); setNote(v.note ?? null);
message.success(to === "approved" ? "Đã duyệt" : "Đã từ chối");
return true;
};
return (
<PageContainer
header={{
title: "Gia hạn Microsoft 365 Business (12 tháng, 10 user)",
breadcrumb: { items: [{ title: <a>Đề xuất</a> }, { title: "#9" }] },
tags: <Tag color={status === "pending" ? "processing" : status === "approved" ? "success" : "error"}>{status === "pending" ? "Chờ duyệt" : status === "approved" ? "Đã duyệt" : "Từ chối"}</Tag>,
}}
content={
<ProDescriptions column={{ xs: 1, sm: 2, lg: 3 }}>
<ProDescriptions.Item label="Người tạo">Trần Thị Lan · Hành chính</ProDescriptions.Item>
<ProDescriptions.Item label="Hạng mục">Phần mềm</ProDescriptions.Item>
<ProDescriptions.Item label="Cần trước">13/11/2026</ProDescriptions.Item>
</ProDescriptions>
}
extraContent={
<Space orientation="vertical" size={0} style={{ textAlign: "right" }}>
<Typography.Text type="secondary">Số tiền đề xuất</Typography.Text>
<Typography.Text strong style={{ fontSize: 28 }}>18.600.000 ₫</Typography.Text>
</Space>
}
footer={status === "pending" ? [
<ModalForm key="r" title="Từ chối đề xuất" width={480} trigger={<Button danger icon={<CloseOutlined />}>Từ chối</Button>} onFinish={decide("rejected")} modalProps={{ okText: "Từ chối", okButtonProps: { danger: true } }}>
<ProFormTextArea name="note" label="Lý do từ chối" rules={[{ required: true, whitespace: true, message: "Cần ghi lý do" }]} />
</ModalForm>,
<ModalForm key="a" title="Duyệt đề xuất" width={480} trigger={<Button type="primary" icon={<CheckOutlined />}>Duyệt</Button>} onFinish={decide("approved")} modalProps={{ okText: "Duyệt" }}>
<ProFormTextArea name="note" label="Ghi chú (tuỳ chọn)" />
</ModalForm>,
] : undefined}
>
<Flex vertical gap={16}>
<ProCard title="Tiến trình" headerBordered>
<Steps current={status === "pending" ? 1 : 2} status={status === "rejected" ? "error" : status === "approved" ? "finish" : "process"}
items={[{ title: "Gửi đề xuất", content: "Trần Thị Lan · 12:52 10/11" }, { title: status === "pending" ? "Quản lý duyệt" : status === "approved" ? "Đã duyệt" : "Từ chối", content: status === "pending" ? "Cần trước 13/11" : "Nguyễn Thu Hà" }]} />
</ProCard>
{status === "rejected" && <Alert type="error" showIcon title="Bị từ chối bởi Nguyễn Thu Hà" description={`Lý do: ${note}`} />}
<Row gutter={[16, 16]}>
<Col xs={24} lg={15}>
<ProCard title="Thông tin" headerBordered style={{ height: "100%" }}>
<Typography.Paragraph>Bản hiện tại hết hạn cuối tháng, cần gia hạn để không gián đoạn email.</Typography.Paragraph>
</ProCard>
</Col>
<Col xs={24} lg={9}>
<ProCard title="Lịch sử" headerBordered style={{ height: "100%" }}>
<Timeline items={events.map((e) => ({ color: e.color, children: <><div>{e.text}</div><Typography.Text type="secondary" style={{ fontSize: 12 }}>{e.at}</Typography.Text></> }))} />
</ProCard>
</Col>
</Row>
</Flex>
</PageContainer>
);
}
Dán vào Claude Code / ChatGPT / Claude
Làm màn hình "Trang chi tiết + duyệt" cho app của tôi theo mẫu manh.run UI playbook (framework_docs("pro")): Trang 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. Dữ liệu lấy từ API của app qua useApiClient(); nhãn và trường theo spec của tôi.Sáu quy tắc cho mọi màn hình
- Chọn component theo việc. Khung app →
AppShell; đầu trang →PageContainer; danh sách →ResourceListhoặcProTable; 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. - Điền đủ các prop hiển thị nội dung.
title,subTitle,tooltip,headerBordered,extra,content,extraContent,valueEnumcó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ở. - 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ằngRow gutter={[16, 16]}+Col, không dùngProCard gutter. - 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ằngtheme.useToken(). Không tự gõ mã hex. - 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" }. - Không dùng
onBacktrênPageContainerhayPageHeadervì trang sẽ sập. Dùngheader.breadcrumb.
Cần biết
ProCard gutterlàm các thẻ thụt vào khoảng 8px so với thẻ rộng ở trên và dưới.checkcảnh báocode.hardcoded-colorkhi gặp mã màu gõ tay (trừ lớp phủ trắng / đen trên ảnh nền), và chặncode.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ằngSteps, lịch sử bằngActivityLog, nút chuyển trạng thái bằngFlowActions. - 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
- Chọn component theo việc — tra nhanh khi bắt đầu một màn hình mới.
- Trang danh sách — trang mẫu đầy đủ nhất của sổ tay.
- Gọi API từ giao diện — thay dữ liệu mẫu bằng
useApiClient().
Cập nhật