# @deckgl-fiber-renderer/dom 中文文档

规范地址：https://npmcn.com/package/%40deckgl-fiber-renderer/dom/

版本：2\.0\.1
npm 元数据更新时间：2026-05-26T13:56:00.249Z
中文译文更新时间：2026-11-11T19:19:24.327Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40deckgl-fiber-renderer/dom
原文对照：https://npmcn.com/package/%40deckgl-fiber-renderer/dom/?lang=original
项目主页：https://github.com/deckgl-fiber-renderer/fiber.gl#readme
源码仓库：https://github.com/deckgl-fiber-renderer/fiber.gl

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

- 包体积（解压后）：32.7 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：@deck\.gl/core \>=9\.1，@deck\.gl/geo-layers \>=9\.1，@deck\.gl/layers \>=9\.1，@deck\.gl/mapbox \>=9\.1，@deck\.gl/mesh-layers \>=9\.1，react ^19，react-dom ^19
- 首次发布：2025-03-14T04:15:03.708Z
- 最新版本发布：2026-05-26T13:56:00.100Z
- 近 30 天下载量：36015（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 2 个）

## 中文简介

Deck.gl 的反相渲染器

## 安装

```sh
npm install @deckgl-fiber-renderer/dom
```

也可以使用：`pnpm add @deckgl-fiber-renderer/dom`、`yarn add @deckgl-fiber-renderer/dom`、`bun add @deckgl-fiber-renderer/dom`

## README

# @ deckgl-fiber-resters/dom (英语)

甲板反射渲染器 利用React组件和钩子来构建地理空间可视化,并配有完整的TypeScript支持.

## 安装

```bash
pnpm add @deckgl-fiber-renderer/dom
```

### 同伴依赖关系

```bash
pnpm add react react-dom @deck.gl/core @deck.gl/layers
```

**所需经费:** 反应 `19.0.0+`, 甲板. gl 数据 `^9.1.0`

* * *

## 教学

### 您的第一个地图

构建3个步骤的可工作散点可视化.

**1\. 创建该部分**

```tsx
import { Deckgl } from "@deckgl-fiber-renderer/dom";
import { ScatterplotLayer } from "@deck.gl/layers";

function App() {
  const data = [
    { position: [-122.45, 37.8], size: 100, name: "Point A" },
    { position: [-122.46, 37.81], size: 200, name: "Point B" },
  ];

  return (
    <Deckgl
      initialViewState={{
        longitude: -122.45,
        latitude: 37.8,
        zoom: 12,
      }}
      style={{ width: "100%", height: "100vh" }}
    >
      <layer
        layer={
          new ScatterplotLayer({
            id: "points",
            data,
            getPosition: (d) => d.position,
            getRadius: (d) => d.size,
            getFillColor: [255, 140, 0],
          })
        }
      />
    </Deckgl>
  );
}
```

**2\. 增加互动性**

```tsx
import { useState } from "react";

function App() {
  const [hovered, setHovered] = useState(null);

  return (
    <Deckgl
      initialViewState={{ longitude: -122.45, latitude: 37.8, zoom: 12 }}
      onHover={(info) => setHovered(info.object)}
      getCursor={() => (hovered ? "pointer" : "grab")}
    >
      <layer
        layer={
          new ScatterplotLayer({
            id: "points",
            data,
            getPosition: (d) => d.position,
            getRadius: (d) => d.size,
            getFillColor: hovered ? [255, 200, 0] : [255, 140, 0],
            pickable: true,
          })
        }
      />
      {hovered && <div className="tooltip">{hovered.name}</div>}
    </Deckgl>
  );
}
```

**3\. 成功标准**

-   在地图上看到橙色点
-   盘旋时的光标变化
-   QQ 工具提示显示点名

