Skip to content

World's first open-source enterprise world model.

17.2 KB
Raw Blame
// 两块画布共用的那台机器(#496)。
//
// `/graph` 画实例与事实,本体页画类与关系。它们的**数据**不共享,语义也不共享,
// 但把数据变成一块能看能点的画布的那套东西是同一份:节点程序的四层解剖、标签
// 何时出没、悬停卡、状态表、相机、拖拽。从前这些在两个文件里各写一遍,字面
// 相同——连解释标签阈值为什么是 5 和 0.8 的那段注释都是逐字两份。代价不是行数,
// 是**会走样**:压暗系数一边 0.52 一边 0.55,谁也不知道哪个是对的。
//
// 分界线:这个文件管「怎么画、怎么动」,页面管「画什么」。页面把自己的数据投影
// 成一张 graphology 图,给每个节点一个类型色,再说清楚哪些该藏;其余的在这里。
//
// `graphVisuals.ts` 是上一轮抽出来的常量与绘制函数,这个文件建在它上面。

import type Graphology from "graphology";
import Sigma from "sigma";
import type { Settings } from "sigma/settings";
import { createNodeBorderProgram } from "@sigma/node-border";

import { NodeSquareShellProgram } from "./squareShellProgram";
import {
  CANVAS_FONT,
  CANVAS_LABEL_SIZE,
  CANVAS_TEXT,
  CANVAS_TEXT_2,
  drawHoverCard,
  drawNodeLabel,
  HOVER_MUTE,
  lerpColor,
  mix,
  MUTED_SHELL,
  NODE_CORE_BASE,
  NODE_SHELL_BASE,
  RING_HOVER_MIX,
  RING_SELECT_MIX,
  TRANSPARENT,
  INK,
} from "./graphVisuals";

/* ============ 节点程序 ============ */

/** Semantica 节点解剖:状态环 → 描边 → 深色壳 → 微彩核心。
 *
 * 两页同一份。从前默认那一种在 `/graph` 叫 `shell`、在本体页叫 `circle`,
 * 而它们是同一个 `createNodeBorderProgram`——两个名字说的是同一件事 */
export const NODE_TYPE_SHELL = "shell";
export const NODE_TYPE_SQUARE = "square";

/* ---------- 高亮的边画在最上层 ---------- */

/** 「最上层」那一批的类型名后缀 */
const TOP = "Top";

/** 一条边高亮时该用的类型名。
 *
 * **`zIndex` 在这里不管用。**sigma 一个程序一批绘制,`zIndex` 只在批内排序;
 * 跨程序谁先谁后,看的是 `edgeProgramClasses` 里键的顺序。于是选中一个节点
 * 之后,它那几条亮线照样会被别的程序里压暗的边切断——放大看就是白线被一条条
 * 细黑条切开。
 *
 * 解法是把同一个程序**注册两遍**(见 `withTopLayer`),高亮的边整批走后注册的
 * 那一份,最后画。两页都踩过这个坑:图谱页先解的,本体页后来又踩了一遍——
 * 所以它收在这里,不在任何一页里。 */
export function drawLast(type: string): string {
  return type.endsWith(TOP) ? type : type + TOP;
}

/** 给一份边程序表配上「最上层」的那一份:同样的程序,键排在后面。
 *  高亮时把 `res.type` 换成 `drawLast(res.type)` 就落进这一批。 */
export function withTopLayer<T>(programs: Record<string, T>): Record<string, T> {
  return {
    ...programs,
    ...Object.fromEntries(
      Object.entries(programs).map(([name, program]) => [drawLast(name), program]),
    ),
  };
}

export const NODE_PROGRAMS = {
  [NODE_TYPE_SHELL]: createNodeBorderProgram({
    borders: [
      { size: { value: 0.1 }, color: { attribute: "ringColor" } },
      { size: { value: 0.07 }, color: { attribute: "borderColor" } },
      { size: { value: 0.3 }, color: { attribute: "shellColor" } },
      { size: { fill: true }, color: { attribute: "color" } },
    ],
  }),
  [NODE_TYPE_SQUARE]: NodeSquareShellProgram,
};

