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和测试计划精心设计的可靠数据模型构建此模型,设计人员将快速、清晰和抵御内容和团队的增长。