Nút Button
Các quy tắc về ngữ nghĩa, kích thước, hình dạng, trạng thái và khả năng truy cập của Button và IconButton.
AIButton tái sử dụng kích thước và ngữ nghĩa của Button đồng thời thêm trạng thái AI Qokit riêng biệt, dễ nhận biết.
Chọn nút AI để xem trước trạng thái hoạt động của nó.
Quy tắc thành phần nút Qokit
Tài liệu này định nghĩa các quy tắc sử dụng nút trong nền tảng Qokit, Builder, CMS, Dashboard, Admin, trang tiếp thị và các trang được tạo. Mục tiêu là thống nhất thành phần, ngữ nghĩa, hình dạng, kích thước, biểu tượng, trạng thái và khả năng truy cập của nút, tránh việc thiết kế lại nút bằng CSS cục bộ trên từng tuyến đường.
1. Mô hình cốt lõi
Nút không chỉ được phân loại theo "hình bầu dục, hình tròn", mà được cấu thành từ năm chiều độc lập:
Component type × semantic priority × size × shape × spatial elevation
Button / IconButton × primary / secondary / ghost / danger × sm / md / lg × pill / rounded × flat / raised / floating- Loại thành phần quyết định nút có văn bản hiển thị hay không và có bắt buộc duy trì vùng nhấp hình vuông hay không.
- Mức độ ưu tiên ngữ nghĩa quyết định mức độ ưu tiên và màu sắc của nút trong tác vụ hiện tại.
- Kích thước quyết định chiều cao ổn định, cỡ chữ và vùng chạm.
- Hình dạng chỉ quyết định bo góc, không thể hiện mức độ ưu tiên hay ngữ nghĩa nghiệp vụ.
- Cấp bậc không gian chỉ cho biết điều khiển có nổi lên trên mặt phẳng hiện tại hay không, không thay đổi ngữ nghĩa thao tác.
Không tạo ra loại nút mới bằng cách kết hợp thêm tên lớp. Hãy chọn từ các thuộc tính hiện có của thành phần dùng chung.
2. Lựa chọn thành phần
Button
Dùng cho tất cả các thao tác có văn bản hiển thị, bao gồm:
- Nút chỉ có văn bản;
- Nút có biểu tượng trước văn bản;
- Nút có biểu tượng sau văn bản;
- Liên kết trang có giao diện giống nút.
Button trong nền tảng mặc định sử dụng pill bo góc toàn phần, trông giống hình bầu dục. Miễn là nút chứa văn bản hiển thị, không nên chuyển sang nút biểu tượng hình tròn.
variant được tách rời khỏi bóng đổ: primary mặc định dùng raised, secondary, danger, ghost mặc định dùng flat. Các thao tác bên trong hàng danh sách, thẻ, thanh công cụ và viên nang phức hợp phải là flat; thao tác chính độc lập có thể dùng raised; chỉ các thao tác nổi trên nội dung mới dùng floating. Viên nang độc lập hoặc điều khiển phân đoạn chỉ vẽ bóng đổ một lần ở lớp ngoài cùng, tuyến đường không được ghi đè cấp bậc dùng chung bằng CSS cục bộ.
import { Button } from '@qokit/components/ui';
<Button type="button" variant="primary">
保存
</Button>
<Button
leadingIcon={<SaveIcon aria-hidden="true" />}
type="button"
variant="primary"
>
保存
</Button>
<Button
href="/projects"
trailingIcon={<ArrowRightIcon aria-hidden="true" />}
variant="secondary"
>
查看项目
</Button>IconButton
Dùng cho các thao tác công cụ gọn chỉ có một biểu tượng, không có văn bản hiển thị, ví dụ: đóng, thêm, quay lại, chuyển đổi menu hoặc xóa.
IconButton duy trì chiều rộng, chiều cao bằng nhau và bo góc toàn phần ở mọi kích thước, do đó về mặt hình ảnh là nút hình tròn. Mặc định dùng ghost và bắt buộc ở cấp độ kiểu là aria-label.
import { IconButton } from '@qokit/components/ui';
<IconButton aria-label="关闭" tooltip="关闭" type="button">
<CloseIcon aria-hidden="true" />
</IconButton>Quy tắc:
- Bản thân biểu tượng dùng
aria-hidden="true", tên nút doaria-labelcung cấp. - Các biểu tượng không quen thuộc hoặc có thể không rõ nghĩa nên dùng thêm
Tooltipdùng chung; tooltip không thể thay thếaria-label. - Không dùng thuộc tính DOM
titlelàm gợi ý sản phẩm, cũng không đặttooltipđồng thời bọc Tooltip thủ công. - Tooltip là lớp thông tin chỉ đọc, không phải nút bầu dục. Nó dùng bo góc Tooltip gọn dùng chung, không được dùng lại hình ảnh
pill, hover, pressed hay focus của nút. - Không dùng
Buttonvới văn bản trống, văn bản ẩn hoặc chiều rộng cố định để mô phỏngIconButton. - Không đặt
shapechoIconButton; hình tròn là ràng buộc thành phần của nó.
Các trường hợp không nên dùng Button
- Tab dùng các thành phần tương ứng như Tabs/PillTabs/Segmented.
- Mục menu dùng thành phần tương ứng Menu/ActionMenu.
- Trạng thái, nhãn và kết quả lọc dùng Pill hoặc thành phần trạng thái.
- Điều hướng văn bản thông thường dùng liên kết ngữ nghĩa; chỉ khi cần nhấn mạnh ở mức nút mới dùng
Buttonvớihref.
3. Cấp bậc ngữ nghĩa variant
| Variant | Ý nghĩa | Tình huống điển hình | Hạn chế sử dụng |
|---|---|---|---|
primary | Thao tác chính trong khu vực hiện tại | Lưu, xuất bản, tạo, trải nghiệm ngay | Một khu vực tác vụ thường chỉ giữ một thao tác chính |
secondary | Thao tác rõ ràng nhưng ở cấp thấp hơn | Xem trước, hủy, quay lại, nhập | Không nên cạnh tranh sự chú ý trực quan với thao tác chính |
ghost | Thao tác công cụ ngữ cảnh, nhấn mạnh thấp | Đóng, thêm, thao tác thanh công cụ, quay lại nhẹ | Mặc định trong suốt, không thể là CTA quan trọng duy nhất |
danger | Thao tác xóa hoặc gây phá hủy rõ rệt | Xóa mục, gỡ nội dung, xóa dữ liệu | Chỉ thể hiện ngữ nghĩa phá hủy, không dùng làm màu nhấn mạnh thông thường |
variant thể hiện cấp bậc ngữ nghĩa và trực quan, không phải hình dạng. Ví dụ ghost có thể là nút bầu dục có văn bản, cũng có thể là IconButton hình tròn.
Thứ tự chọn:
- Tìm bước tiếp theo quan trọng nhất duy nhất của tác vụ hiện tại, đặt làm
primary. - Các thao tác phụ trợ vẫn cần rõ ràng dùng
secondary. - Thao tác nhấn mạnh thấp trong thanh công cụ hoặc ngữ cảnh dùng
ghost. - Chỉ thao tác thực sự phá hủy mới dùng
danger, và tuân theo quy trình xác nhận hiện có.
Không chọn variant dựa trên "màu nào đẹp hơn".
4. Kích thước size
| Size | Chiều cao/Đường kính | Cỡ chữ | Tình huống khuyến nghị |
|---|---|---|---|
sm | 40px | 14px | Thanh điều hướng trên cùng, thanh công cụ gọn, khu vực làm việc dày đặc |
md | 44px | 15px | Biểu mẫu mặc định, CMS, hộp thoại và thao tác thông thường |
lg | 48px | 16px | CTA chính trang tiếp thị, thao tác chính cần khả năng chạm tốt hơn |
Kích thước mặc định là md.
- Cùng một nhóm nút dùng cùng một kích thước.
- Điều khiển gọn không được dưới 40px; thao tác chính trên di động ưu tiên ít nhất 44px.
- Chiều cao của
Buttonvà đường kính củaIconButtondùng cùng bộ token kích thước, do đó có thể căn chỉnh trong cùng một thanh công cụ; kích thước biểu tượng hiển thị củaIconButtonthống nhất là 18px. - Cỡ chữ của
Buttondo token dùng chung tương ứng với size quyết định, không kế thừa cỡ chữ từ Header, Dialog hay bất kỳ vùng chứa cha nào khác. - CSS tuyến đường có thể điều khiển sắp xếp, khoảng cách và chiều rộng cần thiết của nút, nhưng không được định nghĩa lại chiều cao hoặc cỡ chữ của nút dùng chung.
- Khi văn bản dài, ưu tiên điều chỉnh bố cục hoặc vùng chứa nút, không giải quyết bằng cách nén chiều cao, phông chữ hoặc khoảng cách trái phải.
5. Hình dạng shape
| Shape | Biểu hiện | Phạm vi sử dụng |
|---|---|---|
pill | Bo góc toàn phần; khi có văn bản là hình bầu dục | Mặc định nền tảng, phù hợp trang tiếp thị, Dashboard, Builder, CMS và Admin |
rounded | Bo góc 12px | Chỉ dùng khi chủ đề trang được tạo yêu cầu rõ ràng bo góc nhỏ hơn |
Button mặc định là shape="pill". Frontend nền tảng không được đặt rõ rounded, cũng không được ghi đè bo góc trong CSS cục bộ.
// 平台默认:省略 shape 即为 pill
<Button type="button" variant="primary">保存</Button>
// 仅生成站点主题有明确视觉要求时使用
<Button shape="rounded" type="button" variant="primary">
预约咨询
</Button>IconButton luôn là hình tròn, không tham gia lựa chọn nghiệp vụ pill / rounded.
6. Quy tắc biểu tượng
- Biểu tượng trước văn bản dùng
leadingIcon, biểu tượng sau văn bản dùngtrailingIcon. - Một nút thường chỉ dùng một biểu tượng phụ trợ.
- Các thao tác quen thuộc như lưu, thêm, quay lại có thể dùng biểu tượng để tăng nhận diện, nhưng biểu tượng không thể thay thế văn bản hiển thị của nút quan trọng.
- Mũi tên thể hiện tiếp tục, đi vào hoặc mở rộng thường đặt sau văn bản; biểu tượng quay lại thường đặt trước văn bản.
- Không tự viết bố cục biểu tượng và văn bản trong
children, thành phần đã cung cấp khe icon và label. - Dùng biểu tượng dùng chung và kế thừa
currentColor, không mã hóa cứng màu hoặc kích thước biểu tượng trong CSS tuyến đường. - Trạng thái tải phải giữ nguyên chiều rộng và chiều cao của nút, đồng thời cung cấp văn bản ngắn dễ hiểu hoặc phản hồi tải hiện có; không để việc chuyển đổi văn bản gây nhảy thanh công cụ.
7. Nút và liên kết
Thao tác và điều hướng phải dùng đúng ngữ nghĩa:
- Các thao tác trên trang hiện tại như gửi, lưu, mở lớp phủ, chuyển đổi trạng thái dùng
Buttonkhông cóhref, cuối cùng render thành<button>. - Đi đến tuyến đường hoặc tài nguyên khác dùng
Buttoncóhref, cuối cùng render thành Next.js<Link>. - Nút không phải gửi trong biểu mẫu phải ghi rõ
type="button"; nút gửi ghi rõtype="submit". - Không dùng
onClickđể mô phỏng điều hướng trang thông thường.
Liên kết bị vô hiệu hóa sẽ dùng aria-disabled và rời khỏi thứ tự Tab; nút gốc bị vô hiệu hóa sẽ dùng disabled. Trạng thái vô hiệu hóa không được chỉ thể hiện bằng cách giảm độ trong suốt, logic nghiệp vụ cũng phải chặn thao tác.
8. Trạng thái và khả năng truy cập
Thành phần dùng chung chịu trách nhiệm thống nhất cho hover, focus-visible, disabled và trạng thái màu. Mã nghiệp vụ vẫn cần đáp ứng:
- Nút thường chưa chọn khi hover dùng
--control-surface-hover; khi nhấn, chọn và mở rộng dùng--control-surface-active.focus-visiblegiữ--focus-ringtrên bề mặt trung tính, kiểu tuyến đường không được gộp hover và trạng thái duy trì thành cùng một quy tắc xanh nhạt. - Tên nút phải trực tiếp, cụ thể và nói rõ điều gì sẽ xảy ra, ví dụ "Lưu", "Xuất bản trang web", "Xóa mục".
IconButtonphải cung cấparia-labelđã được bản địa hóa.- Biểu tượng trang trí dùng
aria-hidden="true", tránh trình đọc màn hình đọc lặp. - Tiêu điểm bàn phím phải hiển thị; CSS tuyến đường không được gỡ bỏ focus ring dùng chung.
- Không dùng hover làm gợi ý duy nhất, tương tác phải hỗ trợ cả bàn phím và chạm.
- Nút bị vô hiệu hóa chỉ dùng cho thao tác người dùng tạm thời không thực hiện được; nếu cần giải thích lý do, nên cung cấp chú thích gần hoặc tooltip.
- Lỗi, yêu cầu quyền, rủi ro, chi phí và thông tin quan trọng khác của tác vụ phải luôn hiển thị; Tooltip chỉ bổ sung thông tin, không được là cách duy nhất để phát hiện các thông tin này.
- Thao tác không đồng bộ phải chống gửi trùng lặp và giữ phản hồi đang xử lý dễ hiểu.
- Thao tác nguy hiểm dùng
dangervà dùng lại pattern xác nhận nguy hiểm hiện có; không chỉ dựa vào màu đỏ để truyền tải rủi ro. - Văn bản nút bằng tiếng Trung hoặc ngôn ngữ khác không được cắt ngắn đến mức không hiểu được. Phải kiểm tra văn bản dài và chiều rộng trên di động.
9. Ranh giới trách nhiệm kiểu dáng
Cấu trúc, ngữ nghĩa và trạng thái của nút dùng chung do Button / IconButton phụ trách; token trực quan và CSS dùng chung do gói thành phần phụ trách; tuyến đường chỉ phụ trách bố cục.
Lớp dùng chung phụ trách
- DOM, ngữ nghĩa liên kết/nút, hành vi disabled;
- Khe icon/label và ràng buộc kiểu khả năng truy cập;
- Lớp variant, size, shape;
- Chiều cao, bo góc, đệm, cỡ chữ, độ đậm phông;
- Nền, màu văn bản, bóng đổ, hover, focus-visible và trạng thái disabled.
Lớp tuyến đường có thể phụ trách
- Hướng nhóm nút, khoảng cách, căn chỉnh và xuống dòng;
- Sắp xếp phản hồi;
width: 100%hoặc chiều rộng vùng chứa cần thiết cho quy trình cụ thể;- Tên lớp định vị không thay đổi trực quan cơ bản.
Lớp tuyến đường không được phụ trách
- Viết lại chiều cao, cỡ chữ, bo góc, nền, màu văn bản, bóng đổ hoặc focus ring của nút;
- Dùng màu mã hóa cứng hoặc
border-radius: 999pxđể triển khai lại nút dùng chung; - Thêm biến thể trực quan cục bộ như
primary-alt,outline-blue,icon-round; - Cạnh tranh với ràng buộc nút dùng chung bằng
!important; - Sao chép trực tiếp kiểu cơ bản của
.qk-ui-button.
Nếu thực sự xuất hiện biến thể ngữ nghĩa mới cần cho nhiều trang, nên trước tiên thiết lập ràng buộc thống nhất trong ButtonVariant, token và primitives.css dùng chung, thay vì thêm kiểu trong tuyến đường.
10. Tham khảo nhanh API
type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonShape = 'rounded' | 'pill';Các thuộc tính chính của Button:
| Thuộc tính | Giá trị mặc định | Mô tả |
|---|---|---|
variant | primary | Cấp bậc ngữ nghĩa và trực quan |
size | md | Chiều cao, cỡ chữ và đệm ngang |
shape | pill | Hình dạng bo góc của Button |
leadingIcon | Không có | Biểu tượng trước văn bản |
trailingIcon | Không có | Biểu tượng sau văn bản |
href | Không có | Khi cung cấp sẽ render thành liên kết |
disabled | false | Vô hiệu hóa tương tác |
tooltip | Không có | Nội dung bổ sung của Tooltip dùng chung; không thể thay thế thông tin quan trọng hiển thị hoặc aria-label |
tooltipPlacement | bottom | Hướng ưu tiên; Tooltip dùng chung có thể lật để保持在 trong khung nhìn |
tooltipPortal | true | Render bên ngoài vùng chứa bị cắt và không thêm lớp bọc bố cục |
skin | Không có | Cung cấp khe lớp và biến thích ứng theo ràng buộc skeleton/skin |
IconButton kế thừa các thuộc tính Button phù hợp, nhưng không cung cấp shape, leadingIcon hoặc trailingIcon; nó yêu cầu aria-label, mặc định variant="ghost".
Khuyến nghị ghi rõ variant và type nút gốc trong mã nghiệp vụ, để ngữ nghĩa thao tác rõ ràng khi xem xét mã.
11. Các tổ hợp thường dùng
// 主要操作:椭圆形文字按钮
<Button type="submit" variant="primary">
保存
</Button>
// 次要操作
<Button type="button" variant="secondary" onClick={onPreview}>
预览
</Button>
// 低强调文字操作
<Button type="button" variant="ghost" onClick={onCancel}>
取消
</Button>
// 图标 + 文字,仍然使用 Button
<Button
leadingIcon={<PlusIcon aria-hidden="true" />}
type="button"
variant="primary"
>
新建内容
</Button>
// 纯图标:圆形按钮
<IconButton aria-label="更多操作" tooltip="更多操作" type="button">
<MoreIcon aria-hidden="true" />
</IconButton>
// 危险操作
<Button type="button" variant="danger" onClick={openDeleteConfirm}>
删除项目
</Button>12. Danh sách kiểm tra đánh giá
Trước khi gửi UI liên quan đến nút, xác nhận:
- Có ưu tiên dùng lại
ButtonhoặcIconButtonkhông? - Nút có văn bản và nút chỉ biểu tượng đã chọn đúng thành phần chưa?
- Khu vực tác vụ hiện tại chỉ có một
primaryrõ ràng không? secondary,ghost,dangercó được dùng theo ngữ nghĩa thay vì sở thích màu sắc không?Buttonnền tảng có giữ mặc địnhpill,IconButtoncó giữ hình tròn không?- Mỗi Tooltip có vẫn là lớp thông tin bo góc gọn, không giống nút bầu dục có thể nhấp không?
- Đã loại bỏ
titlegốc trình duyệt, bong bóngdata-tooltipCSS, gợi ý trùng lặp và Tooltip đồng nghĩa của nút văn bản chưa? - Kích thước chỉ dùng
sm,md,lg, và chiều cao cùng cỡ chữ trong cùng nhóm nhất quán không? - Nút gốc đã đặt đúng
typerõ ràng chưa? - Biểu tượng có ẩn thông tin đọc màn hình trùng lặp,
IconButtoncóaria-labelđã bản địa hóa không? - Trạng thái focus-visible, disabled, không đồng bộ và xác nhận nguy hiểm có đầy đủ không?
- CSS tuyến đường chỉ xử lý bố cục, không ghi đè trực quan cơ bản của nút?
- Đã kiểm tra văn bản dài, kích thước chạm và sắp xếp nhóm nút ở chiều rộng desktop và di động chưa?
13. Nguồn triển khai
- API thành phần:
packages/components/src/ui/Button/Button.tsx - Export thành phần:
packages/components/src/ui/Button/index.ts - Token kích thước và màu:
packages/components/src/styles/foundations.css - Kiểu nút dùng chung:
packages/components/src/styles/primitives.css - Ràng buộc tích hợp thành phần công khai:
docs/public/design/component-integration.md
Khi tài liệu và triển khai có khác biệt, nên đồng bộ hóa thành phần, token, kiểu và tài liệu này trong cùng một thay đổi.