/* ============ 构造选项 ============ */

/** 两页真正不同的那几项。其余一律在 `sigmaOptions` 里定死——它们决定画布
 *  长什么样、怎么响应,两页长得不一样就是 bug 而不是特性 */
export interface CanvasOptions {
  /** 边的类型名到程序的映射。`/graph` 只有直线与弧,本体页还要箭头 */
  edgeProgramClasses: Settings["edgeProgramClasses"];
  defaultEdgeType: string;
  /** 相机能缩到多远、放到多近。两页的图规模差几个量级,取景范围本就不同 */
  minCameraRatio: number;
  maxCameraRatio: number;
  /** 边上写不写字。`/graph` 的边是谓词,要写;本体页只有关系边写 */
  renderEdgeLabels?: boolean;
  minEdgeThickness?: number;
}

/** `new Sigma(g, el, { ...sigmaOptions(...), nodeReducer, edgeReducer })`。
 *
 * **两个 reducer 不从这里过。** sigma 的 reducer 类型跟着它自己的泛型参数走,
 * 中转一手就把推断掐断了;而 reducer 的**内容**本就是两页各自的事,共用的是
 * 它们调用的那张状态表(下一节),不是函数本身。
 *
 * 标签按距离出没——离得远只看形状,走近了才认名字。**试过不按距离**
 * (阈值归零、只按拥挤程度筛):缩远之后一百多个名字铺开互相压字,读不出也
 * 点不准。阈值 5、每 130px 见方留 0.8 个:只比原先松半档。**放宽到 3 / 1.2
 * 试过一轮,一屏上百个名字铺开,太吵**——这里要的是「远处认得出几个地标」,
 * 不是「每个点都报名字」。放大时 sigma 自己按 1/ratio² 放开这个上限
 * (见 `getLabelsToDisplay`),越走近露得越全,不封顶。
 *
 * 边的字与节点同一档(fine)、同一个次要色。从前是 9px/#a1a1a1——9 比界面里
 * 最小的字还小一半,而 #a1a1a1 是上一版的 ink-2。
 *
 * 边的悬停事件默认是关的,这里一律开:两页都靠 `enterEdge` 让边说话。 */
export function sigmaOptions(o: CanvasOptions) {
  return {
    /* **按层级画**。两个 reducer 一直在设 `res.zIndex`(压暗 0、邻居 2、
       选中 3、指到 4、高亮的边 5),可 sigma 默认不看它——绘制顺序就是缓冲区
       顺序,于是一条高亮的白边会被后画的暗边一段段切断,看着像被虚线打断。
       打开它,那些层级值才真正生效。代价是每帧多一次排序,几百条边这个量级
       可以忽略 */
    zIndex: true,
    allowInvalidContainer: true,
    defaultNodeType: NODE_TYPE_SHELL,
    nodeProgramClasses: NODE_PROGRAMS,
    edgeProgramClasses: o.edgeProgramClasses,
    defaultEdgeType: o.defaultEdgeType,
    enableEdgeEvents: true,
    renderEdgeLabels: o.renderEdgeLabels ?? false,
    ...(o.minEdgeThickness === undefined
      ? {}
      : { minEdgeThickness: o.minEdgeThickness }),
    labelFont: CANVAS_FONT,
    labelSize: CANVAS_LABEL_SIZE,
    labelColor: { color: CANVAS_TEXT },
    labelRenderedSizeThreshold: 5,
    labelDensity: 0.8,
    labelGridCellSize: 130,
    minCameraRatio: o.minCameraRatio,
    maxCameraRatio: o.maxCameraRatio,
    edgeLabelSize: CANVAS_LABEL_SIZE,
    edgeLabelColor: { color: CANVAS_TEXT_2 },
    edgeLabelFont: CANVAS_FONT,
    defaultDrawNodeLabel: drawNodeLabel,
    defaultDrawNodeHover: drawHoverCard,
  };
}

/* ============ 状态表 ============ */