**更多关于甲板. gl 层:** [https://deck.gl/docs/api-参考资料/层](https://deck.gl/docs/api-reference/layers)

* * *

## 如何向导

### 与 MapLibre/ Mapbox 合并

使用间叶渲染来将甲板.gl和基底映射层结合.

```tsx
import { Map, useControl } from "react-map-gl/maplibre";
import { Deckgl, useDeckgl } from "@deckgl-fiber-renderer/dom";

function DeckglOverlay() {
  const deck = useDeckgl();
  useControl(() => deck);
  return null;
}

function App() {
  return (
    <Map
      initialViewState={{ longitude: -122.4, latitude: 37.8, zoom: 12 }}
      mapStyle="https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json"
    >
      <Deckgl interleaved>
        <DeckglOverlay />
        <layer layer={new ScatterplotLayer({ id: "points", data })} />
      </Deckgl>
    </Map>
  );
}
```

**要点:**

-   `<Map>` 包装 `<Deckgl>`,反之亦然
-   `interleaved` 道具允许层相交
-   `useDeckgl()` 提供甲板实例给 `useControl()`

**学习更多:** [https://deck.gl/docs/api-reference/mapbox/overview 页面存档备份,存于互联网档案馆](https://deck.gl/docs/api-reference/mapbox/overview)

### 渲染多视图

用不同的相机分割屏幕或微型相机 .

```tsx
import { MapView, OrthographicView } from "@deck.gl/core";

function App() {
  return (
    <Deckgl>
      <view
        view={
          new MapView({
            id: "main",
            x: 0,
            y: 0,
            width: "70%",
            height: "100%",
          })
        }
      >
        <layer layer={new ScatterplotLayer({ id: "main-points", data })} />
      </view>

      <view
        view={
          new OrthographicView({
            id: "minimap",
            x: "70%",
            y: 0,
            width: "30%",
            height: "100%",
          })
        }
      >
        <layer layer={new ScatterplotLayer({ id: "mini-points", data })} />
      </view>
    </Deckgl>
  );
}
```

**说明:** 通过视图过滤层需要通过道具进行人工控制. 所有层默认在所有视图中渲染 .

**学习更多:** [https://deck.gl/docs/api-reference/core/deck#views 页面存档备份,存于互联网档案馆](https://deck.gl/docs/api-reference/core/deck#views)

### 使用自定义图层

自定义层在没有注册的情况下立即工作 .

```tsx
import { CompositeLayer } from "@deck.gl/core";
import { ScatterplotLayer } from "@deck.gl/layers";

class CustomLayer extends CompositeLayer {
  static layerName = "CustomLayer";

  renderLayers() {
    return new ScatterplotLayer({
      id: `${this.props.id}-scatter`,
      data: this.props.data,
      getPosition: (d) => d.coordinates,
      getRadius: this.props.customRadius || 100,
    });
  }
}

// Use immediately - no registration needed
<layer layer={new CustomLayer({ id: "custom", data, customRadius: 200 })} />;
```

**类型脚本打字( 可选) :**

```tsx
type CustomLayerProps = {
  id: string;
  data: unknown[];
  customRadius?: number;
};

declare global {
  namespace React.JSX {
    interface IntrinsicElements {
      customLayer: CustomLayerProps;
    }
  }
}

// Now <customLayer> has type checking (but <layer> is recommended)
```

**学习更多:** [https://deck.gl/docs/developer-guide/海关一级](https://deck.gl/docs/developer-guide/custom-layers)

* * *

## 参考文献

### API : (英语) `<Deckgl>`

Root容器用于甲板.gl可视化.

```tsx
<Deckgl
  initialViewState={{ longitude: -122.4, latitude: 37.8, zoom: 12 }}
  width="100%"
  height="100vh"
  onLoad={(deck) => console.log("Ready", deck)}
>
  {children}
</Deckgl>
```

**道具 :**

| Prop | 类型 | 说明 |
| --- | --- | --- |
| `initialViewState` | `object` | 初始相机位置(经度、纬度、缩放等) |
| `width` | `string | number` | 容器宽度( 支持 CSS 值) |
| `height` | `string | number` | 集装箱高度(支持CSS值) |
| `interleaved` | `boolean` | 启用用于 Basemap 集成的相叶渲染 |
| `onLoad` | `(deck: Deck) => void` | 甲板. gl 初始化时召回 |
| `onViewStateChange` | `(params) => void` | 视图状态改变时召回 |
| `onHover` | `(info, event) => void` | 盘旋时召回 |
| `onClick` | `(info, event) => void` | 点击后调用 |
| `getCursor` | `(state) => string` | 基于状态的自定义光标 |
| `debug` | `boolean` | 启用日志( 只开发模式) |

**继承道具:** 所有道具从甲板。 GL's (英语) [`DeckProps`](https://deck.gl/docs/api-reference/core/deck#properties) 财务报告和审定财务报表 [`MapboxOverlayProps`](https://deck.gl/docs/api-reference/mapbox/mapbox-overlay#properties) 被支持.

### API : (英语) `useDeckgl()`

钩子进入甲板. gl实例.

```tsx
import { useDeckgl } from "@deckgl-fiber-renderer/dom";

function MyComponent() {
  const deck = useDeckgl();

  useEffect(() => {
    if (deck) {
      console.log("Current view state:", deck.viewState);
    }
  }, [deck]);

  return null;
}
```

**回返情况:** `Deck | null`

**说明:** 回返 `null` 直至 `<Deckgl>` 上马 使用前总是检查.

### API : (英语) `<layer>` 财务报告和审定财务报表 `<view>`

层和视图的通用元素(v2语法).

**`<layer>` 元素 :**

```tsx
<layer layer={new ScatterplotLayer({ id: "points", data })} key="optional-react-key" />
```

| Prop | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `layer` | `Layer` | 对 | 甲板.gl (英语). 图层实例 |
| `key` | `string` | 没有 | 列表渲染的响应密钥 |

**`<view>` 元素 :**

```tsx
<view view={new MapView({ id: "main" })} key="optional-react-key" />
```

| Prop | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `view` | `View` | 对 | deck.gl 视图实例 |
| `key` | `string` | 没有 | 列表渲染的响应密钥 |

**类型脚本通用名 :**

```tsx
type DataPoint = { coordinates: [number, number]; value: number };

<layer
  layer={
    new ScatterplotLayer<DataPoint>({
      id: "points",
      data,
      getPosition: (d) => d.coordinates, // d typed as DataPoint
      getRadius: (d) => d.value, // Full autocomplete
    })
  }
/>;
```

### API : (英语) `extend()` (折旧)

```tsx
import { extend } from "@deckgl-fiber-renderer/dom";
import { MyCustomLayer } from "./my-custom-layer";

extend({ MyCustomLayer });

// Deprecated - use <layer> instead
<myCustomLayer id="custom" data={data} />;
```

**折旧:** 此函数已贬值,将在 v3 中被删除 。 使用 `<layer layer={new MyCustomLayer(...)} />` 换句话说.

* * *

## 解释

### 为什么是反应器?

官方甲板.gl React 绑定了必须的甲板.gl API. 这种限制成分——分层必须是直生子,钩子不起作用,而TypeScript generals是不支持的.

反应调和器在更低的级别集成了deck.gl. 它教 React 如何渲染到 jadle.gl, 使地层一级 React 组件. 这样可以:

-   **缠绕** - 层层可以在您组件树的任何地方
-   **钩子** - 使用状态,使用Context,自定义钩 全部工作
-   **常规** - 进入器函数中的全部类型Script类型推论
-   **组成** - 建立可重复使用的层组件

**权衡:** 稍大的捆绑(~15KB)用于调节器基础设施. 值得团队建立复杂的视觉.

### 持久性模式设计

反应调和器可以变异节点(DOM)或取而代之(原始语如字符串). 此调节器使用 **持久性模式** - 它取代了地层,而不是改变它们.

**为什么?** deck.gl地层被设计为可永恒的描述:

> "Layers是描述对象,非常便宜,可以即时使用. 每个渲染周期都创造出一套新的地层 [deck.gl 文档](https://deck.gl/docs/developer-guide/using-layers)

deck.gl 处理内部高效更新 :

1.  以 ID 匹配层
2.  抖道道具
3.  重用 GPU 资源

调和器在道具变化上创建了新的层例. date.gl的抖动算法检测到实际变化,仅更新了受影响的状态.

**性能 :** 无上行. 创建层例是便宜的 - 它们只是普通对象,直到甲板.gl处理它们.

### 层 ID 和 diffing

**规则:** 总是提供清晰的,稳定的 `id` 道具来.

```tsx
// ✅ Good - explicit, stable ID
<layer layer={new ScatterplotLayer({ id: "points", data })} />

// ❌ Bad - missing ID (auto-generated, changes every render)
<layer layer={new ScatterplotLayer({ data })} />

// ❌ Bad - non-stable ID (changes every render)
<layer layer={new ScatterplotLayer({ id: Math.random().toString(), data })} />
```

**为什么?** deck.gl使用ID进行分解. 没有稳定的身份证:

-   每层都被视为新出土
-   GPU 资源被销毁并重建
-   动画重置
-   性能降低

**开发模式验证 :** 缺少或重复ID触发警告. 这些检查从生产建筑中剥离.

**学习更多:** [https://deck.gl/docs/developer-guide/using-layers#layer-dentity-and-diffing 互联网档案馆的存檔,存档日期2013-12-22](https://deck.gl/docs/developer-guide/using-layers#layer-identity-and-diffing)

### v1 vs v2 语法

#### 理解 v1 自动注册

在 v1 中, 导入副作用模块会自动注册所有 deck. gl 层 :

```tsx
// v1 side-effects import (no longer works in v2)
import "@deckgl-fiber-renderer/reconciler/side-effects";
```

此单导入已执行代码 `extend()` 有30多层构造器:

```tsx
// What the v1 side-effects import did internally:
extend({
  // Views
  MapView,
  OrthographicView,
  OrbitView,
  FirstPersonView,
  GlobeView,

  // @deck.gl/layers (13 layers)
  ArcLayer,
  BitmapLayer,
  IconLayer,
  LineLayer,
  PointCloudLayer,
  ScatterplotLayer,
  ColumnLayer,
  GridCellLayer,
  PathLayer,
  PolygonLayer,
  GeoJsonLayer,
  TextLayer,
  SolidPolygonLayer,

  // @deck.gl/geo-layers (14 layers)
  S2Layer,
  QuadkeyLayer,
  TileLayer,
  TripsLayer,
  H3ClusterLayer,
  H3HexagonLayer,
  Tile3DLayer,
  TerrainLayer,
  MVTLayer,
  GeohashLayer,
  GreatCircleLayer,
  WMSLayer,

  // @deck.gl/mesh-layers (2 layers)
  ScenegraphLayer,
  SimpleMeshLayer,
});
```

注册后,您可以使用特定层次的JSX元素:

```tsx
<scatterplotLayer id="points" data={data} getPosition={(d) => d.coordinates} />
<pathLayer id="routes" data={routes} getPath={(d) => d.path} />
```

#### \* 移徙脚枪

**JSX元素在v2中仍然有TypeScript类型,但没有适当的注册,它们不会在运行时间工作.**

这是最常见的迁移错误:

```tsx
// No registration - JSX types exist but runtime catalog is empty
<scatterplotLayer id="points" data={data} getPosition={(d) => d.coordinates} />
//              ^^^^^^^^^ TypeScript: ✅  Runtime: ❌ "Unknown element type: scatterplotLayer"
```

**为什么会这样:**

1.  **类型脚本存在 :** `@deckgl-fiber-renderer/types` 声明所有层的 JSX 元素的后向兼容性
2.  **运行时注册为空 :** 没有手动 `extend()` 电话,调和器不知道如何即兴演奏 `scatterplotLayer`
3.  **副作用导入为 v2 中的无操作 :** 它只显示一个腐烂的警告 - 它不再记录层
4.  **类型脚本无法抓取 :** 类型定义不能保证运行时的行为

**哪些断层 :**

-   您的应用程序不做任何更改或显示错误
-   地图上没有层
-   控制台显示“ 未知元素类型” 错误

#### 移徙战略

**备选案文1:迁移到 v2 语法(建议)**

用通用 `<layer>` 元素 :

```tsx
// ✅ v2 - No registration needed
import { ScatterplotLayer } from "@deck.gl/layers";

<layer
  layer={
    new ScatterplotLayer({
      id: "points",
      data,
      getPosition: (d) => d.coordinates,
    })
  }
/>;
```

**福利:**

-   \* 无需登记 -- -- 立即工作
-   \* \*\* 带有类型推论的完整类型脚本通用词
-   QQ 自动代码分割( 只捆绑导入的层)
-   QQ 自定义层工作, 不设置
-   \* 未来防(v3中去掉的v1语法)

**备选案文2:坚持v1语法(不建议)**

如果您必须临时停留在 v1 语法上, 您需要使用手动注册层 `extend()`。 。 。 .

**用于完整 v1 行为** (所有默认层):

```tsx
// Recreate v1 side-effects behavior manually
import { extend } from "@deckgl-fiber-renderer/dom";
import {
  FirstPersonView,
  _GlobeView as GlobeView,
  MapView,
  OrbitView,
  OrthographicView,
} from "@deck.gl/core";
import {
  GeohashLayer,
  GreatCircleLayer,
  H3ClusterLayer,
  H3HexagonLayer,
  MVTLayer,
  QuadkeyLayer,
  S2Layer,
  TerrainLayer,
  Tile3DLayer,
  TileLayer,
  TripsLayer,
  _WMSLayer as WMSLayer,
} from "@deck.gl/geo-layers";
import {
  ArcLayer,
  BitmapLayer,
  ColumnLayer,
  GeoJsonLayer,
  GridCellLayer,
  IconLayer,
  LineLayer,
  PathLayer,
  PointCloudLayer,
  PolygonLayer,
  ScatterplotLayer,
  SolidPolygonLayer,
  TextLayer,
} from "@deck.gl/layers";
import { ScenegraphLayer, SimpleMeshLayer } from "@deck.gl/mesh-layers";

// Register all layers
extend({
  // Views
  MapView,
  OrthographicView,
  OrbitView,
  FirstPersonView,
  GlobeView,
  // @deck.gl/layers
  ArcLayer,
  BitmapLayer,
  IconLayer,
  LineLayer,
  PointCloudLayer,
  ScatterplotLayer,
  ColumnLayer,
  GridCellLayer,
  PathLayer,
  PolygonLayer,
  GeoJsonLayer,
  TextLayer,
  SolidPolygonLayer,
  // @deck.gl/geo-layers
  S2Layer,
  QuadkeyLayer,
  TileLayer,
  TripsLayer,
  H3ClusterLayer,
  H3HexagonLayer,
  Tile3DLayer,
  TerrainLayer,
  MVTLayer,
  MvtLayer: MVTLayer,
  WMSLayer,
  WmsLayer: WMSLayer,
  GeohashLayer,
  GreatCircleLayer,
  // @deck.gl/mesh-layers
  ScenegraphLayer,
  SimpleMeshLayer,
});

// Now v1 syntax works
<scatterplotLayer id="points" data={data} />;
```

**最低限度登记** (只需要层):

```tsx
// Register only what you use
import { extend } from "@deckgl-fiber-renderer/dom";
import { ScatterplotLayer, PathLayer } from "@deck.gl/layers";

extend({ ScatterplotLayer, PathLayer });

// Now these specific layers work
<scatterplotLayer id="points" data={data} />
<pathLayer id="routes" data={routes} />
```

**下行停留在v1上:**

-   QQ 在开发模式中显示折旧警告
-   QQ 将在 v3( 完全删除) 中断开
-   QQ 不支持类型脚本通用
-   如果您使用完整的注册, 则将所有层都装入
-   QQ 容易忘记注册层( 运行时间错误)

#### 移徙清单

从 v1 移到 v2 :

1.  **删除副作用导入** (v2中的禁区):
    
    ```tsx
    // ❌ Remove this - doesn't work anymore
    import "@deckgl-fiber-renderer/reconciler/side-effects";
    ```
    
2.  **导入层构造器 :**
    
    ```tsx
    // ✅ Add explicit imports
    import { ScatterplotLayer, PathLayer } from "@deck.gl/layers";
    ```
    
3.  **替换图层元素 :**
    
    ```tsx
    // ❌ Old
    <scatterplotLayer id="points" data={data} getPosition={(d) => d.coordinates} />
    
    // ✅ New
    <layer layer={new ScatterplotLayer({ id: "points", data, getPosition: (d) => d.coordinates })} />
    ```
    
4.  **删除 `extend()` 电话** (不再需要)
    
5.  **添加类型脚本通用** (可选但建议):
    
    ```tsx
    type DataPoint = { coordinates: [number, number]; value: number };
    
    <layer
      layer={
        new ScatterplotLayer<DataPoint>({
          id: "points",
          data,
          getPosition: (d) => d.coordinates, // d typed as DataPoint
        })
      }
    />;
    ```
    

* * *

## 额外资源

-   **deck.gl 文档 :** [https://deck.gl/docs (中文(简体) )](https://deck.gl/docs)
-   **deck.gl 实例 :** [https://deck.gl/examples (英语)](https://deck.gl/examples)
-   **反应调试器 :** [https://github.com/facebook/react/tree/main/packages/react-reconciler 页面存档备份,存于互联网档案馆 (简体中文)](https://github.com/facebook/react/tree/main/packages/react-reconciler)
-   **源代码 :** [https://github.com/deckgl-fiber-renderer/fiber.gl 页面存档备份,存于互联网档案馆](https://github.com/deckgl-fiber-renderer/fiber.gl)

## 常见问题

### @deckgl-fiber-renderer/dom 是什么？

Deck\.gl 的反相渲染器

### 如何安装 @deckgl-fiber-renderer/dom？

在项目目录运行 npm install @deckgl-fiber-renderer/dom，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deck\.gl/core（\>=9\.1）、@deck\.gl/geo-layers（\>=9\.1）、@deck\.gl/layers（\>=9\.1）、@deck\.gl/mapbox（\>=9\.1）、@deck\.gl/mesh-layers（\>=9\.1）、react（^19）、react-dom（^19）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @deckgl-fiber-renderer/dom 支持 TypeScript 吗？

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

### @deckgl-fiber-renderer/dom 支持 ESM 还是 CommonJS？

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

### @deckgl-fiber-renderer/dom 可以商用吗？

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

### @deckgl-fiber-renderer/dom 的下载量有多少？

根据 npm 官方下载统计，@deckgl-fiber-renderer/dom 在 2026/10/12 – 2026/11/10 这 30 天内被下载 36,015 次，日均约 1,201 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @deckgl-fiber-renderer/dom 还在维护吗？

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

