Skip to Content
設計

組件接入

Qokit 共享組件、Pattern、Skin 與樣式 Token 的公開集成契約。

組件接入

Qokit 使用「共享骨架 + Skin 配方」模型。外部集成方依賴組件的語義和互動契約,透過 Skin 和 Token 完成視覺適配。

2026-10-22 · 窄螢幕目前導覽標籤

PillTabs 支援可選的 scrollActiveTabIntoView,預設為 false。水平頁籤在選取或尺寸變化時,將直接子項中啟用的 PillTabLink 或 PillTabButton 捲入可見區域。只捲動標籤軌道,不改變頁面位置或鍵盤焦點;支援 LTR 與 RTL,使用即時定位,並相容減少動態效果。垂直頁籤與未啟用此選項的呼叫保留原行為。

2026-10-20 · 視覺選擇卡片的獨立操作

EditorVisualChoiceGroup 的選項支援可選的 accessory,用於獨立的卡片選單或名稱編輯器。共用 RadioGroup 將其放在原生標籤旁,管理卡片不會觸發單選。可選的 afterOptions 在選項之後放置建立卡片等獨立目錄操作。宿主負責持久化、權限、驗證,以及卡片替換或刪除後的焦點。未提供附加操作的選項保留原結構和行為。

2026-10-17 · 共用工作台面板動效

EditorWorkbenchChrome 透過 BuilderWorkbenchFrame 渲染傳入的兩側面板區域,與創作室和內容編輯使用同一面板骨架。宿主提供內容、顯隱狀態和寬度偏好。桌面網格軌道、面板透明度與位移動效共用 --qk-sidebar-motion-duration 和 --qk-sidebar-motion-easing;拖曳時停用過渡,減少動態效果時立即切換。

面板收起後保持掛載以保留草稿。共用骨架立即設定 inert 和 aria-hidden,平台樣式在退出動效結束後才隱藏面板。緊湊面板在整個退出過程中保留浮層幾何,宿主不得為面板外殼加入 hidden 或 display: none。明確暫時展開的面板保留既有互動。頁首選項在面板展開和收起時均可使用;手機端的多個面板入口需要共用選單時,使用 EditorPanelChoiceShortcuts.mobileMenu。

2026-10-17 · 依可用寬度計算編輯器預設值

useWorkspaceResponsiveProfile 接受可選的 onWidthChange(width),回報扣除橫向內邊距後、用於響應式判斷的同一工作區可用寬度。使用穩定回呼推導比例預設值,無須增加觀察器。useEditorLayout 將 sharedWidths.limits 同時套用至宿主偏好與共用寬度儲存;readEditorLayout 的第四個可選參數接受同一限制。現有呼叫端保留原有預設邊界和行為。

2026-09-30 · SelectionToolbar 無障礙支援

SelectionToolbar.ariaLabel 可選地為工具列區域命名,計數仍作為即時狀態訊息。宿主提供本地化標籤,並可透過 actionContent 組合共用的 EditorToolGroup 與 ActionMenu;權限檢查與操作處理仍由宿主負責。

2026-09-10 · 工作空間身分徽章

ProjectSwitcherProject.badge 接受選用、不可互動的 React 內容,並顯示在項目名稱、未列出的目前內容脈絡,以及文字觸發器的目前名稱旁。純圖示觸發器保持精簡;平台文字觸發器在手機寬度隱藏徽章,以保留工作空間名稱。選單展開後仍顯示徽章。宿主負責範圍正確的資料、本地化標籤與顯示樣式;省略此欄位即保留既有外觀。

2026-09-08 · EmptyState

EmptyState 在透明表面置中呈現選用的裝飾 icon、title、選用的 description 與 action。layout="section" 為精簡預設,layout="workspace" 為空白業務區保留更多空間。操作直接放入 action 槽位,多個按鈕使用 fragment;共用容器處理間距和長標籤。標題為 h2,請使用 title skin 槽位取代 strong 選擇器。保留原有根類別,支援 skin.vars 與 style。宿主負責本地化文案、權限、導覽與建立操作;搜尋結果及錯誤保留各自的訊息與操作。

2026-09-08 · SidebarNavigation

SidebarNavigation 在滑鼠停留 180 毫秒或鍵盤聚焦後預先載入同源路由;固定側欄與彈出導覽共用每 30 秒最多 8 個目標的額度。離線、隱藏分頁、省流量或 2G 網路時暫停預載;下載、停用連結、新視窗目標與同頁錨點不預載。導覽與未儲存離開保護維持原有契約。

2026-09-07 - AccountDropdown / SidebarProfile

AccountDropdown 新增選用的 compact 和 preferences:精簡模式隱藏識別碼與創作歷史,預設保留原有內容。帳戶選單內的 Appearance、Language 使用 triggerRole="menuitem"。選單支援鍵盤導覽與焦點還原,巢狀語言對話框獨立處理 Esc。SidebarNavigation.searchEnabled 預設為 true,少量固定入口可設為 false。僅提供 href、不提供選單的 SidebarProfile 在展開和圖示模式下開啟相同目標。

2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace

表單字級統一,長標籤與輔助資訊自然換行,保留橢圓形態和品牌色。FormField 為組合控制項提供群組名稱;controlId 與內層輸入框 id 對應,實現標籤聚焦。SearchField 清除後恢復焦點。Segmented、ControlMenu 支援停用選項,停用的 ActionMenu 項目不保留連結。忙碌按鈕維持尺寸並顯示指示器。AdminEntityDialog 驗證必填、電子郵件與 JSON,聚焦錯誤、防止重複儲存,失敗保留輸入。EditorWorkspace 提供 ref.focusControl(element),先展開隱藏面板再聚焦欄位。減少動態效果時關閉控制項過渡。 WorkspaceDialog 的長內容獨立捲動,標題和操作區維持可見;短彈窗在行動裝置依內容高度顯示。

2026-09-07 · WorkspaceLocationSync / ProjectSwitcher

路由完成切換後,WorkspaceLocationSync 關閉暫時的空間選擇面板,目標頁面直接顯示功能選單;搜尋和分組偏好繼續保留。側欄範圍名稱與情境說明分兩行顯示,頂部切換器的長名稱在按鈕內省略。

2026-09-07 · 統一工作台導覽與 Qokit 圓潤風格

WorkspaceNavigationDock 在桌面重用宿主側欄及權限,透過 items、fallback、className 和 onClickCapture 接入,不重複載入工作階段。展開、圖示及隱藏狀態共用既有偏好;860px 以下使用統一抽屜。PlatformHeader.leadingContext 同時進入 EditorHeader,保留工作空間和專案切換。保留膠囊按鈕與圓潤表面,移除重複框線。

桌面點擊選單按鈕完全隱藏側欄,再次點擊恢復上次可見模式。拖動選單按鈕或側欄邊緣,在隱藏、僅圖示和展開之間吸附切換;左右方向鍵遵循文字方向。取消拖動不改寫已儲存偏好,手機繼續使用導覽抽屜。

Next 佈局在 Suspense 下掛載一次 WorkspaceLocationSync。useWorkspaceQueryState(key, defaultValue, validate) 回傳 [value, setValue, ready];useWorkspaceQueryRecord(key, defaults, validators) 僅還原明確宣告的平面篩選。憑證及草稿不得寫入 URL。WorkspacePage 還原有容量限制的工作階段捲動位置;內層區域搭配 data-workspace-scroll-region 和 WorkspaceScrollRestoration。可取消的原生前進/後退沿用離開保護,不新增歷史紀錄;其他瀏覽器保留既有回退。AdminEntityDialog 儲存失敗及父頁重繪後保留輸入;版本及儲存結果仍由宿主負責。

