Button-Schaltfläche
Spezifikationen zu Semantik, Größe, Form, Status und Barrierefreiheit von Button und IconButton.
AIButton verwendet die Größen- und Semantikregeln von Button, fügt jedoch einen eindeutigen, wahrnehmbaren Qokit-AI-Zustand hinzu.
Wählen Sie die KI-Schaltfläche aus, um ihren Arbeitszustand vorab anzuzeigen.
Qokit Button-Komponentenspezifikation
Dieses Dokument definiert die Regeln für die Verwendung von Buttons auf der Qokit-Plattform, in Builder, CMS, Dashboard, Admin, Marketing-Seiten und generierten Sites. Ziel ist es, die Komponenten, Semantik, Form, Größe, Icons, Zustände und Barrierefreiheit von Buttons zu vereinheitlichen und zu verhindern, dass verschiedene Routen Buttons durch lokales CSS neu gestalten.
1. Kernmodell
Buttons werden nicht nur nach "oval" oder "rund" kategorisiert, sondern bestehen aus fünf unabhängigen Dimensionen:
Component type × semantic priority × size × shape × spatial elevation
Button / IconButton × primary / secondary / ghost / danger × sm / md / lg × pill / rounded × flat / raised / floating- Der Komponententyp bestimmt, ob sichtbarer Text vorhanden ist und ob die Klickfläche quadratisch bleiben muss.
- Die semantische Priorität bestimmt die Priorität und Farbe des Buttons in der aktuellen Aufgabe.
- Die Größe bestimmt die stabile Höhe, die Schriftgröße des Textes und den Touch-Bereich.
- Die Form bestimmt ausschließlich die Eckenradien und drückt keine Priorität oder geschäftliche Semantik aus.
- Die räumliche Erhebung beschreibt nur, ob sich das Steuerelement von seiner aktuellen Ebene löst; sie ändert nicht die Semantik der Aktion.
Erstellen Sie keine neuen Button-Typen durch das Hinzufügen neuer Klassenkombinationen. Wählen Sie stattdessen zuerst aus den vorhandenen Eigenschaften der Shared Components.
2. Komponentenauswahl
Button
Wird für alle Aktionen mit sichtbarem Text verwendet, einschließlich:
- Reiner Text-Button;
- Button mit Icon vor dem Text;
- Button mit Icon hinter dem Text;
- Seitenlinks, die wie ein Button aussehen.
Button in der Plattform verwendet standardmäßig volle Rundungen pill und wirkt visuell oval. Solange der Button sichtbaren Text enthält, sollte er nicht durch einen runden Icon-Button ersetzt werden.
variant ist vom Schatten entkoppelt: primary verwendet standardmäßig raised; secondary, danger und ghost verwenden standardmäßig flat. Aktionen in Zeilen, Karten, Werkzeugleisten und zusammengesetzten Pillen bleiben flat; eine eigenständige primäre Aktion kann raised verwenden; nur eine über dem Inhalt schwebende Aktion verwendet floating. Eine eigenständige Pille oder segmentierte Steuerung zeichnet die Erhebung nur auf ihrer äußeren Hülle, und Routen dürfen die gemeinsame Erhebung nicht mit lokalem CSS überschreiben.
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
Wird für kompakte Tool-Aktionen verwendet, die nur ein Icon und keinen sichtbaren Text haben, z. B. Schließen, Mehr, Zurück, Menü umschalten oder Löschen.
IconButton behält in jeder Größe gleiche Breite, Höhe und volle Rundung bei, wodurch es visuell rund ist. Es verwendet standardmäßig ghost und erzwingt auf Typenebene aria-label.
import { IconButton } from '@qokit/components/ui';
<IconButton aria-label="关闭" tooltip="关闭" type="button">
<CloseIcon aria-hidden="true" />
</IconButton>Regeln:
- Das Icon selbst verwendet
aria-hidden="true", der Button-Name wird vonaria-labelbereitgestellt. - Unvertraute oder mehrdeutige Icons sollten immer mit einem Shared
Tooltipkombiniert werden; ein Tooltip kannaria-labelnicht ersetzen. - Verwenden Sie keine
Buttonmit leerem, verstecktem Text oder fester Breite, umIconButtonzu simulieren. - Setzen Sie keine
shapefürIconButton; rund ist sein Komponentenvertrag.
Szenarien, in denen Button nicht verwendet werden sollte
- Tabs verwenden die entsprechenden Komponenten wie Tabs/PillTabs/Segmented.
- Menüpunkte verwenden die entsprechenden Komponenten wie Menu/ActionMenu.
- Status, Labels und Filterergebnisse verwenden Pill oder Status-Komponenten.
- Normale Text-Navigation verwendet semantische Links; verwenden Sie nur dann einen
Buttonmithref, wenn eine visuelle Hervorhebung auf Button-Ebene erforderlich ist.
3. Semantische Ebene variant
| Variante | Bedeutung | Typisches Szenario | Nutzungsbeschränkungen |
|---|---|---|---|
primary | Hauptaktion im aktuellen Bereich | Speichern, Veröffentlichen, Erstellen, Jetzt erleben | In einem Aufgabenbereich sollte normalerweise nur eine Hauptaktion beibehalten werden |
secondary | Explizite, aber sekundäre Aktion | Vorschau, Abbrechen, Zurück, Importieren | Sollte nicht um visuelle Aufmerksamkeit mit der Hauptaktion konkurrieren |
ghost | Niedrige Hervorhebung, kontextbezogene Tool-Aktion | Schließen, Mehr, Toolbar-Aktionen, leichtgewichtiges Zurück | Standardmäßig transparent und darf nicht als einzige wichtige CTA dienen |
danger | Aktionen, die löschen oder erheblichen Schaden verursachen | Projekt löschen, Inhalte entfernen, Daten leeren | Drückt nur zerstörerische Semantik aus, dient nicht als normale Hervorhebungsfarbe |
variant drückt semantische und visuelle Hierarchie aus, nicht die Form. Zum Beispiel kann ghost ein ovaler Button mit Text oder ein runder IconButton sein.
Auswahlabfolge:
- Finden Sie den wichtigsten nächsten Schritt für die aktuelle Aufgabe und setzen Sie ihn als
primary. - Für weiterhin klar sichtbare unterstützende Aktionen verwenden Sie
secondary. - Für Aktionen mit niedriger Hervorhebung in der Symbolleiste oder im Kontext verwenden Sie
ghost. - Verwenden Sie
dangernur für tatsächliche zerstörerische Aktionen und folgen Sie dem bestehenden Bestätigungsworkflow.
Wählen Sie die Variante nicht basierend darauf, „welche Farbe besser aussieht“.
4. Größe size
| Größe | Höhe/Durchmesser | Textschriftgröße | Empfohlenes Szenario |
|---|---|---|---|
sm | 40px | 14px | Top-Navigation, kompakte Symbolleisten, dichte Arbeitsbereiche |
md | 44px | 15px | Standardformulare, CMS, Dialoge und allgemeine Aktionen |
lg | 48px | 16px | Haupt-CTA auf Marketing-Seiten, Hauptaktionen mit stärkerer Touch-Anforderung |
Die Standardgröße ist md.
- Verwenden Sie in derselben Button-Gruppe dieselbe Größe.
- Kompakte Steuerelemente dürfen nicht unter 40px liegen; primäre Aktionen auf Mobilgeräten sollten mindestens 44px verwenden.
Buttonverwendet dieselben Größentokens für die Höhe wieIconButtonfür den Durchmesser, sodass sie in derselben Symbolleiste ausgerichtet werden können; die sichtbare Icon-Größe vonIconButtonist einheitlich 18px.- Die Textschriftgröße von
Buttonwird durch das Shared Token entsprechend der Größe bestimmt und erbt nicht die Schriftgröße von Header, Dialog oder anderen übergeordneten Containern. - Routen-CSS kann die Anordnung, den Abstand und die erforderliche Breite von Buttons steuern, darf jedoch die gemeinsame Button-Höhe oder -Schriftgröße nicht neu definieren.
- Bei längeren Texten passen Sie zuerst das Layout oder den Button-Container an; lösen Sie das Problem nicht durch Komprimierung der Höhe, Schriftgröße oder des linken/rechten Abstands.
5. Form shape
| Form | Darstellung | Anwendungsbereich |
|---|---|---|
pill | Volle Rundung; oval bei Text | Plattformstandard, geeignet für Marketing-Seiten, Dashboard, Builder, CMS und Admin |
rounded | 12px Eckenradius | Nur verwendet, wenn das generierte Site-Design explizit einen kleineren Eckenradius erfordert |
Button ist standardmäßig shape="pill". Setzen Sie in der Plattform-Frontend keine expliziten rounded und überschreiben Sie den Eckenradius nicht im lokalen CSS.
// 平台默认:省略 shape 即为 pill
<Button type="button" variant="primary">保存</Button>
// 仅生成站点主题有明确视觉要求时使用
<Button shape="rounded" type="button" variant="primary">
预约咨询
</Button>IconButton ist immer rund und nimmt nicht an der geschäftlichen Auswahl zwischen pill / rounded teil.
6. Regeln für Symbole
- Verwenden Sie
leadingIconfür Symbole vor dem Text undtrailingIconfür Symbole nach dem Text. - Ein Button sollte in der Regel nur ein unterstützendes Symbol verwenden.
- Vertraute Aktionen wie Speichern, Hinzufügen oder Zurückgehen können durch Symbole unterstützt werden, aber Symbole dürfen den sichtbaren Text auf wichtigen Buttons nicht ersetzen.
- Pfeile, die Fortsetzung, Weiterleitung oder Aufklappen anzeigen, stehen normalerweise hinter dem Text; das Zurück-Symbol steht normalerweise vor dem Text.
- Schreiben Sie das Layout von Symbolen und Text nicht manuell in
children; die Komponente stellt bereits Slots für icon und label bereit. - Verwenden Sie freigegebene Symbole und erben Sie
currentColor; kodieren Sie die Farbe oder Größe von Symbolen nicht hart in den Routing-CSS. - Im Ladezustand sollten die ursprünglichen Abmessungen des Buttons beibehalten werden, und es sollte ein verständlicher kurzer Text oder eine vorhandene Ladeanzeige bereitgestellt werden; vermeiden Sie Sprünge in der Toolbar durch Textwechsel.
7. Buttons und Links
Aktionen und Navigation müssen korrekte Semantik verwenden:
- Für Aktionen auf der aktuellen Seite wie Senden, Speichern, Öffnen eines Modals oder Umschalten des Zustands verwenden Sie
Buttonohnehref, das schließlich zu<button>gerendert wird. - Für die Navigation zu einer anderen Route oder Ressource verwenden Sie
Buttonmithref, das schließlich als Next.js<Link>gerendert wird. - Nicht-Sende-Buttons innerhalb von Formularen müssen explizit
type="button"setzen; Sende-Buttons müssen explizittype="submit"setzen. - Simulieren Sie keine normale Seiten-Navigation mit
onClick.
Deaktivierte Links verwenden aria-disabled und werden aus der Tab-Reihenfolge entfernt; deaktivierte native Buttons verwenden disabled. Der Deaktivierungszustand darf nicht nur durch reduzierte Transparenz ausgedrückt werden; die Geschäftslogik muss die Aktion ebenfalls blockieren.
8. Status und Barrierefreiheit
Freigegebene Komponenten übernehmen einheitlich die Zustände hover, focus-visible, disabled und Farben. Der Geschäftscode muss dennoch folgende Anforderungen erfüllen:
- Normale, nicht ausgewählte Schaltflächen verwenden bei hover
--control-surface-hover; gedrückte, ausgewählte und aufgeklappte Zustände verwenden--control-surface-active.focus-visiblebehält--focus-ringauf der neutralen Fläche, und Routen-Styles dürfen hover und dauerhafte Zustände nicht in einer blauen Regel zusammenfassen. - Der Name des Buttons muss direkt und spezifisch sein und beschreiben, was geschieht, z. B. „Speichern“, „Website veröffentlichen“, „Projekt löschen“.
IconButtonmuss lokalisiertearia-labelbereitstellen.- Dekorative Symbole verwenden
aria-hidden="true", um doppelte Ansagen durch Screenreader zu vermeiden. - Der Tastaturfokus muss sichtbar sein; Routing-CSS dürfen den gemeinsamen Fokus-Ring nicht entfernen.
- Verlassen Sie sich nicht ausschließlich auf Hover als Hinweis; Interaktionen müssen sowohl Tastatur- als auch Touch-Eingaben unterstützen.
- Deaktivierte Buttons dienen nur dazu, Aktionen anzuzeigen, die der Benutzer vorübergehend nicht ausführen kann; wenn eine Erklärung erforderlich ist, stellen Sie eine benachbarte Beschreibung oder einen Tooltip bereit.
- Bei asynchronen Aktionen ist eine Mehrfachübermittlung zu verhindern, und ein verständliches Feedback während der Bearbeitung muss erhalten bleiben.
- Gefährliche Aktionen verwenden
dangerund wiederverwenden das bestehende Bestätigungsmuster für gefährliche Aktionen; verlassen Sie sich nicht ausschließlich auf Rot zur Vermittlung von Risiken. - Button-Texte in Chinesisch oder anderen Sprachen dürfen nicht so stark abgeschnitten werden, dass sie unverständlich sind. Lange Texte und mobile Breiten müssen validiert werden.
9. Trennung der Styling-Verantwortlichkeiten
Die Struktur, Semantik und Statusverwaltung freigegebener Buttons liegt bei Button / IconButton; visuelle Tokens und gemeinsames CSS liegen bei der Komponentenbibliothek; Routes sind nur für das Layout verantwortlich.
Verantwortlichkeiten der Shared Layer
- DOM, Semantik von Links/Buttons, Verhalten von disabled;
- Slots für icon/label und barrierefreie Typeneinschränkungen;
- Klassen für variant, size, shape;
- Höhe, Randradius, Innenabstand, Schriftgröße, Schriftgewicht;
- Hintergrund, Textfarbe, Schatten sowie Zustände für hover, focus-visible und disabled.
Verantwortlichkeiten der Route Layer (erlaubt)
- Richtung, Abstand, Ausrichtung und Zeilenumbruch von Button-Gruppen;
- Responsive Anordnung;
width: 100%oder Container-Breiten, die für bestimmte Workflows erforderlich sind;- Positionierungsklassen, die das grundlegende visuelle Erscheinungsbild nicht verändern.
Verantwortlichkeiten der Route Layer (verboten)
- Überschreiben von Button-Höhe, Schriftgröße, Randradius, Hintergrund, Textfarbe, Schatten oder Fokus-Ring;
- Verwendung harter Farbcodes oder
border-radius: 999pxzur Neimplementierung freigegebener Buttons; - Hinzufügen lokaler visueller Varianten wie
primary-alt,outline-blue,icon-round; - Wettbewerb mit dem Shared-Button-Vertrag durch
!important; - Direktes Kopieren der Basisstile von
.qk-ui-button.
Wenn tatsächlich neue semantische Varianten entstehen, die auf mehreren Seiten benötigt werden, sollte zunächst im Shared ButtonVariant, Token und primitives.css ein einheitlicher Vertrag etabliert werden, anstatt Styles in der Route hinzuzufügen.
10. API-Schnellreferenz
type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonShape = 'rounded' | 'pill';Hauptattribute von Button:
| Attribut | Standardwert | Beschreibung |
|---|---|---|
variant | primary | Semantische und visuelle Hierarchie |
size | md | Höhe, Schriftgröße des Texts und horizontaler Innenabstand |
shape | pill | Abgerundete Form von Button |
leadingIcon | Kein | Symbol vor dem Text |
trailingIcon | Kein | Symbol nach dem Text |
href | Kein | Wird als Link gerendert, wenn angegeben |
disabled | false | Interaktion deaktivieren |
skin | Kein | Stellt Slot-Klassen und Variablenanpassungen gemäß Skeleton/Skin-Vertrag bereit |
IconButton erbt die anwendbaren Attribute von Button, bietet jedoch keine shape, leadingIcon oder trailingIcon; es erfordert aria-label, standardmäßig variant="ghost".
Es wird empfohlen, in der Geschäftscode explizit variant und native Button type anzugeben, damit die operationale Semantik im Code-Review klar erkennbar ist.
11. Häufige Kombinationen
// 主要操作:椭圆形文字按钮
<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>Aktualisierung des Tooltip-Vertrags: Verwenden Sie weder DOM-title noch CSS-data-tooltip als Produkthinweis. Das gemeinsame tooltip liefert nur ergänzende Informationen und ersetzt weder aria-label noch sichtbare kritische Hinweise. Die Blase darf nicht die Button-Form pill verwenden; tooltipPlacement ist standardmäßig bottom und tooltipPortal ist true. Kombinieren Sie niemals title und tooltip.
12. Review-Checkliste
Bestätigen Sie vor dem Bereitstellen von UI für Sende-Buttons Folgendes:
- Wurde
ButtonoderIconButtonpriorisiert wiederverwendet? - Wurde für Buttons mit Text und reine Icon-Buttons die richtige Komponente gewählt?
- Gibt es im aktuellen Aufgabenbereich nur einen klaren
primary? - Werden
secondary,ghost,dangersemantisch und nicht nach Farbpräferenz verwendet? - Bleibt das Plattform-
Buttonbeim Standard-pill, und istIconButtonrund? - Werden Größen nur mit
sm,md,lgverwendet, und sind Höhe und Schriftgröße innerhalb derselben Gruppe konsistent? - Haben native Buttons explizit das korrekte
typegesetzt? - Verbergen Icons doppelte Screenreader-Informationen, und hat
IconButtonlokalisiertearia-label? - Sind die Zustände focus-visible, disabled, asynchron und gefährliche Bestätigung vollständig implementiert?
- Behandelt das Routing-CSS nur Layout, ohne die grundlegende visuelle Gestaltung der Buttons zu überschreiben?
- Wurden lange Texte, Touch-Größen und die Anordnung von Button-Gruppen auf Desktop- und mobilen Breiten validiert?
13. Implementierungsquelle
- Komponenten-API:
packages/components/src/ui/Button/Button.tsx - Komponentenexport:
packages/components/src/ui/Button/index.ts - Größen- und Farb-Tokens:
packages/components/src/styles/foundations.css - Gemeinsame Button-Stile:
packages/components/src/styles/primitives.css - Öffentlicher Komponenten-Integrationsvertrag:
docs/public/design/component-integration.md
Bei Diskrepanzen zwischen Dokumentation und Implementierung sind Komponente, Token, Stile und diese Dokumentation im selben Commit synchron zu aktualisieren.