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ò →
AppShelltừmanh/shell(menucóroles,count;publicPathscho trang công khai) · cần khung khác thì dùngProLayout, không tự dựngLayout.Sider. - Tiêu đề trang, nút, tab →
PageContainer(title,subTitle,extralà mảng nút,tabList+onTabChange,contentcho 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(extracho 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 →
ProTablevới tab ởtoolbar.menu(type: "tab") có số đếm Badge,request+params={{ tab }}, cột thao tácvalueType: "option",rowSelection+tableAlertOptionRenderđể duyệt nhiều dòng một lúc · không dùngTable+ 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ặcRow/Col, mỗi trạng thái một cột chứaProListhoặc cácCardxế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,subTitlelà 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
ProCardchứa vàiProListnhỏ (“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,valueEnumcho 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 →
LightFiltertrongtoolbar.filter· nhiều bộ lọc →searchcủaProTable, hoặcQueryFiltertrê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ặcCard+Image·CheckCard.Groupkhi 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/ProTablevới dòngchildren, hoặcTree/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),triggerlà nút mở,onFinishtrảtrueđể đóng,initialValueskhi sửa · không mở trang riêng. - Chứng từ có dòng hàng (đơn hàng, đề nghị mua, hoá đơn) →
EditableProTabletrong form (recordCreatorProps,editable.type="multiple", cột tiền chỉ đọc) hoặcProFormListcho 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ằngProFormSelect request+showSearch(debounceTime). - Tiền, số lượng, phần trăm →
ProFormMoney(locale="vi-VN"),ProFormDigit(min,fieldProps.precision),ProFormSliderhoặcProFormDigit+%. - Ngày →
ProFormDatePicker/ProFormDateRangePickervớitransformsang định dạng API · không chỉ đặtformat(checkcảnh báocode.proform-date-format-submit). - Thiết lập nhiều bước →
StepsForm(mỗi bước mộtStepsForm.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 →ModalFormcóProFormTextAreabắt buộc · thao tác hàng loạt không hoàn tác được →Modal.confirmnêu số lượng và số tiền. - File, ảnh →
Upload(listType="picture-card"cho ảnh,beforeUploadkiểm loại file và dung lượng,customRequestgọi API của bạn hoặc URLpresignPut), hiện bằngImage(preview).
Xem một bản ghi
- Đầu trang bản ghi →
PageContainer:title+Tagtrạng thái +extrachứ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ùngvalueTypevới bảng,dataSourcetừ API chi tiết). - Đang ở bước nào →
Steps(currenttí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) →
ProTablevớisearch={false},toolBarRender={false},pagination={false}, dòngsummarycho tổng. - Chứng từ để in (phiếu giao hàng, hoá đơn) →
Descriptions+Table(bordered,size="small") và nút In gọiwindow.print().
Số liệu và dashboard
- Hàng KPI →
StatRowtừmanh/shell(title,value,descriptionso với kỳ trước,chartmini,onClick) · mỗi ô một số, tối đa 4 ô. - Biểu đồ (đều từ
@ant-design/charts; đặtheight,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) →
Piecó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.
- xu hướng theo thời gian →
- Danh sách xếp hạng (khách hàng lớn, đơn trễ) →
ProList/Tablecỡ nhỏ, mỗi dòng cóProgresshoặcStatistic. - Hạn chót, lịch hẹn →
CalendarvớicellRender(antd v6 đã bỏdateCellRender), hoặcProTablenhóm theo ngày.
Phản hồi và trạng thái
- Đang tải →
Skeletonhoặcloadingcủa bảng · rỗng →Emptykè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 colortừ một bảngvalueEnum· 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 statuscủa antd viết thường ("success"), cònstatustrongvalueEnumcủ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
- Khung app và đầu trang — dựng
AppShellvàPageContainertrước mọi màn hình khác. - Trang danh sách —
ProTableđầy đủ, có ví dụ chạy được. - Sơ đồ, kanban, AI chat — khi bảng và form không đủ.
Cập nhật