/** reducer 收到的属性袋与它要交回去的那一份。sigma 的类型在这一层是 `any`,
 *  两页各自的属性键也不一样,所以这里只认「一袋东西」 */
export type NodeAttrs = Record<string, unknown>;

/** 状态环取节点**自己的类型色**,不取已经混过壳色的 `color`——见 graphVisuals
 *  里 RING_*_MIX 的说明 */
export function ownColorOf(attrs: NodeAttrs): string {
  return (attrs.typeColor as string) ?? NODE_CORE_BASE;
}

/** 压到底:其余都退场,只留形状。
 *
 * 系数从前两页不一样,0.52 与 0.55,没有一处说明为什么。设计表里写的是 0.52,
 * 这里按它统一——那个 0.55 是抄的时候走的样,不是谁定的 */
export const MUTE_SCALE = 0.52;

export function mutedNode(res: NodeAttrs, base: number): NodeAttrs {
  res.size = base * MUTE_SCALE;
  res.color = mix(MUTED_SHELL, NODE_CORE_BASE, 0.3);
  res.shellColor = MUTED_SHELL;
  res.borderColor = TRANSPARENT;
  res.ringColor = TRANSPARENT;
  res.label = "";
  res.zIndex = 0;
  return res;
}

/** 悬停时其余的按 `HOVER_MUTE` 压一档(选中是压到底)。
 *  邻居不压——悬停要回答的是「它连着谁」,把邻居也压掉就等于没回答 */
export function softMutedNode(
  res: NodeAttrs,
  attrs: NodeAttrs,
  base: number,
): NodeAttrs {
  res.size = base * (1 - (1 - MUTE_SCALE) * HOVER_MUTE);
  res.color = lerpColor(
    String(attrs.color ?? NODE_CORE_BASE),
    mix(MUTED_SHELL, NODE_CORE_BASE, 0.3),
    HOVER_MUTE,
  );
  res.shellColor = lerpColor(
    String(attrs.shellColor ?? NODE_SHELL_BASE),
    MUTED_SHELL,
    HOVER_MUTE,
  );
  res.borderColor = TRANSPARENT;
  res.ringColor = TRANSPARENT;
  res.label = "";
  res.zIndex = 0;
  return res;
}

/** 指着的那一个:×1.08,最小 10.4,偏白的环——为的是跳出来。
 *  名字那块牌子的底亮一档并浮起来,与选中那一档同一副形状(选中是反色的
 *  浅底深字)。从前这里是一张浮起来的两行卡片,与选中完全不像 */
export function hoveredNode(
  res: NodeAttrs,
  attrs: NodeAttrs,
  base: number,
): NodeAttrs {
  res.size = Math.max(base * 1.08, 10.4);
  res.ringColor = mix(ownColorOf(attrs), INK, RING_HOVER_MIX);
  res.forceLabel = true;
  res.labelLift = true;
  res.zIndex = 4;
  return deferToHoverLayer(res);
}

/** 交给高亮层画:标签层跳过这一个(见 `drawNodeLabel` 里那段说明)。
 *
 * 正被指着的节点,sigma 会在标签层和高亮层各画一遍名字。这个记号是给标签层
 * 让路用的,**只该落在此刻真被指着的那一个身上**——所以它不属于 `selectedNode`:
 * 选中的那一个没被指着时,画它的正是标签层。 */
export function deferToHoverLayer(res: NodeAttrs): NodeAttrs {
  res.hideBaseLabel = true;
  return res;
}

/** 选中的那一个:**名字反色**。
 *
 * 反的是标签底牌,不是节点自己。节点四层解剖(环/描边/壳/核心)一律不动——
 * 试过让壳吃满类型色、核心退到深色,画面立刻变吵:一个实心亮圈把周围一圈
 * 邻居都压下去了,而邻居正是选中之后最该读的东西。**大小也几乎不动
 * (×1.02)**,一选中就胖一圈,整张图的疏密看着就变了。
 *
 * 于是"选中"全部落在名字上:底牌浅底深字,与指到的那一个(深底浅字)同一副
 * 形状调个个儿,一眼分得出"我正指着"和"我选中了",不必再添第三种记号。
 * 环仍留着,取偏本色那一档,与悬停那圈偏白的分得开。 */
