Przycisk Button
Semantyka, wymiary, kształty, stany i specyfikacje dostępności komponentów Button oraz IconButton.
AIButton wykorzystuje rozmiary i znaczenie przycisku, jednocześnie dodając charakterystyczny, wyraźny stan AI Qokit.
Wybierz przycisk AI, aby wyświetlić jego stan działania.
Specyfikacja komponentu Button w Qokit
Dokument ten definiuje zasady używania przycisków na platformie Qokit, w Builderze, CMS, Dashboardzie, Adminie, stronach marketingowych oraz wygenerowanych witrynach. Celem jest ujednolicenie komponentów, semantyki, kształtów, rozmiarów, ikon, stanów i dostępności przycisków, aby uniknąć projektowania przycisków od nowa za pomocą lokalnego CSS w różnych trasach.
1. Model podstawowy
Przyciski nie są klasyfikowane wyłącznie według „owalnych” czy „okrągłych” kształtów, lecz składają się z pięciu niezależnych wymiarów:
Component type × semantic priority × size × shape × spatial elevation
Button / IconButton × primary / secondary / ghost / danger × sm / md / lg × pill / rounded × flat / raised / floating- Typ komponentu określa, czy przycisk posiada widoczny tekst oraz czy musi zachować kwadratową strefę kliknięcia.
- Priorytet semantyczny decyduje o priorytecie przycisku w bieżącym zadaniu oraz jego kolorze.
- Rozmiar ustala stabilną wysokość, wielkość czcionki tekstu oraz obszar dotyku.
- Kształt określa jedynie zaokrąglenie rogów, nie wyrażając priorytetu ani semantyki biznesowej.
- Poziom przestrzenny opisuje wyłącznie, czy kontrolka odrywa się od bieżącej płaszczyzny; nie zmienia semantyki działania.
Nie twórz nowych typów przycisków poprzez dodawanie kombinacji klas CSS. Zamiast tego wybierz istniejące właściwości ze wspólnego komponentu.
2. Wybór komponentu
Button
Stosowane we wszystkich elementach z widocznym tekstem, w tym:
- przyciski z samym tekstem;
- przyciski z ikoną przed tekstem;
- przyciski z ikoną za tekstem;
- linki do stron wyglądające jak przyciski.
W platformie Button domyślnie stosuje się pełne zaokrąglenia pill, co nadaje im kształt owalny. Dopóki przycisk zawiera widoczny tekst, nie należy zastępować go okrągłym przyciskiem z ikoną.
variant jest niezależny od cienia: primary domyślnie używa raised, a secondary, danger i ghost domyślnie używają flat. Akcje wewnątrz wierszy, kart, pasków narzędzi i złożonych kapsuł pozostają flat; samodzielna akcja główna może używać raised; tylko akcja unosząca się nad treścią używa floating. Samodzielna kapsuła lub kontrolka segmentowa rysuje poziom uniesienia tylko na zewnętrznej powłoce, a style tras nie mogą nadpisywać wspólnego poziomu uniesienia lokalnym CSS.
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
Stosowane w przypadku kompaktowych akcji narzędziowych, które zawierają tylko ikonę bez widocznego tekstu, np. zamknięcie, więcej, powrót, przełączenie menu lub usunięcie.
IconButton zachowuje stałą szerokość, wysokość i zaokrąglenie rogów na każdym rozmiarze, dzięki czemu wizualnie jest to przycisk o kształcie koła. Domyślnie używa ghost, a na poziomie typów wymusza użycie aria-label.
import { IconButton } from '@qokit/components/ui';
<IconButton aria-label="关闭" tooltip="关闭" type="button">
<CloseIcon aria-hidden="true" />
</IconButton>Zasady:
- Ikona sama w sobie używa
aria-hidden="true", a nazwa przycisku jest dostarczana przezaria-label. - W przypadku ikon mało znanych lub o niejednoznacznym znaczeniu należy równolegle udostępniać
Tooltip; tooltip nie może zastępowaćaria-label. - Nie należy symulować
IconButtonza pomocąButtonz pustym, ukrytym tekstem lub o stałej szerokości. - Nie ustawiaj
shapedlaIconButton; okrągły kształt jest częścią umowy komponentu.
Scenariusze, w których nie należy używać Button
- Zakładki powinny wykorzystywać odpowiednie komponenty, takie jak Tabs/PillTabs/Segmented.
- Elementy menu powinny korzystać z komponentów Menu/ActionMenu.
- Stany, etykiety i wyniki filtrów powinny używać komponentu Pill lub komponentów stanu.
- Zwykła nawigacja tekstowa powinna stosować semantyczne linki;
Buttonzhrefnależy używać wyłącznie wtedy, gdy wymagane jest wizualne podkreślenie na poziomie przycisku.
3. Poziom semantyczny variant
| Wariant | Znaczenie | Typowe zastosowanie | Ograniczenia |
|---|---|---|---|
primary | Główna akcja w bieżącym obszarze | Zapisz, opublikuj, utwórz, wypróbuj teraz | W ramach jednego obszaru zadania zazwyczaj pozostawia się tylko jedną główną akcję |
secondary | Wyraźna, ale drugorzędna akcja | Podgląd, Anuluj, Wróć, Importuj | Nie powinna konkurować z główną akcją o uwagę wizualną |
ghost | Akcje narzędziowe o niskim stopniu wyróżnienia | Zamknij, Więcej, akcje na pasku narzędzi, lekki powrót | Domyślnie przezroczyste, nie może być jedyną kluczową akcją CTA |
danger | Akcje powodujące usunięcie lub istotne zmiany | Usuń element, usuń treść, wyczyść dane | Wyraża wyłącznie semantykę destrukcyjną, nie używa się jej jako zwykłego koloru wyróżniającego |
variant odnosi się do poziomu semantycznego i wizualnego, a nie kształtu. Na przykład ghost może być owalnym przyciskiem z tekstem lub okrągłym IconButton.
Kolejność wyboru:
- Zidentyfikuj najważniejszy następny krok dla bieżącego zadania i ustaw go jako
primary. - Dla nadal widocznych akcji pomocniczych użyj
secondary. - Do akcji o niskim stopniu wyróżnienia na pasku narzędzi lub w kontekście użyj
ghost. - Tylko rzeczywiste akcje destrukcyjne oznaczaj jako
danger, stosując istniejący proces potwierdzenia.
Nie wybieraj wariantu na podstawie tego, „który kolor lepiej wygląda”.
4. Rozmiar size
| Rozmiar | Wysokość / Średnica | Rozmiar czcionki | Zalecane zastosowanie |
|---|---|---|---|
sm | 40px | 14px | Górna nawigacja, kompaktowe paski narzędzi, gęste obszary robocze |
md | 44px | 15px | Domyślne formularze, CMS, okna dialogowe i standardowe akcje |
lg | 48px | 16px | Główne CTA na stronach marketingowych, akcje główne wymagające lepszej dostępności dotykowej |
Domyślnym rozmiarem jest md.
- W tej samej grupie przycisków stosuj ten sam rozmiar.
- Kompaktowe elementy sterujące nie powinny mieć mniej niż 40px; na urządzeniach mobilnych główne akcje powinny mieć co najmniej 44px.
Buttonpod względem wysokości orazIconButtonpod względem średnicy używają tego samego zestawu tokenów rozmiaru, dzięki czemu można je wyrównać w tym samym pasku narzędzi; widoczny rozmiar ikony wIconButtonjest jednolity i wynosi 18px.- Rozmiar czcionki w
Buttonjest określany przez udostępniony token odpowiadający wartości size i nie dziedziczy rozmiaru czcionki z nagłówków, okien dialogowych ani innych kontenerów nadrzędnych. - Style CSS oparte na trasach mogą kontrolować układ, odstępy i wymaganą szerokość przycisków, ale nie mogą nadpisywać udostępnionej wysokości ani rozmiaru czcionki przycisku.
- Przy dłuższych tekstach należy preferować dostosowanie układu lub kontenera przycisku, a nie zmniejszanie wysokości, rozmiaru czcionki ani odstępów poziomych.## 5. Kształt
shape
| Kształt | Wygląd | Zasięg użycia |
|---|---|---|
pill | Zaokrąglenie pełne; w przypadku tekstu forma owalna | Domyślne dla platformy, stosowane na stronach marketingowych, Dashboard, Builder, CMS i Admin |
rounded | Zaokrąglenie 12px | Tylko wtedy, gdy motyw generowanej strony wyraźnie wymaga mniejszego zaokrąglenia |
Button domyślnie shape="pill". Nie ustawiaj jawnie rounded we frontendzie platformy ani nie nadpisuj zaokrągleń w lokalnym CSS.
// 平台默认:省略 shape 即为 pill
<Button type="button" variant="primary">保存</Button>
// 仅生成站点主题有明确视觉要求时使用
<Button shape="rounded" type="button" variant="primary">
预约咨询
</Button>IconButton zawsze jest okrągły i nie uczestniczy w wyborach biznesowych pill / rounded.
6. Zasady dotyczące ikon
- Ikony przed tekstem używają
leadingIcon, ikony po tekście używajątrailingIcon. - Przycisk zazwyczaj używa tylko jednej ikony pomocniczej.
- Znane operacje, takie jak zapisywanie, dodawanie czy powrót, mogą być wspierane przez ikony dla lepszej rozpoznawalności, ale ikony nie zastępują widocznego tekstu kluczowego przycisku.
- Strzałki oznaczające kontynuację, wejście lub rozwinięcie zwykle umieszcza się po tekście; ikona powrotu zwykle znajduje się przed tekstem.
- Nie ręcznie układaj ikon i tekstu w
children; komponent już zapewnia sloty icon i label. - Używaj współdzielonych ikon i dziedzicz
currentColor; nie koduj na sztywno koloru ani rozmiaru ikony w CSS routingu. - Stan ładowania powinien zachować oryginalne wymiary przycisku i dostarczać zrozumiały krótki tekst lub istniejącą informację o ładowaniu; unikaj skoków paska narzędzi spowodowanych zmianą tekstu.
7. Przyciski i linki
Operacje i nawigacja muszą używać poprawnej semantyki:
- Dla operacji na bieżącej stronie, takich jak wysyłanie, zapisywanie, otwieranie okna modalnego czy przełączanie stanu, używaj
Buttonbezhref, co renderuje się jako<button>. - Aby przejść do innej trasy lub zasobu, używaj
Buttonzhref, co renderuje się jako Next.js<Link>. - Przyciski w formularzach, które nie są przyciskami wysyłającymi, muszą jawnie zawierać
type="button"; przyciski wysyłające muszą jawnie zawieraćtype="submit". - Nie symuluj normalnej nawigacji po stronie za pomocą
onClick.
Wyłączone linki używają aria-disabled i są usuwane z kolejki tabulacji; wyłączone natywne przyciski używają disabled. Stan wyłączony nie może być wyrażany wyłącznie poprzez obniżenie przezroczystości; logika biznesowa również musi blokować operację.
8. Stany i dostępność
Wspólne komponenty odpowiedzialne są za stany hover, focus-visible, disabled oraz kolorów. Kod biznesowy nadal musi spełniać wymagania:
- Zwykłe niezaznaczone przyciski używają przy hover
--control-surface-hover; stany wciśnięty, zaznaczony i rozwinięty używają--control-surface-active.focus-visiblezachowuje--focus-ringna neutralnej powierzchni, a style tras nie mogą łączyć hover i stanów trwałych w jedną niebieską regułę. - Nazwy przycisków muszą być bezpośrednie, konkretne i informować o tym, co się stanie, np. „Zapisz”, „Opublikuj witrynę”, „Usuń projekt”.
IconButtonmusi dostarczać zlokalizowanearia-label.- Ikony dekoracyjne używają
aria-hidden="true", aby uniknąć powtarzalnego odczytu przez czytniki ekranu. - Fokus klawiatury musi być widoczny; style CSS tras nie mogą usuwać wspólnego pierścienia fokusu.
- Nie polegaj wyłącznie na hoverze jako wskaźniku interakcji; interakcja musi obsługiwać zarówno klawiaturę, jak i dotyk.
- Wyłączanie przycisku służy tylko do sytuacji, gdy użytkownik tymczasowo nie może wykonać akcji; jeśli konieczne jest wyjaśnienie przyczyny, należy dostarczyć sąsiedni opis lub tooltip.
- Operacje asynchroniczne muszą zapobiegać wielokrotnemu wysyłaniu i zachować zrozumiałe informacje o postępie.
- Akcje ryzykowne używają
dangeri ponownie wykorzystują istniejący wzorzec potwierdzenia ryzyka; nie polegaj wyłącznie na czerwonym kolorze do przekazywania ryzyka. - Tekst przycisków w języku chińskim lub innych językach nie może być ucinany w sposób uniemożliwiający zrozumienie. Należy zweryfikować długie teksty i szerokość na urządzeniach mobilnych.
9. Granice odpowiedzialności stylów
Struktura, semantyka i stany wspólnych przycisków są odpowiedzialne za Button / IconButton; tokeny wizualne i wspólne CSS są odpowiedzialne za pakiet komponentów; trasa odpowiada wyłącznie za układ.
Warstwa współdzielona odpowiada za
- semantykę DOM, linków/przycisków oraz zachowanie
disabled; - sloty ikony/etykiety i ograniczenia typów dostępności;
- klasy wariantu, rozmiaru i kształtu;
- wysokość, zaokrąglenia, paddingi, rozmiar czcionki i wagę czcionki;
- tło, kolor tekstu, cienie oraz stany hover, focus-visible i disabled.
Warstwa routingu może odpowiadać za
- kierunek, odstępy, wyrównanie i zawijanie grup przycisków;
- responsywne układy;
- szerokość kontenera lub
width: 100%wymagane przez specyficzne przepływy pracy; - klasy pozycyjne nie zmieniające podstawowego wyglądu.
Warstwa routingu NIE MOŻE odpowiadać za
- nadpisywanie wysokości przycisku, rozmiaru czcionki, zaokągleń, tła, koloru tekstu, cieni lub pierścienia focus;
- używanie sztywno zakodowanych kolorów lub ponowne implementowanie wspólnych przycisków za pomocą
border-radius: 999px; - dodawanie lokalnych wariantów wizualnych takich jak
primary-alt,outline-blue,icon-rounditd.; - rywalizację z kontraktem wspólnych przycisków za pomocą
!important; - bezpośrednie kopiowanie podstawowych stylów z
.qk-ui-button.
Jeśli rzeczywiście pojawi się potrzeba nowych wariantów semantycznych wymaganych na wielu stronach, należy najpierw ustanowić ujednolicony kontrakt we wspólnym ButtonVariant, tokenach i primitives.css, zamiast dodawać style w routingach.
10. Szybki odnośnik do API
type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonShape = 'rounded' | 'pill';Główne właściwości Button:
| Właściwość | Wartość domyślna | Opis |
|---|---|---|
variant | primary | Poziom semantyczny i wizualny |
size | md | Wysokość, rozmiar czcionki tekstu oraz poziomy padding |
shape | pill | Zaokrąglenie kształtu Button |
leadingIcon | Brak | Ikona przed tekstem |
trailingIcon | Brak | Ikona po tekście |
href | Brak | Renderowane jako link, gdy podano |
| disabled | false | Wyłącza interakcję |
skin | Brak | Zapewnia slot klas i zmienne zgodne z kontraktem skeleton/skin |
IconButton dziedziczy odpowiednie właściwości Button, ale nie udostępnia shape, leadingIcon ani trailingIcon; wymaga aria-label, domyślnie variant="ghost".
Zaleca się jawne podawanie variant oraz natywnego przycisku type w kodzie biznesowym, aby semantyka operacji była wyraźnie widoczna podczas przeglądu kodu.
11. Często używane kombinacje
// 主要操作:椭圆形文字按钮
<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>Aktualizacja kontraktu Tooltip: nie używaj title DOM ani data-tooltip CSS jako podpowiedzi produktu. Wspólny tooltip przekazuje wyłącznie informacje uzupełniające i nie zastępuje aria-label ani widocznych informacji krytycznych. Dymek nie może używać kształtu przycisku pill; domyślna wartość tooltipPlacement to bottom, a tooltipPortal to true. Nigdy nie łącz title z tooltip.
12. Checklista przeglądowa
Przed przesłaniem interfejsu przycisku zatwierdzania upewnij się:
- Czy najpierw wykorzystano komponenty
ButtonlubIconButton? - Czy dla przycisków z tekstem i samymi ikonami wybrano właściwy komponent?
- Czy w bieżącym obszarze zadania znajduje się tylko jeden wyraźny
primary? - Czy
secondary,ghostidangersą używane zgodnie z semantyką, a nie preferencjami kolorystycznymi? - Czy platformowy
Buttonzachowuje domyślnypill, aIconButtonpozostaje okrągły? - Czy rozmiary używają wyłącznie
sm,mdilg, przy czym w tej samej grupie wysokość i rozmiar czcionki są spójne? - Czy natywne przyciski mają jawnie ustawiony poprawny
type? - Czy ikony ukrywają powtarzające się informacje dla czytników ekranu, a
IconButtonma zlokalizowanyaria-label? - Czy stany focus-visible, disabled, asynchroniczne i potwierdzenia akcji niebezpiecznych są w pełni obsługiwane?
- Czy CSS routingu obsługuje wyłącznie układ, nie nadpisując podstawowego wyglądu przycisków?
- Czy na desktopie i urządzeniach mobilnych zweryfikowano długie teksty, wymiary dotykowe oraz układ grup przycisków?
13. Źródła implementacji
- API komponentu:
packages/components/src/ui/Button/Button.tsx - Eksport komponentu:
packages/components/src/ui/Button/index.ts - Tokeny rozmiaru i koloru:
packages/components/src/styles/foundations.css - Wspólne style przycisków:
packages/components/src/styles/primitives.css - Kontrakt integracji publicznych komponentów:
docs/public/design/component-integration.md
W przypadku rozbieżności między dokumentacją a implementacją należy zsynchronizować komponent, tokeny, style oraz niniejszą dokumentację w ramach jednej zmiany.