Skip to Content

Chọn component theo việc

Bảng tra để chọn component: người dùng làm việc gì trên màn hình thì dùng component nào của antd, pro-components, charts hay antd X, đặt prop nào và tránh lỗi gì.

Chọn theo việc người dùng làm, không theo kiểu dữ liệu. Mỗi dòng có ba phần: component · các prop cần đặt · lỗi cần tránh.

Trang và điều hướng

  • Khung app, menu theo vai trò → AppShell từ manh/shell (menu có roles, count; publicPaths cho trang công khai) · cần khung khác thì dùng ProLayout, không tự dựng Layout.Sider.
  • Tiêu đề trang, nút, tab → PageContainer (title, subTitle, extra là mảng nút, tabList + onTabChange, content cho dòng tóm tắt) · không dùng <h1> + <Space>.
  • Form dài hoặc trang chi tiết có thanh nút Lưu cố định ở cuối trang → FooterToolbar (extra cho tổng tiền hoặc trạng thái, các nút đặt bên trong).

Danh sách việc cần làm

  • Bản ghi cần xử lý theo trạng thái → ProTable với tab ở toolbar.menu (type: "tab") có số đếm Badge, request + params={{ tab }}, cột thao tác valueType: "option", rowSelection + tableAlertOptionRender để duyệt nhiều dòng một lúc · không dùng Table + tự gọi API.
  • Việc đi qua nhiều bước (sản xuất, pipeline, ticket) → bảng kanban: ProCard split="vertical" hoặc Row/Col, mỗi trạng thái một cột chứa ProList hoặc các Card xếp chồng. Kéo giữa các cột bằng @dnd-kit, chỉ cho kéo sang bước kế tiếp hợp lệ; thêm nút “Chuyển bước tiếp” cho người dùng màn hình cảm ứng và bàn phím · không dùng bảng khi người dùng quen nhìn theo cột.
  • Hộp thư, việc chờ tôi duyệt → ProList (metas: title, description, subTitle là Tag, actions, extra) với tab ở toolbar.menu · hợp khi mỗi mục có 1–3 thao tác.
  • Việc hôm nay của một vai trò → lưới ProCard chứa vài ProList nhỏ (“Cần giao hôm nay”, “Hàng sắp về”) trên một trang.

Danh sách bản ghi

  • Danh sách có tìm kiếm → ProTable (search={{ labelWidth: "auto" }} sinh từ cột, valueEnum cho trạng thái và ô chọn, valueType: "money" | "percent" | "dateTime" | "dateRange", hideInSearch / hideInTable, fieldProps), pagination.showTotal, options={{ density: true, setting: false }} · server trả { data, total }.
  • Ít bộ lọc, gọn → LightFilter trong toolbar.filter · nhiều bộ lọc → search của ProTable, hoặc QueryFilter trên trang không có bảng.
  • Quy tắc hay thứ tự ưu tiên người dùng tự sắp → DragSortTable (dragSortKey, onDragSortEnd).
  • Thẻ sản phẩm, thư viện ảnh → ProList grid={{ gutter: 16, column: 3 }} hoặc Card + Image · CheckCard.Group khi người dùng chọn một hay nhiều thẻ.
  • Dữ liệu dạng cây (danh mục, cấp định mức, sơ đồ tổ chức) → Table / ProTable với dòng children, hoặc Tree / TreeSelect để chọn.

Nhập dữ liệu

  • Tạo, sửa một bản ghi từ danh sách → DrawerForm (từ 6 field hoặc có dòng hàng) / ModalForm (tối đa 5 field), trigger là nút mở, onFinish trả true để đóng, initialValues khi sửa · không mở trang riêng.
  • Chứng từ có dòng hàng (đơn hàng, đề nghị mua, hoá đơn) → EditableProTable trong form (recordCreatorProps, editable.type="multiple", cột tiền chỉ đọc) hoặc ProFormList cho nhóm lặp ngắn. Sau khi lưu, hiện tổng do server tính · không để client gửi giá hay tổng tiền.
  • Field phụ thuộc field khác (khách hàng → địa chỉ, sản phẩm → đơn giá) → ProFormDependency / Form.useWatch; lấy lựa chọn từ API bằng ProFormSelect request + showSearch (debounceTime).
  • Tiền, số lượng, phần trăm → ProFormMoney (locale="vi-VN"), ProFormDigit (min, fieldProps.precision), ProFormSlider hoặc ProFormDigit + %.
  • Ngày → ProFormDatePicker / ProFormDateRangePicker với transform sang định dạng API · không chỉ đặt format (check cảnh báo code.proform-date-format-submit).
  • Thiết lập nhiều bước → StepsForm (mỗi bước một StepsForm.StepForm, onFinish ở bước cuối).
  • Cùng field cho bảng, form và chi tiết → một mảng columns + BetaSchemaForm (layoutType="DrawerForm" | "ModalForm" | "Form").
  • Xác nhận thao tác rủi ro → Popconfirm (một lần bấm) · cần lý do → ModalForm có ProFormTextArea bắt buộc · thao tác hàng loạt không hoàn tác được → Modal.confirm nêu số lượng và số tiền.
  • File, ảnh → Upload (listType="picture-card" cho ảnh, beforeUpload kiểm loại file và dung lượng, customRequest gọi API của bạn hoặc URL presignPut), hiện bằng Image (preview).

