Tích hợp thành phần
Hợp đồng tích hợp công khai cho thành phần chia sẻ, Pattern, Skin và Token kiểu dáng của Qokit.
Tích hợp thành phần
Qokit sử dụng mô hình "khung chia sẻ + công thức Skin". Nhà tích hợp bên ngoài dựa vào hợp đồng ngữ nghĩa và tương tác của thành phần, hoàn tất thích ứng trực quan thông qua Skin và Token.
2026-10-20 · Thao tác độc lập trên thẻ lựa chọn trực quan
Các tùy chọn của EditorVisualChoiceGroup nhận accessory không bắt buộc cho menu thẻ hoặc trình sửa tên độc lập. RadioGroup dùng chung đặt nội dung này cạnh nhãn gốc, nên quản lý thẻ không kích hoạt lựa chọn radio. afterOptions đặt thao tác danh mục riêng, như tạo thẻ, sau các lựa chọn. Ứng dụng chủ quản lý lưu trữ, quyền, xác thực và tiêu điểm sau khi thay hoặc xóa thẻ. Lựa chọn không có phần bổ sung giữ nguyên cấu trúc và hành vi.
2026-10-17 · Chuyển động panel bàn làm việc dùng chung
EditorWorkbenchChrome hiển thị các làn đầu/cuối được tiêm qua BuilderWorkbenchFrame, cùng khung panel skeleton được sử dụng bởi Creator và chỉnh sửa nội dung. Các máy chủ cung cấp nội dung, khả năng hiển thị và sở thích chiều rộng. Máy tính để bàn theo dõi và độ mờ/chuyển vị panel chia sẻ --qk-sidebar-motion-duration và --qk-sidebar-motion-easing; kéo thả vô hiệu hóa các chuyển tiếp và chế độ giảm chuyển động kích hoạt ngay lập tức.
Các panel thu gọn vẫn được gắn kết để duy trì bản nháp. Khung dùng chung ngay lập tức áp dụng inert và aria-hidden, trong khi lớp da nền tảng hoàn tất việc thoát trước khi ẩn khả năng hiển thị. Panel nhỏ gọn duy trì hình thức overlay của chúng xuyên suốt quá trình thoát; máy chủ không được thêm hidden hoặc display: none vào vỏ panel. Panel peek rõ ràng duy trì hành vi tiết lộ tương tác hiện có của chúng. Các lựa chọn header vẫn khả dụng ở cả trạng thái mở/đóng; hãy sử dụng EditorPanelChoiceShortcuts.mobileMenu khi các đích điện thoại nên chia sẻ một menu.
2026-10-17 · Mặc định trình soạn thảo đã đo lường
useWorkspaceResponsiveProfile chấp nhận tùy chọn onWidthChange(width), báo cáo cùng chiều rộng khu vực làm việc khả dụng được sử dụng cho hồ sơ đáp ứng sau khi trừ đệm nội tuyến. Sử dụng callback ổn định để suy ra các mặc định tỷ lệ mà không cần thêm bộ quan sát khác. useEditorLayout áp dụng sharedWidths.limits cho cả sở thích máy chủ cũng như bộ lưu trữ chiều rộng dùng chung; readEditorLayout chấp nhận các giới hạn tương tự là đối số thứ tư tùy chọn của nó. Các caller hiện tại giữ các biên và hành vi mặc định của chúng.
2026-09-30 · Khả năng truy cập của SelectionToolbar
SelectionToolbar.ariaLabel có thể đặt tên cho thanh công cụ dưới dạng một vùng. Số lượng vẫn là thông báo trạng thái trực tiếp. Ứng dụng chủ cung cấp nhãn bản địa hóa và có thể dùng actionContent để kết hợp EditorToolGroup và ActionMenu dùng chung; việc kiểm tra quyền và xử lý thao tác vẫn thuộc ứng dụng chủ.
2026-09-10 · Huy hiệu nhận diện không gian làm việc
ProjectSwitcherProject.badge nhận nội dung React tùy chọn và không tương tác. Huy hiệu xuất hiện bên cạnh tên từng mục, trong hàng ngữ cảnh hiện tại không có trong danh sách và cạnh tên hiện tại của trình kích hoạt dạng chữ. Trình kích hoạt chỉ có biểu tượng vẫn gọn; trình kích hoạt dạng chữ của nền tảng ẩn huy hiệu ở chiều rộng điện thoại để giữ chỗ cho tên không gian làm việc. Menu đã mở vẫn hiển thị huy hiệu. Ứng dụng chủ cung cấp dữ liệu đúng phạm vi, nhãn đã bản địa hóa và kiểu trình bày; bỏ qua trường này sẽ giữ nguyên giao diện hiện có.
2026-09-08 · EmptyState
EmptyState căn giữa icon trang trí tùy chọn, title, description tùy chọn và action trên nền trong suốt. layout="section" mặc định gọn; layout="workspace" dành thêm không gian. Đặt thao tác trực tiếp trong action, dùng fragment cho nhiều nút; vùng chứa xử lý khoảng cách và nhãn dài. Tiêu đề là h2: dùng slot title thay cho strong. Giữ các lớp gốc hiện có; hỗ trợ skin.vars và style. Ứng dụng chủ quản lý bản dịch, quyền, điều hướng và tạo; kết quả tìm kiếm và lỗi giữ thông báo và thao tác riêng.
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-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 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.
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.
Điểm nhập
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';| Điểm nhập | Mục đích |
|---|---|
@qokit/components/ui | Các thành phần cơ bản như Button, Card, Dialog, Menu, Pill |
@qokit/components/patterns | Tổ hợp Header, Footer, vùng làm việc, bảng, tài nguyên và trợ lý AI |
@qokit/components/skins/platform | Công thức trực quan nền tảng và vùng làm việc |
@qokit/components/skins/admin | Công thức trực quan Admin |
@qokit/components/skins/site | Công thức trực quan tạo trang web |
Ranh giới trách nhiệm chung
PromptPanel chấp nhận các thuộc tính tùy chọn referenceReader và referenceCopy được bản địa hóa. Trình đọc trả về các thẻ contentExcerpt và truncated đã trích xuất thông qua file(File, AbortSignal) và website(url, AbortSignal) bất đồng bộ; xác thực và truy cập API do máy chủ chịu trách nhiệm. Thành phần quản lý quá trình đọc, xem trước, thử lại và xóa; khi URL hợp lệ nhưng thiếu văn bản gợi ý, referenceCopy.websitePrompt sẽ bổ sung yêu cầu; lỗi định dạng sử dụng referenceCopy.errors.url và chặn quá trình đọc. Việc gửi khi URL chưa được đọc hoặc đang đọc sẽ chờ nội dung mới nhất và chỉ gửi một lần; thay đổi đầu vào hoặc lỗi đọc sẽ hủy thao tác chờ gửi, việc thử lại không khôi phục yêu cầu cũ. Tệp phải sẵn sàng trước khi gửi. URL đầy đủ sẽ tự động đọc khi dán, mất tiêu điểm hoặc nhấn Enter; URL ban đầu cũng sẽ được đọc và tái sử dụng kết quả đang thực hiện hoặc đã hoàn thành; nếu thất bại sẽ cung cấp hướng dẫn thử lại rõ ràng. Chỉnh sửa hoặc xóa URL sẽ hủy quá trình đọc cũ và xóa kết quả. Khi không cung cấp trình đọc, hệ thống tiếp tục gửi gốc mà không xử lý tham chiếu bất đồng bộ.
Tính năng thu thập tham chiếu được thêm vào tháng 9 năm 2026 dưới dạng khả năng thành phần tùy chọn và tương thích ngược.
Khung thành phần đảm bảo:
- DOM và thẻ ngữ nghĩa;
- Hành vi ARIA, bàn phím, tiêu điểm và disabled;
- Trạng thái và tương tác cơ bản;
- Class mặc định ổn định;
- Vị trí trống Skin có tên.
Skin có thể:
- Thêm class cho các vị trí trống như
root,header,body,item,action; - Truyền biến CSS thông qua
vars; - Sử dụng tone, layer hoặc công tắc thích ứng trực quan đã công khai của thành phần.
Skin không được yêu cầu dữ liệu, thay đổi DOM, nắm giữ quy tắc nghiệp vụ hoặc bỏ qua hành vi khả năng tiếp cận.
Nội dung phần tử được tạo
Các khối tùy chỉnh được tạo tiếp tục sử dụng các phần tử html-* đã đăng ký trong Schema v2, không sử dụng HTML có thể thực thi hoặc loại khối mới. Kể từ tháng 9 năm 2026, @qokit/site-schema cung cấp bindSiteModuleContent, updateSiteModuleBoundContent và forkSiteModuleContentBindings để liên kết nội dung ngôn ngữ. Đường dẫn nội dung được lưu trong module, văn bản dành cho khách được lưu trong ánh xạ nội dung ngôn ngữ; việc cập nhật tuân theo giao dịch hoàn tác và lưu; khi sao chép hoặc di chuyển phần tử giữa các khối, bắt buộc phải phân tách liên kết để tránh làm thay đổi nguồn.
extensionRequirements tùy chọn ghi lại các yêu cầu thời gian chạy chưa được giải quyết, không phải danh sách cài đặt hoặc cấp quyền. createSiteExtensionHandoff xuất các yêu cầu phát triển v1 không thể thực thi; trước khi phát hành trang web có thể chạy, bắt buộc phải giải quyết các yêu cầu này hoặc bị loại trừ rõ ràng sau khi kiểm duyệt.
Điều khiển biểu mẫu
Biểu mẫu chia sẻ sử dụng FormField để liên kết nhãn, mô tả, siêu dữ liệu bắt buộc, lỗi và ID điều khiển. Điều khiển văn bản sử dụng Input, nội dung nhiều dòng sử dụng Textarea, điều khiển lựa chọn sử dụng Checkbox, RadioGroup và Switch; cả Select và SearchField đều sử dụng cùng hợp đồng kích thước và trạng thái.
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 liên kết nhãn, mô tả và lỗi với điều khiển con duy nhất thông qua id, aria-describedby, aria-invalid và required. Không nên bao bọc các điều khiển chia sẻ bằng thêm <label> nữa.
Input, Textarea, Select và SearchField hỗ trợ ba kích thước sm, md và lg, tương ứng là 40px, 44px và 48px. Điều khiển một dòng mặc định sử dụng hình dạng pill; Textarea luôn sử dụng góc bo nhiều dòng chia sẻ. Các trạng thái tương tác và lỗi đều đến từ Token chia sẻ.
Trong giai đoạn chuyển đổi, vẫn có thể sử dụng hợp đồng .qk-field cũ; các tích hợp mới nên sử dụng thành phần chia sẻ và khe Skin có tên.
Lựa chọn danh sách
Kể từ tháng 9 năm 2026, danh sách có thể kết hợp sử dụng useWorkspaceSelectionMode({ enabled, resetKey, onClear }) và WorkspaceFilterToolbar.selection. Hook này ban đầu không được kích hoạt, sẽ được đặt lại khi phạm vi hoặc quyền thay đổi, và phân biệt giữa việc xóa sạch ID đã chọn và thoát chế độ hàng loạt; khóa phạm vi phải bao gồm bộ sưu tập, ngôn ngữ, phân trang và bộ lọc.
Chỉ truyền WorkspaceDataTable.selection khi chế độ hàng loạt được kích hoạt, điều khiển checkbox trên lưới và thiết bị di động sử dụng cùng chế độ. Thanh công cụ chịu trách nhiệm cho các thao tác chọn phổ biến, người dùng cung cấp văn bản bản địa hóa, ID tùy chọn và các thao tác miền đã kiểm tra quyền. actionContent tùy chọn có thể chứa ngữ nghĩa ARIA bổ sung, nhưng không thay thế điều khiển phổ biến hoặc bước xác nhận. Danh sách chỉ đọc không hiển thị chế độ hàng loạt, bộ chọn tệp và phê duyệt đề xuất giữ nguyên ngữ nghĩa riêng.
Các khả năng bổ sung này là tùy chọn và tương thích ngược; việc chọn trên bảng vẫn do người dùng kiểm soát rõ ràng.
Thẻ chỉ số
Tài liệu API bổ sung (tiếng Anh, chờ dịch) · 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" />;Header và Footer nền tảng
Logo mặc định hiển thị ảnh tĩnh. motion="breathe" giữ kích thước khi ẩn rồi hiện một lần bằng chuyển động nhịp thở 4,8 giây khi trang tải xong và ít nhất một nửa logo xuất hiện. Đầu và chân trang không chờ thêm. motionVisibilityDelayMs có thể thêm thời gian hiển thị liên tục, mặc định bằng không. motionOnceKey chia sẻ lịch sử phát khi gắn lại trong cùng tài liệu; đầu và chân trang dùng khóa riêng. Điều hướng, đổi giao diện và cuộn trở lại không phát lại; tải lại toàn trang sẽ đặt lại. Chế độ giảm chuyển động, JavaScript bị tắt hoặc không hỗ trợ quan sát hiển thị sẽ dùng logo tĩnh. motion="reveal" vẫn là bí danh.
PlatformHeader.autoHideOnScroll mặc định là false; PublicPlatformHeader bật tính năng này. Đầu trang ẩn khi cuộn xuống và trở lại khi cuộn lên hoặc gần đỉnh trang. Menu đầu trang đang mở và tiêu điểm bên trong giữ đầu trang hiển thị. Đầu trang của không gian làm việc và trình chỉnh sửa giữ nguyên vị trí.
PlatformHeader là khung Header không có trạng thái nghiệp vụ. PublicPlatformHeader kết hợp điểm vào thương hiệu, điều hướng chung, ngôn ngữ, chủ đề, đăng nhập, "Trải nghiệm ngay" và menu di động trên nó; trạng thái ẩn danh của nền tảng và trang tài liệu trực tiếp tái sử dụng tổ hợp này.
Điều hướng chung được tạo thống nhất thông qua buildPublicHeaderNavItems(copy, links) "Tài nguyên / Giá / Tin tức". Nhà tích hợp chỉ cần phân giải URL nội bộ, trang tài liệu và nền tảng của ứng dụng hiện tại, không nên định nghĩa lại thứ tự menu hoặc văn bản. Header nền tảng sau khi đăng nhập cũng sử dụng hàm tạo cùng.
<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'
}}
/>Lớp dưới navItems vẫn hỗ trợ link, scroll và menu. menu trên máy tính để bàn hỗ trợ nhấp, bàn phím, Escape và nhấp bên ngoài để đóng, trên di động được MobileHeaderMenu mở rộng thành nhóm liên kết.
SiteFooter là khung Footer; nền tảng và trang tài liệu sử dụng PublicPlatformFooter để kết hợp thống nhất Shell bên ngoài, điểm vào thương hiệu, liên kết, công cụ chủ đề và ngôn ngữ. Tích hợp xuyên miền chuyển đổi liên kết tương đối sang địa chỉ tuyệt đối thông qua resolveCompanyHref.
<PublicPlatformFooter
brandHref="https://qokit.com"
copy={footerCopy}
resolveCompanyHref={(href) => `https://qokit.com${href}`}
/>Ứng dụng nghiệp vụ không được sao chép DOM Header, Footer hoặc mảng điều hướng chung; cần biểu hiện trực quan khác nhau thì sử dụng PlatformHeaderSkin, SiteFooterSkin hoặc Skin nền tảng tương ứng.
Chiến lược tương thích
- Thêm thuộc tính tùy chọn và vị trí trống Skin thuộc về thay đổi tương thích ngược;
- Xóa thuộc tính, sửa đổi ngữ nghĩa mặc định hoặc thay đổi hành vi DOM/bàn phím thuộc về thay đổi phá vỡ;
- Thay đổi phá vỡ phải đưa vào Changelog và cung cấp ví dụ di chuyển;
- Không dựa vào class nội bộ, thư mục hoặc cấu trúc định tuyến chưa công khai;
- Khi hai điểm tích hợp trở lên cần ghi đè giống nhau, nên nâng cấp thành Skin hoặc Token công khai.
Chỉnh sửa toàn màn hình
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.
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ý.
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 đặ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 đó.
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.
WorkspaceHeaderPortal.startControl và endControl đặt các công tắc panel trang được quản lý trong các khe tương ứng của máy chủ. Các máy chủ expose các tùy chọn startTarget và endTarget bên cạnh tiêu đề, trạng thái và hành động. Thư viện Tệp và không gian làm việc tài sản đơn lẻ sử dụng workAreaControls; xem trước tài sản giữ nguyên header đầy đủ để danh tính, hành động quay lại và các đích panel của nó vẫn khả dụng. ProjectWorkspace sở hữu các lựa chọn điều hướng/trò chuyện trái dùng chung cho Nội dung và Tệp. Tệp đăng ký các kích thước panel tài sản đã ghi nhớ của nó thông qua useProjectResourcePanel, điều hướng cổng thông qua ProjectContentTools, và chỉ cung cấp điều khiển inspector phải của nó thông qua ProjectToolbar.endControl. Trò chuyện sử dụng cùng làn trái và trình soạn thảo nhúng xuyên suốt các khu vực dự án; các nhiệm vụ tài sản nhỏ gọn, trò chuyện và inspector là loại trừ lẫn nhau.
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. 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.
WorkspaceNavigationMenu / WorkspacePageHeader
Đ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ý. Gợi ý trên nút và aria-keyshortcuts hiển thị tổ hợp; điều hướng toàn cục không còn chiếm phím T riêng lẻ.
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.
Đ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. Thanh bên và ngăn kéo dùng chung tìm kiếm và trạng thái nhóm. Con trỏ chính xác ở mép 300ms sẽ mở bản xem tạm, đóng sau khi rời 320ms; nhấp sẽ giữ mở. Điều khiển cảm ứng và bàn phím vẫn có nút rõ ràng. Dialog mặc định dùng modal={true} và autoFocus={true}; bản xem tạm đặt cả hai thành false để giữ tiêu điểm nhập và cuộn.
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 tách Chỉnh sửa/Tập trung khỏi chế độ toàn màn hình gốc. Xem trước là nút chuyển riêng và quay lại chế độ trước; useEditorWorkMode giữ chế độ đó cho thao tác thoát tùy chỉnh. Các giá trị edit/focus/preview vẫn được hỗ trợ. Xem trước dùng button với aria-pressed thay cho radio trong nhóm chế độ. Toàn màn hình cần một lần nhấp, bao gồm điều hướng và hộp thoại trong phần tử gốc của ứng dụng; ẩn nếu không được hỗ trợ.
Language / Appearance
Language và 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.helpResources và contactSupport cho phép đặt tên liên kết trợ giúp của không gian làm việc.
requestWorkspaceNavigation
Trang có nút bật tắt thanh bên sẽ ẩn nút trình đơn bổ sung ở đầu trang, kể cả khi thu gọn và trên thiết bị di động. Trình chỉnh sửa và trang không có thanh bên vẫn giữ nút này. Nhập requestWorkspaceNavigation(returnFocusTarget?) và useWorkspaceNavigationState() từ @qokit/components/patterns/WorkspaceNavigation: yêu cầu bật tắt ngăn đã đăng ký và trả về false khi không có ngăn khả dụng. Phần tử tùy chọn nhận lại tiêu điểm khi đóng. Kiểm tra .available trước khi hiển thị lối vào khác. Dùng nút hiện có hoặc API này thay vì vị trí DOM của nút đã xóa.
WorkspacePanelReveal
Đ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. useWorkspacePanelReveal({ temporary: true }) mở công cụ tạm thời bằng chuột hoặc bàn phím trong Tập trung. toggle(trigger?) và close(true) giữ bố cục và chế độ, đồng thời trả tiêu điểm khi đóng. Mép màn hình mở điều hướng chung; công cụ phản hồi gần nút riêng. Xem trước ẩn nút bảng chỉnh sửa và cung cấp thao tác rõ ràng để trở về chế độ chỉnh sửa trước đó.
EditorViewControls / Chế độ hiển thị
EDITOR_VIEW_SHORTCUTS → Tooltip + aria-keyshortcuts
EditorHeader cũng quản lý EDITOR_TOOLBAR_SHORTCUTS: Command/Control+S gọi EditorSaveButton đang hiển thị, Shift+P mở EditorStatusAction shortcut="publish", Shift+M mở trình đơn công cụ. Các lệnh dùng cùng điều khiển đang bật như thao tác nhấp; xuất bản vẫn cần thao tác rõ ràng trong bảng. Chỉ tiêu đề đang hoạt động và hiển thị mới phản hồi. Trình đơn con, hộp thoại, soạn thảo IME và sự kiện lặp chặn phím tắt; trong ô nhập chỉ cho phép lưu. Gợi ý và aria-keyshortcuts dùng chung định nghĩa. toolsControl tùy chỉnh đặt aria-keyshortcuts={EDITOR_TOOLBAR_SHORTCUTS.tools.aria} trên nút kích hoạt. ActionMenu.triggerKeyShortcuts thêm thuộc tính và gợi ý, không đăng ký lệnh toàn cục.
Các bảng dùng Shift+A (thêm), Shift+L (trang/lớp), Shift+K (hội thoại), Shift+C (nội dung), Shift+D (thiết kế), Shift+G (phong cách chung). CMS thêm Shift+S (cài đặt), Shift+E (SEO), Shift+H (lịch sử) khi có. Siêu dữ liệu shortcut trên EditorChoiceControl, EditorViewTabs, ActionMenu dùng chung gợi ý. EditorPanelChoiceShortcuts và EditorViewControls.compactActions giữ thao tác khi thu vào trình đơn, kể cả trên điện thoại. EditorPanelShortcuts.commands đăng ký thao tác sẵn có mà không nhân đôi điều khiển. Các giới hạn ẩn, inert, vô hiệu, xem trước và lớp phủ vẫn áp dụng. Thanh bên điện thoại không dạng modal trong cùng không gian cho phép đổi bảng; trình đơn và hộp thoại modal chặn phím tắt. Phím không có bổ trợ giữ hành vi cũ.
| Chế độ hiển thị | |
|---|---|
E | Chỉnh sửa |
T | Chỉnh sửa ↔ Tập trung |
V | Xem trước / Trở lại chỉnh sửa |
F | Mở toàn màn hình / Thoát toàn màn hình |
Chỉ trình chỉnh sửa đang hoạt động phản hồi. Việc nhập văn bản, soạn thảo IME, giữ phím và mở hộp thoại hoặc menu con không chuyển chế độ.
PlatformHeader.workspaceNavigation
PlatformHeader.workspaceNavigation đặt điều hướng chung trước logo; workspaceActions và editorActions giữ các thao tác tài khoản. Không gian làm việc dùng lại nút thanh bên hiện có, còn trình chỉnh sửa đặt nút bảng bên phải trước ảnh đại diện. Trên màn hình hẹp, điều hướng, thương hiệu, tiêu đề và ảnh đại diện nằm trên các công cụ chỉnh sửa và Lưu. Thứ tự DOM theo bố cục; hiệu ứng kính mờ không viền được giữ nguyên.
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.
Chân trang được kết xuất trên máy chủ · 2026-09-07
SiteFooterLayout nhận locale rõ ràng và copy bằng một ngôn ngữ. Thành phần máy chủ kết xuất cấu trúc chân trang dùng chung; các điều khiển giao diện, ngôn ngữ và hộp thoại QR vẫn là thành phần phía máy khách. Các giao diện SiteFooter và PublicPlatformFooter hiện có vẫn được hỗ trợ.
import { SiteFooterLayout } from '@qokit/components/patterns/SiteFooter';
<div className="qk-platform-footer-shell">
<SiteFooterLayout locale={locale} copy={footerCopy} />
</div>Xử lý liên kết giữa các miền trong copy.companyLinks trên máy chủ. Dùng controls để tùy chỉnh vùng điều khiển tương tác.
EditorHeader.titleControl / FloatingAssistant.presentation
EditorHeader.titleControl và EditorWorkspace.titleControl có thể thay tiêu đề bằng menu dự án dùng chung. Giữ title có ý nghĩa và cơ chế bảo vệ thay đổi chưa lưu khi điều hướng. FloatingAssistant.presentation="embedded" hiển thị vùng có tên trong bảng chủ, không có nút nổi hay lớp phủ nền; mặc định vẫn là floating. Thành phần chủ quản lý vị trí và hiển thị; trợ lý giữ trạng thái hội thoại và quyền truy cập.
2026-09-07 · WorkspaceAssembly
WorkspaceAssembly đánh dấu thẻ rời đi và vùng đi vào mà không thêm hộp bố cục. Khi cần phần tử con trực tiếp, đặt workspaceAssemblyAttributes(part, index, phase) trên DOM hiện có. EditorHeader.assemble và BuilderWorkspacePanels.assemble cung cấp dấu cho trình chỉnh sửa.
Chỉ gọi await startWorkspaceAssembly(navigate, destinationPathname) sau khi tạo thành công: chụp các phần đang hiển thị, điều hướng một lần và ghép đích hoặc khung tải tương ứng trong tối đa 720 ms. Đích cần dấu đi vào canvas; useWorkspaceAssemblyPending() giữ màn hình tải cho đến khi ảnh chụp ổn định, đồng thời tải trước dữ liệu và mã. Giảm chuyển động hoặc trình duyệt không hỗ trợ sẽ điều hướng trực tiếp. Chuyển tiếp chậm hoặc bị ngắt sẽ giải phóng ảnh chụp và tiếp tục. Dấu không tự tạo hoạt ảnh khi chỉnh sửa, tải lại hay duyệt lịch sử. Mẫu chung dọn kiểu tạm; ứng dụng quản lý lỗi tạo, tính lũy đẳng và trạng thái tải.
2026-09 · Không gian quản trị
WorkspacePage và WorkspaceLayout nhận variant: overview, list, detail, settings hoặc editor. WorkspaceFormFooter sắp xếp actions, message, tone và busy từ ứng dụng chủ; ứng dụng chủ chịu trách nhiệm lưu dữ liệu.
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)
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. Creator 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 Creator 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. Creator 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.
Bộ điều hợp Web cũng chuyển tiếp FloatingAssistantPanel.composerAttachments. Vị trí này hiển thị phần đính kèm do ứng dụng chủ quản lý trong biểu mẫu tin nhắn, trước ô văn bản. Ứng dụng chủ quản lý vị trí và gửi: thao tác thả chỉ chuẩn bị phần đính kèm; thành công chỉ xóa phần đã gửi; lỗi giữ lại để thử lại.
Hội thoại dùng chung (tham chiếu tiếng Anh; chờ dịch)
@qokit/components/patterns/Conversation exports ConversationPanel, ConversationMessages, ConversationMessage, ConversationSuggestions and ConversationComposer. Creator 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 kết hợp InlineNotice để trình bày gọn trạng thái tác vụ, lỗi, phương án dự phòng và xác nhận lưu trong hội thoại. Cung cấp title đã bản địa hóa, cùng description, tone và action nếu cần. Cả hai dòng dùng cỡ chữ chú thích, khoảng cách nhỏ và nền trong suốt; sắc thái làm nổi bật trạng thái, còn văn bản hỗ trợ được làm dịu. Các giá trị mặc định role="status" và aria-atomic="true" thông báo toàn bộ cập nhật cùng lúc; dùng role="alert" cho lỗi cần người dùng xử lý. Nội dung do trợ lý viết vẫn nằm trong 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.
Tài liệu API bổ sung (tiếng Anh, chờ dịch) · 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,filterstrạng thái,sort,controlsnghiệp vụ, tùy chọnadvanced,resetcó điều kiện,resulttài nguyên vàsummarybổ trợ.presentation:view, hiển thịcontrolsvàoptionsnhư số cột hiển thị và kích thước trang. Tùy chỉnh widget trang thuộc về các hành động tiêu đề trang.actions: persistent operations, followed by the optionalselectioncontrol at the logical end. UseToolbarButtonswithiconand localizedcompactLabelfor 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.
Dùng query.result={{ label, count, total?, locale? }} cho tên tài nguyên và số kết quả. WorkspaceResultSummary hiển thị “Tên · số lượng”, chỉ thêm “/ tổng” khi tổng chưa lọc đáng tin cậy khác số kết quả; định dạng số theo ngôn ngữ giao diện và tách số trong văn bản hai chiều. Bỏ result khi chưa biết số lượng; số không là hợp lệ. Không thêm hàng tên và số lượng khác trên cùng danh sách. AdminFilterBar.result nhận cùng đối tượng. Tiêu đề trang, phần có ý nghĩa, phân trang và số mục chọn giữ vai trò riêng; dùng query.summary cho đơn vị khác, ngữ cảnh truy vấn hoặc thông tin cập nhật.
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.
Tham chiếu API bổ sung (tiếng Anh, chờ bản dịch) · 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.
Các tùy chọn lựa chọn và menu hỗ trợ annotation để thêm dấu chấm theo màu chủ đề và đưa ý nghĩa đã bản địa hóa vào tên trợ năng. Nút mở ControlMenu cũng hiển thị dấu chấm của tùy chọn hiện tại; triggerAnnotation: null chỉ giữ dấu trong menu. Chọn lại một tùy chọn đang được chọn và được bật sẽ gọi onReselect. Tùy chọn gốc hiển thị chú thích cạnh nhãn; hidden loại mục giữ chỗ khỏi danh sách. Máy chủ quyết định giá trị được đánh dấu và hành động; điều khiển dùng chung không suy luận tính kế thừa hoặc ghi dữ liệu.
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
Đặt CustomizableWidgetLayoutControls trong các hành động tiêu đề trang sau trợ giúp ngữ cảnh và trước hành động chính, bao gồm trên thiết bị di động. Sử dụng copy.customize đã địa phương hóa để đặt tên rõ ràng cho hành động (ví dụ: “Tùy chỉnh widget”). Mục chỉ với biểu tượng này hiển thị aria-pressed và aria-expanded, và trở thành copy.done khi đang chỉnh sửa. customizeButtonRef tùy chọn kích hoạt việc khôi phục trọng tâm cho host; disabledCustomize vô hiệu hóa mục mà không thay đổi hình học của nó. Chỉ cung cấp onCollapseToggle và areWidgetsCollapsed cho các host hỗ trợ thu gọn widget; việc bỏ qua chúng sẽ khiến mục tùy chỉnh xuất hiện đơn lẻ.
CustomizableWidgetLibrary sở hữu tiêu đề thư viện chung, các hành động đặt lại/đóng, bố cục cuộn đáp ứng, trọng tâm nút đóng ban đầu và xử lý phím Escape. Việc đóng trả lại trọng tâm cho điều khiển gọi khi trọng tâm vẫn nằm bên trong thư viện; nhấp ngoài giữ trọng tâm đích của nó. Các host duy trì định nghĩa widget, lệnh thêm/xóa/sắp xếp/thay đổi kích thước, tính năng lưu trữ và ý nghĩa đặt lại. Các slot lớp CMS và Admin vẫn khả dụng cho các hook miền, nhưng không được xác định các bề mặt thư viện hoặc bố cục di động riêng biệt.
2026-10-17 · Kích hoạt ActionMenu phong phú
ActionMenu.renderTrigger có thể tái sử dụng một điều khiển phong phú như SelectableTile. Nó nhận aria-expanded, aria-haspopup, disabled, và onClick; trải chúng lên kích hoạt thực tế. Máy chủ giữ lại ngữ nghĩa lựa chọn và giao diện của điều khiển. Định vị Portal, điều hướng bàn phím menu, đóng, trả lại tiêu điểm, và các sheet di động tùy chọn vẫn do ActionMenu sở hữu. Các kích hoạt nút và biểu tượng mặc định không thay đổi.
Điều khiển bán kính và khoảng giá trị
RangeNumber từ @qokit/components/ui/RangeNumber kết hợp thanh trượt gốc với Input số chính xác. Truyền label, value, min, max, tùy chọn step và unit, cùng onChange. Giá trị chưa xác định hiển thị dấu gạch cho giá trị hỗn hợp; thay đổi một đầu vào sẽ đặt một số trong giới hạn. onCommit giúp ứng dụng nhóm các thay đổi liên tục vào lịch sử hoàn tác hiện có. disabled, điều hướng bàn phím, mật độ gọn, RTL và kiểu tiêu điểm được dùng chung; ứng dụng quản lý lưu trữ. RangeNumberSkin cung cấp các vị trí gốc, thanh trượt, đầu vào và đơn vị.
EditorRadiusControl từ @qokit/components/patterns/EditorRadiusControl kết hợp xem trước hình dạng trực tiếp, bốn đầu vào góc vật lý, RangeNumber và các mẫu hình dạng tùy chọn. value và onChange dùng cú pháp rút gọn CSS border-radius; ứng dụng dịch cornerLabels và tên mẫu. Trong RTL, thứ tự vẫn là trên trái, trên phải, dưới phải, dưới trái. max giới hạn chỉnh sửa ở giá trị pixel có biên; bỏ qua để giữ đơn vị CSS và cú pháp góc elip. Bán kính hỗn hợp không hiển thị một số duy nhất cho đến khi đặt cả bốn góc cùng nhau. EditorRadiusControlSkin tùy chọn điều chỉnh các vị trí gốc, sơ đồ, xem trước và mẫu mà không thay đổi trạng thái hay lưu trữ.
2026-10-22 · Thẻ điều hướng đang hoạt động trên màn hình hẹp
PillTabs nhận tùy chọn scrollActiveTabIntoView, mặc định là false. Với thẻ ngang, tùy chọn đưa phần tử con trực tiếp đang hoạt động PillTabLink hoặc PillTabButton vào vùng nhìn khi chọn hoặc đổi kích thước. Chỉ dải thẻ cuộn; vị trí trang và tiêu điểm bàn phím giữ nguyên. Hỗ trợ LTR và RTL với điều chỉnh tức thì, kể cả khi giảm chuyển động. Thẻ dọc và lời gọi không dùng tùy chọn vẫn giữ hành vi cũ.