export function selectedNode(
  res: NodeAttrs,
  attrs: NodeAttrs,
  base: number,
): NodeAttrs {
  res.size = Math.max(base * 1.02, 9.2);
  res.ringColor = mix(ownColorOf(attrs), INK, RING_SELECT_MIX);
  res.forceLabel = true;
  res.labelLift = true;
  // **反色**:浅底深字。指到的那一个是底亮一档的牌子,同一副形状调个个儿——
  // 一眼分得出"我正指着"和"我选中了",而不必再多一种记号
  res.labelInvert = true;
  // 再加粗一档。反色要看向它才读得出来,字重在余光里也分得清
  res.labelBold = true;
  res.zIndex = 3;
  return res;
}

/** 选中的那一个的邻居。
 *
 * `scale` 两页不同,这一处是真的设计差别不是走样:`/graph` 上千个节点,
 * 收到 0.76 是为了给选中的那一条路让地方;本体页几十个类,收了反而显得瘫 */
export function neighborNode(
  res: NodeAttrs,
  base: number,
  scale = 1,
): NodeAttrs {
  if (scale !== 1) res.size = Math.max(base * scale, 4);
  res.zIndex = 2;
  return res;
}

/* ============ 相机 ============ */

export interface Point {
  x: number;
  y: number;
}

export function nodePosition(sigma: Sigma, id: string): Point {
  const graph = sigma.getGraph();
  return {
    x: graph.getNodeAttribute(id, "x") as number,
    y: graph.getNodeAttribute(id, "y") as number,
  };
}

/** 节点此刻是否在视口里(按上一次渲染的相机算) */
export function nodeInView(sigma: Sigma, id: string, margin = 48): boolean {
  const { x, y } = sigma.graphToViewport(nodePosition(sigma, id));
  const { width, height } = sigma.getDimensions();
  return (
    x >= margin && x <= width - margin && y >= margin && y <= height - margin
  );
}

/** 相机推到一个节点上。sigma 的相机坐标是归一化到 [0,1] 的「框内」坐标,
 *  不是图坐标——直接喂图坐标(x 动辄几百)相机会飞出画面几万像素,画布
 *  一片空白。sigma 没有公开的图→框内换算,绕一趟视口:`graphToViewport` 用的
 *  是上一次渲染的矩阵,与 `viewportToFramedGraph` 用同一台相机,一来一回把
 *  相机抵消掉,剩下的就是框内坐标 */
export function focusNode(sigma: Sigma, id: string, maxRatio = 0.5): void {
  if (!sigma.getGraph().hasNode(id)) return;
  const framed = sigma.viewportToFramedGraph(
    sigma.graphToViewport(nodePosition(sigma, id)),
  );
  const ratio = Math.min(sigma.getCamera().ratio, maxRatio);
  sigma
    .getCamera()
    .animate({ x: framed.x, y: framed.y, ratio }, { duration: 300 });
}

/** 把一张刚算好的图**搬进**正在渲染的那一张。
 *
 * sigma 绑死在构造时给它的那个 graphology 实例上,所以"图变了"很容易被写成
 * "杀掉重建"。代价不小:GPU 缓冲、相机、悬停与选中态全部丢掉,还要再走一遍
 * 首帧——本体页为了把一个类揭进画面就走一遍这套,画面会明显顿一下。
 *
 * graphology 每一次增删改都发事件,sigma 听得见,所以**就地改本来就是它支持的
 * 路**。这里做的是最朴素的对账:多的删掉、少的补上、留下的属性覆盖一遍。
 * 几十上百个类的规模,一次全量覆盖比算精确差异更省事,也不容易错。
 *
 * 删点会连带删掉它的边,所以先取一份快照再遍历(`nodes()` 返回的是数组)。 */