Xem một bản ghi

  • Đầu trang bản ghi → PageContainer: title + Tag trạng thái + extra chứa những thao tác mà vai trò hiện tại được làm ở trạng thái này. Thao tác nào vai trò này không bao giờ được làm thì ẩn hẳn, đừng chỉ làm mờ.
  • Các field → ProDescriptions (column={{ xs: 1, md: 2, xl: 3 }}, cùng valueType với bảng, dataSource từ API chi tiết).
  • Đang ở bước nào → Steps (current tính từ trạng thái, status="error" khi bị huỷ hoặc từ chối) · nút chuyển trạng thái → FlowActions · lịch sử → ActivityLog (ai · làm gì · lúc nào, mới nhất trên cùng).
  • Danh sách liên quan (dòng hàng, thanh toán, xuất nhập) → ProTable với search={false}, toolBarRender={false}, pagination={false}, dòng summary cho tổng.
  • Chứng từ để in (phiếu giao hàng, hoá đơn) → Descriptions + Table (bordered, size="small") và nút In gọi window.print().

Số liệu và dashboard

  • Hàng KPI → StatRow từ manh/shell (title, value, description so với kỳ trước, chart mini, onClick) · mỗi ô một số, tối đa 4 ô.
  • Biểu đồ (đều từ @ant-design/charts; đặt height, autoFit, hàm định dạng nhãn trục cho tiền):
    • xu hướng theo thời gian → Line / Area;
    • so sánh nhóm → Column / Bar;
    • tỷ trọng (tối đa 6 phần) → Pie có innerRadius;
    • mục tiêu so với thực tế → Progress / Gauge / Liquid;
    • hai đại lượng, hai thang → DualAxes;
    • tỷ lệ rớt qua từng bước → Funnel.
  • Danh sách xếp hạng (khách hàng lớn, đơn trễ) → ProList / Table cỡ nhỏ, mỗi dòng có Progress hoặc Statistic.
  • Hạn chót, lịch hẹn → Calendar với cellRender (antd v6 đã bỏ dateCellRender), hoặc ProTable nhóm theo ngày.

Phản hồi và trạng thái

  • Đang tải → Skeleton hoặc loading của bảng · rỗng → Empty kèm một câu hướng dẫn và nút làm bước tiếp theo · lỗi, không có quyền, đã xong → Result (status="403" | "404" | "success" | "warning").
  • Báo ngắn sau thao tác → App.useApp().message · việc chạy lâu hoặc khác trang → notification · thông báo lỗi 4xx từ server hiện nguyên văn.
  • Trạng thái ở mọi nơi → Badge status / Tag color từ một bảng valueEnum · quá hạn, thiếu hàng → Typography.Text type="danger".
  • Hướng dẫn lần đầu → Tour · chèn hình mờ lên trang in hoặc file xuất → Watermark.

Tính năng AI

Chỉ thêm khi sản phẩm cần. Dùng @ant-design/x: khung chat = Bubble.List + Sender, gợi ý = Prompts, danh sách hội thoại = Conversations. Phía server gọi manh/openai.

Cần biết

  • Badge status của antd viết thường ("success"), còn status trong valueEnum của ProTable viết hoa chữ đầu ("Success"). Nếu dùng chung một bảng cho cả hai, phải chuyển đổi qua lại. Quên bước này thì chấm màu biến mất mà không báo lỗi gì.
  • Kéo thả kanban chỉ là phần giao diện. API vẫn phải từ chối khi có người nhảy cóc bước.

Bước tiếp theo

Cập nhật