Skip to Content
Projektowanie

Przycisk Button

Semantyka, wymiary, kształty, stany i specyfikacje dostępności komponentów Button oraz IconButton.

Komponent w trybie czasu rzeczywistegoPrzycisk / Ikona przycisku / AIButton

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 przez aria-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ć IconButton za pomocą Button z pustym, ukrytym tekstem lub o stałej szerokości.
  • Nie ustawiaj shape dla IconButton; 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; Button z href należy używać wyłącznie wtedy, gdy wymagane jest wizualne podkreślenie na poziomie przycisku.

3. Poziom semantyczny variant

WariantZnaczenieTypowe zastosowanieOgraniczenia
primaryGłówna akcja w bieżącym obszarzeZapisz, opublikuj, utwórz, wypróbuj terazW ramach jednego obszaru zadania zazwyczaj pozostawia się tylko jedną główną akcję
secondaryWyraźna, ale drugorzędna akcjaPodgląd, Anuluj, Wróć, ImportujNie powinna konkurować z główną akcją o uwagę wizualną
ghostAkcje narzędziowe o niskim stopniu wyróżnieniaZamknij, Więcej, akcje na pasku narzędzi, lekki powrótDomyślnie przezroczyste, nie może być jedyną kluczową akcją CTA
dangerAkcje powodujące usunięcie lub istotne zmianyUsuń element, usuń treść, wyczyść daneWyraż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:

  1. Zidentyfikuj najważniejszy następny krok dla bieżącego zadania i ustaw go jako primary.
  2. Dla nadal widocznych akcji pomocniczych użyj secondary.
  3. Do akcji o niskim stopniu wyróżnienia na pasku narzędzi lub w kontekście użyj ghost.
  4. 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

RozmiarWysokość / ŚrednicaRozmiar czcionkiZalecane zastosowanie
sm40px14pxGórna nawigacja, kompaktowe paski narzędzi, gęste obszary robocze
md44px15pxDomyślne formularze, CMS, okna dialogowe i standardowe akcje
lg48px16pxGłó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.
  • Button pod względem wysokości oraz IconButton pod 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 w IconButton jest jednolity i wynosi 18px.
  • Rozmiar czcionki w Button jest 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łtWyglądZasięg użycia
pillZaokrąglenie pełne; w przypadku tekstu forma owalnaDomyślne dla platformy, stosowane na stronach marketingowych, Dashboard, Builder, CMS i Admin
roundedZaokrąglenie 12pxTylko 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 Button bez href, co renderuje się jako <button>.
  • Aby przejść do innej trasy lub zasobu, używaj Button z href, 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-visible zachowuje --focus-ring na 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”.
  • IconButton musi dostarczać zlokalizowane aria-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ą danger i 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-round itd.;
  • 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ślnaOpis
variantprimaryPoziom semantyczny i wizualny
sizemdWysokość, rozmiar czcionki tekstu oraz poziomy padding
shapepillZaokrąglenie kształtu Button
leadingIconBrakIkona przed tekstem
trailingIconBrakIkona po tekście
hrefBrakRenderowane jako link, gdy podano
disabledfalseWyłącza interakcję
skinBrakZapewnia 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 Button lub IconButton?
  • 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, ghost i danger są używane zgodnie z semantyką, a nie preferencjami kolorystycznymi?
  • Czy platformowy Button zachowuje domyślny pill, a IconButton pozostaje okrągły?
  • Czy rozmiary używają wyłącznie sm, md i lg, 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 IconButton ma zlokalizowany aria-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.

Na tej stronie