管理文字使用固定層級:頁標題 20px/650,分組標題 16px/600,正文和導覽 14px,標籤 13px,輔助說明 12px。--qk-workspace-body-ink 與 --qk-workspace-active-ink 衍生自既有平台色彩。

橢圓主按鈕保留 Logo 藍原色 #4695D8,明暗主題下均使用白色文字、圖示和載入指示器。懸停保留既有輕微提亮;次要按鈕和危險按鈕繼續使用各自的語意顏色。

下拉選單與工作空間切換器共用 --menu-option-font-size(14px)和 --menu-option-font-weight(500),行高為 1.45;選中項字重 600,輔助資訊 12px/400。WorkspaceNavigationDock 在滑鼠停留或鍵盤聚焦時預載入同源目標,並限制去重記錄數量。導覽仍使用既有離開保護與宿主路由。

2026-09-07 - ColumnLayout

桌面管理宿主的 ColumnLayout 使用貼邊導覽、獨立內容捲動區和置頂頁面工具列填滿視窗。WorkspacePage 使用平整分區及共用控制項圓角 Token。860px 及以下保留導覽抽屜,關閉的抽屜不可互動。屬性和業務行為不變。宿主應移除重複外部留白,將閱讀寬度限制放在表單內容上。

匯入入口

import { Button, Card, Dialog, IconButton } from '@qokit/components/ui';
import { PlatformHeader, SiteFooter } from '@qokit/components/patterns';
import { platformButtonSkin } from '@qokit/components/skins/platform';
import { siteCardSkin } from '@qokit/components/skins/site';
入口用途
@qokit/components/uiButton、Card、Dialog、Menu、Pill 等基礎組件
@qokit/components/patternsHeader、Footer、工作區、表格、資源和 AI 助手等組合
@qokit/components/skins/platform平台與工作區視覺配方
@qokit/components/skins/adminAdmin 視覺配方
@qokit/components/skins/site生成站點視覺配方

公共職責邊界

PromptPanel 接受可選的 referenceReader 與在地化 referenceCopy 屬性。讀取器以非同步 file(File, AbortSignal) 和 website(url, AbortSignal) 回傳擷取的 contentExcerpt 與 truncated 標記,驗證及 API 存取由宿主負責。元件管理讀取、預覽、重試與移除;有效網址沒有提示文字時由 referenceCopy.websitePrompt 補上請求,格式錯誤使用 referenceCopy.errors.url 並阻止讀取。網址尚未讀取或讀取中送出時會等待最新內容且只送出一次;輸入變更或讀取失敗會取消待送出操作,重試不會恢復舊操作。檔案須就緒後才能送出。完整網址在貼上、失焦或按 Enter 時自動讀取,初始網址也會讀取並重用進行中或完成的結果;失敗提供明確重試。編輯或移除網址會取消舊讀取並清除結果。未提供讀取器時維持原生送出,不做非同步參考處理。

參考資料擷取於 2026 年 9 月以可選且向後相容的元件能力加入。

骨架組件保證:

  • DOM 與語義標籤;
  • ARIA、鍵盤、焦點和 disabled 行為;
  • 狀態與基礎互動;
  • 穩定預設 class;
  • 具名 Skin 槽位。

Skin 可以:

  • 為 root、header、body、item、action 等槽位增加 class;
  • 透過 vars 傳入 CSS 變數;
  • 使用組件已公開的 tone、layer 或視覺適配開關。

Skin 不得請求資料、改變 DOM、持有業務規則或繞過可存取性行為。

產生元素內容

產生的自訂區段在 Schema v2 中繼續使用已註冊的 html-* 元素,不使用可執行 HTML 或新區塊類型。自 2026 年 9 月起,@qokit/site-schema 提供 bindSiteModuleContent、updateSiteModuleBoundContent 與 forkSiteModuleContentBindings 以綁定語系內容。內容路徑保存在模組中,訪客文案保存在語系內容對應中,更新沿用復原與儲存交易;複製或跨區塊移動元素時必須分叉綁定,避免改變來源。

可選的 extensionRequirements 記錄未解決的執行階段需求,並非安裝清單或權限授予。createSiteExtensionHandoff 匯出不可執行的 v1 開發請求;發布可執行站點前必須解決或經審查明確排除。

表單控制項

共享表單使用 FormField 關聯標籤、說明、必填中繼資料、錯誤與控制項 ID。文字使用 Input,多行內容使用 Textarea,選擇使用 Checkbox、RadioGroup 和 Switch;既有 Select 與 SearchField 採用相同尺寸及狀態契約。

import { FormField, Input } from '@qokit/components/ui';

<FormField label="Site name" description="Up to 60 characters" error={errors.name} required>
  <Input name="name" value={name} onChange={handleChange} />
</FormField>;

FormField 透過 id、aria-describedby、aria-invalid 和 required 將標籤、說明與錯誤連結到唯一子控制項。不要再以額外的 <label> 包覆共享控制項。

Input、Textarea、Select 與 SearchField 支援 sm、md 和 lg,對應 40px、44px 與 48px。單行控制項預設為 pill;Textarea 一律使用共享的多行圓角。各互動與錯誤狀態均來自共享 Token。

遷移期間仍可使用舊有 .qk-field 契約;新整合應使用共享元件與具名 Skin 插槽。

清單選取

自 2026 年 9 月起,清單可搭配 useWorkspaceSelectionMode({ enabled, resetKey, onClear }) 與 WorkspaceFilterToolbar.selection。此 Hook 初始未啟用,在範圍或權限變更時重設,並區分清除所選 ID 與退出批次模式;範圍鍵應包含集合、語言、分頁及篩選。

僅在批次模式啟用時傳入 WorkspaceDataTable.selection,網格與行動版核取控制使用同一模式。工具列負責通用選取操作,使用方提供在地化文案、可選 ID 及通過權限檢查的領域操作。可選的 actionContent 可承載額外 ARIA 語意,但不取代通用控制或確認。唯讀清單不顯示批次模式,檔案選擇器與提案審查保留各自語意。

這些新增能力可選且向後相容;表格選取仍由使用方明確控制。

指標卡片

新增 API 參考(英文,譯文待同步) · 2026-10

DataCard provides a title and optional headerAction, body content with an optional emphasized value, and optional footerText and footerAction. Pass other body content as children. density="default" has a 144px minimum height and 20px padding; density="compact" has a 112px minimum height and 16px padding. Cards grow when content needs more room. variant selects the shared Card surface: surface, muted, or state. Choose these shared sizes instead of overriding height, padding, or value typography in route CSS.

Use shared UI controls in action slots. Keep the card root non-interactive when it has actions; a whole-card action cannot contain nested buttons or links. MetricCard composes the same skeleton and retains label, detail, semantic tone, and optional visuals.

import { DataCard, MetricCard } from '@qokit/components/patterns';
import { Button } from '@qokit/components/ui';

<DataCard
  title="Published"
  value={24}
  headerAction={<Button size="sm" variant="ghost">View</Button>}
  footerText="Up 3 from last week"
  footerAction={<Button size="sm" variant="secondary">Details</Button>}
  density="compact"
/>;

<MetricCard density="compact" label="Published" value={24} tone="success" />;

Logo 預設為靜態圖片。motion="breathe" 隱藏時保留尺寸,頁面載入完成且至少一半可見時,以 4.8 秒呼吸動效顯現一次;頁首與頁尾不額外等待。motionVisibilityDelayMs 可增加連續可見的停留時間,預設為零。motionOnceKey 在同一文件重新掛載時共用播放記錄,平台頁首和頁尾使用獨立識別碼。站內導覽、主題切換和捲回不會重播,完整重新載入才會重設。減少動態效果、停用 JavaScript 或無法觀察可見性時顯示靜態圖片。motion="reveal" 保留為別名。

