更新记录

1.0.0（2026-07-19）

关系图谱 / 知识图谱引擎首发。

• 双布局器：force（Barnes-Hut 四叉树力导 + Fruchterman-Reingold，确定性 seed 撒点）/ hierarchy（层次，TB/LR 方向 + 有向箭头）。
• 四件套交互：平移缩放（触摸双指捏合 / 桌面滚轮）、拖节点实时重仿真（钉住 + 局部升温）、点击命中（节点 / 边 / 空白三态）、焦点邻接高亮（setFocus 高亮节点 + 邻居、其余淡出）。
• 标签 LOD：auto（按视口密度裁剪，万级不糊）/ always / off；节点半径按 value 线性映射。
• 分组配色 + 图例：categories 分组自动配色 + 类别图例；亮 / 暗双主题。
• 原生视图组件：App 端 <uni-nex-graph-view>（手势热环路时钟自驱、零桥接开销）+ H5 端 <uni-nex-graph-canvas>（帧循环自驱、触摸 + 桌面鼠标双模态）。
• 三端同源：Android / iOS / H5 同一渲染内核，19 个 API 三端一致。
• 安全上限：20 万节点 / 50 万边（超限报错不静默截断）；跨调用边界 panic 兜底。
• 性能：万级节点单轮布局计算 9.4m

平台兼容性

uni-app x(5.14)

nex-graph 关系图谱 / 知识图谱引擎（原生渲染 + 原生视图直贴）

万节点关系网络，拖得动的图谱。JS 图库画几千节点力导就卡成幻灯片的场景，本插件用原生渲染引擎 + Barnes-Hut 四叉树力导：万级节点单轮布局计算 9.4ms（本机基准实测），布局在原生视图时钟里自驱舒展、收敛即停——不做每帧全量重绘，交互后按需刷新。力导 / 层次双布局、拖节点实时重仿真、点击命中邻接高亮、标签万级不糊，三端同源一套 API。

特性

• 双布局器：force（力导，Barnes-Hut 四叉树斥力近似 + Fruchterman-Reingold，确定性 seed 撒点，同一 option 每次布局一致）/ hierarchy（层次，TB 自上而下 / LR 自左而右，有向箭头汇报关系）
• 万级规模 + 交互布局：单轮力导布局计算 9.4ms @万级节点（本机基准）——布局迭代在原生视图时钟里跑（headless），收敛后停钟省电；交互后按需重绘（render-on-change），不做每帧全量动画。十万级节点走静态导出 / 离线布局档
• 拖节点实时重仿真：单指按住节点拖动，force 模式下钉住 + 局部升温、周边节点让位重新舒展；松手续冷却
• 点击命中 + 邻接高亮：单击命中节点即高亮它 + 直接邻居、其余淡出——一眼看清一个实体的关系圈；再点空白清除。节点 / 边 / 空白三态命中，节点优先
• 标签 LOD（万级不糊）：auto 档按视口密度自动裁剪标签（缩得远只画点、放大才显名），always 全画 / off 全关；节点半径按 value 线性映射
• 分组配色 + 图例：categories 分组自动配色，类别图例一行；亮 / 暗双主题
• <uni-nex-graph-view> 原生视图（App）：手势 → 命中 / 拖钉 / 视口 → 时钟自驱 tick+取帧 → Android View / iOS UIView 直贴位图，手势热环路全程零桥接开销（多指抬起 / 取消正确收尾）
• 三端同源：App(Android/iOS) + H5(浏览器) 同一渲染内核，19 个 API 三端一致；H5 端统一组件 <uni-nex-graph-canvas>（canvas 帧循环 + 触摸 / 桌面鼠标双模态，滚轮缩放）
• 无第三方原生依赖：干净跨平台编译，纯计算内核不带任何系统库

快速上手

1. 建引擎 + 布局 + 取帧（H5 三端同一套 API）

import { GraphEngine, ensureReady } from '@/uni_modules/nex-graph'

// H5 端出图能力异步初始化，应用启动时 await 一次（App 端无此概念，可跳过）
await ensureReady()

// 建引擎：知识图谱（力导），3 个类别 + 分组配色 + 标签 LOD
const engine = GraphEngine.create(JSON.stringify({
  layout: 'force',
  nodes: [
    { id: 'a', name: '莎士比亚', category: 0, value: 40 },
    { id: 'b', name: '哈姆雷特', category: 1, value: 30 },
    { id: 'c', name: '皇家剧院', category: 2, value: 25 }
  ],
  edges: [
    { source: 'a', target: 'b' },
    { source: 'a', target: 'c' }
  ],
  categories: [{ name: '人物' }, { name: '作品' }, { name: '机构' }],
  style: { nodeSize: [8, 40], label: 'auto', arrow: false },
  force: { repulsion: 90, edgeLength: 55, gravity: 0.12, maxIter: 300, seed: 42 },
  legend: { show: true }
}))

2. H5 端：<uni-nex-graph-canvas> 统一组件（自驱舒展 + 手势 + 邻接高亮）