export function syncGraph(live: Graphology, next: Graphology): void {
  for (const node of live.nodes()) if (!next.hasNode(node)) live.dropNode(node);
  next.forEachNode((node, attrs) => {
    if (live.hasNode(node)) live.replaceNodeAttributes(node, { ...attrs });
    else live.addNode(node, { ...attrs });
  });
  for (const edge of live.edges()) if (!next.hasEdge(edge)) live.dropEdge(edge);
  next.forEachEdge((edge, attrs, source, target) => {
    if (live.hasEdge(edge)) live.replaceEdgeAttributes(edge, { ...attrs });
    else live.addEdgeWithKey(edge, source, target, { ...attrs });
  });
}

/* ============ 拖拽 ============ */

/** 拖一个节点。**按下只记候选,位移超过阈值才升格成拖拽**——否则一次纯点击
 *  也会被当成拖了 0 像素的拖拽,鼠标松手的时机跟点选打架。
 *
 * 升格的那一刻冻住包围盒:拖着拖着节点飞出画面边缘时,相机不该跟着自动缩放去
 * 「适应」新的包围盒,那样一拖全图就跟着抖。松手再解开——「归位」要看得见刚
 * 挪过去的新位置,不能还按拖拽开始前的旧范围来算。
 *
 * 两页对「拖动过程中还要做什么」的回答不同:`/graph` 要把光标位置喂进力模拟,
 * 本体页要把位置记进它自己的坐标表。所以那两件事是回调,不在这里。 */
export function attachDrag(
  sigma: Sigma,
  o: {
    /** 升格成拖拽的那一刻。`/graph` 在这里唤醒力模拟 */
    onStart?: (node: string) => void;
    /** 每一帧的新位置。写进图的那两笔已经做过了 */
    onMove?: (node: string, pos: Point) => void;
    /** 松手。`/graph` 在这里安排力模拟停下 */
    onEnd?: (node: string) => void;
    /** 光标形状归谁管;不给就不动光标 */
    container?: () => HTMLElement | null;
    /** 悬停在节点上是不是「可以抓」的样子。本体页给,`/graph` 不给 */
    hovering?: () => boolean;
  } = {},
): void {
  const graph = sigma.getGraph();
  let dragCandidate: string | null = null;
  let downPoint: Point | null = null;
  let dragged: string | null = null;
  const cursor = (v: string) => {
    const el = o.container?.();
    if (el) el.style.cursor = v;
  };

  sigma.on("downNode", (e) => {
    dragCandidate = e.node;
    downPoint = { x: e.event.x, y: e.event.y };
  });
  sigma.getMouseCaptor().on("mousemovebody", (e) => {
    if (!dragCandidate) return;
    if (!dragged) {
      if (!downPoint || Math.hypot(e.x - downPoint.x, e.y - downPoint.y) < 4)
        return;
      dragged = dragCandidate;
      cursor("grabbing");
      if (!sigma.getCustomBBox()) sigma.setCustomBBox(sigma.getBBox());
      o.onStart?.(dragged);
    }
    const pos = sigma.viewportToGraph(e);
    graph.setNodeAttribute(dragged, "x", pos.x);
    graph.setNodeAttribute(dragged, "y", pos.y);
    o.onMove?.(dragged, pos);
    // 阻止相机跟着平移
    e.preventSigmaDefault();
    e.original.preventDefault();
    e.original.stopPropagation();
  });
  const endDrag = () => {
    dragCandidate = null;
    downPoint = null;
    if (!dragged) return;
    const node = dragged;
    dragged = null;
    cursor(o.hovering?.() ? "grab" : "");
    sigma.setCustomBBox(null);
    o.onEnd?.(node);
  };
  sigma.getMouseCaptor().on("mouseup", endDrag);

  // 悬停在节点上方给个「可以抓」的提示——发现得靠猜的交互等于没有
  if (o.hovering) {
    sigma.on("enterNode", () => {
      if (!dragged) cursor("grab");
    });
    sigma.on("leaveNode", () => {
      if (!dragged) cursor("");
    });
  }
}