PlatformHeader.autoHideOnScroll 預設為 false;PublicPlatformHeader 會啟用此功能。向下捲動時隱藏,向上捲動或接近頂端時顯示。頁首選單開啟或焦點在頁首內時保持可見。工作區和編輯器頁首維持固定。

PlatformHeader 是無業務狀態的 Header 骨架。PublicPlatformHeader 在它之上組合品牌入口、公共導航、語言、主題、登入、「立即體驗」和行動選單,平台匿名狀態與文檔站直接復用該組合。

公共導航透過 buildPublicHeaderNavItems(copy, links) 統一產生「資源 / 價格 / 新聞」。接入方只解析當前應用的站內、文檔站和平台 URL,不應重複定義選單順序或文案。登入後的平台 Header 也使用同一產生函數。

<PublicPlatformHeader
  copy={headerCopy}
  links={{
    brandHref: '/',
    resourceCenterHref: '/resources',
    userManualHref: 'https://docs.qokit.com/manual',
    developerDocsHref: 'https://docs.qokit.com/developers',
    changelogHref: 'https://docs.qokit.com/changelog',
    pricingHref: '/pricing',
    newsHref: '/news',
    loginHref: '/login',
    studioHref: '/studio'
  }}
/>

底層 navItems 仍支援 link、scroll 和 menu。menu 桌面端支援點擊、鍵盤、Escape 和點擊外部關閉,行動端由 MobileHeaderMenu 展開為連結分組。

SiteFooter 是 Footer 骨架;平台與文檔站使用 PublicPlatformFooter 統一組合外層 Shell、品牌入口、連結、主題和語言控制項。跨域接入透過 resolveCompanyHref 把相對平台連結轉換為絕對地址。

<PublicPlatformFooter
  brandHref="https://qokit.com"
  copy={footerCopy}
  resolveCompanyHref={(href) => `https://qokit.com${href}`}
/>

業務應用不得複製 Header、Footer DOM 或公共導航陣列;需要不同視覺表現時使用 PlatformHeaderSkin、SiteFooterSkin 或對應平台 Skin。

相容策略

  • 新增可選屬性和 Skin 槽位屬於向後相容變更;
  • 刪除屬性、修改預設語義或改變 DOM/鍵盤行為屬於破壞性變更;
  • 破壞性變更必須進入 Changelog,並提供遷移範例;
  • 不要依賴未公開的內部 class、目錄或路由結構;
  • 兩個以上接入點需要相同覆寫時,應提升為公開 Skin 或 Token。

全螢幕編輯

EditorWorkspace 整合全螢幕對話框、焦點管理與響應式面板。透過 dirty 確認是否捨棄修改、busy 防止儲存時離開,並以 onSave 處理 Ctrl/Cmd+S。權限、資料、儲存與發布由宿主負責。

view / onViewChange 統一切換 edit、focus、preview,不替換正文編輯器。preview 提供預覽,previewPanel 重用既有面板。layout 支援 writing、structure、canvas;storageKey 只記憶面板寬度與收合偏好,不儲存正文。

onSaveAndClose 在確認儲存成功後回傳 true,失敗回傳 false;宿主已導覽時回傳 handled,業務驗證仍需使用者決定時回傳 pending。失敗時保持編輯器開啟。只有宿主保留草稿時才使用 closeBehavior="collapse"。EditorSaveStatus 顯示宿主確認的狀態;既有工作區也可組合 EditorViewControls、EditorLeaveDialog 與 useEditorLayout。

鍵盤遷移:Segmented 只佔一個 Tab 停駐點,透過方向鍵及 Home / End 切換選項。Dialog 尊重子浮層對 Escape 的處理;編輯器接著先退出專注或預覽,再處理關閉。LivePreviewToolbar.exitControl 可接入共用視圖控制項。儲存快捷鍵呼叫宿主,發布與權限仍由宿主負責。

import { EditorWorkspace } from '@qokit/components/patterns';

<EditorWorkspace
  open={open}
  title={title}
  dirty={dirty}
  busy={saving}
  onClose={closeEditor}
  onSave={saveDraft}
  onSaveAndClose={saveDraft}
  saveState={saveState}
  layout="writing"
  storageKey="article"
  preview={preview}
  navigation={structure}
  inspector={properties}
  actions={saveActions}
>
  {editor}
</EditorWorkspace>

SidebarToggleSlot

SidebarToggleSlot 將現有側欄收合按鈕放到工作區頁首,每個工作區配合一個左側欄使用一個插槽。展開狀態、快捷鍵與行動抽屜仍由 SidebarNavigation 管理;未提供插槽時保留原位置。行動抽屜也由頁首按鈕關閉,關閉後焦點返回同一按鈕。

EditorHeader

EditorHeader 將宿主的 Logo、頭像與全域選單保留在目前編輯器中。startControl、endControl 分別控制兩側面板,center 放檢視命令,actions 放儲存操作。PlatformHeader.editorActions 重用響應式導覽、語言與主題控制項。onNavigate 必須先處理尚未儲存的內容,再執行導覽回呼。窄螢幕頂列分為兩行,子選單優先處理 Escape。

WorkspaceHeaderPortal.startControl 和 endControl 將受控頁面面板切換按鈕放置在宿主對應的槽位中。宿主公開可選的 startTarget 和 endTarget,與標題、狀態和動作並列。Files 庫和單一資產工作區使用 workAreaControls;資產預覽保留完整標題,使其身份、返回動作和面板目的地保持可用。ProjectWorkspace 擁有內容和 Files 的共用左側導航/對話選擇。Files 透過 useProjectResourcePanel 註冊其記憶中的資源面板尺寸,透過 ProjectContentTools 門戶導航,並僅透過 ProjectToolbar.endControl 提供其右側檢查器控制項。對話在所有專案區域使用相同的左側面板區域和嵌入式編輯器;緊湊型資源、對話和檢查器任務互斥。

EditorNavigationMenu

EditorNavigationMenu 將宿主完整的 SidebarNavigation 放入覆蓋式抽屜,保留權限與專案上下文,不擠動畫布。語言與主題位於底部,子選單優先處理 Escape。專注與瀏覽器全螢幕互相獨立;導覽會等待進行中的儲存並保護草稿。

WorkspaceNavigationMenu / WorkspacePageHeader

全域導覽使用 Mac 的 Command+\ 或 Windows/Linux 的 Control+\,在創作室內也可獨立使用。T 與 Shift+T 保留編輯版面功能;快速鍵會忽略可編輯目標、輸入法組合輸入、重複及已處理事件。 按鈕提示和 aria-keyshortcuts 顯示組合鍵;全域導覽不再占用單獨的 T。

登入後的工作區透過 PlatformHeader.workspaceActions 在所有寬度共用帳戶及導覽區,WorkspacePageHeader 統一標題與操作。WorkspaceNavigationMenu 顯示目前側欄,保留權限與業務脈絡;EditorNavigationMenu 保留為相容別名。Studio 保留自己的任務工具列。公共頁首沿用現有呈現方式。

WorkspaceNavigationGuard 透過 dirty、busy、error 與可選的 onSave 保護全域導覽。儲存確認成功並回傳 true 後才能離開,失敗保留草稿。Language.onBeforeChange(apply) 允許宿主透過同一保護延後語言切換。儲存期間停用表單欄位。