组件内部自 resize、自驱帧循环（收敛后停）、处理触摸 / 桌面鼠标手势——页面只需 ensureReady() 后建好对象传进来：

<template>
  <uni-nex-graph-canvas
    v-if="engine != null"
    :engine="engine"
    :width-px="320" :height-px="300"
    :auto-layout="true"
    :auto-focus="true"
    @nodetap="onNodeTap" @edgetap="onEdgeTap"
    @viewportchange="onViewport" @layoutend="onLayoutEnd" />
</template>

<script>
  import { GraphEngine, ensureReady } from '@/uni_modules/nex-graph'
  export default {
    data() { return { engine: null as GraphEngine | null } },
    onLoad() {
      // #ifdef H5
      ensureReady().then(() => { this.engine = GraphEngine.create('{"nodes":[...],"edges":[...]}') })
      // #endif
    },
    methods: {
      // auto-focus=true 时组件已在引擎侧做好邻接高亮，这里只需读命中节点
      onNodeTap(payload: string) { const hit = JSON.parse<{ id?: string }>(payload); /* ... */ }
    }
  }
</script>

⚠️ 换布局 / 换方向要换绑一个新引擎对象：组件监听的是 engine 对象身份（换对象才重渲）——在同一对象上 setOption 不会触发重绘。tab 切换、TB/LR 方向切换都请新建一个 GraphEngine 对象赋给 engine（组织架构数据很小，TB/LR 各建一个换绑最干净）。

3. App 端：<uni-nex-graph-view> 原生视图（手势热环路零桥接开销）

<template>
  <uni-nex-graph-view
    :engine-id="engineId" :auto-layout="true" :auto-focus="true"
    style="width: 750rpx; height: 600rpx;"
    @nodetap="onNodeTap" @viewportchange="onViewport" @layoutend="onLayoutEnd" />
</template>

<script>
  import { GraphEngine } from '@/uni_modules/nex-graph'
  export default {
    data() { return { engineId: 0 } },
    onLoad() {
      // #ifndef H5
      const engine = GraphEngine.create('{"nodes":[...],"edges":[...]}')
      this.engineId = engine.graphId()  // 懒注册句柄；原生视图经 graphById 反查回引擎
      // #endif
    }
  }
</script>

4. 组织架构（层次布局 + 方向切换 + 箭头）

// 层次布局：CEO → VP → 经理，有向箭头表明汇报关系；TB / LR 各建一个对象换绑切方向
const orgTB = GraphEngine.create(JSON.stringify({
  layout: 'hierarchy',
  nodes: [{ id: 'ceo', name: '总裁' }, { id: 'vp', name: '技术副总' }, { id: 'm', name: '经理' }],
  edges: [{ source: 'ceo', target: 'vp' }, { source: 'vp', target: 'm' }],
  hierarchy: { direction: 'TB', layerGap: 70, nodeGap: 22 },
  style: { arrow: true, label: 'always' }
}))

API 一览（19 个 · 三端一致）

对象 GraphEngine（create 建）上 15 个实例方法 + 4 个顶层函数。完整签名 / DSL 字段 / 命中 JSON 形状 / 坐标契约见 插件契约。

FAQ

Q：能画多大的图？ 上限 20 万节点 / 50 万边（超限报错不静默截断）。布局计算在万级量级 9.4ms/轮（本机基准），装得进交互预算；渲染随边数与结构变——知识图谱 / 组织架构这类有结构的图边短、渲染便宜。十万级请走静态导出 / 离线布局档（一次布局出图，不做实时交互动画）。性能数字均为本机开发机基准，中端真机档位以真机实测为准。

Q：为什么不是每帧 60fps 全量动画？ 诚实说：万级节点每帧把所有边重新抗锯齿描边是数秒级开销，做不到 60fps 满帧动画。本插件的设计是布局在原生视图时钟里自驱舒展（headless）→ 收敛即停 → 交互后按需重绘（render-on-change）——你看到的是流畅的开场舒展 + 拖拽响应，而不是持续烧 GPU 的满帧动画。这是万级图的正确做法。

Q：拖节点 / 点击高亮没反应？ ① H5 组件的 engine prop 要传一个 GraphEngine 对象（不是 id）；② 点击邻接高亮需 :auto-focus="true"（默认 false 时只上抛 @nodetap 事件、不自动高亮）；③ 换布局记得换绑新对象（见上「⚠️」）。

Q：H5 端和 App 端 API 一样吗？ 一样，19 个 API 三端一致。差异仅：H5 端 renderToFile（无文件系统）、graphId/detachView（原生视图注册表为 App 专属）在 H5 调用会明确抛错——H5 出图用 renderFrame() 取 RGBA 自行编码 / 下载，H5 组件 <uni-nex-graph-canvas> 直接持对象无需注册表。

Q：坐标系怎么对齐？ hitAt/pinNode 收逻辑像素（iOS 不乘 scale、H5 不除 dpr），renderFrame() 无参、画布尺寸经 resize(w, h, dpr) 一次设定。详见契约「坐标空间契约」。

平台支持

许可 / 定价见插件市场详情页。问题反馈请在插件市场评论区留言。