Skip to Content
設計

設計契約更新

Qokit 公開設計 Token、組件 API 與接入契約的變更記錄。

設計契約更新

2026-10-21 · 捲動選單的固定操作

ActionItem.pinned 支援 start 或 end,使對應操作及 ActionMenu.dropdownHeader 保持在捲動清單之外,鍵盤導覽和選取語義涵蓋所有區域。Portal 宿主可用 --qk-menu-available-height 限制選單高度,該值依觸發器實際展開方向測量;未指定 pinned 時保留原選單結構。

2026-10-17 · Widget 自訂入口

頁面 Widget 自訂使用專案、內容與儀表板共用的標題入口。CustomizableWidgetLayoutControls 新增可選的 customizeButtonRef 和 disabledCustomize;折疊控制項為可選。CustomizableWidgetLibrary 在各宿主間共用行動裝置幾何結構、初始焦點、Escape 鍵及焦點回傳機制。Widget 持久化與指令仍由宿主擁有。請參閱 widget customization integration。

2026-10-17 · 受控工作區面板控制項

WorkspaceHeaderPortal 接受可選的 startControl 和 endControl,並配有對應的可選宿主目標。受控 Files 檢視使用與單一資產編輯和預覽相同的標題面板槽位和工作區域幾何結構。現有宿主可繼續僅提供標題、狀態和動作。請參閱 EditorHeader integration。

2026-10-17 · 測量編輯器預設值

useWorkspaceResponsiveProfile 新增可選的 onWidthChange(width) 用於取得可用工作區域的測量數據。useEditorLayout 現在也將配置的共用寬度限制套用至宿主儲存空間,且 readEditorLayout 接受可選限制作為其第四個參數。現有呼叫者保留其預設值。請參閱 Component Integration。

2026-10-08 · 工作區標題返回導覽

WorkspaceLayout 和 WorkspacePageHeader 新增選用的 backControl,放在標題之前。使用 WorkspaceBackButton,傳入本地化 label 及原有 href 或 onClick,共用組件提供箭頭、可存取名稱、Tooltip 和 RTL 鏡像。返回目標、清單狀態與離開保護繼續由宿主控制;未傳入該槽位的標頭保留現有版面。

2026-09-26 · 創作室 · 風格方案

精細間距 · 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.

按鈕與連結: 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 → 自動.

進階色彩: mutedColor, borderColor, buttonTextColor, cardSurfaceColor 与对应 dark* 字段 (--qk-site-color-card-rgb).

2026-09-09 · 全域導覽快速鍵

SidebarNavigation / WorkspaceNavigationMenu: 全域導覽使用 Mac 的 Command+\ 或 Windows/Linux 的 Control+\,在創作室內也可獨立使用。T 與 Shift+T 保留編輯版面功能;快速鍵會忽略可編輯目標、輸入法組合輸入、重複及已處理事件。

2026-09-08 · EmptyState

專案與 CMS 文章/商品的建立引導統一使用 EmptyState,採置中、透明表面、精簡文字層級及可換行操作。支援選用的 icon、layout、style,description 亦為選用。標題改用 h2;自訂 strong 選擇器請遷移至 title skin 槽位。多個操作使用共用容器,權限與建立處理仍由宿主負責。

2026-09-08 · SidebarNavigation

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

2026-09-08 - Primary button foreground

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

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 衍生自既有平台色彩。

橢圓主按鈕透過 --accent-action 直接使用 Logo 藍原色 #4695D8,取消加深漸層。懸停僅混入 8% 白色提亮;文字使用品牌墨色混入 10% 黑色,維持清晰。導覽高亮繼續使用同源品牌藍淺底與適配明暗主題的文字色。

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

2026-09-07 - ColumnLayout

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

2026-09-05 · WorkspaceNavigationMenu / WorkspacePageHeader

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

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

2026-09-05 · EditorNavigationMenu

EditorNavigationMenu 將宿主完整的 SidebarNavigation 放入覆蓋式抽屜,保留權限與專案上下文,不擠動畫布。語言與主題位於底部,子選單優先處理 Escape。1120px 以下含本值使用兩行頁首,檢視選單顯示目前模式名稱。專注與瀏覽器全螢幕互相獨立;導覽會等待進行中的儲存並保護草稿。