桌面導覽保留展開和圖示模式,並新增自動隱藏。常駐側欄與抽屜共享搜尋和分組狀態。精確指標在導覽邊緣停留 300ms 後暫時喚出,離開 320ms 後收回;點擊後保持展開。觸控與鍵盤保留明確入口。Dialog 預設使用 modal={true} 和 autoFocus={true};懸停預覽將兩者設為 false,保留原輸入焦點與捲動。

EditorViewControls

編輯與專注使用同一個雙向按鈕:編輯時顯示「專注」,專注時顯示「編輯」。點擊或按 T 切換,E 仍可直接返回編輯。窄螢幕保留切換按鈕,預覽、全螢幕與附加操作收進更多選單。

EditorViewControls 將編輯/專注與螢幕全螢幕分開控制。預覽為獨立開關,關閉後返回先前的工作模式;自訂退出動作透過 useEditorWorkMode 保留該模式。原有 edit/focus/preview 值繼續有效。預覽入口改為帶 aria-pressed 的 button,不再是模式群組內的 radio。全螢幕由使用者點擊進入,應用程式根節點包含導覽與彈層;瀏覽器不支援時隱藏入口。

Language / Appearance

Language 與 Appearance variant="menu" 支援可選的 layout="row",同一列顯示標籤、目前值和箭頭。預設精簡布局及語言切換保護維持相容。SiteHeaderCopy.helpResources 與 contactSupport 可選提供工作區說明入口文案。

requestWorkspaceNavigation

有側欄開關的頁面不再顯示額外的頁首選單按鈕,收合和手機版面也遵循此規則;編輯器及無側欄頁面保留入口。從 @qokit/components/patterns/WorkspaceNavigation 匯入 requestWorkspaceNavigation(returnFocusTarget?) 和 useWorkspaceNavigationState():請求切換已註冊的抽屜,無可用抽屜時回傳 false,可選元素用於關閉後恢復焦點。顯示備用入口前檢查 .available。請使用既有開關或此 API,不再依賴已移除按鈕的 DOM 位置。

WorkspacePanelReveal

全域導覽使用選單圖示,編輯工具使用左右分欄圖示。useWorkspacePanelReveal({ temporary: true }) 在專注中支援點擊和鍵盤暫時開啟工具;toggle(trigger?) 和 close(true) 保留已儲存的版面和工作模式,並在關閉後恢復焦點。螢幕邊緣喚出全域導覽,工具只回應自身按鈕附近的懸停。預覽隱藏編輯面板開關,提供「返回編輯」,恢復先前的編輯模式。

EditorViewControls / 顯示模式

EDITOR_VIEW_SHORTCUTS → Tooltip + aria-keyshortcuts

EditorHeader 同時管理 EDITOR_TOOLBAR_SHORTCUTS:Command/Control+S 呼叫可見的 EditorSaveButton,Shift+P 開啟 EditorStatusAction shortcut="publish" 的發佈設定或檢查,Shift+M 開啟編輯工具選單。快捷鍵與點擊使用同一可用控制項,正式發佈仍須在面板內明確操作。只有目前可見標頭回應;子選單、對話框、輸入法組字及重複事件不回應,輸入欄位內只允許儲存組合鍵。提示與 aria-keyshortcuts 共用定義。自訂 toolsControl 在觸發按鈕設定 aria-keyshortcuts={EDITOR_TOOLBAR_SHORTCUTS.tools.aria};ActionMenu.triggerKeyShortcuts 只加入屬性與共用提示,不註冊全域快捷鍵。

面板快捷鍵為 Shift+A 新增、Shift+L 頁面/圖層、Shift+K 對話、Shift+C 內容、Shift+D 設計、Shift+G 全站風格。CMS 在入口可用時提供 Shift+S 設定、Shift+E SEO、Shift+H 歷史。以 shortcut 中繼資料將 EditorChoiceControl/EditorViewTabs 選項與 ActionMenu 操作接入共用提示;EditorPanelChoiceShortcuts 與手機工具的 EditorViewControls.compactActions 在選項收進選單後保留原操作。自訂 EditorPanelShortcuts.commands 可註冊既有操作,不重複繪製控制項。隱藏、inert、停用、預覽與浮層限制仍有效;同一工作區的手機非模態側欄允許切換面板,選單和模態對話框仍攔截快捷鍵。未按 Shift 的既有快捷鍵保持原行為。

顯示模式
E編輯
T編輯 ↔ 專注
V預覽 / 返回編輯
F進入全螢幕 / 退出全螢幕

僅目前的編輯器回應;輸入文字、輸入法組字、持續按鍵及子對話框或選單開啟時,不切換模式。

PlatformHeader.workspaceNavigation

PlatformHeader.workspaceNavigation 將全域導覽放在 Logo 前,workspaceActions 與 editorActions 保留帳戶操作。一般工作區沿用既有側欄開關,編輯器的右側工具開關位於頭像之前。窄螢幕上排放導覽、品牌、標題與頭像,下排放編輯工具與儲存;DOM 順序配合版面,保留無邊框毛玻璃效果。

2026-09-06 - EditorHeader.preview / EditorViewControls.returnView

EditorHeader.preview 僅顯示 center,收成無邊框的精簡預覽工具列;Logo、帳號、儲存和面板入口保持掛載但隱藏。宿主使用獨立 LivePreviewToolbar 時可隱藏編輯頁首,透過 EditorViewControls.returnView(edit 或 focus)還原原工作模式。保留無障礙返回與獨立全螢幕操作;網站本身的頁首繼續顯示。

2026-09-06 · Builder / CMS

Builder 與 CMS 內容編輯透過 BuilderWorkspace、EditorCatalog 和 EditorComponentSettings 共用工作區面板、插入圖示及樣式設定。預設一次套用關聯設定並保留既有內容,儲存與復原由宿主負責。工作區控制項跟隨平台主題,內容呈現跟隨網站主題。

伺服器端頁尾 · 2026-09-07

SiteFooterLayout 接受明確的 locale 和單一語言的 copy。伺服器元件輸出共用頁尾結構;主題、語言控制項和 QR 碼對話框仍以用戶端元件執行。既有的 SiteFooter、PublicPlatformFooter 介面繼續保留。

import { SiteFooterLayout } from '@qokit/components/patterns/SiteFooter';

<div className="qk-platform-footer-shell">
  <SiteFooterLayout locale={locale} copy={footerCopy} />
</div>

請先在伺服器端將跨網域連結整理至 copy.companyLinks;透過 controls 自訂互動控制項插槽。

EditorHeader.titleControl / FloatingAssistant.presentation

EditorHeader.titleControl 與 EditorWorkspace.titleControl 可將純標題替換為共用專案選單。保留具描述性的 title 作為工作區識別,導覽繼續經過現有未儲存變更保護。FloatingAssistant.presentation="embedded" 在宿主面板內呈現具名稱的區域,省去浮動入口和遮罩;預設仍為 floating。宿主負責位置與顯示狀態,對話狀態和權限繼續由助理管理。

2026-09-07 · WorkspaceAssembly

WorkspaceAssembly 標記離開的卡片與進入的工作區,不增加佈局容器。依賴直接子元素的宿主應將 workspaceAssemblyAttributes(part, index, phase) 放在現有 DOM 上;EditorHeader.assemble 和 BuilderWorkspacePanels.assemble 提供編輯器標記。

僅在建立成功後呼叫 await startWorkspaceAssembly(navigate, destinationPathname),擷取可見區塊、導覽一次,並在最多 720 毫秒內組合目標或相符的載入骨架。目標須提供進入階段的 canvas 標記;用 useWorkspaceAssemblyPending() 保持載入介面掛載直到快照完成,並預載入資料與程式碼。減少動態效果或不支援時直接導覽;過慢或中斷時釋放快照並繼續。標記不會自行觸發編輯、重新整理或歷史導覽動畫。共用模式負責暫時樣式與清理,宿主保留建立錯誤、冪等與載入狀態。

