Skip to Content
Ontwerp

Button-knop

Specificaties voor semantiek, afmetingen, vormen, statussen en toegankelijkheid van Button en IconButton.

Live-componentKnop / IconButton / AIButton

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 door aria-label.
  • Voor onbekende of mogelijk onduidelijke pictogrammen moet ook de gedeelde Tooltip worden gebruikt; een tooltip kan aria-label niet vervangen.
  • Gebruik het DOM-title-attribuut niet als producttip, en stel niet tegelijkertijd tooltip in 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 Button met lege tekst, verborgen tekst of vaste breedte om IconButton na te bootsen.
  • Stel geen shape in voor IconButton; 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 Button met href gebruikt.

3. Semantische lagen variant

VariantBetekenisTypische scenario'sGebruiksbeperkingen
primaryPrimaire actie in het huidige gebiedOpslaan, publiceren, aanmaken, nu proberenEen taakgebied heeft doorgaans slechts één primaire actie
secondaryDuidelijke maar secundaire actieVoorbeeld, annuleren, terug, importerenMag niet de visuele aandacht van de primaire actie afpakken
ghostLage nadruk, contextuele werkbalkactieSluiten, meer, werkbalkacties, licht terugStandaard transparant; mag niet de enige cruciale CTA zijn
dangerActie die verwijdert of aanzienlijke schade veroorzaaktItem verwijderen, inhoud verwijderen, gegevens wissenDrukt 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:

  1. Zoek de enige belangrijkste volgende stap in de huidige taak en stel deze in als primary.
  2. Hulpacties die duidelijk zichtbaar moeten blijven gebruiken secondary.
  3. Acties met lage nadruk in werkbalken of context gebruiken ghost.
  4. Alleen daadwerkelijk destructieve acties gebruiken danger, met het bestaande bevestigingsproces.

Kies geen variant op basis van 'welke kleur er mooier uitziet'.

4. Afmetingen size

SizeHoogte/diameterTekstgrootteAanbevolen scenario's
sm40px14pxBovenste navigatie, compacte werkbalken, dichte werkruimten
md44px15pxStandaard formulieren, CMS, dialogen en gewone acties
lg48px16pxPrimaire 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 Button en de diameter van IconButton gebruiken dezelfde afmetingstokens, zodat ze in dezelfde werkbalk kunnen worden uitgelijnd; de zichtbare pictogramgrootte van IconButton is uniform 18px.
  • De tekstgrootte van Button wordt 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

ShapeUiterlijkGebruiksbereik
pillVolledig afgerond; ovaal bij tekstPlatformstandaard, geschikt voor marketingpagina's, Dashboard, Builder, CMS en Admin
rounded12px hoekradiusAlleen 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 gebruiken trailingIcon.
  • 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 children is 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.

Acties en navigatie moeten de juiste semantiek gebruiken:

  • Acties op de huidige pagina zoals indienen, opslaan, layer openen, status wisselen gebruiken Button zonder href, wat uiteindelijk wordt weergegeven als <button>.
  • Navigatie naar een andere route of bron gebruikt Button met href, wat uiteindelijk wordt weergegeven als Next.js <Link>.
  • Niet-indienknoppen in formulieren moeten expliciet type="button" schrijven; indienknoppen schrijven expliciet type="submit".
  • Gebruik geen onClick om 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-hover bij hover; --control-surface-active bij ingedrukt, geselecteerd en uitgevouwen. focus-visible behoudt --focus-ring op 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'.
  • IconButton moet gelokaliseerde aria-label bieden.
  • 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 danger en 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:

EigenschapStandaardwaardeBeschrijving
variantprimarySemantische en visuele laag
sizemdHoogte, tekstgrootte en horizontale padding
shapepillHoekradiusvorm van Button
leadingIconGeenPictogram vóór tekst
trailingIconGeenPictogram na tekst
hrefGeenWordt weergegeven als link wanneer opgegeven
disabledfalseInteractie uitschakelen
tooltipGeenAanvullende inhoud voor gedeelde Tooltip; kan zichtbare cruciale informatie of aria-label niet vervangen
tooltipPlacementbottomVoorkeursrichting; gedeelde Tooltip kan omkeren om binnen de viewport te blijven
tooltipPortaltrueRendert buiten de裁剪-container zonder layout-wrappinglaag toe te voegen
skinGeenBiedt 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 Button of IconButton?
  • Hebben knoppen met tekst en pictogram-only knoppen de juiste component?
  • Heeft het huidige taakgebied slechts één duidelijke primary?
  • Worden secondary, ghost, danger gebruikt op basis van semantiek in plaats van kleurvoorkeur?
  • Behoudt het platform Button de standaard pill en blijft IconButton rond?
  • 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, lg en zijn hoogte en tekstgrootte binnen dezelfde groep consistent?
  • Hebben native knoppen expliciet de juiste type ingesteld?
  • Verbergen pictogrammen dubbele schermlezerinformatie en heeft IconButton gelokaliseerde aria-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.

Op deze pagina