# @cosmos\.gl/deck-layers 中文文档

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

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

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

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

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

- 包体积（解压后）：149 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：0 个
- peer 依赖：@deck\.gl/core ~9\.3\.0，@luma\.gl/core ~9\.3\.0，@luma\.gl/engine ~9\.3\.0，@cosmos\.gl/graph ^3\.6\.0，@luma\.gl/shadertools ~9\.3\.0
- 首次发布：2026-09-08T07:02:01.094Z
- 最新版本发布：2026-11-04T17:14:53.504Z
- 近 30 天下载量：3600（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

一个运行并绘制出宇宙图的甲板.gl地层——甲板相机下的宇宙.gl的自制器,在一个共享的luma.gl设备上

## 安装

```sh
npm install @cosmos.gl/deck-layers
```

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

## README

# @cosmos.gl/deck-layers (中文(简体) )

A 类 [甲板.gl (英语)](https://deck.gl/) 运行并绘制图层 [宇宙号gl](https://github.com/cosmosgl/graph) 图表。 模拟运行在甲板.gl的自有的luma.gl设备上,以及 **cosmos.gl自己的制造器** 把它拉入甲板的相机下方 位置永远不要离开GPU 所有宇宙(cosmos.gl)可以画出——点形,图像,曲线链接,箭头,破折克,灰出, 戒指,是你们的 `config` 编辑 `Graph`。 。 。 .

版本以锁定方式发布 `@cosmos.gl/graph` ——安装匹配版本.

## 安装

```bash
npm install @cosmos.gl/deck-layers @cosmos.gl/graph @deck.gl/core@~9.3.0 @luma.gl/core@~9.3.0 @luma.gl/engine@~9.3.0 @luma.gl/shadertools@~9.3.0 @luma.gl/webgl@~9.3.0
```

`@cosmos.gl/graph`, (中文(简体) ), `@deck.gl/core` 财务报告和审定财务报表 `@luma.gl/*` 是同伴的依赖关系:整个 点是宇宙、甲板和地层共享 **一个** luma.gl 设备,需要 一个luma.gl安装。 甲板.gl (英语) `~9.3` 与 luma.gl 成对 `~9.3`。 。 。 .

## 宇宙绘图

给它点和链接,它拥有其余的。 它造成一个无头 `Graph` 在甲板的装置, 装入您的数据, 将模拟从甲板运行时的每个框架推进一次 手甲板对宇宙的视线 在每张画之前就放出 cosmos.gl 绘图——无渲染-loop接线,无 `_animate`没有设备管道.

```js
import { Deck, OrthographicView } from '@deck.gl/core'
import { CosmosGraphLayer } from '@cosmos.gl/deck-layers'

new Deck({
  views: new OrthographicView({ flipY: false }), // cosmos's space has y up
  initialViewState: { target: [2048, 2048, 0], zoom: -2 },
  controller: true,
  layers: [
    new CosmosGraphLayer({
      id: 'graph',
      // cosmos-native binary mode — zero copies:
      points: { length: pointCount, initialPositions }, // Float32Array [x0, y0, x1, y1, …]
      links: linkIndices,                               // Float32Array [src0, tgt0, src1, tgt1, …]
      config: { curvedLinks: true, linkDefaultArrows: true },
      pickable: true,
      enablePointDrag: true,
      autoHighlight: true,
    }),
  ],
})
```

或者把它交给平地物体和进入器, 平地-平地-平地- id index 映射和种子未随机设置位置:

```js
new CosmosGraphLayer({
  id: 'graph',
  points: nodes,                        // e.g. [{ id: 'a', group: 0 }, …]
  links: edges,                         // e.g. [{ source: 'a', target: 'b' }, …]
  getPointId: (p) => p.id,              // lets links reference ids
  getPointColor: (p) => COLORS[p.group],
  getPointSize: (p) => p.weight,
  config: { simulationGravity: 0.25, simulationRepulsion: 1.5, pointDefaultShape: PointShape.Hexagon },
  onGraphCreated: (graph) => { /* pause, pin, restart, shapes, trackers, sparse writes */ },
})
```

-   **发作是宇宙. gl's.** `config` 是宇宙号,gl号 `GraphConfig` 减去密钥甲板拥有 (单位:千美元)`DECK_OWNED_CONFIG_KEYS`: 视图和缩放、框架循环、指针调回、 画布。 每个其它键都像在cosmos.gl, 渲染键包含; 键被忽略 返回引擎默认值.
-   **颜色** 在访问器中遵循 deck.gl 常规: 0.255 中的 RGBA 通道,转换 为宇宙。 尺寸和宽度在宇宙.gl的单位(`scalePointsOnZoom`, (中文(简体) ), `pointSizeScale`, (中文(简体) ), `linkWidthScale`) (中文(简体) ). 你离开的接通者什么也没有发出: 元素然后绘制配置密钥取而代之(`pointDefaultColor`, (中文(简体) ), `pointDefaultSize`, (中文(简体) ), `linkDefaultColor`, (中文(简体) ), `linkDefaultWidth`)),或者宇宙gl的默认,当它被忽略了也.
-   **二进制样式**: 二进制模式, `points.attributes` 财务报告和审定财务报表 `links.attributes` 键入 由它们取代的存取器键入的数组 - `getPointColor`, (中文(简体) ), `getPointSize`, (中文(简体) ), `getLinkColor`, (中文(简体) ), `getLinkWidth`A级 `Float32Array` 是cosmos.gl本身的形式(颜色以0.1为单位)并到达 如图所示,零份;a `Uint8Array` 以0.255字节转换。 链接取用 窗体 `{ pairs, attributes }`; 空对数组为 `{ pairs }`。一个新的 `points` 或者说 `links` 对象在相同位置或对的位置上重排:仅重装图表 当位置或对子本身改变时.
-   **风景.** cosmos.gl的视野是统一的尺度和与y相上下的翻译,所以 层画入 `OrthographicView({ flipY: false })` 或投出0和0的地图视图 标有 0 (参见 _在地图上_ 在故事书中。 旋转、 投放或 Y- down 视图为 在控制台上报告过一次,没有画出.
-   **选取是甲板的.** 在甲板的取出道口 Cosmos.gl 画出取出道的颜色——一种指数 每个点和每个链接,硬化的,破碎的缺口包括——所以 `pickable` 给徘徊和 单击: `info.elementType` 实值 `'point'` 或者说 `'link'`, (中文(简体) ), `info.index` 算在内, 财务报告和审定财务报表 `info.object` 是您的数组数据原始记录. `autoHighlight` 灯光 悬浮点或与宇宙相接,gl自己的悬浮环和悬浮-相接宽度 (单位:千美元)`config.hoveredPointRingColor`, (中文(简体) ), `config.hoveredLinkWidthIncrease`, (中文(简体) ), `config.hoveredLinkColor`); 重点(`focusedPointIndex`, (中文(简体) ), `focusedLinkIndex`留下来吧. 甲板的车 `highlightColor` 未使用.
-   **拖动** (单位:千美元)`enablePointDrag: true`,与 `pickable`:一个拖曳抓住点——被固定 抓取,随指针移动,按 `unpinOnDragEnd`· ; `dragReheatAlpha` 重新启动 在低相上模拟,所以图形在移动点周围响应. 视图平面 只有在抓住一点时才被压制。 地图上也有工作.
-   **还没有**: 无头 `Graph` 一次应用数据变化,所以 `transitions` 编辑 转换键 `config` 没有效果;一个由主机驱动的过渡时钟是下一步.

### 驱动图

这层 `Graph` 是你的电话.. `onGraphCreated` 把它交出来,然后 `onGraphDataLoaded` 除了层层本身的行为外

| 属于你的 | 这层 |
| --- | --- |
| `setPointShapes`, (中文(简体) ), `setLinkArrows`, (中文(简体) ), `setLinkStyles`, (中文(简体) ), `setLinkStrength`, (中文(简体) ), `setPointClusters`, (中文(简体) ), `setClusterPositions`, (中文(简体) ), `setPinnedPoint(s)`, (中文(简体) ), `start` 编号 : `pause` 编号 : `unpause`, (中文(简体) ), `trackPointPositionsByIndices`位置读取, `setPointPosition` 编号 : `setPointPositionsByIndices` | `setPointPositions`, (中文(简体) ), `setLinks`: 任何时候再次加载 `points` 或者说 `links` 变化. `setPointColors`, (中文(简体) ), `setPointSizes`, (中文(简体) ), `setLinkColors`, (中文(简体) ), `setLinkWidths`: 当您给出匹配的存取器或属性时, 层是您的 |
| —— 说 | `config`: 改变时再次适用,以及 `Graph.setConfig` 重排新配置所遗漏的内容, 通过道具设置配置 |

该图层在运行时也会对每个框架进行分级(`pause()` 它会自己踩出它, 接下来 `deck.redraw()` 在每个之后 `step()`) (中文(简体) ).

每个点或每个链接发出的矩阵都遵循图表的索引,重装可以移动 他们. `onGraphDataLoaded` 每次负载后起火,一旦图中包含新的数据和地图 您的这些指数数据 : `pointIndexById` (与 `getPointId`和 `links`,矩阵 链接图表的顺序。 最终点名无点的链接,所以 链接的索引可以与其数组中的索引不同。 每点发送和每链接发送数组 在那里,他们排队说:

```js
new CosmosGraphLayer({
  // …
  onGraphDataLoaded: ({ graph, pointsLoaded, linksLoaded, links }) => {
    if (pointsLoaded) graph.setPointShapes(Float32Array.from(nodes, (n) => SHAPES[n.kind]))
    if (linksLoaded && links) {
      graph.setLinkArrows(links.map((l) => l.directed))
      graph.setLinkStrength(Float32Array.from(links, (l) => l.weight))
    }
    graph.render() // applies what was set
  },
})
```

当引擎长度与链接相匹配时, 它会重新使用它最后发送的强度阵列 计算,所以新的链接集 相同的长度将拉 与旧的长处 命令 : 每一次再次发送 `linksLoaded`。第一个呼叫是当图表准备好了, 后来在甲板的地层更新中:在两个图上调用都很好,而修改到 层道具应该等待.

现场实例: _一体化_ 页:1 [宇宙.gl 故事书](https://cosmosgl.github.io/graph)。 。 。 .

## 带上自己的图

通过一个无头 `Graph` 您创建通过 `graph` 当应用程序需要拥有时: 在图层存在前创建, 保存在图层之间, 或驱动它从 在应用程序的其他地方。 它必须运行在甲板的装置上。 层层从甲板上走出 并画出它,但绝不加以配置或毁灭. `config` 财务报告和审定财务报表 `onGraphCreated` 只应用 用于图层创建.

`points` 决定谁装入数据。 别管了,图层画什么 手持并写入其中, 甚至连造型访问器都没有: 加载和样式图 自己,在图层存在之前或之后,布局存活下来去除并重新添加 层。 给一层 `points` (和 `links`把它们装入图中 设备检查一旦通过 进入器,不管它持有什么.

```js
let deck
const devicePromise = new Promise((resolve) => {
  deck = new Deck({ /* … */, onDeviceInitialized: resolve, layers: [] })
})

// headless, on deck's device, never destroyed by cosmos; the application loads it
const graph = new Graph(null, config, devicePromise)
graph.setPointPositions(positions)
graph.setPointColors(colors) // cosmos's 0..1
graph.setLinks(links)
graph.render()

deck.setProps({
  // no `points`: the layer draws the graph as loaded
  layers: [new CosmosGraphLayer({ id: 'graph', graph })],
})

// Take over stepping: pause it, step it yourself, then ask deck to repaint
graph.pause()
graph.step()
deck.redraw()

// Teardown order matters: the device belongs to deck.
graph.destroy()
deck.finalize()
```

几层可以画出一个图, 说一个主视图和一个微缩图: 它每帧步数一次 无论多层画,只要其中的一层 `points`。正在装入新的 数据从不再加热:呼叫 `graph.start()` 之后 `render()` 那时模拟已经定了.

## 您自己的渲染器 : `PositionTextureSource`

要画布局 以其他方式 管道,一个 Three.js 材料,一个 MapLibre 自定义层 – 输入对 `PositionTextureSource` 从 `@cosmos.gl/graph`。 。 。 . `Graph` 财务报告和审定财务报表 `GraphSimulation` 两者都执行 这个. `getPointPositionTexture()` 返回 a `PointPositionTexture`: 点 `i` 住在特克塞尔 `(i % textureSize, floor(i / textureSize))` 作为 `[x, y, i, unused]`,缺出点读作 NaN,和手柄改变 作为模拟乒乓球, 所以每次调整它 `version` 变化.

位置从不离开 GPU : 没有回放, 没有副本, 没有每个帧的上传, 所以一个成本 移动布局不会随点数而增长. 一个要求是共享设备: 模拟必须运行在您的渲染器的 luma.gl 设备上, 因为无法使用纹理 WebGL 语境 .

这个 _自定义甲板层_ 故事就是实例: 一个独立的 `GraphSimulation` {\\fn华文楷体\\fs16\\1che0e0e0}在甲板上 设备,由自己的两层甲板所绘制(`PointsLayer`, (中文(简体) ), `LinksLayer` 输入 故事的来源) `texelFetch` 纹理按实例索引——带有二进制属性, `highlightColor`盘旋和一拖拉住被抓住的点。 它们是示例代码,而不是软件包输出:复制并制作为您.

## 通用后退: CPU 读取后退

当您需要库存甲板层(属性过渡、扩展、位置文本)时, 运行一个无头模拟和快照位置到普通属性——相同 配方与任何渲染主机一起工作,成本为每发一发GPU CPU副本. 实际达上万分;把快照推倒.

```js
const simulation = new GraphSimulation(config) // its own hidden device
// per animation frame: simulation.step()
// every ~100 ms: await simulation.getPointPositionsAsync(positions), then update
// a ScatterplotLayer/LineLayer with `data: {length, attributes}` and an updateTrigger
```

## 制约因素

-   **仅WebGL 2** – 宇宙. gl 仅为 WebGL; 层会向 a 扔出可操作错误 WebGPU 设备.
-   **安装了1个luma.gl** a 包括: `Device` 重复的 luma.gl 副本共享为 不支持边框; 保持对等版本对齐 .
-   **平地,Y-up风景** —— 说 `OrthographicView({ flipY: false })`,或投出0和 带0. cosmos.gl 的视线不能表达出投出或承接.

## 许可证

麻省理工学院

## 常见问题

### @cosmos\.gl/deck-layers 是什么？

一个运行并绘制出宇宙图的甲板\.gl地层——甲板相机下的宇宙\.gl的自制器,在一个共享的luma\.gl设备上

### 如何安装 @cosmos\.gl/deck-layers？

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

### @cosmos\.gl/deck-layers 支持 TypeScript 吗？

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

### @cosmos\.gl/deck-layers 支持 ESM 还是 CommonJS？

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

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

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

### @cosmos\.gl/deck-layers 可以商用吗？

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

### @cosmos\.gl/deck-layers 的下载量有多少？

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

### @cosmos\.gl/deck-layers 还在维护吗？

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