2026-09 · 管理工作區

WorkspacePage 和 WorkspaceLayout 接受 variant:overview、list、detail、settings 或 editor。WorkspaceFormFooter 統一宿主提供的 actions、message、tone 和 busy 回饋位置,不負責儲存資料。

窄螢幕 WorkspaceDataTable 和 AdminDataTable 預設顯示帶欄位標籤的記錄,保留選取、自訂表頭與操作。需要欄對齊的比較矩陣使用 mobileLayout="scroll"。WorkspaceFilterToolbar 先放搜尋與篩選,再放排序和檢視控制項。側欄標題使用 h2,頁面保留 h1。

2026-09-08 · Task focus

useSidebarTaskFocus(active) 在專注任務期間暫時隱藏導覽,退出時恢復先前顯示方式;任務期間使用者主動修改導覽模式時,以使用者選擇為準。自動隱藏不會改寫已儲存的偏好。

新增 API 參考(英文,譯文待同步)

EditorHeader.contextMode="title" displays the editor's own titleControl instead of the host workspace picker. The default "host" behavior is unchanged; navigation, brand, account controls and leave guards retain their existing ownership. Hosts supply responsive placement for their title control.

EditorViewControls.focusInMenu shows a labelled preview action and moves focus mode into the shared menu. Its default remains false; view shortcuts and returning from preview keep the existing behavior.

EditorViewControls.toolsControl replaces the fallback menu with a host-owned tools control. Hosts retain its accessible trigger, menu state and actions; view buttons and keyboard shortcuts keep their existing behavior. 創作室 uses this slot for its complete editor tools menu beside Add, Layers and Preview.

EditorViewControls.responsiveLabels displays text beside focus and preview icons above 720px, reserving space for both focus labels. At phone widths the labels are hidden while accessible names and tooltips remain. EditorSaveButton.showStatusLabel displays saved/saving status or a retry action when state is provided; it reserves label space across states. Both options default to false.

ResizablePanels.middlePanelProps forwards section attributes such as inert to the middle panel, matching the existing side-panel attribute slots. An editor can keep its canvas mounted while preventing keyboard and pointer interaction when a compact conversation view covers it. Hosts still control panel visibility and restore focus when switching views; the prop does not unmount content.

ProjectSwitcher.currentWorkspaceId optionally marks the parent workspace independently of currentProjectId; only the current location receives the selected surface. IDs must match the supplied projects items. onActionSelect(action, event) lets the host guard shortcut navigation after the menu closes; omitted callbacks retain normal link behavior. Creation shortcuts use ordinary menu surfaces. Optional SiteHeaderCopy.projectSwitcherCreate and projectSwitcherWebsites label creation and the current workspace's website group without renaming the 創作室 product.

AccountDropdown.usageSummary is an optional slot below the account identity for host-supplied credit balances, plan usage and links to details. It also accepts ({ environmentInfo }) => ReactNode to place the shared ID disclosure and copy controls in the summary without duplicating them below. Links use role="menuitem" and retain menu keyboard behavior and navigation guards. The platform header shows credits and plan usage in two columns, with ID details expanding below; the sidebar account retains appearance and language. Failed reads never appear as zero, and reopening the menu refreshes the data.

PublicPlatformHeader.workspaceAction optionally supplies { href, label } for an authenticated visitor's return link. It replaces the desktop login icon and stays visible beside the mobile menu; the mobile menu then omits anonymous account actions. Session detection belongs to the host. The platform home uses a lightweight local session check, updates after focus/storage changes, and keeps ?view=public on its brand link so explicit website visits survive refresh.

contextAfter places editor-specific scope controls after the host project picker, preserving their DOM and keyboard order. The host retains project navigation and leave guards; the editor owns page and content-language selection. Hosts may adapt the responsive layout to put this context on its own row.

WorkspaceNavigationMenu.footerLinks supplies direct icon links alongside the sidebar display control. footerMenus accepts ordered WorkspaceNavigationFooterMenu entries, each with a label, icon and link items (with optional separatorBefore). The platform uses one menu for Website Home, Pricing, Templates and News, and a book-icon Help & Support menu for the user manual and contact support. The single footerMenu prop remains supported when footerMenus is omitted. Desktop menus open upward with ActionMenu placement="top" portal; mobile uses bottom sheets. The controls form one row when expanded and a column in icon mode; on mobile the sidebar control closes the navigation drawer. Each icon retains an accessible name and tooltip. profile adds the user name, plan and account menu without duplicating an existing sidebar account. Omitting footer links and menus retains the existing preferences and fullscreen actions.

Set a footer menu item's newTab to open a reference destination with target="_blank" and rel="noopener noreferrer". The skeleton adds a trailing arrow and localized screen-reader notice; other items keep current-page navigation. Website Home, Pricing, Templates, News, the manual and contact support use new tabs so the workspace stays open. An explicit public-home visit preserves ?view=public to bypass the signed-in landing redirect, including after refresh.

Editor tool palettes can use Dialog with keepMounted to preserve search and form state while closed. Closed dialogs immediately become inert, hidden from assistive technology, and leave the focus stack, including during a visual exit transition; the default still unmounts their content. Pair nonmodal palettes with DialogPanel to reuse the global overlay surface. Toolbar accepts a DOM ref for bounded positioning while retaining its shared arrow-key navigation.

useFloatingSurface from @qokit/components/patterns/FloatingTools supports defaultHeight: 'auto' for content-sized palettes. Keep the host body shrinkable with internal scrolling; the hook caps the surface to its workspace bounds and observes size changes. Moving an automatic palette stores its position without freezing the measured height. Resizing explicitly stores a fixed height, including across reloads; reset() or Home on a movement/resize handle restores automatic sizing. Numeric defaultHeight retains the existing fixed-height behavior.

FloatingToolPanel composes the shared DialogPanel, TreeToggle, pin button, tooltip and close button. Place it inside a nonmodal Dialog; the host controls pinned, collapsed, their callbacks and document operations. Pinning keeps the palette open after an operation; it does not lock its position. The title and header whitespace accept useFloatingSurface().dragHandle, while buttons, menus and inputs never initiate dragging or folding. Double-click the title or whitespace to fold; the explicit fold button supports keyboard and touch. Folding hides the body without unmounting it, preserving searches and tree state. Pass the same collapsed value to useFloatingSurface to retain the expanded height while moving the folded header. Optional actions and skin slots reuse the same structure; styles stay in the shared stylesheet.

Optional FloatingToolPanel.viewKey adds a short opacity transition when the active tool changes, without replacing its body instance. Ordinary parameter updates do not animate. Opening, closing, unfolding and pin feedback share the existing motion Tokens and respect reduced motion. Dragging stays direct; useFloatingSurface coalesces pointer movement to one geometry update per animation frame and saves the final position on release. Browsers without discrete display transitions close immediately.

Unified editors pass focus={false} to omit the separate Focus control. primaryActions accepts shared tool buttons before Preview; onTogglePanels handles T, and onToggleAllPanels handles Shift+T. 創作室 uses T to cycle from visible panels to floating launchers to fully hidden and back to the last visible layout; ordinary launcher clicks still open their panel. Shift+T directly hides everything and restores the exact preceding state. Both sidebar shortcuts are inactive in Preview and respect editable targets and active overlays. Existing hosts keep Edit/Focus behavior by default.