2026-09-05 · EditorHeader

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

2026-09-05 · SidebarToggleSlot

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

2026-09-05 · EditorWorkspace / Dialog / Segmented

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 可接入共用視圖控制項。儲存快捷鍵呼叫宿主,發布與權限仍由宿主負責。

2026-09 · EditorWorkspace

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

2026-08 · 緊湊指標密度

  • 為 MetricCard 新增可選的 density="compact" API,用於高密度營運工作區;
  • 維持既有預設密度與 DOM 語意不變;
  • 將緊湊內距、數值尺度和最小高度集中於共享元件樣式。

2026-07 · 統一表單控制項

  • 在 @qokit/components/ui 新增 FormField、Input、Textarea、Checkbox、RadioGroup 和 Switch;
  • 由共享 FormField 骨架連結標籤、說明、錯誤、必填狀態與 ARIA 參照;
  • 將 Input、Textarea、Select 和 SearchField 統一到 40px、44px、48px 尺寸和共享互動 Token;
  • 為新表單基礎元件加入平台、Admin 和產生站點 Skin 配方;
  • 保留既有 .qk-field 樣式作為向後相容的遷移路徑。

2026-07 · 按鈕尺寸排版

  • 新增 --button-font-size-sm、--button-font-size-md、--button-font-size-lg 三個語義 Token;
  • Button 的 sm、md、lg 現在分別固定使用 14px、15px、16px 文字,不再繼承 Header、Dialog 或頁面容器字號;
  • 站點 Skin 如需調整按鈕排版,應覆蓋對應語義 Token,不再通過路由 class 重寫 font-size。

2026-07 · 平台公共導航骨架

  • 新增無登入依賴的 PlatformHeader,平台與文檔站使用同一語義骨架;
  • 新增 PublicPlatformHeader 與 buildPublicHeaderNavItems,平台匿名狀態和文檔站復用同一公共 Header 組合及導航配置;
  • HeaderNavItem 新增 menu 類型,桌面 Header 使用可關閉的下拉選單,移動 Header 自動展開為連結分組;
  • SiteFooter 新增可選的 brandHref 與 controls,支援公開文檔等不同接入場景;
  • 新增 PublicPlatformFooter,平台和文檔站復用同一 Footer Shell,並允許跨域解析平台連結;
  • 以上均為向後相容的可選 API,原有平台 Header 狀態邏輯和 Footer 預設控制項保持不變。

2026-07 · 公開設計指南

  • 將公開設計契約與內部 AI 實現規範分離;
  • 公開視覺 Token、組件匯入、Skeleton/Skin 邊界、Button、Card 和無障礙要求;
  • 明確破壞性組件變更必須提供遷移說明;
  • 公開搜尋、Sitemap 與 LLM 輸出只包含可對外依賴的內容。

相容性說明

  • 新增可選屬性、可選 Skin 槽位和語義 Token 通常保持向後相容;

  • 刪除或重新命名屬性、改變預設 DOM/語義/鍵盤行為屬於破壞性變更;

  • 破壞性變更將在本頁說明影響範圍、替代 API 和遷移步驟。

  • 2026-09-06: 桌面導覽保留展開和圖示模式,並新增自動隱藏。 SidebarNavigation / WorkspaceNavigationMenu / Dialog

  • 2026-09-06: EditorViewControls 將編輯/專注與螢幕全螢幕分開控制。 EditorViewControls

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

  • 2026-09-06: 有側欄頁面移除重複的頁首選單按鈕,保留既有開關及導覽 API。 WorkspaceNavigation

  • 2026-09-06: 全域導覽使用選單圖示,編輯工具使用左右分欄圖示。 WorkspacePanelReveal / EditorViewControls

  • 2026-09-06: 顯示模式 · E / T / V / F · Segment.shortcut. EditorViewControls

  • 2026-09-06: PlatformHeader.workspaceNavigation 將全域導覽放在 Logo 前 PlatformHeader.workspaceNavigation

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-06 - EditorViewControls

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

2026-09 · 管理工作區

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

2026-09-08 · Task focus

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

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

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.

本頁目錄