Drag&Drop小部件和預置

1）概念和情景

Drag&Drop Widgets是交互式塊（圖形卡、表格、過濾器、按鈕動作）,用戶可以自由放置在帶有網格綁定的畫布上。預置-保存的布局和樣式（布局+主題+參數）,可快速應用、共享和驗證。

• 從成品塊（KPI卡，圖形，過濾器）組裝行貨板。
• 通過「緊湊型」、「分析」、「演示」預設快速更改布局。
• 聯合編輯：出售小部件,分析師配置來源.
• 為牛排者發布「僅讀」。

2）建築原則

1.網格第一：在邏輯列/行中的定位（12/24）,像素是導數。
2.Snapping&Guides：磁性導軌,粘在網格和鄰居上,對齊。
3.Constraint-aware：尺寸/比例限制器,min/max, lock-aspect。
4.安全默認：連續自動保存、事務性發布、undo/redo。
5.A11y-first：dnD從鍵盤和語音更改。
6.Realtime-ready： CRDT/OT用於多人遊戲。
7.主題：設計令牌、主題預設、淺色/深色/對比度模式。
8.便攜式：JSON/YAML進出口；電路轉換。

3）數據模型（簡化）

json
{
"id": "layout_01",
"name": "Analytics - Compact,"
"version": "2. 1. 0",
"grid": { "cols": 12, "rowHeight": 8, "gutter": 8, "margin": 16 },
"theme": { "preset": "light-pro", "tokens": { "radius": 12, "elevation": "soft" } },
"widgets": [
{
"id": "w_kpi_1",
"type": "kpi",
"title": "GGR",
"pos": { "x": 0, "y": 0, "w": 3, "h": 4, "z": 1 },
"constraints": { "minW": 2, "minH": 3, "lockAspect": false },
"props": { "format": "currency", "source": "ggr_daily" }
},
{
"id": "w_chart_1",
"type": "lineChart",
"title": "Deposits Trend",
"pos": { "x": 3, "y": 0, "w": 6, "h": 8, "z": 1 },
"props": { "source": "deposits", "legend": true }
},
{
"id": "w_table_1",
"type": "table",
"title": "Top Segments",
"pos": { "x": 9, "y": 0, "w": 3, "h": 12, "z": 2 },
"props": { "source": "segments_top", "pageSize": 12 }
}
],
"meta": { "createdBy": "dima", "updatedAt": "2025-11-03T17:55:00Z" }
}

4）網格，綁定和指南

網格：12個臺式機揚聲器，6個平板電腦揚聲器，4個手機揚聲器；「rowHeight」相同以實現穩定的垂直音高。
快照：沿邊緣/中心綁定；4/8 px的「磁鐵」；接近鄰居時的智能海德。
自動流動：碰撞時自動移至下方；「入射塊」算法。
可恢復性：breakpoints →每個breakpoint下的替代「pos」。

5） DnD事件和狀態

События: `dragStart`, `drag`, `dragOver`, `drop`, `resizeStart`, `resize`, `resizeEnd`, `select`, `group`, `ungroup`, `reorder`, `undo`, `redo`.

• Ghost/Preview：拖動時半透明的輪廓。
• Placeholders：禁用（紅色）的允許區域（綠色突出顯示）。
• Collision map：快速計算繁忙的細胞（bitset/interval tree）。

6）重組，對齊，z索引

轉彎手柄+保持「Shift」以保持比例。
組對齊：「沿左/右邊緣」，「沿中心」，「均勻分布」。
覆蓋級別：「z」具有範圍限制，「前/後」按鈕。

7）組、容器和嵌套

群組：多重選取、聯合拖曳、群組對齊。
容器小部件：禁忌，手風琴，旋轉木馬-知道如何接收子部件。
容器限制器：外部網格≠內部（其他列）。

8） Presets（模板）和版本

預置類型：布局，主題（主題），「小部件集」，「布局+數據」。
轉化：「semver」方案和遷移（字段映射，默認值）。
預覽和應用：應用前預覽。
Scoped presets：個人，團隊，全球；閱讀/編輯權。
導出/導入：JSON/YAML、校驗和簽名、版本兼容性檢查。

9）可用性（A11y）和鍵盤

• 「Enter/Space」-開始轉移；箭頭-移動到網格間距；「Shift」+箭頭-加速間距；「Esc」-取消。
• 「Ctrl/Cmd+G」-分組；「Ctrl/Cmd+Shift+G」-分組。
• 「Alt」-暫時禁用網格綁定。
• SR配音："移至（x，y）。粘附：打開。沖突：是/否。"
• 焦環，大型手柄，帶描述的dropa區域。

10） Tach和移動模式

Long-press（300-500 ms）開始DnD。
增加的靶標（最少40-48 px）。
自適應工具欄（底部塢站）。
「編輯模式」（Edit Mode）：在移動到邊緣時阻塞畫布滾動，垂直自動滾動。

11）小部件動作（Actionable Widgets）