useWorkspacePanelVisibility().togglePanels hides the visible editor panels or restores their preceding layout. Desktop and compact layouts are remembered independently, and forceCollapsed (for example during Preview) does not overwrite that memory. The host owns global navigation visibility and any edge launchers.

For floating editor panels, pass skin: platformWorkspacePanelRevealSkin from @qokit/components/skins/platform and spread the returned panelProps onto the existing panel. The skin applies only while revealed; the docked panel and its mounted content remain intact. ResizablePanels merges startPanelProps, middlePanelProps, and endPanelProps class names with its own skin slots. Pair focus controls with Toolbar and platformFloatingToolbarSkin for shared keyboard navigation and compact spacing. Both skins share the global DialogPanel surface (background, shadow and blur); panel corners use the card radius and toolbar corners use the control radius. Hosts own positioning and available space, not a separate overlay palette.

useWorkspacePanelEdgeDrag is an opt-in hook for an existing workspace root ref. Mark its focusable borders with data-workspace-panel-edge="start" or "end"; ResizablePanels supplies these attributes on its own separators. The host provides each side's mode (expanded, icons, hidden), saved width and bounds through getState, applies onChange, and returns a rollback callback from onBegin. onResizing should suspend layout transitions; onFinish restores focus to the resulting control, and onReset restores the host's default width. One captured mouse or touch gesture crosses all three states, with RTL direction handling and cancellation on Escape, pointer cancellation or window changes. Arrow keys resize or step states, Shift increases the step, Home/double-click resets, and End expands to the allowed maximum. This hook adds no visual controls or stored content. Hosts can pair hidden borders with useWorkspacePanelReveal for temporary shortcut access while retaining their normal click actions; hosts without the hook keep existing resizer behavior.

FloatingAssistant.headerActionsTarget optionally accepts an HTMLElement in the host heading. The assistant portals its existing conversation history and new-conversation controls into that element and omits its internal header. Without a target, the original header remains. The host owns the heading and placement; the assistant retains action handlers, accessibility labels and conversation state. The Web adapter forwards this slot.

FeatureHint is exported from @qokit/components/patterns/FeatureHint. Use it for contextual first-use guidance attached to a real control. Provide a versioned id, a stable user scopeKey, an anchor: HTMLElement, an active eligibility signal, localized title, description, dismissLabel, and action: { label, onClick }. Set completed when the user discovers the capability independently. A null scope or unavailable anchor suppresses the hint.

The shared component allows one hint at a time, waits briefly for a visible target, follows scrolling and resizing, supports RTL, and keeps content inside the viewport. It does not add a backdrop, steal focus, or perform the action automatically. Escape, the close button, or clicking elsewhere dismisses it; Tab from the target reaches the action. The target receives a temporary highlight and accessible description. Seen hints are remembered in the current browser per scope and version, with an in-memory fallback if storage is unavailable; this is not cross-device progress. Hosts own permissions, review-state suppression and the actual action. skin, className and style adapt presentation.

AssistantContextCard is exported from @qokit/components/patterns/FloatingAssistant. Place it in composerContext to summarize the current editing target. Its typed contract includes title, description, scope, preview, parameters: { id, label, value }[], optional controls, status and notice, plus actions, onLocate and clearAction. Pass localized labels and formatted values, including units, from the host.

The card renders a read-only definition list, an optional controls slot for a few common adjustments, and a live status region. Reuse the host’s existing editing controls and commands in this slot; keep complete settings behind an explicit action that opens the existing inspector. Hosts retain ownership of selection, permissions, save, undo and AI requests. Conversation, canvas editing and inspector editing can operate together, with independent panel visibility. Selecting an object updates the card and an already open inspector without opening a closed panel or moving focus. Removing a conversation reference preserves canvas selection and direct editing; keep the conversation entry independent of this card and of floating-tool visibility. Changing the target or a parameter updates this live card without appending chat messages. Both draft and project conversations can use the same component. className, style and AssistantContextCardSkin support visual adaptation; styles are loaded with the component.

FloatingAssistantPanel.composerContext 接收输入框上方的实时上下文区域。提供此插槽时,顶部旧的 activeContext 摘要隐藏,activeContext.promptPlaceholder 仍供输入框使用。实时参数属于当前编辑状态,不应追加到历史消息列表;Web 适配器透传此插槽。

Hosts can set hoverReveal={false} to disable navigation previews from the trigger and window edge while retaining explicit controls and drag resizing; the default remains true.

WorkspaceNavigationDock prefetches same-origin destinations on mouse hover or keyboard focus, with bounded deduplication.

Web 適配器同時透傳 FloatingAssistantPanel.composerAttachments:在訊息表單內部、文字輸入區之前放置宿主管理的附件。宿主負責網格位置與傳送生命週期:拖入只加入待傳送附件,成功後僅清除本次提交的附件,失敗保留以便重試。

共享對話元件(英文參考,待翻譯)

@qokit/components/patterns/Conversation exports ConversationPanel, ConversationMessages, ConversationMessage, ConversationSuggestions and ConversationComposer. 創作室 generation, draft refinement and the embedded project assistant use these structures and the same token-based stylesheet. Hosts own requests, history, permissions, selected objects and review/apply actions.

ConversationFeedback 組合 InlineNotice,在對話中精簡呈現任務狀態、失敗、備援和儲存回執。提供在地化的 title,以及選用的 description、tone 和 action。兩行均使用說明文字字級、緊密間距和透明表面;色調凸顯狀態,輔助文字保持淡化。預設的 role="status" 與 aria-atomic="true" 將整個更新一併播報;需要使用者處理的失敗使用 role="alert"。助理撰寫的正文繼續放在 ConversationText 中。

Place the scrollable ConversationMessages and the fixed ConversationComposer directly inside the panel. Supply a localized label for the messages region and inputProps for the controlled textarea. The composer accepts attachments, notice and actions slots, plus formProps and formRef; it creates the form, so do not nest it in another form. Enter inserts a newline; Cmd/Ctrl+Enter requests submission with composition and disabled/busy guards. Preserve user input while a request is running when the host supports it.

PromptPanel.presentation="conversation" reuses the composer while retaining reference reading, upload/menu controls and serialized form fields. The default "prompt" preserves the landing-page prompt behavior. FloatingAssistant.presentation="embedded" uses the shared panel, messages, suggestions and composer; floating assistants retain their compact presentation.

新增 API 參考(英文,譯文待同步) · 2026-10

2026-10-10 · Pagination dot display

Pagination from @qokit/components/ui accepts pageDisplay="dots" for compact visual choosers. Combine it with layout="centered" for centered arrows and 6px indicators with 32px-wide click targets. Dot colors, hover and keyboard focus use shared theme Tokens; PaginationSkin.dot adapts the indicator slot. Hosts supply currentPage, totalPages, onPageChange and localized navigation labels. pageLabel names each dot; its fallback combines ariaLabel with the page and total. Browsing pages only invokes the host callback. The default "numbers" display retains numeric pagination and formatPageNumber.

2026-10-10 · ActionMenu search header

ActionMenu.dropdownHeader accepts host-owned content before the actions in both dropdown and mobile sheet presentations. onOpenChange reports opening and dismissal so hosts can reset transient search state. Search hosts supply localized copy, filtering and initial input focus; ArrowDown from the input should focus the first enabled result, then the shared menu handles result navigation, selection and Escape.

2026-10-09 · Inline ColorPicker

ColorPicker from @qokit/components/ui/ColorPicker accepts presentation="inline" to expand its editor beneath the field trigger. It renders a named group in the document flow, keeps the surrounding workspace available, and retains palette, HEX, opacity, gradient and reset capabilities. Hosts should reserve a full row for the field. Changes to the controlled value, including undo and reset, update the open inline editor; leaving the field finishes the current edit. The default "popover" presentation retains its portal, outside-click dismissal and Escape behavior.

