Componente Button
Specifiche di semantica, dimensioni, forma, stati e accessibilità per Button e IconButton.
AIButton riutilizza le dimensioni e la semantica del pulsante, aggiungendo uno stato Qokit AI distintivo e percepibile.
Seleziona il pulsante IA per visualizzare lo stato di lavoro.
Specifiche del componente Button di Qokit
Questo documento definisce le regole di utilizzo dei pulsanti nella piattaforma Qokit, nel Builder, nel CMS, nella Dashboard, nell'Admin, nelle pagine di marketing e nei siti generati. L'obiettivo è uniformare componenti, semantica, forma, dimensioni, icone, stati e accessibilità dei pulsanti, evitando che ogni rotta ridisegni i pulsanti tramite CSS locale.
1. Modello di base
I pulsanti non si classificano semplicemente come "ovali" o "circolari", ma sono composti da cinque dimensioni indipendenti:
Component type × semantic priority × size × shape × spatial elevation
Button / IconButton × primary / secondary / ghost / danger × sm / md / lg × pill / rounded × flat / raised / floating- Tipo di componente determina se il pulsante ha testo visibile e se deve mantenere un'area di clic quadrata.
- Priorità semantica determina la priorità e il colore del pulsante nell'attività corrente.
- Dimensione determina l'altezza fissa, la dimensione del testo e l'area di tocco.
- Forma determina solo il raggio del bordo, senza esprimere priorità o semantica di business.
- Livello spaziale indica solo se il controllo si solleva dal piano corrente, senza modificare la semantica dell'azione.
Non creare nuovi tipi di pulsante combinando nuove classi. Scegli prima tra le proprietà esistenti dei componenti condivisi.
2. Selezione del componente
Button
Utilizzato per tutte le azioni con testo visibile, tra cui:
- Pulsanti con solo testo;
- Pulsanti con icona prima del testo;
- Pulsanti con icona dopo il testo;
- Link di pagina con aspetto di pulsante.
Il Button nella piattaforma utilizza di default il pill completamente arrotondato, con aspetto visivo ovale. Finché il pulsante contiene testo visibile, non deve essere sostituito con un pulsante icona circolare.
variant è disaccoppiato dalle ombre: primary utilizza di default raised, mentre secondary, danger, ghost utilizzano di default flat. Le azioni all'interno di righe di elenco, card, barre degli strumenti e capsule composite devono essere flat; le azioni principali isolate possono essere raised; solo le azioni fluttuanti sopra il contenuto utilizzano floating. Le capsule isolate o i controlli segmentati devono avere l'ombra disegnata una sola volta dal contenitore più esterno; le rotte non devono sovrascrivere i livelli condivisi con CSS locale.
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
Utilizzato per azioni compatte con strumenti che hanno solo un'icona e nessun testo visibile, come chiudere, altro, indietro, attivare menu o eliminare.
IconButton mantiene larghezza, altezza e arrotondamento completo uguali in ogni dimensione, risultando quindi visivamente come un pulsante circolare. Utilizza di default ghost e impone a livello di tipo aria-label.
import { IconButton } from '@qokit/components/ui';
<IconButton aria-label="关闭" tooltip="关闭" type="button">
<CloseIcon aria-hidden="true" />
</IconButton>Regole:
- L'icona stessa utilizza
aria-hidden="true", il nome del pulsante è fornito daaria-label. - Le icone non familiari o dal significato potenzialmente ambiguo devono utilizzare anche il
Tooltipcondiviso; il tooltip non può sostituirearia-label. - Non utilizzare l'attributo DOM
titlecome suggerimento di prodotto, né impostare contemporaneamentetooltipe avvolgere manualmente un Tooltip. - Il Tooltip è un livello informativo di sola lettura, non un pulsante ovale. Utilizza l'arrotondamento compatto condiviso per i Tooltip e non deve riutilizzare
pill, né gli stati visivi hover, pressed o focus del pulsante. - Non utilizzare
Buttoncon testo vuoto, testo nascosto o larghezza fissa per simulareIconButton. - Non impostare
shapesuIconButton; la forma circolare è parte del contratto del componente.
Scenari in cui non utilizzare Button
- Per le schede utilizzare i componenti corrispondenti Tabs/PillTabs/Segmented.
- Per le voci di menu utilizzare i componenti corrispondenti Menu/ActionMenu.
- Per stati, etichette e risultati di filtri utilizzare Pill o componenti di stato.
- Per la navigazione testuale normale utilizzare link semantici; utilizzare
Buttonconhrefsolo quando è necessaria un'enfasi visiva da pulsante.
3. Livelli semantici variant
| Variant | Significato | Scenari tipici | Limiti di utilizzo |
|---|---|---|---|
primary | Azione principale dell'area corrente | Salva, pubblica, crea, prova ora | Un'area di attività di solito mantiene una sola azione principale |
secondary | Azione chiara ma secondaria | Anteprima, annulla, indietro, importa | Non deve competere con l'azione principale per l'attenzione visiva |
ghost | Azione di contesto a bassa enfasi | Chiudi, altro, azioni della barra degli strumenti, indietro leggero | Di default trasparente, non può essere l'unico CTA chiave |
danger | Azione che elimina o causa danni significativi | Elimina elemento, rimuovi contenuto, svuota dati | Esprime solo semantica distruttiva, non come colore di enfasi generico |
variant esprime semantica e livello visivo, non forma. Ad esempio, ghost può essere un pulsante ovale con testo o un IconButton circolare.
Ordine di selezione:
- Individuare l'unico passo successivo più importante per l'attività corrente e impostarlo come
primary. - Le azioni secondarie che devono rimanere chiaramente visibili utilizzano
secondary. - Le azioni a bassa enfasi nella barra degli strumenti o nel contesto utilizzano
ghost. - Solo le azioni effettivamente distruttive utilizzano
danger, mantenendo il flusso di conferma esistente.
Non scegliere il variant in base a "quale colore è più bello".
4. Dimensioni size
| Size | Altezza/diametro | Dimensione testo | Scenari consigliati |
|---|---|---|---|
sm | 40px | 14px | Navigazione superiore, barre degli strumenti compatte, aree di lavoro dense |
md | 44px | 15px | Form predefiniti, CMS, finestre di dialogo e azioni normali |
lg | 48px | 16px | CTA principali nelle pagine di marketing, azioni principali con maggiore touch-friendliness |
La dimensione predefinita è md.
- Lo stesso gruppo di pulsanti utilizza la stessa dimensione.
- I controlli compatti non devono essere inferiori a 40px; le azioni principali su mobile dovrebbero utilizzare almeno 44px.
- L'altezza di
Buttone il diametro diIconButtonutilizzano gli stessi token di dimensione, quindi possono essere allineati nella stessa barra degli strumenti; la dimensione visibile dell'icona diIconButtonè uniformata a 18px. - La dimensione del testo di
Buttonè determinata dal token condiviso corrispondente alla size, non eredita la dimensione del testo da Header, Dialog o altri contenitori padre. - Il CSS delle rotte può controllare disposizione, spaziatura e larghezza necessaria dei pulsanti, ma non può ridefinire l'altezza o la dimensione del testo dei pulsanti condivisi.
- Quando il testo è lungo, dare priorità alla modifica del layout o del contenitore del pulsante, non risolvere comprimendo altezza, font o spaziatura laterale.
5. Forma shape
| Shape | Aspetto | Ambito di utilizzo |
|---|---|---|
pill | Arrotondamento completo; ovale con testo | Predefinito della piattaforma, adatto a pagine di marketing, Dashboard, Builder, CMS e Admin |
rounded | Raggio di 12px | Solo quando il tema del sito generato richiede esplicitamente un raggio minore |
Button è di default shape="pill". Il frontend della piattaforma non deve impostare esplicitamente rounded, né sovrascrivere il raggio nel CSS locale.
// 平台默认:省略 shape 即为 pill
<Button type="button" variant="primary">保存</Button>
// 仅生成站点主题有明确视觉要求时使用
<Button shape="rounded" type="button" variant="primary">
预约咨询
</Button>IconButton è sempre circolare e non partecipa alla scelta di business pill / rounded.
6. Regole per le icone
- L'icona prima del testo utilizza
leadingIcon, l'icona dopo il testo utilizzatrailingIcon. - Un pulsante di solito utilizza una sola icona ausiliaria.
- Azioni familiari come salva, aggiungi, indietro possono utilizzare icone per rafforzare il riconoscimento, ma l'icona non può sostituire il testo visibile dei pulsanti chiave.
- Le frecce che indicano continua, entra o espandi di solito vanno dopo il testo; l'icona indietro di solito va prima del testo.
- Non scrivere a mano il layout di icona e testo in
children; il componente fornisce già gli slot icon e label. - Utilizzare icone condivise ed ereditare
currentColor, non codificare a livello di rotta il colore o la dimensione delle icone nel CSS. - Lo stato di caricamento deve mantenere le dimensioni originali del pulsante e fornire un breve testo comprensibile o un feedback di caricamento esistente; non far sì che il cambio di testo causi salti nella barra degli strumenti.
7. Pulsanti e link
Azioni e navigazione devono utilizzare la semantica corretta:
- Per azioni sulla pagina corrente come invio, salvataggio, apertura di un layer, cambio di stato, utilizzare
Buttonsenzahref, che alla fine renderizza come<button>. - Per andare a un'altra rotta o risorsa, utilizzare
Buttonconhref, che alla fine renderizza come Next.js<Link>. - I pulsanti non di invio all'interno dei form devono scrivere esplicitamente
type="button"; i pulsanti di invio devono scrivere esplicitamentetype="submit". - Non utilizzare
onClickper simulare la navigazione normale tra pagine.
I link disabilitati utilizzano aria-disabled ed escono dall'ordine di Tab; i pulsanti nativi disabilitati utilizzano disabled. Lo stato disabilitato non può essere espresso solo riducendo l'opacità; la logica di business deve anche impedire l'azione.
8. Stati e accessibilità
I componenti condivisi gestiscono uniformemente gli stati hover, focus-visible, disabled e colore. Il codice di business deve comunque soddisfare:
- I pulsanti normali non selezionati in hover utilizzano
--control-surface-hover; premuti, selezionati ed espansi utilizzano--control-surface-active.focus-visiblemantiene--focus-ringsu superfici neutre; gli stili delle rotte non devono unire hover e stato persistente nella stessa regola di azzurro chiaro. - I nomi dei pulsanti devono essere diretti, specifici e descrivere cosa accadrà, come "Salva", "Pubblica sito", "Elimina elemento".
IconButtondeve fornirearia-labellocalizzato.- Le icone decorative utilizzano
aria-hidden="true"per evitare che lo screen reader le ripeta. - Il focus da tastiera deve essere visibile; il CSS delle rotte non deve rimuovere il focus ring condiviso.
- Non utilizzare l'hover come unico suggerimento; l'interazione deve supportare sia tastiera che tocco.
- I pulsanti disabilitati si usano solo per azioni che l'utente non può eseguire temporaneamente; se è necessario spiegare il motivo, fornire una spiegazione vicina o un tooltip.
- Errori, requisiti di autorizzazione, rischi, costi e altre informazioni critiche per l'attività devono rimanere visibili; il Tooltip può solo integrare le informazioni, non essere l'unico modo per scoprirle.
- Le operazioni asincrone devono prevenire l'invio duplicato e mantenere un feedback comprensibile di avanzamento.
- Le azioni pericolose utilizzano
dangere riutilizzano il pattern di conferma pericolosa esistente; non affidarsi solo al rosso per comunicare il rischio. - Il testo dei pulsanti in cinese o altre lingue non deve essere troncato fino a diventare incomprensibile. È necessario verificare testi lunghi e larghezze su mobile.
9. Confini di responsabilità degli stili
La struttura, la semantica e gli stati dei pulsanti condivisi sono gestiti da Button / IconButton; i token visivi e il CSS condiviso sono gestiti dal pacchetto componenti; le rotte gestiscono solo il layout.
Responsabilità del livello condiviso
- DOM, semantica link/pulsante, comportamento disabled;
- Slot icon/label e vincoli di tipo per l'accessibilità;
- Classi variant, size, shape;
- Altezza, raggio, padding, dimensione testo, peso del font;
- Sfondo, colore testo, ombra, stati hover, focus-visible e disabled.
Responsabilità del livello rotta
- Direzione, spaziatura, allineamento e wrapping dei gruppi di pulsanti;
- Disposizione responsiva;
width: 100%o larghezza del contenitore necessari per flussi di lavoro specifici;- Classi di posizionamento che non modificano l'aspetto di base.
Il livello rotta non deve
- Riscrivere altezza, dimensione testo, raggio, sfondo, colore testo, ombra o focus ring del pulsante;
- Reimplementare i pulsanti condivisi con colori hardcoded o
border-radius: 999px; - Aggiungere varianti visive locali come
primary-alt,outline-blue,icon-round; - Competere con il contratto dei pulsanti condivisi usando
!important; - Copiare direttamente gli stili di base di
.qk-ui-button.
Se emergono davvero nuove varianti semantiche necessarie in più pagine, stabilire prima un contratto unificato nei ButtonVariant condivisi, nei token e nei primitives.css, invece di aggiungere stili nelle rotte.
10. Riferimento rapido API
type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonShape = 'rounded' | 'pill';Proprietà principali di Button:
| Proprietà | Valore predefinito | Descrizione |
|---|---|---|
variant | primary | Livello semantico e visivo |
size | md | Altezza, dimensione testo e padding orizzontale |
shape | pill | Forma con raggio di Button |
leadingIcon | Nessuno | Icona prima del testo |
trailingIcon | Nessuno | Icona dopo il testo |
href | Nessuno | Se fornito, renderizza come link |
disabled | false | Disabilita l'interazione |
tooltip | Nessuno | Contenuto supplementare per il Tooltip condiviso; non può sostituire informazioni chiave visibili o aria-label |
tooltipPlacement | bottom | Direzione preferita; il Tooltip condiviso può capovolgersi per rimanere nel viewport |
tooltipPortal | true | Renderizza fuori dal contenitore ritagliato senza aggiungere wrapper di layout |
skin | Nessuno | Fornisce slot di classe e adattamenti di variabili secondo il contratto skeleton/skin |
IconButton eredita le proprietà applicabili di Button, ma non fornisce shape, leadingIcon o trailingIcon; richiede aria-label, con default variant="ghost".
Si consiglia di scrivere esplicitamente variant e type del pulsante nativo nel codice di business, affinché la semantica dell'azione sia chiaramente visibile nella revisione del codice.
11. Combinazioni comuni
// 主要操作:椭圆形文字按钮
<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. Checklist di revisione
Prima di inviare UI relative ai pulsanti, confermare:
- È stata data priorità al riutilizzo di
ButtonoIconButton? - I pulsanti con testo e solo icona hanno scelto il componente corretto?
- L'area di attività corrente ha un solo
primarychiaro? secondary,ghost,dangersono usati in base alla semantica e non alla preferenza di colore?- La piattaforma
Buttonmantiene il defaultpill, eIconButtonmantiene la forma circolare? - Ogni Tooltip rimane un livello informativo con raggio compatto, non simile a un pulsante ovale cliccabile?
- Sono stati eliminati
titlenativi del browser, bolle CSSdata-tooltip, suggerimenti duplicati e Tooltip sinonimi per i pulsanti di testo? - Le dimensioni utilizzano solo
sm,md,lg, con altezza e dimensione testo coerenti nello stesso gruppo? - I pulsanti nativi hanno impostato esplicitamente il corretto
type? - Le icone hanno nascosto le informazioni duplicate per lo screen reader, e
IconButtonhaaria-labellocalizzato? - Gli stati focus-visible, disabled, asincrono e conferma pericolosa sono completi?
- Il CSS delle rotte gestisce solo il layout, senza sovrascrivere l'aspetto di base dei pulsanti?
- Sono stati verificati testi lunghi, dimensioni di tocco e disposizione dei gruppi di pulsanti su larghezze desktop e mobile?
13. Origini dell'implementazione
- API del componente:
packages/components/src/ui/Button/Button.tsx - Export del componente:
packages/components/src/ui/Button/index.ts - Token di dimensione e colore:
packages/components/src/styles/foundations.css - Stili condivisi dei pulsanti:
packages/components/src/styles/primitives.css - Contratto di accesso ai componenti pubblici:
docs/public/design/component-integration.md
Quando ci sono differenze tra documentazione e implementazione, componente, token, stili e questo documento devono essere sincronizzati nella stessa modifica.