# @cosmos\.gl/graph 中文文档

规范地址：https://npmcn.com/package/%40cosmos.gl/graph/

版本：3\.6\.0
npm 元数据更新时间：2026-11-04T17:15:50.220Z
中文译文更新时间：2026-11-10T20:24:29.105Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cosmos.gl/graph
原文对照：https://npmcn.com/package/%40cosmos.gl/graph/?lang=original
项目主页：https://cosmosgl.github.io/graph
源码仓库：https://github.com/cosmosgl/graph

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：5.9 MB，53 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：12 个
- peer 依赖：@luma\.gl/core ~9\.3\.0，@luma\.gl/webgl ~9\.3\.0，@luma\.gl/engine ~9\.3\.0，@luma\.gl/shadertools ~9\.3\.0
- 首次发布：2025-05-08T23:51:58.715Z
- 最新版本发布：2026-11-04T17:15:49.988Z
- 近 30 天下载量：435407（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：54（近 12 个月 41 个）

## 中文简介

基于 GPU 的力量图布局和渲染

## 安装

```sh
npm install @cosmos.gl/graph
```

也可以使用：`pnpm add @cosmos.gl/graph`、`yarn add @cosmos.gl/graph`、`bun add @cosmos.gl/graph`

## README

![cosmos.gl logo](https://assets.cosmograph.app/cosmos-light-theme.svg)

GPU 加速力图

**宇宙号gl** 是一个高性能的WebGL Force Graph算法和渲染引擎. 所有计算和绘图都发生在被片段和顶点遮蔽的GPU上,避免了昂贵的内存操作. 它能够实时模拟由数十万个点和现代硬件链接组成的网络图.

这个引擎的力量 [宇宙图](https://cosmograph.app/) ——探索复杂网络和AI嵌入的工具集.

[与其他图书馆的比较](https://www.youtube.com/watch?v=HWk78hP8aEE)

[来看看我们的故事本](https://cosmosgl.github.io/graph/)

* * *

### 快速启动

安装软件包 :

```bash
npm install @cosmos.gl/graph
```

> **说明:** [润滑剂gl](https://luma.gl/) (单位:千美元)`@luma.gl/core`, (中文(简体) ), `@luma.gl/engine`, (中文(简体) ), `@luma.gl/shadertools`, (中文(简体) ), `@luma.gl/webgl`,兼容范围 `~9.3.0`)是同级依赖关系。 npm 7+ 自动安装它; 带有 Yarn 或 pnpm 配置, 跳过自动安装对等器, 明确添加四个包 `~9.3.0` 赤裸的安装会得到一个更新的luma.gl. 将luma.gl保持为对等点让cosmos.gl共享一个luma.gl安装——和一个GPU `Device` ——主机有"甲板"等. gl.

获取数据, [配置](https://cosmosgl.github.io/graph/?path=/docs/configuration--docs) 图表并运行模拟:

```ts
import { Graph } from '@cosmos.gl/graph'

const div = document.querySelector('div')
const config = {
  simulationFriction: 0.1, // keeps the graph inert
  simulationGravity: 0, // disables the gravity force
  simulationRepulsion: 0.5, // increases repulsion between points
  curvedLinks: true, // curved links
  fitViewOnInit: true, // fit the view to the graph after initialization
  fitViewDelay: 1000, // wait 1 second before fitting the view
  fitViewPadding: 0.3, // centers the graph with a padding of ~30% of screen
  rescalePositions: false, // rescale positions, useful when coordinates are too small
  enableDrag: true, // enable dragging points
  onClick: (pointIndex) => { console.log('Clicked point index: ', pointIndex) },
  /* ... */
}

const graph = new Graph(div, config)

// Points: [x1, y1, x2, y2, x3, y3]
const pointPositions = new Float32Array([
  0.0, 0.0,    // Point 1 at (0,0)
  1.0, 0.0,    // Point 2 at (1,0)
  0.5, 1.0,    // Point 3 at (0.5,1)
]);

graph.setPointPositions(pointPositions)

// Links: [sourceIndex1, targetIndex1, sourceIndex2, targetIndex2]
const links = new Float32Array([
  0, 1,    // Link from point 0 to point 1
  1, 2,    // Link from point 1 to point 2
  2, 0,    // Link from point 2 to point 0
]);

graph.setLinks(links)

graph.render()
```

* * *

### V3.0里有什么新鲜事?

cosmos.gl v3.0 带来了一个新的渲染引擎,aync初始化,以及一些新的特性:

-   **luma.gl (WebGL 2) (中文(简体) )** 从regl到 [润滑剂gl](https://luma.gl/),支持共享自定义 `Device` 跨越多个图表通过 `new Graph(div, config, devicePromise)`。 。 。 .
-   **同步初始化** ——构造器立即返回;所有公用方法排队直到设备准备好. 使用 `graph.ready` 编号 : `graph.isReady` 以便知道何时可以使用图表.
-   **模拟控制** ——渲染现在与模拟分离. 默认自动启动模拟; 使用 `start()`, (中文(简体) ), `stop()`, (中文(简体) ), `pause()`,以及 `unpause()` 独立控制它.
-   **链接取样** 屏幕上的可见链接样本 `getSampledLinks()` 财务报告和审定财务报表 `getSampledLinkPositionsMap()` 用于在链接上渲染标签或覆盖.
-   **触摸和笔接支持** - 电话和平板电脑上的窃听器、拖动器和相接器 长压(~500ms)会触发上下文菜单回调. `onMouseMove` 并且所有点击都从触摸输入中调用回火.
-   **上下文菜单支持** ——右键点击桌面的新回调和tuch/pen的长压: `onContextMenu`, (中文(简体) ), `onPointContextMenu`, (中文(简体) ), `onLinkContextMenu`, (中文(简体) ), `onBackgroundContextMenu`。 。 。 .
-   **将视图端口切入点数** —— 说 `setZoomTransformByPointPositions()` 缩放和平板以适合一组点入视野.
-   **配置驱动的突出显示** - 以必要选择方法取代 `highlightedPointIndices`, (中文(简体) ), `highlightedLinkIndices`,以及 `outlinedPointIndices` 配置属性 。 点和链接单独突出。 通过下列途径使重点联系更加广泛: `focusedLinkIndex` 编号 : `focusedLinkWidthIncrease`新建 `findPointsInRect()`, (中文(简体) ), `findPointsInPolygon()`, (中文(简体) ), `getNeighboringPointIndices()`, (中文(简体) ), `getConnectedLinkIndices()`,以及 `getConnectedPointIndices()` 方法。 。 .
-   **链接混合控制** —— 说 `linkBlending: false` 禁用 alpha 混合, 用于在稠密的图上显著地更快的链接渲染 .
-   **四. 改进工作** —— 说 `onPointMouseOver` 现在包括 `isHighlighted` 财务报告和审定财务报表 `isOutlined` 参数; 当点相重叠时,会正确显示最顶点.
-   **配置 API 更改** —— 说 `setConfig()` 现在在应用前将所有值重新设置为默认值; 使用新值 `setConfigPartial()` 更新个人属性而不重置其余属性.
-   **仅输入配置字段** —— 说 `initialZoomLevel`, (中文(简体) ), `randomSeed`,以及 `attribution` 只能设置在初始化期间,并保存在配置更新中.
-   **切换运行时间模拟** —— 说 `enableSimulation` 现在可以在运行时通过 `setConfig()` 或者说 `setConfigPartial()`。 。 。 .
-   **GPU 转换** ——指点位置,指点颜色/大小,以及连接颜色/widths 现在默认为动能(`transitionDuration: 800`, (中文(简体) ), `transitionEasing: TransitionEasing.CubicInOut`) (中文(简体) ). 使用 `transitionDuration: 0` 保持快速更新.
-   **过渡回调** ——使用 `onTransitionStart`, (中文(简体) ), `onTransition`,以及 `onTransitionEnd` 跟踪过渡生命周期和进展.
-   **默认点形状** ——新设 `pointDefaultShape` 配置属性允许您在不提供每个点形状时为所有点设置倒计时形状。 接受一个 `PointShape` enum值(例如, `PointShape.Star`),一个平数(例如, `6`),或数字字符串(例如, `"6"`) (中文(简体) ).
-   **碰撞力** ——新的GPU-加速相撞力能使点能避免重叠,使用空间-hash网格来缩放成大图. 启用它 `simulationCollision`,并调整间隔 `simulationCollisionRadius` (固定半径与大小)和 `simulationCollisionPadding` (各点间有外差). 见 [碰撞实例](https://cosmosgl.github.io/graph/?path=/story/examples-forces--collision)。 。 。 .
-   **导出默认值** —— 说 `defaultConfigValues` 现在属于公共API.
-   **最佳悬浮探测** ——鼠标未移动时跳过GPU工作.

检查 [移徙指南](https://npmcn.com/package/%40cosmos.gl/graph/migration-notes.md) 从v2升级.

### V2.0里有什么新情况?

cosmos.gl v2.0在性能和数据处理方面作出重大改进:

-   增强具有WebGL兼容格式的数据结构.
-   方法一样 `setPointPositions` 财务报告和审定财务报表 `setLinks` 替换 `setData` 提高效率.
-   通过Float32Array直接控制点和链接属性(如颜色,大小,宽度等).
-   基于索引而不是对象更新的事件处理 .
-   新点集群部队`setPointClusters`, (中文(简体) ), `setClusterPositions` 财务报告和审定财务报表 `setPointClusterStrength`) (中文(简体) ).
-   拖取点的能力.

检查 [移徙指南](https://npmcn.com/package/%40cosmos.gl/graph/migration-notes.md) 用于从v1升级.

* * *

### 实例

-   [行动](https://cosmosgl.github.io/graph/?path=/story/examples-get-started--actions)

* * *

### 显示大小写( 通过) [相册. app](https://cosmograph.app/)(中文(简体) )

-   [丝绸之路案例:比特币交易](https://run.cosmograph.app/public/987cf266-fd90-4940-b52d-f75a1e006237) (单位:千美元)[更多信息](https://medium.com/@cosmograph.app/visualizing-darknet-6846dec7f1d7)(中文(简体) )
-   [ABACUS 贝壳](https://run.cosmograph.app/public/b099a861-47ba-4110-b778-c4ef0f29644f) (单位:千美元)[来源](http://sparse.tamu.edu/Puri/ABACUS_shell_hd)(中文(简体) )
-   [数学工作公司:对称正向确定矩阵](https://run.cosmograph.app/public/cb6f43f2-71c7-47de-97c5-d86ac549cfed) (单位:千美元)[来源](https://sparse.tamu.edu/MathWorks/Kuu)(中文(简体) )

* * *

### 已知问题

-   ~从15.4版本开始,iOS停止支持关键WebGL扩展为我们的多Body力执行提供动力(`EXT_float_blend`) (中文(简体) ). 我们正在调查这个问题并探索解决办法.~ 最新iOS又成功了!
-   cosmos.gl不工作 在Android设备 不支持 `OES_texture_float` WebGL 扩展名.

* * *

### 文档

-   🧑‍💻 [快速启动](https://cosmosgl.github.io/graph/?path=/docs/welcome-to-cosmos-gl--docs)
-   🛠 [配置](https://cosmosgl.github.io/graph/?path=/docs/configuration--docs)
-   ⚙️ [API 参考](https://cosmosgl.github.io/graph/?path=/docs/api-reference--docs)
-   🚀 [移徙指南](https://github.com/cosmosgl/graph/blob/main/migration-notes.md)

* * *

### 许可证

**麻省理工学院**

* * *

### 联系人

[GitHub 讨论](https://github.com/orgs/cosmosgl/discussions)

## 常见问题

### @cosmos\.gl/graph 是什么？

基于 GPU 的力量图布局和渲染

### 如何安装 @cosmos\.gl/graph？

在项目目录运行 npm install @cosmos\.gl/graph，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@luma\.gl/core（~9\.3\.0）、@luma\.gl/webgl（~9\.3\.0）、@luma\.gl/engine（~9\.3\.0）、@luma\.gl/shadertools（~9\.3\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cosmos\.gl/graph 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cosmos\.gl/graph 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cosmos\.gl/graph 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cosmos\.gl/graph 可以商用吗？

@cosmos\.gl/graph 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cosmos\.gl/graph 的下载量有多少？

根据 npm 官方下载统计，@cosmos\.gl/graph 在 2026/10/11 – 2026/11/09 这 30 天内被下载 435,407 次，日均约 14,514 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cosmos\.gl/graph 还在维护吗？

最新版本 3\.6\.0 发布于 2026/11/05（6 天前）；至今共发布 54 个版本，其中过去 12 个月发布了 41 个；首次发布于 2025/05/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。