2026-10-07 · WorkspacePanelGrid

WorkspacePanelGrid from @qokit/components/patterns/WorkspaceLayout places independent detail panels below the shortest available column. It responds to content and container size changes without moving or remounting child nodes; DOM and keyboard order remain unchanged. Narrow containers use one column. Keep continuous panels in one grid rather than separate rows. Metrics, tables, paired fields and ordered workflows retain their own layouts.

Each direct child is a panel. Use data-workspace-panel-span="full" or a numeric column span on that child's root for wider panels. The optional skin has a root slot and variables; --qk-workspace-panel-grid-gap controls shared spacing, and --qk-workspace-panel-grid-max-columns defaults to 2. Without JavaScript or ResizeObserver, panels retain the responsive ordinary grid.

2026-10-08 · Shared list toolbar groups

WorkspaceFilterToolbar now has one container-responsive contract across Projects, CMS and Admin:

  • query:search、狀態 filters、sort、業務 controls、advanced 選項、依條件顯示的 reset、資源 result 與輔助 summary。
  • presentation:view,顯示 controls 和 options,例如可見欄位和頁面大小。頁面 Widget 自訂應放在頁面標題動作中。
  • actions: persistent operations, followed by the optional selection control at the logical end. Use ToolbarButtons with icon and localized compactLabel for refresh and other familiar actions.

The shared component measures its own available width. Controls show icons with labels above 960px and accessible icon buttons at or below 960px. At or below 640px, search occupies the first row and tool groups wrap in query → presentation → actions order. Routes must not override group widths or hide individual labels. ControlMenu and ViewMenu inherit this presentation without a route-specific responsive flag.

透過 query.result={{ label, count, total?, locale? }} 提供資源名稱和結果數量。共用 WorkspaceResultSummary 顯示「名稱 · 數量」,僅在可靠的未篩選總數與結果數量不同時加入「/ 總數」,並依介面語言格式化及隔離雙向數字。數量未知時省略 result;零是有效結果。同一清單上方不要另加名稱和數量列。AdminFilterBar.result 接受相同物件。頁面標題、有效分組標題、分頁和選取數量各歸其位;其他計量單位、查詢脈絡或更新時間使用 query.summary。

Give overflow a localized label to move advanced and display options into More when compact. query.compactItems and presentation.compactItems supply complete menu choices replacing their corresponding controls; controlled values and callbacks remain in the host. Permanent menu actions use overflow.items. Selection and refresh stay outside More. Select and Done share the end slot, hit target and reserved idle toolbar height, including wrapped mobile rows.

This replaces the old flat toolbar API: migrate search, filters, sort, reset and secondaryControls into query; migrate view and display controls into presentation; move persistent endActions to actions. The former adaptive / inline-wrap CSS modes and WorkspaceFilterControlGroup capsule are removed; use these three semantic groups rather than compatibility aliases.

2026-10-10 · EditorItemDisclosure

EditorItemDisclosure from @qokit/components/patterns/EditorItemCollection accepts title, summary, open, onOpenChange, leading, actions and children for editing within a list. Sibling items remain visible. Escape collapses the item and restores trigger focus; opening does not scroll or autofocus. useEditorItemDisclosure scopes single-item expansion with scopeKey and restores adjacent focus after deletion. EditorItemCollection uses the same interaction; hosts still own content, ordering, persistence and undo. The existing EditorFocusedItem export remains available for flows that require a separate detail view.

API 參考補充(英文,譯文待同步) · 2026-10

2026-10-15 · Shared inspector choices

EditorStyleChoice uses the shared EditorChoiceControl for finite settings. In auto mode, two or three illustrated options use a segmented group; larger illustrated sets use a portalled ControlMenu showing the current icon and name. Text-only choices retain a native Select. Existing custom values remain selectable.

Select 與選單選項可透過 annotation 在名稱後顯示主題色圓點,並將本地化含義加入可存取名稱;ControlMenu 的觸發器也會顯示目前選項的圓點,triggerAnnotation: null 可僅在選單內保留標記。選單再次選擇已選取的可用項目時,可透過 onReselect 接收回呼。原生 Select 在名稱旁直接顯示說明;hidden 可將預留位置排除於選項清單之外。宿主決定標記的值及選擇後的行為,共用控制項不推斷繼承關係或寫入資料。

Use presentation="visual" for labeled diagram choices and presentation="toolbar" for familiar tools such as four-way text alignment. The toolbar has separate targets without a shared capsule. Native radios, shared menu keyboard handling, visible focus, disabled states and theme Tokens are retained. Hosts own labels, allowed values, persistence and undo. id identifies the control; ControlMenu also accepts triggerId and disabled.

Inspector menus, inputs, collapsed summaries and reset actions share a 32px mouse field height, restored to 40px on narrow screens and coarse pointers. Field icons use 16px and diagram choices keep an 8px gap. EditorComponentSettings reuses these choices for columns, density, image fit and aspect ratio, while composition layouts retain detailed previews. If saving briefly disables native radios, the shared skeleton restores focus to the selected option for continuous arrow-key editing.

Inspector labels and diagram captions use the 12px caption scale; values, actions and section titles use the 13px field scale. Visual choices have no decorative outer border: a soft selected surface and centered caption identify the current option, while keyboard focus retains its ring. Font specimens in the inspector use a compact, bounded scale.

2026-10-15 · Responsive workspace tables

WorkspaceDataTable reflows mobileLayout="records" into two columns of labeled facts, with the primary identity and sticky end actions spanning the record. Names and identifiers can use two lines. Column labels and selection remain accessible. Comparison tables using mobileLayout="scroll" retain their columns.

When a host toolbar already provides sorting or other header actions, set mobileHeader="labels" to remove duplicate header controls from the mobile layout and tab order. Column names remain available to assistive technology; desktop headers are unchanged. The default "controls" preserves custom header controls on mobile.

2026-10-14 · Independent editor panels

resolveWorkspaceResponsiveProfile and useWorkspaceResponsiveProfile from WorkspacePanels, and EditorWorkbenchChrome, accept the optional panelPolicy="independent". With BuilderWorkbenchFrame and the platform editor skin, both panels remain docked above the mobile threshold. Shared styles temporarily compress displayed widths while retaining remembered sizes, and the canvas fits the remaining space. Effective work areas at or below 720px retain mobile task switching.

Hosts own panel visibility. When supplying a measured profile, use the same policy for the measurement hook and Chrome. Omitting panelPolicy retains the default "adaptive" policy with its existing desktop, two-column and overlay layouts.

Editor workspace integration

workspaceNavigation connects the host's shared business navigation through EditorWorkbenchChrome: desktop navigation reserves space beside the content, while mobile uses the shared drawer. It is separate from the document structure panel navigation and retains the host's permissions and unsaved-change protection.

EditorSaveButton.showIcon keeps the save glyph beside its label. iconOnly reduces the control to an icon while retaining an accessible action and status name and tooltip. Editor hosts can use useCompactWorkspaceHeader() to show icons and labels in roomy layouts and icons alone in compact layouts. EditorStatusAction.iconOnly follows the same rule while retaining its issue count.

2026-10-15 · EditorControlGroup title actions

The headerActions slot on EditorControlGroup remains visible in both expanded and collapsed groups, for actions such as content visibility beside a group title. Pointer and keyboard interactions with these actions do not toggle the group. summaryActions still appears only when collapsed. Hosts own action names, state and persistence; icon actions must use the shared IconButton with a localized accessible name.

2026-10-14 · Management groups and summaries

