glassbrain 0.1.4 → 0.2.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,938 @@
1
+ # kglens
2
+
3
+ 通用图谱查看器。多图层 · 视角切换 · 分治布局 · 可插拔 profile。
4
+
5
+ 零依赖于任何业务:库里没有一处认识"功能点""业务模型"这类概念。领域知识全部住在
6
+ 调用方给的一个 **profile** 对象里。
7
+
8
+ ```
9
+ react/ GraphCanvas · Toolbar · DetailPanel
10
+ core model · profile · view · elements · style · layout/
11
+ ```
12
+
13
+ 依赖方向永远向下,反向为零。`model / view / elements / layout` 全是纯模块(无 React、
14
+ 无 DOM),node 里可以直接跑,也就可以直接写测试。
15
+
16
+ ---
17
+
18
+ ## 30 秒上手
19
+
20
+ ```tsx
21
+ import { parseSources, GraphCanvas } from 'kglens';
22
+
23
+ const model = parseSources([{ origin: 'graph.json', text }]); // 认 {nodes, edges}
24
+ <GraphCanvas model={model} />
25
+ ```
26
+
27
+ `graph.json` 的物理契约就是两个数组:
28
+
29
+ ```json
30
+ {
31
+ "nodes": [{ "id": "a", "label": "甲", "kind": "box", "parent": "root", "layer": "L1" }],
32
+ "edges": [{ "source": "a", "target": "b", "kind": "dep", "label": "依赖", "weight": 0.8 }]
33
+ }
34
+ ```
35
+
36
+ 只有 `id` / `label` / `source` / `target` 是必需的。
37
+
38
+ ---
39
+
40
+ ## 核心概念
41
+
42
+ ### 1. 模型 (`GraphNode` / `GraphEdge`)
43
+
44
+ | 字段 | 作用 |
45
+ |---|---|
46
+ | `parent` | compound 嵌套,**结构层级的唯一来源**(包含边、虚拟根、过渡里"从哪儿长出来"都读它) |
47
+ | `kind` | 语义分类,透传成 cytoscape class → profile 用它着色 |
48
+ | `layer` | 图层。多层视图与 2.5D 平面按它分组 |
49
+ | `origin` | 来源标识(通常是文件名)。**子图筛选与将来写回定位的锚**,由 `parseSources` 自动盖章 |
50
+ | `flags` | 布尔标记,每个变成一个 class(如 `unfilled`) |
51
+ | `data` | 原始对象,原样交给详情面板 |
52
+
53
+ #### 数据、结构、派生、呈现:四层各归各的
54
+
55
+ 库只认中间那个**模型**。哪一层归谁、能不能存,一条线划清:
56
+
57
+ | 层 | 是什么 | 谁产出 | 存不存 |
58
+ |---|---|---|---|
59
+ | 源数据 | 宿主自己的 json 方言,可以是一堆文件 | 宿主(流水线、人) | 宿主的事 |
60
+ | 模型 | 节点 `id / label / kind / parent / layer / data`,边 `source / target / kind / weight` | `profile.parse` + `merge` | **唯一会被改、会被存的那一层** |
61
+ | 派生 | flag(如 `unfilled`)、校验结果、`origin` 盖章、缺省的层归属、虚拟根 | profile 和库现算 | **永远不存**,模型一变就重算 |
62
+ | 呈现 | 配色、kind 的名字、`flagNotes` 那句解释 | profile | 跟数据无关 |
63
+
64
+ 举个例子:「未填充:脊柱里有这个功能点,但抽取阶段没落地内容」不是数据带的,也不是库加
65
+ 的——是 `examples/kg-profile.ts` 的 `merge` 在折叠脊柱时**算出来**一个 `unfilled` flag,
66
+ `placeholderFlags` 让它画成骨架,`detail.flagNotes` 给了这句话。这个功能点哪天被填上,
67
+ flag 自己就没了,不需要谁去删。换一套结构的数据,这三样换掉就行,库一行不用改。
68
+
69
+ **每个参数住在哪。** 每个开关都回答三个问题——谁定、活多久、存在哪——答完它就只有一个家:
70
+
71
+ | 类 | 回答什么 | 谁改 | 活多久 | 在哪 |
72
+ |---|---|---|---|---|
73
+ | 数据 | 图是什么 | 宿主 / 流水线;看图的人经编辑提出修改 | 永久,宿主存 | `model` 进来,`onEdit` 出去 |
74
+ | 方言 | 这种数据怎么读 | 开发者写一次 | 代码 | `profile`,没有界面 |
75
+ | 视图 | 此刻在看哪 | 看图的人 | 这一次会话 | 画布上:搜索、层、来源筛选、图例的开关(`view` / `onViewChange`) |
76
+ | 偏好 | 我喜欢怎么画 | 看图的人 | 跨会话,宿主存 | 按种类的在图例上(`look` / `onLookChange`);全局的是 prop(`theme`、`nodeScale`…),宿主放进自己的设置里 |
77
+ | 集成 | 跟宿主怎么接 | 开发者 | 代码 | prop,没有界面(`pool`、`matchKey`、`layout`、回调、`controls`) |
78
+
79
+ 没有哪个出现在两处;派生的哪儿都不出现——它们现算。
80
+
81
+ ### 2. 视图 (`GraphView`) —— 子图 / 搜索 / 图层是同一件事
82
+
83
+ **总图只有一张,视图只决定谁可见。** 两个筛选轴按顺序叠加,最后做祖先闭包
84
+ (可见节点的父盒子链一定在场):
85
+
86
+ ```ts
87
+ {
88
+ layers: ['req'], // 看哪一层(planes: true 时可以是几层,叠成 2.5D)
89
+ origins: ['card.json'], // 子图:只看某个来源
90
+ query: '登录', // 搜索 —— 只标命中,不藏任何东西
91
+ hiddenNodeKinds: ['author'], // 总图里隐去的种类(见下)
92
+ hiddenEdgeKinds: ['authored-by'],
93
+ }
94
+ ```
95
+
96
+ 这几个轴**只切 display**:不重建实例、不重排坐标、不闪。
97
+
98
+ **按种类隐去只管总图。** `hiddenNodeKinds` / `hiddenEdgeKinds` 让一类东西不出现在总图里——不画、
99
+ 点不中,位置照旧占着,所以形状不跳——但人伸手去够的照常出来:悬停的那一跳(跟着悬停一起淡入)、
100
+ 搜索命中、选中的那个连同它的一跳。隐去的点身上的边一起隐去。关掉一类是"总览时别挡我",不是"它
101
+ 不存在":悬停一篇论文却不给看它的作者,那是悬停在说谎。做在画笔这一层、不碰 display,所以带出来
102
+ 是即时的,开关本身是一下淡入淡出。
103
+
104
+ **聚光一类**是宿主的临时口子:`<GraphCanvas emphasis={{ nodeKinds: ['author'] }}>` 让这一类亮、其余
105
+ 压暗(跟搜索命中同一套,盖过它),隐去着的也照样带出来;边类连带两端的点。
106
+
107
+ **图例**(左下,库自带;`legend={false}` 关掉)列出数据里有的种类和个数。停在一格上(或点、触、回车)
108
+ 弹出它的面板,同时图上那一类亮起来——显示开关、颜色、大小倍数(½ / 1 / 2),一行。改了结果的那一下
109
+ (开关、选定颜色)面板收起、高亮撤掉,看到的就是改完的样子。记号(形状、线型、端头)从图上现读,
110
+ profile 的 `style` 写什么它就画什么。关掉的那一格名字划掉、色块空心,数字还在。名字来自
111
+ `profile.kindLabels`(节点和边的 kind 共用);没有自己名字的几格——没配颜色的节点、包含边、对比时的
112
+ 几类变更——只有记号和个数,名字在悬停提示里。窄的画布上它先收着。
113
+
114
+ 隐去哪几类归视图(`hiddenNodeKinds` / `hiddenEdgeKinds`);颜色和大小是看图的人的**外观**——`GraphLook`,
115
+ 叠在 profile 和主题上,从不写回它们;受控或自持,跟 `view` 一样:
116
+
117
+ ```tsx
118
+ <GraphCanvas look={look} onLookChange={setLook} /> // 想按数据集记住就自己存
119
+ ```
120
+
121
+ **搜索不筛选。** 它把命中以外的压暗、命中的字排前;回车(或在下拉里点一条)选中它、
122
+ 相机飞过去(远的先拉远再推近)。筛掉的话子图会收紧重排,人刚认出来的形状就没了——
123
+ 搜索是导航,不是视角。
124
+
125
+ **怎么算命中**(`searchNodes`,下拉里的加粗用的是同一份 `queryMarker`):
126
+
127
+ - 不分大小写,名字、id、`data` 里的字都搜。
128
+ - 整串的档位从严到宽:名字全等 → 名字打头 → 名字里有 → id 里有 → 内容里有;同档先短后长。
129
+ - **空格分开的几个词:尽量都中。** 有全中的就只要全中(像"与");一个全中的都没有,才退
130
+ 到中得最多的那些(`新增 增加` 这种同义词自然成了"或")。整串命中的永远排在分词命中前面。
131
+ 只留最好的那一批,所以一个常见词不会把半张图点亮。
132
+ - **`/…/` 是正则**(比如 `/^DOC-\d+$/`)。写坏了就当普通文字搜,不报错。
133
+ - 没有开关,不做拼写容错:结果要说得清"为什么是它"。
134
+
135
+ 视图里没有任何东西会改变元素集合:只有换 `model`(或 `profile`)才重建、重新布局。
136
+ `GraphView` 里的一切都只切可见性。
137
+
138
+ 子视图的坐标策略(三档,都在 `GraphCanvas` 的 `applyView` 里):
139
+
140
+ | 子视图长什么样 | 怎么排 |
141
+ |---|---|
142
+ | 小(≤60 节点) | 沿用全局坐标当种子,先按节点数等比压到该有的密度,再力导向解重叠——相对排布还认得出来,空洞没了 |
143
+ | 大(≤400 节点) | 重排。从几千节点里抠出来的几百个彼此隔着被隐藏的一大片,硬保持相对位置只会得到"两团东西加一根长线" |
144
+ | 结构被筛没了(无边无嵌套) | 铺成网格。没有可保留的相对关系,力导向也拢不动 |
145
+
146
+ 超过 400 就不收紧了——那已经是大视图,全局坐标本来就合适,再算一次只是白等。
147
+ 退出子视图时全局坐标会被还原回去。
148
+
149
+ ### 2.5 时间 —— 一次数据切换是一次「并集过渡」
150
+
151
+ 视图给的是**空间**,过渡和 diff 给的是**时间**,而它们是同一件事的两种读法:
152
+
153
+ ```
154
+ diff = 把并集停住看
155
+ 切数据 = 把并集演一遍,再把过去那一半收起来
156
+ ```
157
+
158
+ 换一份数据不是"把旧的换成新的",是**让新旧两版同时在场,演完再收**。这一个决定
159
+ 消掉了一整类问题:**位置的终点是并集布局,而它只有一份**,于是"两版怎么对齐"根本
160
+ 不存在。在**两套**坐标之间插值才是所有乱窜的来源,而这里没有第二套。
161
+
162
+ 一次切换是**一段有先后的戏**,不是一次插值。从导演那头想 step1→step2:先把要消失的
163
+ 那块从枝上切下来——**边先断,那块猛地弹开一点、暗一档**,然后像落叶一样慢慢飘散淡出;
164
+ 飘到一半,留下来的开始 duang 到新位置;快停住时,新增的像抽条一样从它爹那儿长出来,
165
+ **最后才接上它跟既有结构之间的连线**。镜头先张开给这一切观看空间,最后收窄、撇开空白。
166
+
167
+ 反过来 step2→step1 是**同一张分镜**——差别只在数据(一边 43 片叶子 0 个新芽,一边反
168
+ 过来)。所以既不需要两套编排,也不需要判断"这次是放大还是缩小"。
169
+
170
+ | 轨道 | 谁参与 | 窗口 | 曲线 |
171
+ |---|---|---|---|
172
+ | 剪断 | **跨过剪口的边**(一头还活着) | 0 – 10% | 线性,快 |
173
+ | 弹开 | 被剪下来的那块:短促地弹开一截,**同时暗掉一档** | 7 – 20% | easeOutCubic |
174
+ | 落叶 | 然后慢慢飘散、淡完(片内形状一点不变) | 18 – 95% | 近匀速,末速度不为零 |
175
+ | 位移 | 留下来的全场 | 22 – 74% | **sigmoid** |
176
+ | 到场 | 入场的透明度(含跟着新枝一起长的边)+ 旧皮变新皮 | 64 – 94% | 线性 |
177
+ | 萌发 | 入场集 = added ∪ 它们自己的结构 | 68 – 100% | 轻微过冲(easeOutBack) |
178
+ | 接合 | **新节点接到既有结构上的那些边** | 86 – 100% | 线性 |
179
+ | 张 / 收 | 相机 | 0–30% / 58–100% | sigmoid |
180
+
181
+ 分镜表是**首尾对称**的:**头上的「剪断」断开旧的连接,尾上的「接合」接上新的连接,
182
+ 中间全是移动。** 两头是同一条道理——一条边跨在"要走的那块"和"留下来的那块"之间时,
183
+ 它的长度由两头独立决定,一头走远就被拉成一条丝。所以退场那边先剪断,入场这边最后
184
+ 才接上;不跨界的边跟着自己那块走,全程长度不变。
185
+
186
+ 轨道首尾交叠,所以有先后可读,又不用三倍时长。
187
+
188
+ ### 一句话讲完整套模型
189
+
190
+ 每条通道 = 基点 + Σ(轨道进度 × 增量)
191
+
192
+ 三条通道:**位置**(x,y)、**存在**(透明度)、**外观**(皮)。形状完全一样,基点一律
193
+ 是"切换前最后一帧的值":
194
+
195
+ | | 位置的基点 | 叠加的腿 |
196
+ |---|---|---|
197
+ | kept / changed | 上一帧的位置 | 位移 → 它在并集里的位置 |
198
+ | moved | 上一帧的位置(**不是**旧父盒) | 位移 → 新位置 |
199
+ | merged | 它自己 | 跟着配对走 + 汇聚到它身上 |
200
+ | removed | 它自己 | **整片**弹开 + 飘散(剪断之后就不跟树走了) |
201
+ | added | **锚点**(父链上第一个上一帧就在场的祖先) | 跟着锚点走 + **抽条**到自己的位置 |
202
+
203
+ 于是 t=0 时所有轨道进度都是 0,每条通道都等于基点 ——
204
+
205
+ > **"第 0 帧跟上一帧一模一样"不是一条要守的纪律,是这个模型的推论。**
206
+
207
+ 这一条是花了代价换来的。早先只有位置是加法:`moved` 从"旧父盒"起步("它换了个树杈"
208
+ 的那个说法),代价是一个二级节点在开演的瞬间当场跳到它爹身上(实测 449 单位)。而且
209
+ **这一跳发生在任何一帧动起来之前,逐帧比对相邻两帧的位移永远抓不到它**——要抓它,得拿
210
+ "点击前的那一帧"跟"过渡的第 0 帧"比,而且得按**归一化后的 key** 比:配对会给节点改名,
211
+ 按 id 比会把换树杈的那批全漏掉(这个坑在这个项目里出现过不止一次)。
212
+
213
+ 而透明度和皮从前各有各的写法,于是各自要再守一遍同一条纪律,**总有守不到的地方**:
214
+ 并集挂上去到布局算完之间隔着一个 await、一次渲染、若干帧,那几帧没有任何人管——
215
+ `gk-added` 在浏览模式下只是个普通 class,于是新节点新边按默认样式**全量画了出来**。
216
+ 观众先看见"新的已经在了",之后再演剪断、再演萌发,全都失去了意义。换皮更刺眼:它会
217
+ 先跳到新皮,等过渡开演再被盖回旧皮,**往回倒一次**。
218
+
219
+ 三条通道统一成加法之后,第 0 帧的值既不依赖分镜也不依赖坐标(全是基点),所以**并集
220
+ 挂上去的那一刻就能写**:布局算得慢,只是多停一会儿在上一帧。修法不是"把那个窗口缩
221
+ 短"——那只是把概率调低——而是让那个窗口里画的东西**就是第 0 帧**。
222
+
223
+ "它是从旧树杈上来的"这件事,靠它从自己的旧位置走到新位置就说清楚了——旧位置本来就长在
224
+ 旧树杈上。要更明确的指认,那是覆盖层的事(画一条线指回旧父盒),不是拿位置去演。
225
+
226
+ 六条铁律,丢一条就会出现"这个演了那个没演":
227
+
228
+ 1. **边由它的两端认定,换一端就是另一条边。** 一条边活不过它的端点;而"换了树杈"
229
+ 不是一个节点属性,是**一条包含边没了 + 一条包含边来了**。连线模式下"包含"是渲染
230
+ 时从 `parent` 现生成的合成边,永远没有标记——这一增一删只认标记就必然漏掉,后果
231
+ 见下面"换了树杈"那一节。
232
+ 2. **时刻和速度不是同一个数。** 轨道的窗口是时刻,曲线是速度。从前是先把 `p` 过一遍
233
+ 全局 easing 再拿去比时刻,于是所有时刻整体塌到开头——easeOutCubic 下 `0.4` 这个
234
+ 时刻落在墙钟的 **15.7%**,700ms 里就是第 110ms,看上去就是"根本没演"。现在采样
235
+ 只有一个输入:墙钟时刻。
236
+ 3. **"现在"的一切由同一个数驱动**:入场的透明度、旧皮变成新皮的进度,就是 `fade.in`
237
+ 那一个标量。不另起时间线,就不会各演各的。
238
+ 4. **按"皮"分组,不逐元素写样式。** 同一对旧皮/新皮的元素,差异完全一样,每帧一次
239
+ 整批 style 调用就够。实测 206 个节点 4 条属性 **2.79ms/帧**,跟"存在"通道已经在
240
+ 花的钱同一量级;逐元素写是 6.06ms/帧,那才是烤机器的写法。存在通道同理:全场只有
241
+ 四条包络(剪断 / 退场 / 到场 / 接合),每帧四次整批调用。
242
+ 5. **回弹只许出现在曲线里,不许出现在尺寸里。** 位置本来就逐帧在写(任何位移动画的
243
+ 地板价),换条曲线是**零成本**;而"从 0.85 弹到 1"要逐帧写 width/height,那会连带
244
+ 触发样式重算、包围盒失效、父盒重算,完全不同的量级。所以"萌发"是**位移**不是缩放
245
+ ——从它爹那儿抽出来,末尾轻轻顶过头一点。
246
+ 6. **不造影子元素。** "n2 淡出、n1 移动,那条边却还拽着 n1"的正解不是复制一份不可见
247
+ 的 n1,是把「跟着爹走」和「自己飘开」拆成**两条叠加的腿**:展开算一下就知道,在
248
+ 位移那一拍里 n2 与 n1 严丝合缝地一起走(边长不变),只有落叶那一拍让它脱开。帧
249
+ 函数里一个乘加,没有多出来的元素、没有 id 冲突、没有布局副作用。
250
+
251
+ 退场这一拍的单位是**片**,不是节点:一片 = 由 parent 链连起来的一群退场节点(一棵
252
+ 被剪掉的子树)。片内所有节点共用**同一组腿**,于是整片平移,内部
253
+ 形状一点不变——一绺头发落下来,不是一把粒子炸开。按节点各算各的会出一个很显眼的事故:
254
+ 一片里顶上那个的爹还活着(跟着走一千多),它底下孩子的爹也是退场的(Δ=0,不跟),
255
+ **一块东西上半截跟着走、下半截不跟,当场扯成一条拉丝**。
256
+
257
+ **剪断之后就不跟了。** 剪断和跟随是互相矛盾的两件事:一块已经掉下来的东西不会再跟着
258
+ 树走。给退场的加"跟着爹走"本来是为了治"边被拽长",而那个病现在由剪断治了——于是跟随
259
+ 不但多余,还会把一块剪下来的东西拖着跑几千个单位(实测 4016),落幕再拽回原位,那正是
260
+ "剪的那一瞬结构瞬变"的观感。头发掉在地上,是人走开,不是头发跟着人走。
261
+
262
+ 而**跨过剪口的那些边必须先断**。片内的边跟着片一起飘,全程长度不变;一头还活着的那些
263
+ 不断的话,飘多远就拉多长一条丝。所以它们走一条短得多的包络(前 10%),断干净了那块
264
+ 才动——剪断的那一瞬间那块还是实的,才看得出是"断"。这也是"要不要复制一份不可见的父
265
+ 节点"那个问题的最终答案:**不要**。要的不是把边留住,是把边剪掉。
266
+
267
+ **剪断得看得见,所以它是两拍。** 边断完之后,那块先**猛地弹开一小段、同时暗掉一档**
268
+ (弹开,7–20%),剩下的距离和剩下的透明度才交给落叶慢慢走完(18–95%)。一条曲线做不到
269
+ 这件事——曲线只能改速度,改不了"两拍";而位置上一记短促的冲量配上透明度同一拍里掉的
270
+ 那一档,剪口才有重量。两条腿共线、整片共用,所以片还是刚体,形状一点不变。
271
+
272
+ 对称地,**新边最后才接上**(接合,86–100%):先长出来,才接得上。
273
+
274
+ ### 换了树杈 = 一条包含边没了 + 一条包含边来了
275
+
276
+ 两头合起来只有一条公理:**新增走生长,删除走飘落;而边由它的两端认定,换一端就是
277
+ 另一条边。**
278
+
279
+ 所以"换了树杈"根本不是一个节点属性。连线模式下包含边是渲染时从 `parent` 现生成的,
280
+ 而并集里 `moved` 节点带的是**新爹**——于是这一增一删**光看标记永远发现不了**:新那条
281
+ 连的是「新爹 → 它」,可它在第 0 帧还站在旧位置上,开演瞬间凭空多出一条横跨全图的粗线
282
+ (实测中位 **1257**);同时旧那条说没就没。两头都是突变。
283
+
284
+ 正解不是在"存在"通道里给包含边开特例,是让并集**完整**:`diffModels` 把旧爹记在节点上
285
+ (`prevParent`),`buildElements` 把两条都如实吐出来、各自带上 `gk-added` / `gk-removed`
286
+ (旧那条 `_force=false`,只来演一次离场,不参与任何一次求解)。下游于是根本不必认识
287
+ "包含边"这回事。
288
+
289
+ 剩下的只是把"跟着两端走"在每条边上算出结果。**边没有自己的位置**,它只能被画在两端
290
+ 之间:
291
+
292
+ | 两端 | 命运 |
293
+ |---|---|
294
+ | 同命(都要走 / 都新来) | 跟着走:整片一起飘,或者陪着新枝一起长——全程长度不变 |
295
+ | 异命 | 跟不了,只能断开;那就挑**两端都不动**的那段时间露面 |
296
+
297
+ 一头一尾看着不对称,其实是同一个判据:**过去那一侧还要走,未来那一侧已经停了。**
298
+ 退场的边,它活着的那一端马上要去新位置(位移 22–74%),不在那之前断干净就会被拉成
299
+ 一条横跨全图的丝;入场的边,它的老那一端早就到位了,所以等得起。
300
+
301
+ 这也是"要不要造一个透明节点来钉住变更边"的最终答案:**不要。** 被拉长的长度是**活着
302
+ 那一端**贡献的,钉住将死的那一端没用;要不拉长就得两端都钉,那等于给旧图做一份冻结的
303
+ 副本——正好退回"在两套坐标之间插值",而并集就是为了消掉它。**用时序,不用补偿。**
304
+
305
+ 飘散的距离要**小**。这一拍要突显的是"尖端被剪断",不是"炸开":四散的距离很小,形状还
306
+ 看得出来是原来那绺。缺省 **8%**(拉着滑块定的:8% 是"一眼看得出有东西掉下来了"和
307
+ "炸开"之间的那条线),飘得再远就把剪口这件事盖掉了。
308
+
309
+ **退场是全场最长的一拍**,而且故意穿过后面几拍:新芽开始抽条的时候,碎片还在飘、还
310
+ 剩三成透明度。这样一眼就能比出"减了多少 vs 增了多少"——两边同框,而不是一前一后各演
311
+ 各的。曲线也得配:`easeOutCubic` 在头 20% 就把位移走完了,剩下全程那片碎片是"停着
312
+ 淡",观感跟原地淡出没区别;飘散要的是**末速度不为零**(甩脱的那一记冲量归"弹开"那一
313
+ 拍单独演,所以飘本身近乎匀速)。每片碎片再各自浮动一点(飘多远 ±30%,加一点横向偏摆,
314
+ 种子取 id 的 hash),否则一起等比例外扩看着是"一个壳在放大"。这些都只在排分镜时算一
315
+ 次,帧里还是一次乘加。
316
+
317
+ 飘多远的**量纲只能是"占画面多大比例"**:镜头是按图取景的,所以全图跨度的百分之几就是
318
+ 屏幕的百分之几,换一张图、换一个缩放都成立。按"自己到爹的距离"算过一版,不行——那个
319
+ 距离在一张图里差两个数量级(贴着爹的叶子 140,挂在虚拟根上的顶层 2400),近的那批飘
320
+ 出去 60 个单位,而它们同时还在跟着爹走一千多,完全被淹没,看着就是原地淡出。
321
+
322
+ **取景只有一个口径:可见的那些节点。** 从前"没筛选也没退场"时留了一条 `cy.fit()` 的
323
+ 快路(= 全体元素,含边和边上的标签),于是同一张图有两个口径,用哪个取决于**上一步有
324
+ 没有退场**——那是上一段戏漏进了这一段。
325
+
326
+ **空拍掐白掐出来的零宽轨道"不发生",不是"瞬间走完"。** 一步只换皮时,镜头的「张」会被
327
+ 整条掐到 0 宽;零宽窗口要是除以一个下限,第一帧就饱和成 1——内容轨道无所谓(那几组本来
328
+ 就是空的),可镜头吃的是同一个数,于是画面在第 1 帧瞬移到并集取景再慢慢正回来。第 0 帧
329
+ 是连的、第 1 帧就跳,这正是"翻个跟头"的形状。
330
+
331
+ **空拍不留白,剩下的也不许抻长。** 这一次没有落叶、也没有位移,就别让"到场"干等到
332
+ 64%:把开头那段空白掐掉(窗口前移、归一化回 [0,1]),**同时把墙钟时长乘上 `span`**。
333
+ 两个缩放正好抵消,于是
334
+
335
+ > **一拍该演多久,跟这一步有几拍无关。**
336
+
337
+ | 这一步有什么 | span | 实际时长(缺省 1800ms) |
338
+ |---|---|---|
339
+ | 有落叶(完整一场) | 1 | 1800ms |
340
+ | 只有位移 | 0.78 | 1404ms |
341
+ | 只有到场(换皮 / 生长) | 0.36 | **648ms** |
342
+
343
+ 从前只做了前移:剩下那段被拉满回 [0,1],时长一动不动,于是"只填了内容"的一步把到场
344
+ 那一拍**抻慢了 2.78 倍**、照样演满 1800ms。观众等的不是空拍,是被抻长的那一拍。
345
+
346
+ 外观是第三种变化,跟"在不在""在哪"平级,而且**跟 `changed` 不是一回事**:`changed`
347
+ 比的是 data,皮是 kind/flags 算出来的,两者可以各自单独发生(那个 flag 常常取决于
348
+ **别的**节点存不存在)。真实数据里这一条很致命——某一步的全部内容可能就是"167 个
349
+ 占位被填上了",位移、增删、边全是 0;不把外观算成一个通道,那一步就等于没有动画。
350
+
351
+ 变色怎么演出来的:**内核不认识任何具体颜色。** 过渡开始时它问渲染器"这个元素按旧皮
352
+ 算出来什么样、按新皮算出来什么样",自动挑出真正有差异的属性,能取中间态的(颜色按
353
+ 分量、数值按线性)逐帧插,没有中间态的(`dashed`→`solid` 这种枚举)留到「到场」那一拍的
354
+ 起点切。**写的是行内样式,不是换 class**——行内盖在 class 之上,收尾把它撤掉就自然
355
+ 落回新皮,不需要"再换回去"的补救动作。所以换任何 profile、任何配色、以后新加的任何
356
+ 样式属性都自动走这条路,不用预先登记。
357
+
358
+ 外观通道**只改涂什么颜色,不改占多大地方**:宽高、padding、字号、形状一概不碰。坐标
359
+ 是按新皮的尺寸算出来的,补间里把尺寸改回旧的,父盒边界和边的端点就跟坐标对不上了。
360
+
361
+ **缺省就开,不用接线。**
362
+
363
+ ```tsx
364
+ <GraphCanvas model={next} /> // 已经在演了
365
+ <GraphCanvas model={next} animate={false} /> // 关掉
366
+ <GraphCanvas model={next} animate={{ duration: 900 }} /> // 快一点
367
+ <GraphCanvas model={next} animate={{ drift: 0.2, bounce: 2 }} /> // 飘狠一点
368
+ ```
369
+
370
+ 缺省是 **1800ms / 飘散 8% / 回弹 0.6**。这三个数纸上定不了,是拉着滑块看出来的——
371
+ 这一段戏要给人看的是"减了多少 vs 增了多少",不是一个转场特效,快了就只剩一团糊。
372
+ `duration` 说的是**一场完整的戏**:这一步没有的拍子不占时间(见上面的 `span`)。
373
+
374
+ "收起过去那一半"是**切 display**——跟视图筛选走同一条路,也就是库里那条铁律。
375
+ 不重建、不重排、没有最后一下跳变。
376
+
377
+ #### 一次过渡是一段不可打断的戏
378
+
379
+ 演到一半又来一份新数据,不是插队,是**攒着**:落幕之后接着演下一段,而且只留最新的
380
+ 那一份——中间那几版一帧都没画过,跳过它们不丢任何信息(这正是 throttle 该有的语义)。
381
+ 中途换数据就是把这段戏腰斩:上一段的碎片还在半空飘着,整个并集就被换成了另一段的。
382
+
383
+ ```tsx
384
+ <GraphCanvas model={next} onBusy={setBusy} />
385
+ ```
386
+
387
+ `onBusy` 是那扇门的开关,宿主拿它把"切数据"的入口灰掉。**不给反馈的话,用户点了没
388
+ 反应,比拦住更糟。** 窗口跟这段戏严丝合缝:从接受一次切换(开始算布局)到落幕收尾,
389
+ **布局那一段等待也算在内**——那时画面停在上一帧,它属于这次切换。
390
+
391
+ #### 配对判据是 `key`,不是 id
392
+
393
+ ```tsx
394
+ <GraphCanvas model={next} matchKey={(n) => n.id.replace(/^[^~]+~/, '')} />
395
+ ```
396
+
397
+ id 是**宿主**给东西起的名字,不是"同一个东西"的定义。两版处在不同命名空间时
398
+ (合并前每条枚举各带一个前缀、合并后统一编号),逐字比 id 会得出"全增全删",
399
+ 而它们明明是同一批东西。给一个归一化函数就够了。
400
+
401
+ 而**两个旧节点归到同一个 key、新版只有一个**,那不是冲突,正是「合并」:第一个当
402
+ 本体,其余记成 `merged` 指向它,过渡里它们会朝它汇聚。`diffModels` 吃的是同一个
403
+ `key`,所以配对只有一处实现——不会出现"动画说是同一个、diff 说一增一删"。
404
+
405
+ **故意不做相似度匹配**:猜错时画面会理直气壮地演一个不存在的对应关系,比"认不出来"
406
+ 更糟。认不出来就退化成增+删,那是诚实的。只有上游才知道的对应关系走显式 `mapping`。
407
+
408
+ #### 坐标从哪来
409
+
410
+ 布局和动画是两件事。过渡拿的只是「当前坐标」和「目标坐标」,插值就完了——**它不问
411
+ 目标是谁算的**。目标按这个次序取,取到就停:
412
+
413
+ | | |
414
+ |---|---|
415
+ | ① **`layout`**(你给的) | 这一版的 `{ 节点id: {x, y} }`。盖住了这一版的全部点就原样用。有好几版就按版本各存一份、传当前那一版的。 |
416
+ | ② **本机缓存** | `localStorage`,按结构寻址:这台机器上这份结构最近一次的结果,不管当初是怎么来的。刷新还在;`clearLayoutCache()` 清。 |
417
+ | ③ **现解**,按 `layoutMode` | `'fresh'`(缺省)只按结构完整重算。`'continue'` 同样全部重算,但从已有的坐标(屏幕上的,没有就从 `layout` 里取)出发而不是随机起步——幸存的点只挪一点。两种解法的缓存各存各的。 |
418
+
419
+ 每产出一份布局都经 `onLayout(positions, info)` 报出来——`info.source` 是 `preset`、`cache`、
420
+ `fresh`、`continue` 或 `relayout`(`cache` = 没有现算、复用了已有的结果:本机缓存,或者屏幕上正是这一份)。
421
+ 要留着就存下来,下次当 `layout` 传回去。`layout` 本身永远不被改写;把 `onLayout` 刚报的那份原样传回来,什么也不会发生。
422
+
423
+ 看图的人在画布 ⋯ 菜单里有「重新布局」:同一份数据随机换一种摆法,有动画,写进本机缓存、
424
+ 报给 `onLayout`。不想给就 `controls={{ relayout: false }}`。
425
+
426
+ 一步步往下走、不想跳的数据:用 `layoutMode="continue"` 走一遍,把每一步 `onLayout` 报的按版本存下来,
427
+ 随数据一起发,每一版传它自己那一份——相邻两步之间幸存的点只挪一点,而且每次打开都一样。demo 里
428
+ `boards-docs/_layout.json`(版本名 → 坐标)就是这么来的。改了 `layout` 或 `layoutMode`,画布当场按次序重新取一次
429
+ ——按内容比,换了个对象、坐标一样不算改。动画播放时,要重排的改动(`layout`、`layoutMode`、「重新布局」、对比的融合旋钮)
430
+ 都等落幕后补一次。对比模式下 `layout` 指新版那一版:那一侧的取法跟浏览时一模一样,开关对比它一个点都不动。
431
+
432
+ ```tsx
433
+ <GraphCanvas model={step} layout={saved} layoutMode="continue" onLayout={(pos) => save(pos)} />
434
+ ```
435
+
436
+ **同一份布局输入只解一次。** 力导向没有可复现的不动点:同一份输入解两次会得到两份差
437
+ 不少的排布(实测中位差 512,图宽约 2400),而且加迭代预算只会更糟——它不是在收敛,
438
+ 是在游走。所以答案不是"解得更狠",是"别再解":坐标按**结构**寻址,输入没变就把屏幕上
439
+ 那份原样还回去。只多了几百条渲染边的那一步,因此一个坐标都不动。
440
+
441
+ **这张图的身份是它的结构。** 三样,没了:谁是节点、谁的父亲是谁、哪些边受力。不含详情
442
+ 负载,不含你标了不受力的边,**也不含尺寸**。
443
+
444
+ 最后那一条是踩出来的:尺寸是渲染的结果,会随皮变。有一步只是把占位内容填上
445
+ (`unfilled` 这个 flag 掉了),结构一个字没变、标签一个字没变,可 79 个节点的皮变了 →
446
+ 量出来的尺寸变了 → hash 变了 → 从缓存里按**另一把钥匙**取回**另一次自由解** → 整张图
447
+ 挪了一次(实测中位 1246,而读数是"布局 0ms"——它根本没重解,只是换了一份坐标)。
448
+
449
+ 更糟的是尺寸是从**并集**上量的,而并集是过渡的产物:同一份 step2,从 step1 走过来和从
450
+ step3 走过来是两个不同的实例。于是"自由解跟你怎么走过来的无关"这条主张在尺寸这一项上
451
+ 是假的——第一次在两版之间切会翻跟头,之后就不翻了,因为并集的成分从那以后固定了。
452
+ **路径依赖就是这么混进一个号称路径无关的解里的。**
453
+
454
+ 所以尺寸只参与**怎么解**(力导向要按真实大小避让),不参与**是不是同一份输入**。代价
455
+ 说在明处:标签变长之后沿用旧坐标可能会挤一点——但"数据没变、图却动了一大截"比"挤一
456
+ 点"难受得多。
457
+
458
+ #### diff:并集从不求解
459
+
460
+ `diffModels` 出的是一张并集图,但**坐标不解它**。解两次单版,再把"只在旧版有"的
461
+ 那些整体平移过来、贴到幸存的锚点旁:
462
+
463
+ ```
464
+ pos[幽灵] = posBefore[幽灵] + ( 锚点在新图的位置 − 锚点在旧图的位置 )
465
+ ```
466
+
467
+ 纯平移,不旋转不缩放;锚点 = 这一坨幽灵在旧图里的邻居中、新版还活着的那些。
468
+
469
+ 对并集做一次自由解是从前那条路,它把"两个时间"当成"一张更大的图":AB→CD 会排成
470
+ 四叉平铺,而且**幸存的那部分也被重排了**——CD 在并集里的坐标跟你浏览 CD 时看到的
471
+ 毫无关系,看图人于是失去了唯一的锚:「这张图我认识」。
472
+
473
+ 现在新版那一侧的布局输入跟浏览这一版时**逐字节相同**(`shapeHash` 只认结构),所以
474
+ **按下"对比",幸存的节点一个都不动**。而且大变更会**自动退化**,不需要阈值也不需要
475
+ 模式开关:锚点越少,越多的块按**刚体**摆放;全都没锚点时两栏就各画各的那一版,
476
+ 两边都还长着各自本来的样子。
477
+
478
+ #### 双栏:同一张图的两个视图
479
+
480
+ **diff 就是双栏,没有别的排法**:左=过去、右=现在,**共用同一份坐标和同一个视口**
481
+ ——任何一个两版都有的节点在两栏是**同一个屏幕像素**(实测两栏最大坐标差为 0),眼睛扫一
482
+ 下就对上了。左栏那个实例是面**哑镜子**:不跑布局、不管视图代数、不参与过渡,只铺坐标、
483
+ 写可见性、跟视口。
484
+
485
+ **左栏画的是旧版自己的元素表,不是并集。** 这一条是踩出来的:并集里两版都有的节点一律
486
+ **以新版为准**(label / kind / data 全是新的),旧版那一份只在 `prevData` 里留了 data。
487
+ 拿并集去画左栏,画出来是"新版的内容摆在旧版的结构上"——两栏看上去是同一版,而那正是双
488
+ 栏要回答的那个问题。所以 `unionSides` 的两侧来路不同:新版那侧从并集里切(保住"布局输入
489
+ 逐字节相同"),旧版那侧回到旧版原件上取内容,只把 id 换进并集的命名空间。
490
+
491
+ #### 融合:一副共享的冻结骨架
492
+
493
+ 双栏之后才有条件做"让变更落在相近的位置"。起点是新版的自由解(= 你浏览它时那一份),
494
+ 旧版独有的那些按 `diffPositions` 平移到位,然后轮流把各自独有的那部分**推开**:
495
+
496
+ ```
497
+ x 共用节点的坐标,两栏共用同一份
498
+ ownA 只在旧版有的 ownB 只在新版有的
499
+
500
+ for k in 0..rounds-1:
501
+ iter = ⌊iterations / 2^k⌋ 推挤轮数每步减半,到 0 收尾
502
+ 松弛 (k 偶数 ? 旧版 : 新版),种子 = x ∪ 该侧独有,snap 开着时 x 钉死
503
+ ```
504
+
505
+ **关键在 `ownA` 和 `ownB` 从来不在同一个问题里**——所以它们之间没有斥力,各自会去填同一
506
+ 块空地,左栏那根旧枝和右栏那根新枝因此长在同一个位置上。"互不占空间"不是一条写进力场
507
+ 的约束,是"不在同一个问题里"的推论。
508
+
509
+ 同一条推论还管着**没有任何锚点的整块**该摆哪儿:两版**永远不同框**,所以让开是白让——
510
+ 实测两版毫无交集时(107 增 / 141 删 / 0 共用),让开会把并集从 1945 宽撑到 3898 宽,而
511
+ 两栏共用一个视口,于是**每一栏都有一半是空的**。所以整块原样保留旧布局的形状(共用同一
512
+ 个平移,内部一个点都不动),只把它对到新图中心上。
513
+
514
+ | | 含义 |
515
+ |---|---|
516
+ | `rounds` | 轮流几次。**1 = 新版一动不动,旧版单方面适应**(缺省) |
517
+ | `iterations` | 第一步推几轮,每走一步减半 |
518
+ | `snap` | 开(缺省)= 共用坐标钉死在新版的自由解上;关 = 跟着每一步跑 |
519
+
520
+ #### 那一步为什么不是力导向
521
+
522
+ 本来是。实测之后换掉了,数字记在 `layout/relax.ts` 顶上(124 节点、图宽约 2200):
523
+
524
+ - **cose-bilkent 拿到任何 `numIter < 400` 都抛** `RangeError: Invalid array length`,
525
+ 而且是**在自己的 tick 里异步抛的** —— `layoutstop` 永远不来,`await` 永远不返回,
526
+ 整块画布卡死在"布局准备中",不留任何线索。
527
+ - **`numIter` 根本不是步长。** fcose 给 1 和给 1200,位移一模一样(1461 对 1523)。
528
+ 这两个引擎都没有"只走一小段"这回事。
529
+ - **哪怕带着种子,一次解也会把共用节点挪走中位 586、最大 1422。** 而共用坐标随后要被
530
+ `snap` 按回去——于是独有的那些是相对一副瞬移过的骨架落的位,落在哪儿都不对。
531
+ - **fcose 的 `fixedNodeConstraint` 在这条流水线上也用不了**:分治把图切成组件之后,
532
+ 约束里的 id 有一多半不在这个组件的作业里,它直接抛。
533
+
534
+ 而"再算一遍"本来要解决的也不是重新排布,是**平移不做碰撞检查、搬过去会压在别人头上**。
535
+ 那是个局部问题,一个局部算子就够,而且局部算子天然吃"迭代几步"这个旋钮:每轮把重叠的
536
+ 框沿最小平移向量推开,再把可动那批的**重心**拉回出发点(逐点拉回是错的,它会跟分离
537
+ 互相掐死)。实测同样这份数据,整个融合 2–5ms,最大位移 41,钉住的一个都没动。
538
+
539
+ #### diff 的 UI 语言:栏位承载信息,色相只做加强
540
+
541
+ 图元的颜色平时归用户。从前 diff 把五个变更类别各映射成一个色值,等于把「时间」压进
542
+ 「颜色」——而颜色的辨识预算还要同时装领域语义和选中/命中,挤爆是结构性的。
543
+
544
+ 双栏之后这事根本不用争:**"在哪一栏"已经把增和删说完了**。色相退成冗余加强,而冗余
545
+ 加强正是红绿唯一安全的用法。但光靠"可以用"还不够,配色本身也得对红绿色弱(约占男性
546
+ 8%)负责,所以三档是按**明度**排的:
547
+
548
+ | | 墨 | 明度 |
549
+ |---|---|---|
550
+ | 删(只在左栏) | 深红 | **最暗** |
551
+ | 增(只在右栏) | 偏青的绿 | 中间 |
552
+ | 改(两栏都标) | 浅黄 | **最亮** |
553
+
554
+ (具体色值在 `DIFF_INK` 里,随时可调;CSS 的 fallback 和 demo 图例都从那一处现取。)
555
+
556
+ 三件事叠起来:**栏位**让红和绿永远不并排(一栏内只需分辨「删 vs 改」或「增 vs 改」);
557
+ **绿往青里偏**让右栏那对落在红绿色弱保留的青-黄轴上;**红压深、黄提浅**让左栏那对拉开
558
+ 明度。一句话:色相负责好看,明度和栏位负责说清楚。
559
+
560
+ 两栏都**不去色**:左栏就是旧版本身、右栏就是新版本身,各长各的样子。`diffStyle` 因此
561
+ 一条领域规则都不覆盖,只把选中/命中抬回最上面。
562
+
563
+ 覆盖层画在 canvas **下面**(cytoscape 的 canvas 是 z-index 1–3 且透明),所以 diff
564
+ 不覆盖用户图元的一个像素。整层只有**个位数个 DOM 元素**:同色同档的圆角矩形和曲线拼进
565
+ 同一个 `d`,一条 path 画完一类。**没有常驻闪烁**——它无论画在哪都要付全视口的每帧代价,
566
+ 而且一半时间在藏信息,而双栏要的正是"一起看"。
567
+
568
+ #### 变更有多大:三档强度
569
+
570
+ `NodeChange.amount`(0–1)给光圈分三档半径。它只对**两版都有**的节点有定义——增和删是
571
+ 存在性的,一个节点要么在要么不在,没有"存在了三成"这回事,所以它们恒为最高档。
572
+
573
+ 算法是**真编辑距离**,但有两个约束让它跑得起来(实测 96 处变更 12ms):
574
+
575
+ - **只比变了的那几个字段**,两边各拼成一个串比**一次**。逐字段比的话,一个 22 字段的
576
+ 节点就是 22 次 DP,上百个节点直接进十亿量级。
577
+ - **逐字比到 512 字为止**,再长的部分整段算不同。一次比较因此恒为 `O(CAP²)`,跟 `data`
578
+ 里那坨东西有多大无关。
579
+
580
+ 归一化**跨节点**:除以全图最大值,**不做任何提亮**。不是"占它自己字段数的比例"——后者
581
+ 会把"22 个字段里只改了一个"一律算成 4.5%,那样同一步里谁重谁轻就分不出来了。也试过开方
582
+ 压长尾,但那是在替看图的人撒谎:只改了一个 `dependencies` 的节点**本来就该很微弱**。
583
+ 实测「依赖分析」那一步 41 处变更里 **34 处落在最低档** —— 那正是它该有的样子。
584
+
585
+ **一档同时驱动半径和浓度**,只动半径的话三档看着差不多。最低档故意很弱,但不是零:
586
+ 强度是用来**排序**的,凑近了还得看得见。
587
+
588
+ **分档不连续**,两个理由都很实在:同色同档拼成一条 path,整层 DOM 个数才跟图的大小
589
+ 无关;而人眼本来也比不出连续的半径差。
590
+
591
+ #### 包含边:只在「它是唯一信源」时才标
592
+
593
+ 包含边不是数据,是 `parent` 的投影。所以问题不是"它变了没有",而是**这句话有没有别人
594
+ 在说**:
595
+
596
+ | | 谁在说 | 边标不标 |
597
+ |---|---|---|
598
+ | 节点新增 / 删除 | 节点自己的晕染已经说完了 | **不标**。边长面积大,说两遍会把节点那句盖掉 |
599
+ | **换了树杈** | **没有别人在说** —— 两版都在、都亮着"变了",唯一的差别就是它挂在谁下面 | **必须标**:左栏那条红、右栏那条青 |
600
+
601
+ 左右两栏的标记方向是反的,所以 `buildElements` 有个 `past` 开关:`prevParent` 的语义
602
+ 始终是"**另一版**里它挂在谁下面",开关说的是这一版是哪一版。左栏那条**照样受力**——它
603
+ 就是旧版的结构;只有"另一版那条"是合成出来给它演一次退场的,不进任何一次求解。
604
+
605
+ #### 把它读回来
606
+
607
+ ```tsx
608
+ <GraphCanvas onTransition={(r) => console.log(r)} />
609
+ // { total, moved, movedMedian, entering, leaving, relocated, converging,
610
+ // edgesIn, edgesOut, layoutMs, animated }
611
+ ```
612
+
613
+ 动画没法回放着看。这份读数就是它留下的凭据。**看 `movedMedian`,别看 `moved`**:
614
+ 后者是个超过小阈值就计数的数,一次几个单位的沉降它也报"全体都动了",什么也说明不了。
615
+
616
+ ### 3. 图层与 2.5D
617
+
618
+ `profile.layers` 声明有哪些层。`structural: false` 的层是**依附层**:不进结构受力,
619
+ 布局完按关联重心摆放(典型:公理层 / 参考层)。
620
+
621
+ 多层的图上,"看哪几层"和"怎么摆"是两件事:
622
+
623
+ - **叠层**(缺省;`planes` 不给或 `true`):任选几层(至少一层,全选就是 `layers: null`),
624
+ 叠成上下几层——多层的数据,第一眼该看到的是"它有几层、层与层怎么连"。上下顺序由数据定
625
+ (`layers` 的声明顺序 / `z`),界面上不提供调。
626
+ - **不叠**(`planes: false`):恰好一层,铺平(`layers: ['req']`)。关掉叠层时留下选中的
627
+ 最靠前那一层,没选过就是第一个结构层。
628
+
629
+ 没有"几层压在一个平面上":依附层就摆在它关联的那些点正上方,压平了就是一层盖住另一层。
630
+ 工具条上对应的是一排层名加一个「叠层」开关:关着时层名是单选,开着时是多选。
631
+
632
+ ```
633
+ x' = x + t·(y·shear + z·dx)
634
+ y' = y + t·(y·squash − z·gap − y)
635
+ ```
636
+
637
+ cytoscape 是严格 2D 的,但坐标是库自己算好后灌进去的(preset 布局),所以分层不需要
638
+ 换渲染器。层间边自然变成近似垂直的连线。仿射对 `t` 是线性的,所以"一层 ↔ 叠层"**从不
639
+ 重算**:布局只有一份,切换就是 `t` 从 0 走到 1(或者走回来),进来的层连同它的底板淡入、
640
+ 出去的淡出。每层的高度是固定的,收起中间一层就留一个空档,不会让别的层上下挪。
641
+
642
+ 几个不写死的地方:
643
+ - **底板一样大**:每块都是所有层的并集外框。上下对齐,上一层的点才读得出"悬在下一层
644
+ 哪一片的正上方";各量各的话,稀的那层板子小一圈、还错开。
645
+ - **层间距按图的实际尺度推**(不给 `gap` 时 = 最高一层的 1.35 倍)。写死常数在小图上
646
+ 刚好、在几千节点的大图上两层就叠在一起了。
647
+ - **底板画在图下面,层名画在图上面**——两者都是 `absolute inset:0`,靠 DOM 顺序和
648
+ z-index 分开;层名压在底下会被节点遮掉。
649
+ - **fit 要把底板并进去**:`cy.fit` 只认节点,而底板按设计外扩于节点范围。
650
+ - 分层模式下不做子视图收紧(会把节点推离所属平面)。
651
+
652
+ ### 4. 布局
653
+
654
+ 只有一个布局:`cose-bilkent`(柔性)。画笔、墨量守恒、可读性场都是按它调的;视图和布局
655
+ 是绑在一起的,要加新的看法是连同它的布局一起加,不是再给一个下拉框。**布局不由 profile
656
+ 定制**——参数可以含逐元素受力函数,过不了 worker 边界。
657
+
658
+ 流程:切组件 → 各组件并行布局 → 依附层摆放 → 粗图二次布局(组件当超级节点)→ 平移
659
+ 拼装。坐标按内容 hash 缓存进 localStorage,刷新秒开。2.5D 投影在画布那边按 `t` 现做。
660
+
661
+ **执行通道**(`pool`)有两个,跑的是同一份计算体,结果一致:
662
+
663
+ | | 用在哪 |
664
+ |---|---|
665
+ | `inlinePool`(**默认**) | 任何环境。离线 `file://` 页面**必须**用它——那里浏览器直接禁用 `Worker` |
666
+ | `workerPool` | 宿主有打包器时(Next/webpack、Vite),多核并行、主线程不卡 |
667
+
668
+ ```tsx
669
+ import { workerPool } from 'kglens/layout/worker-pool';
670
+ <GraphCanvas model={model} pool={workerPool} />
671
+ ```
672
+
673
+ 库默认选"永远能用"的那个,不去猜宿主的打包器。
674
+
675
+ ---
676
+
677
+ ## 写一个 profile
678
+
679
+ 三档递进,缺什么补什么,没填的字段自动落到通用缺省:
680
+
681
+ **① 什么都不给** —— 吃 `{nodes, edges}`,单层。整张图画成一棵骨架(见[配色](#配色色相来自配置其余由数据算))。
682
+
683
+ **② 给个对象** —— 加自己的图层与配色:
684
+
685
+ ```ts
686
+ const profile = defineProfile({
687
+ id: 'flow',
688
+ layers: [
689
+ { id: 'ui', label: '界面', z: 0 },
690
+ { id: 'data', label: '数据', z: 1, structural: false, color: '#14b8a6' },
691
+ ],
692
+ layerOf: (n) => (n.kind === 'table' ? 'data' : 'ui'),
693
+ nodePalette: { table: '#10b981' },
694
+ kindLabels: { table: '数据表' },
695
+ detail: { list: [{ key: 'columns', label: '字段' }] },
696
+ });
697
+ ```
698
+
699
+ **③ 给解析器** —— 让库直接吃自家的 json 方言,不必先转换:
700
+
701
+ ```ts
702
+ defineProfile({
703
+ id: 'x',
704
+ parse(origin, text) {
705
+ const raw = JSON.parse(text);
706
+ if (!raw.steps) return parsePhysical(origin, text); // 不认就交回通用解析
707
+ return { origin, title: raw.name, nodes: /* … */, edges: /* … */ };
708
+ },
709
+ merge(slices) { /* 需要跨文件合成骨架时才写;缺省是同 id 首见为准 */ },
710
+ });
711
+ ```
712
+
713
+ 完整可参照的实例:`examples/kg-profile.ts`(四种方言 + 脊柱折叠 + 两层 + 领域校验),
714
+ 它在**库外**——这就是"库不绑死项目"的可执行证据。
715
+
716
+ ### profile 全部字段
717
+
718
+ | 字段 | 缺省 | 说明 |
719
+ |---|---|---|
720
+ | `parse(origin, text)` | `parsePhysical` | 返回 `null` = 不认这份数据(静默跳过,不算损坏) |
721
+ | `merge(slices)` | 同 id 首见为准 | 需要跨文件合成骨架时才写 |
722
+ | `layers` | 单层 | `{ id, label, z?, color?, structural? }` |
723
+ | `layerOf(node)` | `node.layer` | |
724
+ | `nodePalette` / `edgePalette` | `{}` | 语义 `kind → 颜色`;没列进来的 kind 就是骨架 |
725
+ | `nodeSize` / `edgeWidth` | `{}` | `kind → 倍数`:乘在数据算出的直径 / 粗细上;没列的是 1。纯外观,布局不让位 |
726
+ | `placeholderFlags` | `[]` | 带这些 flag 的节点是占位,画成骨架 |
727
+ | `style` | `[]` | 逃生舱:颜色说不了的(形状、虚线),追加在调色板之后 |
728
+ | `nodeClass` / `edgeClass` | kind | 额外的 cytoscape class |
729
+ | `kindLabels` | `{}` | 详情面板标题 |
730
+ | `detail` | `{}` | `line` / `list` 字段表、`skip`、`flagNotes`、`linkify` |
731
+ | `validate(model)` | 无 | 领域校验(**通用的悬空边 / 重复 id / 重复的边库自带,别重复写**;一条边由两端 + kind 认定)。每条 `GraphIssue` 可以带 `group`(这一类叫什么),校验面板按它分组 |
732
+ | `layoutEdge(edge)` | 都不参与 | `true` = 这条语义边**也参与布局受力**。包含关系(`parent`)永远是结构,不走这里。缺省不参与:几百条跨枝的线一受力,树就被拉成一团 |
733
+ | `singleRoot` / `rootLabel` | `true` / `Overview` | 多顶层时合成虚拟根盒子。根只住在第一个结构层、只收这一层的顶层;图里一条包含关系都没有时不合成 |
734
+
735
+ ### 保留字
736
+
737
+ 节点 `kind` 请避开这些 class:`container` `crosslayer` `contains` `root`
738
+ `gk-node` `gk-hit`,以及 diff 的标记 `gk-added` `gk-removed` `gk-changed` `gk-moved`
739
+ `gk-merged` `gk-kept`。虚拟根的 id 是 `__gk_root__`。
740
+
741
+ ---
742
+
743
+ ## 配色:色相来自配置,其余由数据算
744
+
745
+ 节点一律平权:容器和功能点的区别只有"是什么"和"底下挂了多少",各占一个通道。
746
+
747
+ - **颜色 = kind。** 一个 kind 一个平涂色(`profile.nodePalette`),不随大小变。没进调色板
748
+ 的 kind(容器、虚拟根、占位)是**默认节点**:它们就是骨架本身,所以走 `theme.skeleton` 的
749
+ 色阶——挂得越多越亮,跟同一层的包含边一个色系。
750
+ - **大小 = 同一个保底 + log(底下的叶子数)**,封顶 1.8 倍——看得出来,不抢戏;有内容的节点
751
+ (kind 进了调色板的)保底再 ×1.5,主角是内容,默认节点是底。同一个数
752
+ 也决定标签字号(12–15px)和谁先抢到位置。
753
+ - **结构的主次交给边。** 包含边用 `theme.skeleton` 的整条色阶:主干深而粗、叶子浅而细
754
+ (盒子模式下是嵌套本身)。语义边每种一个色(`edgePalette`),粗细和线的透明度跟 `weight`;
755
+ 每种还能整类放大缩小(`nodeSize` / `edgeWidth`,倍数,乘在数据算出的大小之上)。形状、线型、端头是
756
+ "这类东西是什么"的语义编码,写在 `style`。
757
+
758
+ 所以只有一个结构色要配,没配置的图也完整,列进调色板的 kind 才"长出颜色"。占位(结构里
759
+ 声明了、内容还没填)是默认节点,不是它那个 kind 的浅色版——把它的 flag 写进
760
+ `placeholderFlags`;等它被填上,切版本时就是一次默认色 → kind 色的换皮。浅端从
761
+ `theme.canvas` 混出来,换深色主题自动跟着对。
762
+
763
+ 换 `theme`、调色板或 `placeholderFlags` 都只换样式表,不重建、不重排。宿主别往元素上写
764
+ 行内样式——那是画布的过渡通道在用的。图例用 `skeletonColor(theme, share)` 和
765
+ `defaultNodeColor(theme, share)`,拿到的就是图上那两样。
766
+
767
+ ## 大图里的点和边
768
+
769
+ 浏览模式下,屏幕上的点和边不由 cytoscape 画,由 `src/paint.ts` 画:cytoscape 照旧管数据、
770
+ 样式表、布局、事件和过渡,画笔只读它算好的值,按颜色批量画出来;鼠标命中也换成直接算点到
771
+ 点、点到线的距离。三千个点的图上,一下鼠标从几百毫秒降到十几毫秒。对比模式、关掉 `readable`
772
+ 时一切照 cytoscape 原样。
773
+
774
+ 缩放下怎么画,四条规则:
775
+
776
+ - **骨架跟着几何走。** 点的直径、包含边的粗细都随缩放成比例变。小到画不出来时不再缩,改成
777
+ 变淡——屏幕上的"墨"跟真实分量成正比,密处自然深、稀处自然淡,一个元素都不丢。包含边远看
778
+ 另有一条按分量给的下限:主干远看也有几像素,叶子那一级退成淡线。点也一样:叶子画得比 4px
779
+ 还小以后(只有大图会缩到这么远),挂得多的点按分量少缩,挂满的就停在那一刻的大小——远看
780
+ 主次还在,小图适配窗口时大点只略大一点。
781
+ - **语义边是发丝线。** 缺省 1px,不随缩放变粗(weight 和 `edgeWidth` 的倍数按比例加粗);浓度由 `semanticOpacity`(缺省 0.5)给,缩远了
782
+ 再按缩放淡下去。虚线和箭头只在近看时画。
783
+ - **画的先后就是层级**:容器盒 → 淡雾 → 边(按样式表的 z-index,语义边在包含边之上)→ 点。
784
+ - **点只看它在屏幕上多大**:很小时脚下铺一层同色淡雾(远看一簇簇有体量),雾淡出的同一段里
785
+ 每个点外长出一圈画布色的间隙(一颗颗分开,不粘成块),再大就是实点。
786
+
787
+ 鼠标命中跟画用同一套数:点按画出来的大小算;边的命中带 =(命中宽 + 线宽)× 墨量守恒给它的
788
+ 透明度,连续变窄;窄到不足 1px(鼠标落点是整像素,分辨不出更细的)就不算。悬停那一跳的语义边
789
+ 按条数守恒:几条以内是实线,再多每条按 √(几条 / 条数) 淡下去,一大把连线是有疏有密的扇子。
790
+ 悬停时被悬停的那个点的字一定显示,那一跳其余的字加分排在前面、挤不下的照常让位,不会一大簇
791
+ 硬挤成一坨。
792
+
793
+ 样式表里的宽度、粗细仍是图上单位;数值和理由在 `paint.ts` 顶上。
794
+
795
+ ## 大图里的字
796
+
797
+ 浏览模式下,节点的字画在叠在 cytoscape **上面**的一层 canvas 里,所以字永远在任何点
798
+ 之上(cytoscape 是逐个元素"先点后字"画的,后画的点必然盖住先画的字,样式表怎么排都救
799
+ 不回来)。哪些字显示是按分数(`share` + 离视口焦点多近)贪心占位,分高的——挂得多的
800
+ 大节点——先挑:一个字只有在不跟别的字重叠、**也不压住任何有名字的点**时才显示;挂在点
801
+ 下面放不下就依次试上、右、左。没名字的小点可以被字盖住,这样缩得很小也有足够的字;被盖住
802
+ 的点自己就不再出名字。缩小看主干,放大看叶子。字底染一层节点自己的颜色,字和点一眼对得上。
803
+ 字号是屏幕常量,所以每个字(连同它的晕)只栅格化一次,之后每帧贴图。
804
+ 名字超过 16 个字号宽(约 16 个汉字 / 28 个字母)就截断加"…",不换行:一行长句压在图上像段落,
805
+ 两行又成了一块字框。全名在详情栏和搜索下拉里。布局量字框用的也是截断后的宽度(样式表
806
+ `text-max-width`),判的、排的、画的是同一个框。
807
+ `labelSpacing`(缺省 6px)是字与字之间的最小缝,越小越密。对比模式两栏各排各的字(同一套规则,各自一层画布),有变化的节点(新增、删除、改了内容、换了
808
+ 位置)加分排在前面。字上也带着修订模式的记号:删除线 = 删除(只在左栏)、下划线 = 新增;线染变更色,跟图例、光圈
809
+ 同色。改了内容、换了位置不标。两栏各判各的,所以同一个没变的节点偶尔一边有字一边没有——两栏合着排一次是
810
+ 以后的事。
811
+
812
+ ## 悬停、选中、深色
813
+
814
+ 悬停和选中是两个正交的通道,可以叠加:
815
+
816
+ - **悬停 = 注意力,临时。** 一个点、它的一跳邻居和相连的边名字强制显示、去掉半透明,语义边
817
+ 加粗;其余压暗——选中的点也照常被压暗。悬停一条边:它和两端的点。渐入渐出(约 160ms),
818
+ 在点和点之间划过不闪。悬停不改任何元素的样式:画的时候整张图乘一个透明度,关注到的一跳在
819
+ 上面原样再画一遍。只在浏览模式(diff 只压暗一栏,"没变的东西在两栏是同一个像素"就不成立了)。
820
+ - **选中 = 身份,持久。** 它不压暗任何东西,只把"这一个"标出来:一圈从外面收拢进来的强调
821
+ 色环,画在 cytoscape 上面的字那一层——所以悬停把底下压暗时,它照样醒目。
822
+ - **语义边画在包含边之上**:结构是底,画上去的在上层。
823
+ - 开合详情栏、改窗口大小,**相机不动**:画面正中的那一点仍在正中,缩放不变。只有第一次
824
+ 拿到尺寸时取一次全景。
825
+ - **深色**:传 `theme={DARK_THEME}`,再覆盖 `--gk-*` CSS 变量。不靠透明度凑——默认节点和
826
+ 包含边的色阶从 `theme.canvas` 混出来,换了底自动跟着对。2.5D 的层色也只给色相,底板由
827
+ `plateColors` 从画布色混出来。
828
+
829
+ ## 主题
830
+
831
+ cytoscape 用 canvas 渲染,读不到 CSS 变量,所以图元主题是一个对象(`GraphTheme`,
832
+ 传给 `<GraphCanvas theme>`)。宿主 UI(工具条 / 详情面板)则是普通 DOM,走 `--gk-*`
833
+ CSS 变量,宿主覆盖即可换肤;不覆盖也有完整缺省值,所以离线单文件页面开箱好看。
834
+
835
+ **调色板只配一份,按浅底配。** 深底上每个颜色过一遍 `themeColor(theme, hex)`:在 OKLCH 里把
836
+ 明度按"离画布多远"对折——`L' = lc + (1−L)(1−lc)`,`lc` 是画布的明度——色相不动,彩度按"占这个
837
+ 明度下能有的最大彩度的几成"带过去。一条式子管所有颜色、没有阈值,所以明暗先后两边整个倒过来:
838
+ 浅糖果色到深底上是同色相的暗色,浅底上最醒目的黑到深底上是最亮的。暗下去的黄是棕(暗的黄本来
839
+ 就是棕)。对折是一一映射,`untheme` 能反解:深色下取色器里显示的就是图上画的,存的是浅底那一份
840
+ (选白、显示白、存黑);深底上选的浅而鲜的颜色存回去是近黑,十六进制在那一段分辨率粗,再显示出
841
+ 来会差几个单位。
842
+
843
+ **长文本**(详情里节点的 `description`、列表字段)按 markdown 渲染:段落、列表、强调、代码、链接、图片,
844
+ 直接产出 React 元素——数据里写的 HTML 一律当文字。外部链接新窗口打开;`node:<id>` 链接飞到那个节点
845
+ (profile 的 `linkify` 可以把引用改写成这种);相对路径经 `resolveUrl(url, node)` 补全,从文档抽出来的图片
846
+ 就能显示。宿主有自己的渲染器就传 `renderText`。
847
+
848
+ **检查器**(详情、编辑)从右边滑进来;`--gk-inspector-bg` 让它跟宿主的侧栏同色。窄的画布上它是一张从底下
849
+ 拉起来的卡,工具条撑满一行。
850
+
851
+ **文案。** 库自己画的每一个字都在一个对象里,缺省英文;传 `strings`(整份或几个键)就换掉,
852
+ 跟 AG Grid 的 `localeText`、MUI 的 locale 一个路数:画布里不放语言开关,那是宿主的事。
853
+ `examples/strings-zh.ts` 是一份完整的中文,也是写别的语言的样板。画布上常驻的字只来自数据;库自己的
854
+ 字只出现在悬停提示、弹层和检查器里。数据里的字(节点名、层名、kind 的名字、校验消息)归数据和 profile。
855
+
856
+ ```tsx
857
+ import { ZH_CN } from './strings-zh'; // 从 examples/ 拷过去
858
+ <GraphCanvas strings={ZH_CN} />
859
+ ```
860
+
861
+ ## 画布上的常驻工具
862
+
863
+ 只有三样,按"人什么时候要它"摆:左上是搜索(`/` 或 ⌘K)和层的切换(多层的图才有),
864
+ 不常动的(只看某个来源;可编辑时的新增节点 / 新增连线)收在「更多 ⋯」里、没东西就不出;右下是相机
865
+ (放大、缩小、适应窗口,也可以按 `+` `-` `0`),旁边是校验。布局、盒子/连线、折叠层数、
866
+ 重算都不在画布上——那些是开发者在代码里定的事,不是看图的人每天要按的按钮。
867
+
868
+ **校验**是派生出来的(`validateModel` = 库的通用检查 + `profile.validate`),一个总是很大的
869
+ 数字等于墙纸,所以:钮上只报最要紧的那一级——有错误报错误数(红),没有才报提醒数(淡);
870
+ 点开先按 `group` 列出"是什么、几条",再点开那一类看条目;点一条带节点的,选中并飞过去。
871
+
872
+ `controls` 可以逐个关掉宿主已有等价入口的分区,避免两个真相:
873
+
874
+ ```tsx
875
+ // 平台里左侧文件树已经是"来源/子图"的选择器,画布上就别再放一个下拉
876
+ <GraphCanvas controls={{ origins: false }} />
877
+ ```
878
+
879
+ 分区:`search` `origins` `layers` `zoom`。
880
+
881
+ ## 交互
882
+
883
+ - 滚轮 / 双指 = 平移;Ctrl(⌘)+滚轮 或捏合 = 光标处缩放(同 Figma / tldraw)
884
+ - 悬停 = 瞄一眼:亮出它和它的一跳,移开就没
885
+ - 单击节点 = 选中:详情面板和选中环;点空白 = 取消
886
+ - **双击节点 = 放大到它**(地图软件的习惯):相机框住它和它的一跳。只动相机,"看什么"一样
887
+ 没变,所以没有什么要退出的
888
+ - 详情栏打开时,点过的那个点在屏幕上不动(只有会被详情栏盖住时才挪出来),所以双击的
889
+ 第二下还点得中
890
+ - `/` 或 ⌘K = 搜索;↑↓ 挑着看(相机跟过去),回车选中,Esc 清除
891
+ - 更多 ⋯ → 来源 = 只看一个文件。筛着的时候工具条旁边有一枚标签,× 一下回到全部。视图里
892
+ 指向这份数据没有的文件就当没给,所以换数据永远不会筛成白屏。叠层时底板收拢到看得见的
893
+ 那一片,被筛空的层不画板子
894
+
895
+ ## 编辑
896
+
897
+ 传了 `onEdit`,图就能编辑;不传,画布上一点都不变。新建刻意放得不显眼——**更多 ⋯ →
898
+ 新增节点… / 新增连线…**——改和删在对象身上:详情面板多一个**编辑**,原地变成表单。
899
+
900
+ 库不碰你的模型,也不碰文件。每一处修改是一条 `EditOp`:你落到自己的模型上、把新模型传回来,
901
+ 普通的过渡就把它演出来:
902
+
903
+ ```tsx
904
+ const [ops, setOps] = useState<EditOp[]>([]);
905
+ const model = useMemo(() => applyEdits(base, ops, profile).model, [base, ops]);
906
+ <GraphCanvas model={model} profile={profile} onEdit={(op) => setOps([...ops, op])} />
907
+ ```
908
+
909
+ 这串 op 就是一份 **patch**,它一身三用:撤销(去掉最后一条、重放)、草稿、导出——源数据有几个
910
+ 文件都一样,导出永远是一份小文件。流水线重新生成源数据之后再重放一遍,人工的修改不丢;落不下去
911
+ 的那几条跳过并报出来,不中断。
912
+
913
+ 哪些能改、怎么改:
914
+
915
+ | | 字段 | 由谁把关 |
916
+ |---|---|---|
917
+ | 界面约束 | `id`(新建时填、当场查重、建好后不变)、挂在谁下面、边的两端 | 输入框和节点选择器(边打边搜),结果一定合法 |
918
+ | 自由内容 | `label`、`kind`、`data`;边的 `kind` / `label` | 一个 JSON 框——用 `renderEditor` 换成你自己的编辑器 |
919
+ | 不能改 | 层的定义和节点归哪层(跟着挂在的那个节点,profile 按字段算的话以它为准)、`origin`(正按来源筛着就归那个来源,否则跟着它爹)、flags、校验结果、虚拟根 | —— |
920
+
921
+ 只能删叶子,连着它的边一起走(确认里说清几条)。对比模式只读。`checkEdit(model, op)` 告诉你
922
+ 一条 op 为什么落不下去;`toPhysical(model)` 把整张图写回通用的 `{nodes, edges}`。
923
+
924
+ ## 踩过的坑(改这个库之前先读)
925
+
926
+ cytoscape 有几处行为不符直觉,库里都绕过了,别改回去:
927
+
928
+ - **父节点 `display:none` 会把整棵子树一起隐掉。** 所以可见性闭包必须闭到**元素层**
929
+ 的父链(含合成的虚拟根),只闭模型里的 `parent` 会让整张图变空白。
930
+ - **`visible()` / `:visible` 有缓存**,刚改完 `display` 立刻查会拿到上一轮的结果。
931
+ 一律以 `resolveView` 的结果为准,不要用 `:visible` 选择器。
932
+ - **`eles.layout()`(作用在子集上的布局)开 `animate:true` 会静默地什么都不做。**
933
+ 用 `animate:false` 同步落位,再单独动画视口。
934
+ - **布局刚落位时包围盒缓存还是旧的**,要等一帧再 `fit`。
935
+ - **`<svg>` 是替换元素**,只给 `position:absolute; inset:0` 会退回 300×150 的固有
936
+ 尺寸,必须显式 `width:100%; height:100%`。
937
+ - **容器判断不能问 cytoscape**(`isChildless()`):连线模式下父子是显式边不是
938
+ compound,它会对所有节点都返回 true。用 `buildElements` 返回的 `containers`。