Button-knop
Specificaties voor semantiek, afmetingen, vormen, statussen en toegankelijkheid van Button en IconButton.
AIButton hergebruikt de grootte en semantiek van Knop, maar voegt een kenmerkend, waarneembaar Qokit AI-status toe.
Selecteer de AI-knop om zijn werkstatus te bekijken.
Qokit-knopcomponentrichtlijnen
Dit document definieert de regels voor het gebruik van knoppen in het Qokit-platform, Builder, CMS, Dashboard, Admin, marketingpagina's en gegenereerde sites. Het doel is om de componenten, semantiek, vormen, afmetingen, pictogrammen, statussen en toegankelijkheid van knoppen te uniformeren, en te voorkomen dat knoppen per route worden herontworpen met lokale CSS.
1. Kernmodel
Knoppen worden niet alleen geclassificeerd als 'ovaal' of 'rond', maar bestaan uit vijf onafhankelijke dimensies:
Component type × semantic priority × size × shape × spatial elevation
Button / IconButton × primary / secondary / ghost / danger × sm / md / lg × pill / rounded × flat / raised / floating- Componenttype bepaalt of de knop zichtbare tekst heeft en of het klikgebied vierkant moet blijven.
- Semantische prioriteit bepaalt de prioriteit en kleur van de knop binnen de huidige taak.
- Afmeting bepaalt de vaste hoogte, tekstgrootte en het aanraakgebied.
- Vorm bepaalt alleen de hoekradius en drukt geen prioriteit of bedrijfsemantiek uit.
- Ruimtelijke laag geeft alleen aan of het besturingselement van het huidige vlak afwijkt, zonder de actiesemantiek te veranderen.
Maak geen nieuwe knoptypen door klassen te combineren. Kies eerst uit de bestaande eigenschappen van gedeelde componenten.
2. Componentselectie
Button
Gebruikt voor alle acties met zichtbare tekst, waaronder:
- Knoppen met alleen tekst;
- Knoppen met pictogram vóór de tekst;
- Knoppen met pictogram na de tekst;
- Paginalinks die eruitzien als knoppen.
De Button in het platform gebruikt standaard volledig afgeronde pill, wat visueel een ovale vorm oplevert. Zolang een knop zichtbare tekst bevat, mag deze niet worden vervangen door een ronde pictogramknop.
variant is ontkoppeld van schaduwen: primary gebruikt standaard raised, terwijl secondary, danger, ghost standaard flat gebruiken. Acties binnen lijstrijen, kaarten, werkbalken en samengestelde capsules moeten flat zijn; onafhankelijke primaire acties mogen raised gebruiken; alleen acties die boven de inhoud zweven gebruiken floating. Onafhankelijke capsules of gesegmenteerde besturingselementen krijgen slechts één keer een schaduw van de buitenste laag; routes mogen de gedeelde laag niet overschrijven met lokale 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
Gebruikt voor compacte werkbalkacties met alleen een pictogram en geen zichtbare tekst, zoals sluiten, meer, terug, menu wisselen of verwijderen.
IconButton behoudt bij elke afmeting gelijke breedte, hoogte en volledige afronding, waardoor het visueel een ronde knop is. Het gebruikt standaard ghost en vereist op type-niveau aria-label.
import { IconButton } from '@qokit/components/ui';
<IconButton aria-label="关闭" tooltip="关闭" type="button">
<CloseIcon aria-hidden="true" />
</IconButton>Regels:
- Het pictogram zelf gebruikt
aria-hidden="true"; de knopnaam wordt geleverd dooraria-label. - Voor onbekende of mogelijk onduidelijke pictogrammen moet ook de gedeelde
Tooltipworden gebruikt; een tooltip kanaria-labelniet vervangen. - Gebruik het DOM-
title-attribuut niet als producttip, en stel niet tegelijkertijdtooltipin en wikkel handmatig een Tooltip. - Een Tooltip is een alleen-lezen informatielaag, geen ovale knop. Het gebruikt de gedeelde compacte Tooltip-hoekradius en mag niet de visuele stijl van
pill, knop-hover, -pressed of -focus hergebruiken. - Gebruik geen
Buttonmet lege tekst, verborgen tekst of vaste breedte omIconButtonna te bootsen. - Stel geen
shapein voorIconButton; rond is het componentcontract.
Scenario's waarin Button niet moet worden gebruikt
- Tabbladen gebruiken de overeenkomstige componenten Tabs/PillTabs/Segmented.
- Menu-items gebruiken de overeenkomstige componenten Menu/ActionMenu.
- Statussen, labels en filterresultaten gebruiken Pill of statuscomponenten.
- Gewone tekstnavigatie gebruikt semantische links; alleen wanneer visuele nadruk op knopniveau nodig is, wordt
Buttonmethrefgebruikt.
3. Semantische lagen variant
| Variant | Betekenis | Typische scenario's | Gebruiksbeperkingen |
|---|---|---|---|
primary | Primaire actie in het huidige gebied | Opslaan, publiceren, aanmaken, nu proberen | Een taakgebied heeft doorgaans slechts één primaire actie |
secondary | Duidelijke maar secundaire actie | Voorbeeld, annuleren, terug, importeren | Mag niet de visuele aandacht van de primaire actie afpakken |
ghost | Lage nadruk, contextuele werkbalkactie | Sluiten, meer, werkbalkacties, licht terug | Standaard transparant; mag niet de enige cruciale CTA zijn |
danger | Actie die verwijdert of aanzienlijke schade veroorzaakt | Item verwijderen, inhoud verwijderen, gegevens wissen | Drukt alleen destructieve semantiek uit, niet als gewone accentkleur |
variant drukt semantische en visuele lagen uit, niet vormen. Bijvoorbeeld ghost kan een ovale knop met tekst zijn of een ronde IconButton.
Selectievolgorde:
- Zoek de enige belangrijkste volgende stap in de huidige taak en stel deze in als
primary. - Hulpacties die duidelijk zichtbaar moeten blijven gebruiken
secondary. - Acties met lage nadruk in werkbalken of context gebruiken
ghost. - Alleen daadwerkelijk destructieve acties gebruiken
danger, met het bestaande bevestigingsproces.
Kies geen variant op basis van 'welke kleur er mooier uitziet'.
4. Afmetingen size
| Size | Hoogte/diameter | Tekstgrootte | Aanbevolen scenario's |
|---|---|---|---|
sm | 40px | 14px | Bovenste navigatie, compacte werkbalken, dichte werkruimten |
md | 44px | 15px | Standaard formulieren, CMS, dialogen en gewone acties |
lg | 48px | 16px | Primaire CTA op marketingpagina's, primaire acties met sterkere aanraakbaarheid |
De standaardafmeting is md.
- Dezelfde knopgroep gebruikt dezelfde afmeting.
- Compacte besturingselementen mogen niet kleiner zijn dan 40px; primaire acties op mobiel hebben bij voorkeur minstens 44px.
- De hoogte van
Buttonen de diameter vanIconButtongebruiken dezelfde afmetingstokens, zodat ze in dezelfde werkbalk kunnen worden uitgelijnd; de zichtbare pictogramgrootte vanIconButtonis uniform 18px. - De tekstgrootte van
Buttonwordt bepaald door de gedeelde token voor de overeenkomstige size en erft niet de tekstgrootte van Header, Dialog of andere bovenliggende containers. - Route-CSS mag de indeling, spatiëring en benodigde breedte van knoppen bepalen, maar mag de gedeelde hoogte of tekstgrootte van knoppen niet herdefiniëren.
- Bij langere tekst heeft aanpassing van de indeling of knopcontainer de voorkeur; los dit niet op door hoogte, lettertype of horizontale spatiëring te comprimeren.
5. Vormen shape
| Shape | Uiterlijk | Gebruiksbereik |
|---|---|---|
pill | Volledig afgerond; ovaal bij tekst | Platformstandaard, geschikt voor marketingpagina's, Dashboard, Builder, CMS en Admin |
rounded | 12px hoekradius | Alleen wanneer het thema van de gegenereerde site expliciet een kleinere hoekradius vereist |
Button is standaard shape="pill". De platform-frontend mag rounded niet expliciet instellen en mag de hoekradius niet overschrijven in lokale CSS.
// 平台默认:省略 shape 即为 pill
<Button type="button" variant="primary">保存</Button>
// 仅生成站点主题有明确视觉要求时使用
<Button shape="rounded" type="button" variant="primary">
预约咨询
</Button>IconButton is altijd rond en neemt niet deel aan de bedrijfsmatige keuze van pill / rounded.
6. Pictogramregels
- Pictogrammen vóór tekst gebruiken
leadingIcon, pictogrammen na tekst gebruikentrailingIcon. - Een knop gebruikt doorgaans slechts één hulppictogram.
- Bekende acties zoals opslaan, toevoegen, terug kunnen worden versterkt met een pictogram, maar pictogrammen mogen de zichtbare tekst van cruciale knoppen niet vervangen.
- Pijlen die doorgaan, binnengaan of uitvouwen aangeven staan doorgaans na de tekst; terug-pictogrammen staan doorgaans vóór de tekst.
- Handmatige indeling van pictogrammen en tekst in
childrenis niet nodig; het component biedt al icon- en label-slots. - Gebruik gedeelde pictogrammen en erf
currentColor; hardcode geen pictogramkleuren of -afmetingen in route-CSS. - De laadstatus moet de originele afmetingen van de knop behouden en begrijpelijke korte tekst of bestaande laadfeedback bieden; laat tekstwisselingen de werkbalk niet laten verspringen.
7. Knoppen en links
Acties en navigatie moeten de juiste semantiek gebruiken:
- Acties op de huidige pagina zoals indienen, opslaan, layer openen, status wisselen gebruiken
Buttonzonderhref, wat uiteindelijk wordt weergegeven als<button>. - Navigatie naar een andere route of bron gebruikt
Buttonmethref, wat uiteindelijk wordt weergegeven als Next.js<Link>. - Niet-indienknoppen in formulieren moeten expliciet
type="button"schrijven; indienknoppen schrijven expliciettype="submit". - Gebruik geen
onClickom gewone paginanavigatie na te bootsen.
Uitgeschakelde links gebruiken aria-disabled en verlaten de Tab-volgorde; uitgeschakelde native knoppen gebruiken disabled. Uitgeschakelde status mag niet alleen worden uitgedrukt door transparantie te verminderen; de bedrijfslogica moet de actie ook blokkeren.
8. Statussen en toegankelijkheid
Gedeelde componenten zijn uniform verantwoordelijk voor hover-, focus-visible-, disabled- en kleurstatussen. Bedrijfscode moet nog steeds voldoen aan:
- Gewone niet-geselecteerde knoppen gebruiken
--control-surface-hoverbij hover;--control-surface-activebij ingedrukt, geselecteerd en uitgevouwen.focus-visiblebehoudt--focus-ringop neutrale oppervlakken; routestijlen mogen hover en aanhoudende statussen niet samenvoegen tot dezelfde lichtblauwe regel. - Knopnamen moeten direct, specifiek zijn en beschrijven wat er gaat gebeuren, zoals 'Opslaan', 'Website publiceren', 'Item verwijderen'.
IconButtonmoet gelokaliseerdearia-labelbieden.- Decoratieve pictogrammen gebruiken
aria-hidden="true"om te voorkomen dat schermlezers dubbel voorlezen. - Toetsenbordfocus moet zichtbaar zijn; route-CSS mag de gedeelde focus-ring niet verwijderen.
- Gebruik hover niet als enige hint; interactie moet zowel toetsenbord als aanraking ondersteunen.
- Uitgeschakelde knoppen zijn alleen voor acties die de gebruiker tijdelijk niet kan uitvoeren; als een uitleg nodig is, bied dan nabije uitleg of een tooltip.
- Fouten, machtigingsvereisten, risico's, kosten en andere taak-kritieke informatie moeten zichtbaar blijven; Tooltips mogen alleen aanvullende informatie bieden en mogen niet de enige manier zijn om deze informatie te ontdekken.
- Asynchrone acties moeten dubbele indiening voorkomen en begrijpbare voortgangsfeedback behouden.
- Gevaarlijke acties gebruiken
dangeren hergebruiken het bestaande gevaarlijke bevestigingspatroon; vertrouw niet alleen op rood om risico over te brengen. - Knop-tekst in het Chinees of andere talen mag niet worden afgekapt tot onbegrijpelijkheid. Valideer lange tekst en mobiele breedte.
9. Verantwoordelijkheden voor stijlen
De structuur, semantiek en statussen van gedeelde knoppen worden beheerd door Button / IconButton; visuele tokens en gedeelde CSS worden beheerd door het componentpakket; routes zijn alleen verantwoordelijk voor de indeling.
Gedeelde laag is verantwoordelijk voor
- DOM, link-/knopsemantiek, disabled-gedrag;
- icon-/label-slots en toegankelijkheidstypebeperkingen;
- variant-, size-, shape-klassen;
- hoogte, hoekradius, padding, tekstgrootte, lettertypegewicht;
- achtergrond, tekstkleur, schaduw, hover, focus-visible en disabled-statussen.
Routelaag mag verantwoordelijk zijn voor
- richting, spatiëring, uitlijning en wrapping van knopgroepen;
- responsieve indeling;
width: 100%of containerbreedte die nodig is voor specifieke workflows;- positieklassen die de basisvisuele stijl niet veranderen.
Routelaag mag niet verantwoordelijk zijn voor
- het overschrijven van knophoogte, tekstgrootte, hoekradius, achtergrond, tekstkleur, schaduw of focus-ring;
- het herimplementeren van gedeelde knoppen met hardgecodeerde kleuren of
border-radius: 999px; - het toevoegen van lokale visuele varianten zoals
primary-alt,outline-blue,icon-round; - het concurreren met het gedeelde knopcontract via
!important; - het direct kopiëren van de basisstijl van
.qk-ui-button.
Als er daadwerkelijk een nieuwe semantische variant nodig is voor meerdere pagina's, moet eerst een uniform contract worden opgebouwd in de gedeelde ButtonVariant, tokens en primitives.css, in plaats van nieuwe stijlen toe te voegen in routes.
10. API-snelreferentie
type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonShape = 'rounded' | 'pill';Belangrijkste eigenschappen van Button:
| Eigenschap | Standaardwaarde | Beschrijving |
|---|---|---|
variant | primary | Semantische en visuele laag |
size | md | Hoogte, tekstgrootte en horizontale padding |
shape | pill | Hoekradiusvorm van Button |
leadingIcon | Geen | Pictogram vóór tekst |
trailingIcon | Geen | Pictogram na tekst |
href | Geen | Wordt weergegeven als link wanneer opgegeven |
disabled | false | Interactie uitschakelen |
tooltip | Geen | Aanvullende inhoud voor gedeelde Tooltip; kan zichtbare cruciale informatie of aria-label niet vervangen |
tooltipPlacement | bottom | Voorkeursrichting; gedeelde Tooltip kan omkeren om binnen de viewport te blijven |
tooltipPortal | true | Rendert buiten de裁剪-container zonder layout-wrappinglaag toe te voegen |
skin | Geen | Biedt class-slots en variabele-aanpassing volgens het skeleton/skin-contract |
IconButton erft toepasselijke Button-eigenschappen, maar biedt geen shape, leadingIcon of trailingIcon; het vereist aria-label, standaard variant="ghost".
Het wordt aanbevolen om in bedrijfscode expliciet variant en native knop-type te schrijven, zodat de actiesemantiek duidelijk zichtbaar is in code-reviews.
11. Veelgebruikte combinaties
// 主要操作:椭圆形文字按钮
<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. Review-checklist
Bevestig voordat u knop-gerelateerde UI indient:
- Heeft u voorrang gegeven aan het hergebruiken van
ButtonofIconButton? - Hebben knoppen met tekst en pictogram-only knoppen de juiste component?
- Heeft het huidige taakgebied slechts één duidelijke
primary? - Worden
secondary,ghost,dangergebruikt op basis van semantiek in plaats van kleurvoorkeur? - Behoudt het platform
Buttonde standaardpillen blijftIconButtonrond? - Is elke Tooltip nog steeds een informatielaag met compacte hoekradius en niet een klikbare ovale knop?
- Heeft u browser-native
title, CSS-data-tooltip-bubbels, dubbele hints en synonieme Tooltips voor tekstknoppen geëlimineerd? - Gebruiken afmetingen alleen
sm,md,lgen zijn hoogte en tekstgrootte binnen dezelfde groep consistent? - Hebben native knoppen expliciet de juiste
typeingesteld? - Verbergen pictogrammen dubbele schermlezerinformatie en heeft
IconButtongelokaliseerdearia-label? - Zijn focus-visible, disabled, asynchroon en gevaarlijke bevestigingsstatussen compleet?
- Behandelt route-CSS alleen de indeling zonder de basisvisuele stijl van knoppen te overschrijven?
- Heeft u lange tekst, aanraakafmetingen en knopgroepschikking gevalideerd op desktop- en mobiele breedte?
13. Implementatiebronnen
- Component-API:
packages/components/src/ui/Button/Button.tsx - Component-exports:
packages/components/src/ui/Button/index.ts - Afmetings- en kleurtokens:
packages/components/src/styles/foundations.css - Gedeelde knopstijlen:
packages/components/src/styles/primitives.css - Openbaar componenttoegangscontract:
docs/public/design/component-integration.md
Wanneer er verschillen zijn tussen documentatie en implementatie, moeten componenten, tokens, stijlen en dit document synchroon worden bijgewerkt in dezelfde wijziging.