WorkspaceSectionGroup, WorkspaceSection, WorkspaceFieldGrid and WorkspaceFacts are exported from @qokit/components/patterns/WorkspaceLayout. Headings and descriptions sit above their content panels on both desktop and mobile, sharing the starting edge. Use the default stacked layout; legacy layout="split" callers also render stacked. Apply qk-workspace-section-group__form to forms within a group to share spacing and save-area alignment. WorkspaceSection accepts optional icon, actions and description slots, keeping headings outside the content panel.

WorkspaceFieldGrid arranges independent short fields in at most two columns according to available width. WorkspaceFacts renders a semantic definition list with stable id, label, value, and optional unit, description, emphasis and tone. columns supports 2, 3 or 4 columns and adapts to narrow containers. Set mobileColumns={2} for short numeric summaries that should retain two columns on phones; the default is one. It is unboxed so summaries can share an existing content panel. Each component supports its named Skin, className and style. Hosts retain form state, permissions, submission, conflicts and recovery; these components do not make requests.

2026-10-14 · Management content panels and disclosures

WorkspaceContentPanel and WorkspaceSection.kind support summary, form, records, and actions. Section toolbar stays outside the content surface; supporting and footer provide compact metadata and end operations. titleId preserves existing heading anchors. The default panel container does not override a host's named container.

Use WorkspacePanelBlock, WorkspacePanelMeta, and WorkspaceRecordRow for subordinate groups, metadata, and repeated records. A record accepts title, description, meta, status, actions, and full-width detail children. Facts always align at the top. Hosts retain business fields, permissions, table columns, and submission boundaries.

WorkspaceActionRow accepts an optional action label or quiet empty/loading status, alongside description and actions. Action identity uses 14px semibold text, status uses 14px regular text, and descriptions use 12px. Copy and controls share a center line on desktop and stack at narrow widths. Card surfaces do not override descendant strong typography or spacing.

WorkspaceDisclosure accepts title, optional status, and children; WorkspaceDisclosureGroup accepts Accordion items and controlled expansion props. They start closed unless the host specifies an initial item, and open at most one sibling. Enter/Space toggles; Escape closes and returns focus to its trigger, handling inner disclosures before their parent. Hidden panels retain their DOM and input state. Optional headingLevel supplies section heading semantics; Skin and class slots only adapt appearance. Import these components from @qokit/components/patterns/WorkspaceLayout.

CustomizableWidgetLayoutControls / CustomizableWidgetLibrary

將 CustomizableWidgetLayoutControls 放置在頁面標題動作中,位於情境說明之後、主要動作之前,包括在行動裝置上。使用本地化的 copy.customize 明確命名該動作(例如,“Customise widgets”)。同一個僅圖示的入口暴露 aria-pressed 和 aria-expanded,並在編輯期間變為 copy.done。customizeButtonRef 可選地暴露觸發器以恢復宿主焦點;disabledCustomize 停用該入口但不改變其幾何結構。僅為支援折疊 Widget 的宿主提供 onCollapseToggle 和 areWidgetsCollapsed;省略它們則僅呈現自訂入口。

CustomizableWidgetLibrary 擁有共同的庫標題、重置/關閉動作、響應式滾動佈局、初始關閉按鈕焦點和 Escape 處理。關閉時,如果焦點仍在庫內,則將焦點返回給呼叫的控制項;外部點擊保持其目的地焦點。宿主保留 Widget 定義、新增/移除/排序/調整大小指令、持久化和重置語義。CMS 和 Admin 類別槽位仍可用於領域鉤子,但不得定義單獨的庫表面或行動版佈局。

2026-10-17 · Rich ActionMenu triggers

ActionMenu.renderTrigger 可以重用一個豐富的控制項,例如 SelectableTile。它接收 aria-expanded、aria-haspopup、disabled 和 onClick;將這些屬性展開到實際的 trigger 上。主機保留該控制項的選擇語義和外觀。Portal 定位、選單鍵盤導航、關閉、焦點返回以及可選的手機端表單仍由 ActionMenu 擁有。預設按鈕和圖示觸發器保持不變。

圓角與範圍控制項

@qokit/components/ui/RangeNumber 的 RangeNumber 將原生範圍滑桿與精確數值 Input 配對。傳入 label、value、min、max、選用的 step 和 unit,以及 onChange。未定義的值顯示混合值短橫線;修改任一輸入會設定範圍內的單一數值。onCommit 讓宿主將連續修改合併到既有復原歷程。disabled、鍵盤導覽、緊湊密度、RTL 和焦點樣式共用;持久化由宿主負責。RangeNumberSkin 提供根、滑桿、輸入和單位槽位。

@qokit/components/patterns/EditorRadiusControl 的 EditorRadiusControl 結合即時形狀預覽、四個實體角輸入、RangeNumber 與選用形狀預設。value 與 onChange 使用 CSS border-radius 簡寫;cornerLabels 與預設名稱由宿主在地化。RTL 下仍依序為左上、右上、右下、左下。設定 max 將編輯限制為有界像素值,省略則保留 CSS 單位和橢圓角語法。混合圓角在使用者統一設定四角前不顯示單一數值。選用的 EditorRadiusControlSkin 調整根、示意圖、預覽與預設槽位,不改變狀態或持久化。

本頁目錄

組件接入2026-10-22 · 窄螢幕目前導覽標籤2026-10-20 · 視覺選擇卡片的獨立操作2026-10-17 · 共用工作台面板動效2026-10-17 · 依可用寬度計算編輯器預設值2026-09-30 · SelectionToolbar 無障礙支援2026-09-10 · 工作空間身分徽章2026-09-08 · EmptyState2026-09-08 · SidebarNavigation2026-09-07 - AccountDropdown / SidebarProfile2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace2026-09-07 · WorkspaceLocationSync / ProjectSwitcher2026-09-07 · 統一工作台導覽與 Qokit 圓潤風格2026-09-07 - ColumnLayout匯入入口公共職責邊界產生元素內容表單控制項清單選取指標卡片新增 API 參考(英文,譯文待同步) · 2026-10平台 Header 與 Footer相容策略全螢幕編輯SidebarToggleSlotEditorHeaderEditorNavigationMenuWorkspaceNavigationMenu / WorkspacePageHeaderEditorViewControlsLanguage / AppearancerequestWorkspaceNavigationWorkspacePanelRevealEditorViewControls / 顯示模式PlatformHeader.workspaceNavigation2026-09-06 - EditorHeader.preview / EditorViewControls.returnView2026-09-06 · Builder / CMS伺服器端頁尾 · 2026-09-07EditorHeader.titleControl / FloatingAssistant.presentation2026-09-07 · WorkspaceAssembly2026-09 · 管理工作區2026-09-08 · Task focus新增 API 參考(英文,譯文待同步)共享對話元件(英文參考,待翻譯)新增 API 參考(英文,譯文待同步) · 2026-102026-10-10 · Pagination dot display2026-10-10 · ActionMenu search header2026-10-09 · Inline ColorPicker2026-10-07 · WorkspacePanelGrid2026-10-08 · Shared list toolbar groups2026-10-10 · EditorItemDisclosureAPI 參考補充(英文,譯文待同步) · 2026-102026-10-15 · Shared inspector choices2026-10-15 · Responsive workspace tables2026-10-14 · Independent editor panelsEditor workspace integration2026-10-15 · EditorControlGroup title actions2026-10-14 · Management groups and summaries2026-10-14 · Management content panels and disclosuresCustomizableWidgetLayoutControls / CustomizableWidgetLibrary2026-10-17 · Rich ActionMenu triggers圓角與範圍控制項