Aggiornamento del contratto di design
Registro delle modifiche ai Token di design, alle API dei componenti e ai contratti di integrazione resi pubblici da Qokit.
Aggiornamento del contratto di design
2026-10-21 · Azioni fisse nei menu scorrevoli
ActionItem.pinned accetta start o end per mantenere azioni e ActionMenu.dropdownHeader fuori dall’elenco scorrevole. Navigazione da tastiera e selezione coprono tutte le aree. Gli host dei portali possono limitare l’altezza con --qk-menu-available-height, misurata sul lato scelto del pulsante di apertura. Senza pinned resta la struttura esistente.
17-10-2026 · Punto di accesso alla personalizzazione dei widget
La personalizzazione del widget della pagina utilizza il punto di accesso dell'intestazione condivisa tra Progetti, Contenuti e dashboard. CustomizableWidgetLayoutControls aggiunge customizeButtonRef e disabledCustomize opzionali; i controlli di compressione sono facoltativi. CustomizableWidgetLibrary condivide la geometria mobile, lo stato attivo iniziale, Escape e il ritorno dello stato attivo tra gli host. La persistenza dei widget e i comandi rimangono di proprietà dell'host. Vedi integrazione personalizzazione widget.
17-10-2026 · Controlli del pannello del banco di lavoro gestito
WorkspaceHeaderPortal accetta startControl e endControl opzionali, con corrispondenti target host opzionali. Le viste File gestiti utilizzano gli stessi slot del pannello dell'intestazione e la stessa geometria dell'area di lavoro della modifica e anteprima di una singola risorsa. Gli host esistenti possono continuare a fornire solo titolo, stato e azioni. Vedi integrazione EditorHeader.
17-10-2026 · Predefiniti dell'editor misurati
useWorkspaceResponsiveProfile aggiunge onWidthChange(width) opzionale per le misure disponibili dell'area di lavoro. useEditorLayout ora applica anche ai limiti di larghezza condivisi configurati allo storage dell'host, e readEditorLayout accetta limiti opzionali come quarto argomento. I chiamanti esistenti mantengono i loro valori predefiniti. Vedi Integrazione Componenti.
2026-09-26 · Creator · Schemi di stile
Spaziatura precisa · v3: site.theme.spacingOverrides 按 desktop/tablet/mobile → sectionPadding (0–240px), pageGutter, cardGap (0–96px). --qk-site-custom-{sectionPadding|pageGutter|cardGap}-{desktop|tablet|mobile}. 980px / 720px.
Pulsanti e collegamenti: primaryButtonStyle, secondaryButtonStyle (solid/outline), buttonFontSize (12–24px), linkUnderline (always/hover/none), linkHoverStyle (none/tint). --qk-site-{primary|secondary}-button-{background|color|border|shadow}, --qk-site-button-font-size, --qk-site-button-size-{sm|md|lg}, --qk-site-link-decoration, --qk-site-link-hover-decoration, --qk-site-link-hover-background. initial → Automatico.
Colori avanzati: mutedColor, borderColor, buttonTextColor, cardSurfaceColor 与对应 dark* 字段 (--qk-site-color-card-rgb).
2026-09-09 · Scorciatoia di navigazione globale
SidebarNavigation / WorkspaceNavigationMenu: La navigazione globale usa Command+\ su Mac o Control+\ su Windows/Linux, anche in modo indipendente dentro Creator. T e Shift+T mantengono le funzioni di layout dell’editor. Campi modificabili, composizione del testo, ripetizioni ed eventi già gestiti vengono ignorati.
2026-09-08 · EmptyState
La creazione di progetti e articoli/prodotti CMS condivide EmptyState: centrato, trasparente, compatto e con azioni su più righe. icon, layout, style e description sono facoltativi. Il titolo usa h2; migrare i selettori strong allo slot skin title. Le azioni condividono un contenitore. Permessi e creazione restano gestiti dall’host.
2026-09-08 · SidebarNavigation
SidebarNavigation precarica le route della stessa origine dopo 180 ms di passaggio del mouse o con il focus da tastiera. La navigazione fissa e a comparsa condivide un limite di 8 destinazioni ogni 30 secondi. Il precaricamento si sospende offline, nelle schede nascoste, con Save-Data o 2G; esclude download, link disabilitati, nuove finestre e ancore locali. Navigazione e protezione delle modifiche restano invariate.
2026-09-08 - Primary button foreground
I pulsanti principali arrotondati mantengono il blu del Logo #4695D8 e usano testo, icone e indicatori bianchi in entrambi i temi. Il passaggio del mouse mantiene il leggero schiarimento. I pulsanti secondari e pericolosi conservano i colori semantici.
2026-09-07 - AccountDropdown / SidebarProfile
AccountDropdown accetta compact e preferences opzionali: la modalità compatta nasconde identificatori e cronologia di creazione; il contenuto esistente resta predefinito. Appearance e Language accettano triggerRole="menuitem" nel menu account. La navigazione da tastiera ripristina il focus e le finestre della lingua annidate gestiscono Esc. SidebarNavigation.searchEnabled è true per impostazione predefinita; usare false per una navigazione breve e fissa. SidebarProfile con href, senza menu, apre la stessa destinazione in entrambe le modalità.
2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace
I moduli condividono la scala tipografica e adattano testi lunghi, mantenendo forme arrotondate e colori del marchio. FormField nomina gruppi: controlId e l’id interna collegano l’etichetta. SearchField ripristina il focus dopo la cancellazione. Segmented e ControlMenu supportano opzioni disabilitate; le voci disabilitate di ActionMenu non hanno link. I pulsanti occupati mantengono dimensioni e indicatore. AdminEntityDialog convalida campi obbligatori, e-mail e JSON, focalizza errori, blocca salvataggi duplicati e conserva gli input dopo un errore. EditorWorkspace offre ref.focusControl(element) per mostrare pannelli nascosti prima di focalizzare. Il movimento ridotto disattiva le transizioni dei controlli. WorkspaceDialog scorre i contenuti lunghi mantenendo visibili titolo e azioni; i dialoghi mobili brevi si adattano al contenuto.
2026-09-07 · WorkspaceLocationSync / ProjectSwitcher
Dopo il cambio di percorso, WorkspaceLocationSync chiude il selettore temporaneo degli spazi e mostra gli strumenti della destinazione. Le preferenze di ricerca e sezione restano invariate. Nome dell’ambito e contesto occupano righe separate; i nomi lunghi nell’intestazione vengono troncati nel pulsante.
2026-09-07 · Navigazione unificata e superfici arrotondate Qokit
WorkspaceNavigationDock riutilizza navigazione e permessi dell’host tramite items, fallback, className e onClickCapture, senza caricare un’altra sessione. Mantiene la preferenza espansa, icone o nascosta; fino a 860px usa il pannello di navigazione. PlatformHeader.leadingContext compare anche in EditorHeader. Restano pulsanti a capsula e superfici arrotondate; si eliminano i bordi ripetuti.
Su desktop, un clic sul menu nasconde la barra laterale o ripristina la sua ultima modalità visibile. Trascinando il menu o il bordo della barra si passa tra nascosta, solo icone ed espansa. Le frecce sinistra/destra seguono la direzione di lettura. Annullare il trascinamento conserva la preferenza salvata; su mobile resta il pannello di navigazione.
Montare WorkspaceLocationSync una volta sotto Suspense nel layout Next. useWorkspaceQueryState(key, defaultValue, validate) restituisce [value, setValue, ready]; useWorkspaceQueryRecord(key, defaults, validators) ripristina solo filtri piatti dichiarati. Non inserire credenziali o bozze negli URL. WorkspacePage ripristina posizioni di scorrimento di sessione limitate; le aree interne usano data-workspace-scroll-region e WorkspaceScrollRestoration. La navigazione nativa annullabile riutilizza la protezione di uscita senza aggiungere cronologia. AdminEntityDialog conserva gli input dopo errori e nuovi rendering; versioni e risultati restano all’host.
La gestione usa ruoli tipografici fissi: titolo pagina 20px/650, sezione 16px/600, testo e navigazione 14px, etichette 13px, note 12px. --qk-workspace-body-ink e --qk-workspace-active-ink derivano dai colori esistenti.
I pulsanti principali arrotondati usano direttamente il blu del Logo #4695D8 tramite --accent-action, senza gradiente scurito. Al passaggio del mouse si aggiunge l’8% di bianco; le etichette usano l’inchiostro del marchio con il 10% di nero per la leggibilità. La navigazione mantiene lo stesso blu e testo adatto al tema.
Menu a discesa e selettori dello spazio condividono --menu-option-font-size (14px) e --menu-option-font-weight (500), con interlinea 1.45; le opzioni selezionate usano 600 e i metadati 12px/400. WorkspaceNavigationDock precarica le destinazioni della stessa origine al passaggio del mouse o al focus da tastiera, con deduplicazione limitata. Restano attive le protezioni in uscita e le rotte host.
2026-09-07 - ColumnLayout
ColumnLayout riempie la finestra di gestione con navigazione ancorata, scorrimento indipendente e barra della pagina fissa. WorkspacePage usa sezioni piatte e Token di raggio condivisi. Fino a 860px, la navigazione resta un pannello, non interattivo quando chiuso. Proprietà e logica applicativa non cambiano. Eliminate i margini esterni duplicati e limitate la larghezza all’interno dei moduli.
2026-09-05 · WorkspaceNavigationMenu / WorkspacePageHeader
Gli spazi autenticati usano PlatformHeader.workspaceActions per condividere account e navigazione a ogni larghezza. WorkspacePageHeader uniforma titoli e azioni. WorkspaceNavigationMenu mostra la barra laterale corrente con permessi e contesto; EditorNavigationMenu resta un alias compatibile. Studio mantiene la propria barra degli strumenti. Le intestazioni pubbliche conservano la loro presentazione.
WorkspaceNavigationGuard protegge la navigazione globale con dirty, busy, error e onSave facoltativo. Solo un salvataggio confermato che restituisce true consente di uscire; gli errori conservano la bozza. Language.onBeforeChange(apply) permette la stessa protezione prima di cambiare lingua. Disabilita i campi durante il salvataggio.
2026-09-05 · EditorNavigationMenu
EditorNavigationMenu riutilizza l’intera SidebarNavigation dell’host in un pannello sovrapposto, mantenendo permessi e contesto del progetto senza spostare l’area di lavoro. Lingua e tema restano in basso; i sottomenu gestiscono Escape per primi. Fino a 1120px, l’intestazione usa due righe e il menu indica la vista attuale. Concentrazione e schermo intero del browser sono indipendenti. La navigazione attende i salvataggi in corso e protegge le bozze.
2026-09-05 · EditorHeader
EditorHeader mantiene logo, account e menu globale nell’editor attivo. startControl e endControl controllano i pannelli laterali, center le viste e actions il salvataggio. PlatformHeader.editorActions riutilizza navigazione responsive, lingua e tema. onNavigate deve gestire le modifiche non salvate prima di eseguire il callback. Su schermi stretti, l’intestazione usa due righe; i sottomenu gestiscono Escape per primi.
2026-09-05 · SidebarToggleSlot
SidebarToggleSlot sposta il comando della barra laterale nell’intestazione. Usa un solo slot con una barra laterale sinistra. SidebarNavigation mantiene stato, scorciatoie e pannello mobile; senza slot conserva i controlli originali. Il pulsante nell’intestazione chiude anche il pannello mobile; alla chiusura il focus torna allo stesso pulsante.
2026-09-05 · EditorWorkspace / Dialog / Segmented
view / onViewChange passano tra edit, focus e preview senza sostituire l’editor. preview fornisce l’anteprima; previewPanel riutilizza un pannello. layout supporta writing, structure e canvas. storageKey ricorda larghezze e pannelli chiusi, mai il documento.
onSaveAndClose restituisce true dopo il salvataggio confermato, false in caso di errore, handled se l’applicazione ha già navigato o pending se la validazione richiede una decisione. Gli errori mantengono aperto l’editor. Usare closeBehavior="collapse" solo se l’applicazione conserva la bozza. EditorSaveStatus mostra stati confermati. EditorViewControls, EditorLeaveDialog e useEditorLayout sono componibili anche negli spazi esistenti.
Migrazione tastiera: Segmented ha un solo arresto Tab e usa frecce / Home / End. Dialog rispetta Escape gestito da una sovrapposizione figlia; poi l’editor esce dalla concentrazione o dall’anteprima prima di chiudersi. LivePreviewToolbar.exitControl accetta i controlli condivisi. Salvataggio, pubblicazione e permessi restano gestiti dall’applicazione.
2026-09 · EditorWorkspace
EditorWorkspace combina una finestra a schermo intero, la gestione del focus e pannelli adattivi. dirty conferma se scartare le modifiche, busy impedisce la chiusura durante il salvataggio e onSave gestisce Ctrl/Cmd+S. Permessi, dati, salvataggio e pubblicazione spettano all’applicazione.
2026-08 · Densità delle metriche compatta
- Aggiunta un'API
density="compact"opzionale perMetricCard, destinata a workspace operativi ad alta densità; - Mantenute invariate la densità predefinita attuale e la semantica del DOM;
- Unificati padding compatti, scale dei valori e altezze minime nello stile dei componenti condivisi, eliminando la necessità di override visivi a livello di routing.
2026-07 · Controlli di modulo unificati
- Aggiunti
FormField,Input,Textarea,Checkbox,RadioGroupeSwitcha@qokit/components/ui; - Associati etichette, descrizioni, errori, stato obbligatorio e riferimenti ARIA tramite lo scheletro condiviso
FormField; - Unificati
Input,Textarea,SelecteSearchFieldalle dimensioni 40px, 44px e 48px, utilizzando Token di interazione condivisi; - Aggiunte ricette Skin per piattaforma, Admin e siti generati ai nuovi componenti base dei moduli;
- Conservati gli stili
.qk-fieldesistenti come percorso di migrazione per la compatibilità con le versioni precedenti.
2026-07 · Impaginazione delle dimensioni dei pulsanti
- Aggiunti tre Token semantici
--button-font-size-sm,--button-font-size-md,--button-font-size-lg; - Il testo di
Buttonnei contestism,md,lgè ora fissato rispettivamente a 14px, 15px, 16px e non eredita più la dimensione del carattere dall'intestazione, dalla finestra di dialogo o dal contenitore della pagina; - Se lo Skin del sito richiede una modifica all'impaginazione dei pulsanti, deve sovrascrivere il Token semantico corrispondente, senza più riscrivere
font-sizetramite class di routing.
2026-07 · Struttura della navigazione pubblica della piattaforma
- Aggiunto
PlatformHeaderindipendente dall'accesso, che utilizza la stessa struttura semantica per la piattaforma e il sito della documentazione; - Aggiunti
PublicPlatformHeaderebuildPublicHeaderNavItems, che consentono alla piattaforma in stato anonimo e al sito della documentazione di riutilizzare la stessa combinazione di intestazione pubblica e configurazione di navigazione; HeaderNavItemintroduce il tipomenu: l'intestazione desktop utilizza un menu a discesa chiudibile, mentre l'intestazione mobile si espande automaticamente in gruppi di link;SiteFooteraggiungebrandHrefecontrolsopzionali, supportando diversi scenari di integrazione come la documentazione pubblica;- Aggiunto
PublicPlatformFooter, che permette alla piattaforma e al sito della documentazione di riutilizzare lo stesso Footer Shell, consentendo anche la risoluzione cross-domain dei link della piattaforma; - Tutte queste sono API opzionali backward-compatible; la logica dello stato dell'intestazione della piattaforma originale e i controlli predefiniti del Footer rimangono invariati.
2026-07 · Linee guida di design pubbliche
- Separazione del contratto di design pubblico dalle specifiche di implementazione AI interne;
- Pubblicazione dei Token visivi, degli import dei componenti, dei confini Skeleton/Skin, di Button, Card e dei requisiti di accessibilità;
- Le modifiche distruttive ai componenti devono includere obbligatoriamente istruzioni di migrazione;
- La ricerca pubblica, la Sitemap e l'output LLM contengono solo contenuti su cui è possibile fare affidamento esternamente.
Note sulla compatibilità
-
L'aggiunta di proprietà opzionali, slot Skin e Token semantici mantiene generalmente la compatibilità backward;
-
La rimozione o la rinomina di proprietà, nonché la modifica del comportamento predefinito DOM/semantico/tastiera, costituiscono modifiche distruttive;
-
Le modifiche distruttive indicheranno in questa pagina l'impatto, le API alternative e i passaggi di migrazione.
-
2026-09-06: La navigazione desktop mantiene la barra espansa e le icone e aggiunge la scomparsa automatica. SidebarNavigation / WorkspaceNavigationMenu / Dialog
-
2026-09-06: EditorViewControls separa Modifica/Concentrazione dallo schermo intero nativo. EditorViewControls
-
2026-09-06:
LanguageeAppearance variant="menu"supportanolayout="row"per mostrare etichetta, valore attuale e freccia. Il layout compatto predefinito e la protezione del cambio lingua restano invariati.SiteHeaderCopy.helpResourcesecontactSupportdefiniscono facoltativamente i collegamenti di aiuto dello spazio di lavoro. Language / Appearance -
2026-09-06: Le pagine con barra laterale rimuovono il pulsante di menu duplicato; restano disponibili il comando esistente e l’API di navigazione. WorkspaceNavigation
-
2026-09-06: La navigazione globale usa un’icona di menu, gli strumenti icone di pannello direzionali. WorkspacePanelReveal / EditorViewControls
-
2026-09-06: Modalità di visualizzazione ·
E/T/V/F·Segment.shortcut. EditorViewControls -
2026-09-06:
PlatformHeader.workspaceNavigationcolloca la navigazione globale prima del logo PlatformHeader.workspaceNavigation
2026-09-06 - EditorHeader.preview / EditorViewControls.returnView
EditorHeader.preview mostra solo center come barra di anteprima compatta senza bordi; logo, account, salvataggio e pannelli restano montati ma nascosti. Con una LivePreviewToolbar separata è possibile nascondere l’intestazione dell’editor e usare EditorViewControls.returnView (edit o focus) per ripristinare la modalità precedente. Mantenere ritorno accessibile e schermo intero indipendente; l’intestazione del sito resta visibile.
2026-09-06 · Builder / CMS
Builder e CMS condividono BuilderWorkspace, EditorCatalog ed EditorComponentSettings per pannelli, illustrazioni di inserimento e impostazioni visive. I preset applicano insieme le impostazioni collegate e preservano i contenuti; ogni applicazione gestisce salvataggio e annullamento. I controlli seguono il tema della piattaforma e i contenuti quello del sito.
2026-09-06 - EditorViewControls
Un pulsante cambia in entrambe le direzioni: durante la modifica mostra Concentrazione, durante la concentrazione Modifica. Fai clic o premi T; E torna direttamente alla modifica. Nelle intestazioni strette il pulsante resta visibile; anteprima, schermo intero e azioni aggiuntive sono in Altro. EditorViewControls
2026-09 · Aree di gestione
Le tabelle strette (WorkspaceDataTable, AdminDataTable) mostrano record etichettati con selezione, intestazioni personalizzate e azioni. Usare mobileLayout="scroll" per matrici comparative. WorkspaceFilterToolbar dispone ricerca e filtri prima di ordinamento e vista. La barra laterale usa h2; la pagina usa h1.
2026-09-08 · Task focus
useSidebarTaskFocus(active) nasconde temporaneamente la navigazione durante un’attività che richiede concentrazione. All’uscita ripristina la vista precedente, salvo una modifica esplicita dell’utente. La preferenza salvata resta invariata.
Nuovi riferimenti API (inglese; traduzione in attesa)
Optional FloatingToolPanel.viewKey animates tool changes without remounting the body. Shared opening, closing, unfolding and pin feedback respect reduced motion; pointer geometry updates run at most once per animation frame. Closed Dialog keepMounted surfaces become inert and hidden from assistive technology immediately, including during an exit transition. Existing props and document state ownership are unchanged.
The opt-in useWorkspacePanelEdgeDrag hook connects existing workspace borders to expanded, icon and hidden states in one mouse or touch gesture, with keyboard resizing, RTL and cancellation. ResizablePanels now marks its separators with data-workspace-panel-edge; existing hosts retain their behavior until they enable the hook. Hosts own widths, state, focus and visual skins. See the integration contract.
Nuovi riferimenti API (inglese; traduzione in attesa) · 2026-10
2026-10-08 · Workspace title navigation
WorkspaceLayout and WorkspacePageHeader accept optional backControl before the title. Use WorkspaceBackButton with a localized label and the existing href or onClick; it supplies an icon, accessible name, Tooltip and RTL mirroring. Hosts retain return destinations, list state and navigation guards. Existing headers without this slot keep their layout.