Skip to Content
Design

Componente Button

Specifiche di semantica, dimensioni, forma, stati e accessibilità per Button e IconButton.

Componente in tempo realePulsante / IconButton / AIButton

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 da aria-label.
  • Le icone non familiari o dal significato potenzialmente ambiguo devono utilizzare anche il Tooltip condiviso; il tooltip non può sostituire aria-label.
  • Non utilizzare l'attributo DOM title come suggerimento di prodotto, né impostare contemporaneamente tooltip e 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 Button con testo vuoto, testo nascosto o larghezza fissa per simulare IconButton.
  • Non impostare shape su IconButton; 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 Button con href solo quando è necessaria un'enfasi visiva da pulsante.

3. Livelli semantici variant

VariantSignificatoScenari tipiciLimiti di utilizzo
primaryAzione principale dell'area correnteSalva, pubblica, crea, prova oraUn'area di attività di solito mantiene una sola azione principale
secondaryAzione chiara ma secondariaAnteprima, annulla, indietro, importaNon deve competere con l'azione principale per l'attenzione visiva
ghostAzione di contesto a bassa enfasiChiudi, altro, azioni della barra degli strumenti, indietro leggeroDi default trasparente, non può essere l'unico CTA chiave
dangerAzione che elimina o causa danni significativiElimina elemento, rimuovi contenuto, svuota datiEsprime 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:

  1. Individuare l'unico passo successivo più importante per l'attività corrente e impostarlo come primary.
  2. Le azioni secondarie che devono rimanere chiaramente visibili utilizzano secondary.
  3. Le azioni a bassa enfasi nella barra degli strumenti o nel contesto utilizzano ghost.
  4. 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

SizeAltezza/diametroDimensione testoScenari consigliati
sm40px14pxNavigazione superiore, barre degli strumenti compatte, aree di lavoro dense
md44px15pxForm predefiniti, CMS, finestre di dialogo e azioni normali
lg48px16pxCTA 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 Button e il diametro di IconButton utilizzano gli stessi token di dimensione, quindi possono essere allineati nella stessa barra degli strumenti; la dimensione visibile dell'icona di IconButton è 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

ShapeAspettoAmbito di utilizzo
pillArrotondamento completo; ovale con testoPredefinito della piattaforma, adatto a pagine di marketing, Dashboard, Builder, CMS e Admin
roundedRaggio di 12pxSolo 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 utilizza trailingIcon.
  • 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.

Azioni e navigazione devono utilizzare la semantica corretta:

  • Per azioni sulla pagina corrente come invio, salvataggio, apertura di un layer, cambio di stato, utilizzare Button senza href, che alla fine renderizza come <button>.
  • Per andare a un'altra rotta o risorsa, utilizzare Button con href, 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 esplicitamente type="submit".
  • Non utilizzare onClick per 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-visible mantiene --focus-ring su 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".
  • IconButton deve fornire aria-label localizzato.
  • 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 danger e 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 predefinitoDescrizione
variantprimaryLivello semantico e visivo
sizemdAltezza, dimensione testo e padding orizzontale
shapepillForma con raggio di Button
leadingIconNessunoIcona prima del testo
trailingIconNessunoIcona dopo il testo
hrefNessunoSe fornito, renderizza come link
disabledfalseDisabilita l'interazione
tooltipNessunoContenuto supplementare per il Tooltip condiviso; non può sostituire informazioni chiave visibili o aria-label
tooltipPlacementbottomDirezione preferita; il Tooltip condiviso può capovolgersi per rimanere nel viewport
tooltipPortaltrueRenderizza fuori dal contenitore ritagliato senza aggiungere wrapper di layout
skinNessunoFornisce 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 Button o IconButton?
  • I pulsanti con testo e solo icona hanno scelto il componente corretto?
  • L'area di attività corrente ha un solo primary chiaro?
  • secondary, ghost, danger sono usati in base alla semantica e non alla preferenza di colore?
  • La piattaforma Button mantiene il default pill, e IconButton mantiene la forma circolare?
  • Ogni Tooltip rimane un livello informativo con raggio compatto, non simile a un pulsante ovale cliccabile?
  • Sono stati eliminati title nativi del browser, bolle CSS data-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 IconButton ha aria-label localizzato?
  • 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.

In questa pagina