內置CTA（按鈕）,上下文菜單,drag-clone（復制到「Alt」）。
小部件的「快速預設」（密度，圖例，配色方案）。
狀態：加載/empty/error，安全存根（「數據滯後」）。

12）協作和出版物

Realtime： CRDT（例如Yjs）或OT （Quill方法）-參與者遊標,組鎖定。
權利：「所有者」，「編輯」，「查看者」；發布快照（immutable snapshot）。
流：草稿→評論→出版；比較更改（diff布局）。

13） Undo/Redo和汽車保護

命令總線：每個操作都是帶有「do/undo」的命令。
客戶端上的日誌（in-memory+presential persist）,長度限制。
自動保存：每N秒/每秒「idle」,指示符為「保存」。

14）主題化和設計令牌

json
{
"themeId": "light-pro",
"tokens": {
"fontScale": { "h1": 24, "h2": 18, "body": 14 },
"radius": 12,
"elevation": "soft",
"palette": { "primary": "#3366FF", "critical": "#E53935" }
}
}

切換主題而不重新計算層（僅限視覺令牌）。
AA/AAA的對比，高對比模式，黑暗主題，正確的灰色。

15）生產力

按圖層渲染（用於復雜圖形的canvas/webgl,用於鉻的DOM）。
列表/表虛擬化,throttle 'drag' （16 ms）, requestAnimationFrame。
Diff渲染：僅重新繪制更改的小部件。
沖突計數緩存和海線。

16）內容安全和保護

用於HTML小部件的Sunbox（iframe，CSP，「sandbox」標誌）。
Drop限制：whitelist類型（文件，鏈接，JSON預設）；檢查大小和內容。
預設權（RBAC/ABAC），導入/導入審核。

17） Widget API（合同）

ts interface Widget {
id: string;
type: string;
pos: { x:number; y:number; w:number; h:number; z:number };
constraints?: { minW?:number; minH?:number; maxW?:number; maxH?:number; lockAspect?:boolean };
props: Record<string, unknown>;
validate? (props): { ok: boolean; errors?: string[] };
onDrop? (dataTransfer): DropResult ;//support for external drop onAction? (actionId: string, payload?: any): void;
}

生命周期事件：「mount」，「resize」，「visibilityChange」。
Props在出版前的驗證。

18）進口/出口和遷移

導出：「grid」，「widgets」，「theme」，「meta」。
導入：驗證架構版本、自動遷移（map字段/默認）、報告。
使用哈希鎖定文件預設,以確保完整性。

19）熱鍵（推薦）

導航：'←↑→↓'-移動；'Shift'+箭頭是一個快速的步驟。
重新設計：「Alt」+箭頭。
操作：「Ctrl/Cmd+D」是重復的；「Ctrl/Cmd+G」是組；「Ctrl/Cmd+Shift+G」是分組。
級別：「［/］」-通過z-index來回。

Undo/Redo: `Ctrl/Cmd+Z` / `Ctrl/Cmd+Shift+Z` (или `Y`).

預設：「Ctrl/Cmd +1..9」-快速套用儲存的預設。

20）UX模式

首次啟動時的快速粘合劑（在3-5個步驟上進行微旁路）。
網格模式：「顯示/隱藏網格」單選按鈕。
沖突中的入線提示（「不可用：widget寬度=3」）。
布局歷史：返回到以前的版本。

21）測試計劃

Unit：沖突計算，狙擊，constraints驗證器。
集成：鼠標/tachem/鍵盤的 DnD；分組；容器。
E2E：從頭開始組裝行貨板，應用預設、出版、出口/進口。
混亂：渲染延遲，連接丟失（realtime），權利沖突。
A11y：鍵盤腳本，SR配音，對比度。

22）實施支票

• 網格/breakpoints和snapping設置
• 重新設計/組/對齊工作並進行了測試
• 包括鍵盤DnD和屏幕提示
• AutoEve, undo/redo,布局歷史
• 預設：版本、權利、出口/進口
• 主題和設計令牌，高對比模式
• 實時協作和解決沖突
• 禁食限制,文件驗證,sandbox HTML
• 度量標準：adoption,第一次放置之前的時間,沖突錯誤

23） Mini-FAQ

為什麼只有網格而不是自由坐標？
網格通過適應性、預置便攜性和性能簡化了對齊。

如何將不同的布局存儲在斷路器下?

每個Widget都具有「pos」到breakpoint（desktop/tablet/mobile），帶有自動倒退。

合作選擇什麼-OT或CRDT?

CRDT對於離線/沖突更簡單；OT-用於線性文本操作。對於布局，使用CRDT的頻率更高。

底線

好的Drag&Drop小部件不僅僅是「拖卡」。它們是：嚴格的網格和鏟球，方便的組和對齊方式，鍵盤的可用性，穩定的版本和導出預設，安全的出版物和協作。圍繞由UX和測試計劃精心設計的可靠數據模型構建此模型,設計人員將快速、清晰和抵禦內容和團隊的增長。