Cập nhật Hợp đồng Thiết kế
Ghi lại các thay đổi đối với Token thiết kế, API thành phần và hợp đồng tích hợp công khai của Qokit.
Cập nhật Hợp đồng Thiết kế
2026-10-21 · Thao tác cố định trong menu cuộn
ActionItem.pinned nhận start hoặc end để giữ thao tác và ActionMenu.dropdownHeader ngoài danh sách cuộn. Điều hướng bàn phím và lựa chọn bao phủ mọi vùng. Ứng dụng chủ portal có thể giới hạn chiều cao bằng --qk-menu-available-height, đo ở phía mở đã chọn của nút kích hoạt. Không có pinned thì giữ nguyên cấu trúc menu hiện tại.
2026-10-17 · Điểm vào tùy chỉnh widget
Tùy chỉnh widget trang sử dụng điểm vào header dùng chung trên các Dự án, Nội dung và bảng điều khiển. CustomizableWidgetLayoutControls thêm các tùy chọn customizeButtonRef và disabledCustomize; các điều khiển thu gọn là tùy chọn. CustomizableWidgetLibrary chia sẻ hình học di động, tiêu điểm ban đầu, phím Escape và trả lại tiêu điểm giữa các máy chủ. Việc lưu trữ widget và các lệnh vẫn do máy chủ sở hữu. Xem tích hợp tùy chỉnh widget.
2026-10-17 · Điều khiển panel bàn làm việc được quản lý
WorkspaceHeaderPortal chấp nhận các tùy chọn startControl và endControl, với các đích máy chủ tùy chọn tương ứng. Các chế độ xem Quản lý Tệp sử dụng cùng các khe panel header và hình học khu vực làm việc như chỉnh sửa và xem trước tài sản đơn lẻ. Các máy chủ hiện tại có thể tiếp tục chỉ cung cấp tiêu đề, trạng thái và hành động. Xem tích hợp EditorHeader.
2026-10-17 · Mặc định trình soạn thảo đã đo lường
useWorkspaceResponsiveProfile thêm tùy chọn onWidthChange(width) cho các phép đo khu vực làm việc khả dụng. useEditorLayout bây giờ cũng áp dụng các giới hạn chiều rộng dùng chung đã cấu hình cho bộ nhớ máy chủ, và readEditorLayout chấp nhận các giới hạn tùy chọn là đối số thứ tư của nó. Các caller hiện tại giữ mặc định của chúng. Xem Tích hợp Thành phần.
2026-09-26 · Creator · Bộ phong cách
Khoảng cách chi tiết · 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.
Nút và liên kết: 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 → Tự động.
Màu nâng cao: mutedColor, borderColor, buttonTextColor, cardSurfaceColor 与对应 dark* 字段 (--qk-site-color-card-rgb).
2026-09-09 · Phím tắt điều hướng toàn cục
SidebarNavigation / WorkspaceNavigationMenu: Điều hướng toàn cục dùng Command+\ trên Mac hoặc Control+\ trên Windows/Linux, kể cả độc lập trong Creator. T và Shift+T vẫn điều khiển bố cục trình chỉnh sửa. Bỏ qua mục nhập có thể sửa, quá trình tổ hợp văn bản, sự kiện lặp và sự kiện đã xử lý.
2026-09-08 · EmptyState
Hướng dẫn tạo dự án và bài viết/sản phẩm CMS dùng chung EmptyState: căn giữa, nền trong suốt, phân cấp chữ gọn và thao tác tự xuống dòng. icon, layout, style và description là tùy chọn. Tiêu đề dùng h2; chuyển bộ chọn strong tùy chỉnh sang slot skin title. Nhiều thao tác dùng vùng chứa chung. Quyền và xử lý tạo vẫn thuộc ứng dụng chủ.
2026-09-08 · SidebarNavigation
SidebarNavigation tải trước các tuyến cùng nguồn khi chuột dừng 180 ms hoặc nhận tiêu điểm bàn phím. Điều hướng cố định và bật lên dùng chung giới hạn 8 đích mỗi 30 giây. Tạm dừng khi ngoại tuyến, tab bị ẩn, bật Save-Data hoặc dùng 2G; bỏ qua tải xuống, liên kết bị tắt, cửa sổ mới và neo cùng trang. Điều hướng và bảo vệ thay đổi chưa lưu được giữ nguyên.
2026-09-08 - Primary button foreground
Nút chính hình viên thuốc giữ màu xanh Logo #4695D8, dùng chữ, biểu tượng và chỉ báo tải màu trắng ở cả hai giao diện. Hiệu ứng rê chuột vẫn sáng nhẹ. Nút phụ và thao tác nguy hiểm giữ màu theo ý nghĩa riêng.
2026-09-07 - AccountDropdown / SidebarProfile
AccountDropdown hỗ trợ tùy chọn compact và preferences: chế độ gọn ẩn mã định danh và lịch sử sáng tạo; mặc định giữ nội dung cũ. Appearance và Language nhận triggerRole="menuitem" trong menu tài khoản. Điều hướng bàn phím khôi phục tiêu điểm, còn hộp thoại ngôn ngữ lồng nhau tự xử lý Escape. SidebarNavigation.searchEnabled mặc định là true; dùng false cho điều hướng ngắn, cố định. SidebarProfile có href và không có menu mở cùng đích trong chế độ mở rộng và biểu tượng.
2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace
Biểu mẫu dùng thang chữ chung và ngắt văn bản dài, giữ hình viên thuốc và màu thương hiệu. FormField đặt tên nhóm: controlId và id bên trong liên kết nhãn. SearchField trả tiêu điểm sau khi xóa. Segmented và ControlMenu hỗ trợ tùy chọn vô hiệu; mục ActionMenu vô hiệu không có liên kết. Nút đang xử lý giữ kích thước và chỉ báo. AdminEntityDialog kiểm tra trường bắt buộc, email và JSON, tập trung vào lỗi, chặn lưu lặp và giữ dữ liệu khi thất bại. EditorWorkspace cung cấp ref.focusControl(element) để hiện bảng ẩn trước khi tập trung. Giảm chuyển động tắt chuyển tiếp điều khiển. WorkspaceDialog cuộn nội dung dài nhưng giữ tiêu đề và thao tác hiển thị; hộp thoại ngắn trên di động vừa chiều cao nội dung.
2026-09-07 · WorkspaceLocationSync / ProjectSwitcher
Sau khi chuyển tuyến hoàn tất, WorkspaceLocationSync đóng bảng chọn không gian tạm thời để hiển thị ngay công cụ của trang đích. Tùy chọn tìm kiếm và nhóm vẫn được giữ. Tên phạm vi và ngữ cảnh nằm trên hai dòng; tên dài ở đầu trang được rút gọn trong nút.
2026-09-07 · Điều hướng thống nhất và bề mặt bo tròn Qokit
WorkspaceNavigationDock dùng lại điều hướng và quyền của ứng dụng chủ qua items, fallback, className, onClickCapture, không tải thêm phiên. Chia sẻ tùy chọn mở rộng, biểu tượng hoặc ẩn; từ 860px trở xuống dùng ngăn điều hướng. PlatformHeader.leadingContext cũng xuất hiện trong EditorHeader. Giữ nút dạng viên và bề mặt bo tròn, bỏ đường viền lặp.
Trên máy tính, nhấp vào menu để ẩn thanh bên hoặc khôi phục chế độ hiển thị gần nhất. Kéo menu hoặc mép thanh bên để chuyển giữa ẩn, chỉ biểu tượng và mở rộng. Các phím mũi tên trái/phải tuân theo hướng đọc. Hủy kéo không thay đổi tùy chọn đã lưu; trên điện thoại vẫn dùng ngăn điều hướng.
Gắn WorkspaceLocationSync một lần dưới Suspense trong layout Next. useWorkspaceQueryState(key, defaultValue, validate) trả về [value, setValue, ready]; useWorkspaceQueryRecord(key, defaults, validators) chỉ khôi phục bộ lọc phẳng đã khai báo. Không lưu thông tin xác thực hoặc bản nháp vào URL. WorkspacePage khôi phục vị trí cuộn phiên có giới hạn; vùng bên trong dùng data-workspace-scroll-region và WorkspaceScrollRestoration. Điều hướng lùi/tiến gốc có thể hủy dùng bảo vệ rời trang mà không thêm lịch sử. AdminEntityDialog giữ dữ liệu sau lỗi lưu và kết xuất lại; ứng dụng chủ quản lý phiên bản và kết quả lưu.
Chữ trong trang quản lý dùng các vai trò cố định: tiêu đề trang 20px/650, tiêu đề mục 16px/600, nội dung và điều hướng 14px, nhãn 13px, chú thích 12px. --qk-workspace-body-ink và --qk-workspace-active-ink lấy từ màu nền tảng hiện có.
Nút chính hình viên thuốc dùng trực tiếp màu xanh Logo #4695D8 qua --accent-action, bỏ chuyển sắc tối. Khi rê chuột, thêm 8% trắng; nhãn dùng màu mực thương hiệu pha 10% đen để dễ đọc. Điều hướng giữ cùng sắc xanh và chữ thích ứng với giao diện.
Menu thả xuống và bộ chuyển không gian dùng chung --menu-option-font-size (14px), --menu-option-font-weight (500) và chiều cao dòng 1.45; mục được chọn dùng độ đậm 600, thông tin phụ dùng 12px/400. WorkspaceNavigationDock tải trước đích cùng nguồn khi rê chuột hoặc lấy tiêu điểm bàn phím, với bản ghi khử trùng lặp có giới hạn. Cơ chế bảo vệ khi rời trang và tuyến của ứng dụng chủ vẫn được giữ nguyên.
2026-09-07 - ColumnLayout
ColumnLayout lấp đầy cửa sổ quản lý với điều hướng cố định, vùng cuộn riêng và thanh công cụ trang bám trên cùng. WorkspacePage dùng các phần phẳng và Token bo góc chung. Ở 860px trở xuống, điều hướng là ngăn kéo, không thể tương tác khi đóng. Thuộc tính và hành vi nghiệp vụ không đổi. Bỏ lề ngoài trùng lặp và giới hạn chiều rộng đọc trong biểu mẫu.
2026-09-05 · WorkspaceNavigationMenu / WorkspacePageHeader
Không gian làm việc đã đăng nhập dùng PlatformHeader.workspaceActions để chia sẻ vùng tài khoản và điều hướng ở mọi chiều rộng. WorkspacePageHeader thống nhất tiêu đề và thao tác. WorkspaceNavigationMenu hiển thị thanh bên hiện tại với quyền và ngữ cảnh; EditorNavigationMenu vẫn là bí danh tương thích. Studio giữ thanh công cụ riêng. Đầu trang công khai giữ cách trình bày hiện có.
WorkspaceNavigationGuard bảo vệ điều hướng chung bằng dirty, busy, error và onSave tùy chọn. Chỉ rời đi khi lưu thành công được xác nhận và trả về true; lỗi giữ lại bản nháp. Language.onBeforeChange(apply) cho phép bảo vệ tương tự trước khi đổi ngôn ngữ. Vô hiệu hóa trường biểu mẫu trong lúc lưu.
2026-09-05 · EditorNavigationMenu
EditorNavigationMenu dùng toàn bộ SidebarNavigation của ứng dụng trong ngăn phủ, giữ quyền và ngữ cảnh dự án mà không dịch chuyển vùng soạn thảo. Ngôn ngữ và giao diện nằm ở dưới; menu con xử lý Escape trước. Ở chiều rộng tối đa 1120px, đầu trang có hai hàng và menu hiển thị tên chế độ hiện tại. Tập trung và toàn màn hình trình duyệt độc lập. Điều hướng chờ lưu hoàn tất và bảo vệ bản nháp.
2026-09-05 · EditorHeader
EditorHeader giữ logo, tài khoản và menu chung của ứng dụng trong trình chỉnh sửa đang hoạt động. startControl và endControl điều khiển các bảng bên, center chứa lệnh đổi chế độ xem và actions chứa thao tác lưu. PlatformHeader.editorActions tái sử dụng điều hướng thích ứng, ngôn ngữ và giao diện. onNavigate phải xử lý thay đổi chưa lưu trước khi gọi callback. Trên màn hình hẹp, phần đầu dùng hai hàng; menu con xử lý Escape trước.
2026-09-05 · SidebarToggleSlot
SidebarToggleSlot đặt nút thanh bên vào phần đầu không gian làm việc. Dùng một vị trí với một thanh bên trái. SidebarNavigation vẫn quản lý trạng thái, phím tắt và ngăn trên điện thoại; nếu không có vị trí này, các nút giữ nguyên chỗ cũ. Nút ở phần đầu cũng đóng ngăn trên điện thoại; khi đóng, tiêu điểm trở về chính nút đó.
2026-09-05 · EditorWorkspace / Dialog / Segmented
view / onViewChange chuyển giữa edit, focus và preview mà không thay thế trình soạn thảo. preview cung cấp bản xem trước; previewPanel dùng lại bảng hiện có. layout hỗ trợ writing, structure và canvas. storageKey chỉ ghi nhớ chiều rộng và trạng thái thu gọn bảng, không lưu tài liệu.
onSaveAndClose trả về true sau khi xác nhận lưu, false khi thất bại, handled nếu ứng dụng đã chuyển trang hoặc pending nếu việc xác thực cần quyết định. Khi lưu thất bại, trình soạn thảo vẫn mở. Chỉ dùng closeBehavior="collapse" khi ứng dụng giữ lại bản nháp. EditorSaveStatus hiển thị trạng thái đã xác nhận. Có thể kết hợp riêng EditorViewControls, EditorLeaveDialog và useEditorLayout.
Thay đổi bàn phím: Segmented có một điểm dừng Tab, dùng phím mũi tên / Home / End. Dialog tôn trọng Escape do lớp con xử lý; sau đó trình soạn thảo thoát chế độ tập trung hoặc xem trước rồi mới đóng. LivePreviewToolbar.exitControl nhận bộ điều khiển chế độ dùng chung. Lưu, xuất bản và quyền truy cập vẫn do ứng dụng quản lý.
2026-09 · EditorWorkspace
EditorWorkspace kết hợp hộp thoại toàn màn hình, quản lý tiêu điểm và các bảng thích ứng. dirty yêu cầu xác nhận bỏ thay đổi, busy ngăn đóng khi đang lưu và onSave xử lý Ctrl/Cmd+S. Ứng dụng chủ chịu trách nhiệm về quyền, dữ liệu, lưu và xuất bản.
2026-08 · Mật độ chỉ số tinh gọn
- Thêm API
density="compact"tùy chọn choMetricCard, dùng cho không gian làm việc vận hành mật độ cao; - Giữ nguyên mật độ mặc định hiện tại và ngữ nghĩa DOM;
- Đưa padding tinh gọn, thang đo giá trị và chiều cao tối thiểu vào kiểu thành phần chia sẻ, giúp route không cần ghi đè trực quan nữa.
2026-07 · Thống nhất điều khiển biểu mẫu
- Thêm
FormField,Input,Textarea,Checkbox,RadioGroupvàSwitchvào@qokit/components/ui; - Liên kết nhãn, mô tả, lỗi, trạng thái bắt buộc và tham chiếu ARIA thông qua khung xương
FormFieldchia sẻ; - Thống nhất kích thước 40px, 44px, 48px và Token tương tác chia sẻ cho
Input,Textarea,SelectvàSearchField; - Thêm công thức Skin nền tảng, Admin và trang được tạo mới cho các thành phần cơ bản của biểu mẫu;
- Giữ lại kiểu
.qk-fieldhiện có làm đường dẫn di chuyển tương thích ngược.
2026-07 · Bố cục kích thước nút
- Thêm ba Token ngữ nghĩa
--button-font-size-sm,--button-font-size-md,--button-font-size-lg; Buttonhiện cố định sử dụng kích thước chữ 14px, 15px, 16px chosm,md,lgtương ứng, không còn thừa hưởng kích thước chữ từ Header, Dialog hoặc vùng chứa trang;- Nếu Skin trang web cần điều chỉnh bố cục nút, nên ghi đè Token ngữ nghĩa tương ứng, không nên ghi đè
font-sizethông qua class định tuyến.
2026-07 · Khung điều hướng chung nền tảng
- Thêm
PlatformHeaderkhông phụ thuộc đăng nhập, nền tảng và trang tài liệu sử dụng cùng khung ngữ nghĩa; - Thêm
PublicPlatformHeadervàbuildPublicHeaderNavItems, trạng thái ẩn danh của nền tảng và trang tài liệu tái sử dụng cùng tổ hợp Header chung và cấu hình điều hướng; HeaderNavItemthêm loạimenu, Header trên máy tính để bàn sử dụng menu thả xuống có thể đóng, Header di động tự động mở rộng thành nhóm liên kết;SiteFooterthêmbrandHrefvàcontrolstùy chọn, hỗ trợ các kịch bản tích hợp khác nhau như tài liệu công khai;- Thêm
PublicPlatformFooter, nền tảng và trang tài liệu tái sử dụng cùng Footer Shell, cho phép phân giải liên kết nền tảng xuyên miền; - Tất cả đều là API tùy chọn tương thích ngược, logic trạng thái Header nền tảng ban đầu và điều khiển mặc định Footer vẫn được giữ nguyên.
2026-07 · Hướng dẫn thiết kế công khai
- Tách biệt hợp đồng thiết kế công khai khỏi quy phạm triển khai AI nội bộ;
- Công khai Token trực quan, nhập thành phần, ranh giới Skeleton/Skin, Button, Card và yêu cầu khả năng tiếp cận;
- Rõ ràng rằng các thay đổi phá vỡ thành phần phải cung cấp hướng dẫn di chuyển;
- Công khai tìm kiếm, Sitemap và đầu ra LLM chỉ bao gồm nội dung có thể phụ thuộc bên ngoài.
Giải thích tương thích
-
Các thuộc tính tùy chọn, vị trí trống Skin tùy chọn và Token ngữ nghĩa mới thường duy trì tương thích ngược;
-
Xóa hoặc đổi tên thuộc tính, thay đổi hành vi DOM/ngữ nghĩa/bàn phím mặc định thuộc về thay đổi phá vỡ;
-
Thay đổi phá vỡ sẽ mô tả phạm vi ảnh hưởng, API thay thế và các bước di chuyển trên trang này.
-
2026-09-06: Điều hướng máy tính giữ chế độ mở rộng và biểu tượng, đồng thời thêm tự động ẩn. SidebarNavigation / WorkspaceNavigationMenu / Dialog
-
2026-09-06: EditorViewControls tách Chỉnh sửa/Tập trung khỏi chế độ toàn màn hình gốc. EditorViewControls
-
2026-09-06:
LanguagevàAppearance variant="menu"hỗ trợlayout="row"để hiển thị nhãn, giá trị hiện tại và mũi tên. Bố cục gọn mặc định và cơ chế bảo vệ khi đổi ngôn ngữ được giữ nguyên.SiteHeaderCopy.helpResourcesvàcontactSupportcho phép đặt tên liên kết trợ giúp của không gian làm việc. Language / Appearance -
2026-09-06: Trang có thanh bên bỏ nút trình đơn trùng lặp; nút hiện có và API điều hướng vẫn khả dụng. WorkspaceNavigation
-
2026-09-06: Điều hướng chung dùng biểu tượng trình đơn, công cụ dùng biểu tượng bảng trái/phải. WorkspacePanelReveal / EditorViewControls
-
2026-09-06: Chế độ hiển thị ·
E/T/V/F·Segment.shortcut. EditorViewControls -
2026-09-06:
PlatformHeader.workspaceNavigationđặt điều hướng chung trước logo PlatformHeader.workspaceNavigation
2026-09-06 - EditorHeader.preview / EditorViewControls.returnView
EditorHeader.preview chỉ hiển thị center thành thanh xem trước gọn, không viền; logo, tài khoản, lưu và bảng vẫn được gắn nhưng bị ẩn. Khi dùng LivePreviewToolbar riêng, có thể ẩn đầu trình chỉnh sửa và dùng EditorViewControls.returnView (edit hoặc focus) để khôi phục chế độ trước. Giữ thao tác quay lại dễ tiếp cận và toàn màn hình độc lập; đầu trang của website vẫn hiển thị.
2026-09-06 · Builder / CMS
Builder và CMS dùng chung BuilderWorkspace, EditorCatalog và EditorComponentSettings cho bảng điều khiển, hình minh họa chèn và thiết lập hiển thị. Các mẫu thiết lập áp dụng đồng thời những tùy chọn liên quan và giữ nguyên nội dung; mỗi ứng dụng quản lý lưu và hoàn tác. Điều khiển theo giao diện nền tảng, còn nội dung theo giao diện trang web.
2026-09-06 - EditorViewControls
Một nút chuyển theo cả hai chiều: khi chỉnh sửa hiển thị Tập trung, khi tập trung hiển thị Chỉnh sửa. Nhấp hoặc nhấn T; E trở về chỉnh sửa trực tiếp. Trên đầu trang hẹp, nút vẫn hiển thị; xem trước, toàn màn hình và thao tác bổ sung nằm trong Thêm. EditorViewControls
2026-09 · Không gian quản trị
Bảng hẹp (WorkspaceDataTable, AdminDataTable) hiển thị bản ghi có nhãn, giữ lựa chọn, tiêu đề tùy chỉnh và thao tác. Dùng mobileLayout="scroll" cho ma trận so sánh. WorkspaceFilterToolbar đặt tìm kiếm và bộ lọc trước sắp xếp và chế độ xem. Thanh bên dùng h2; trang dùng h1.
2026-09-08 · Task focus
useSidebarTaskFocus(active) tạm ẩn điều hướng trong tác vụ cần tập trung. Khi thoát, chế độ hiển thị trước đó được khôi phục trừ khi người dùng chủ động đổi chế độ. Tự động ẩn không ghi đè tùy chọn đã lưu.
Tài liệu API bổ sung (tiếng Anh, chờ dịch)
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.
Tài liệu API bổ sung (tiếng Anh, chờ dịch) · 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.