企业官网建设流程全解析

在 deck.gl 中使用 TypeScript：从 v9 官方类型到 v8 与旧版本的完整类型方案指南

【免费下载链接】deck.glWebGL2 powered visualization framework项目地址: https://gitcode.com/GitHub_Trending/de/deck.gl

deck.gl 是一个基于 WebGL2 的开源数据可视化框架，从 v9 开始官方为全部模块发布了一等公民的 TypeScript 类型支持；本文将以 docs/get-started/using-with-typescript.md 为主线，完整覆盖 v9+ 的官方类型用法、v8.x 的typed预览入口，以及 v8.8 之前依赖第三方类型库@danmarshall/deckgl-typings的迁移方案，并结合仓库源码验证各版本类型导出的真实实现，帮助你为项目选择并落地最合适的类型接入方式。

deck.gl v9+：官方类型开箱即用

从 deck.gl v9.0 开始，官方为所有模块发布了 TypeScript 类型声明。只要你的项目启用了 TypeScript，直接导入@deck.gl/*包即可自动获得完整的类型提示、编译期检查和编辑器自动补全，无需任何额外配置。

值和类型分开导入

官方推荐的用法是将「运行时的值」与「纯类型」分开导入，前者参与打包执行，后者仅在编译期使用，可以被编译器完全擦除：

// 值（运行时使用） import {DeckGL} from '@deck.gl/react'; import {GeoJsonLayer} from '@deck.gl/layers'; // 纯类型（仅编译期使用，可被擦除） import type {DeckGLRef} from '@deck.gl/react'; import type {GeoJsonLayerProps} from '@deck.gl/layers';

v9 类型为什么能“开箱即用”：包级类型声明的源码依据

从当前仓库的源码可以确认，v9 的每个模块在发布时都内置了类型声明文件。以核心模块为例，其package.json中直接声明了顶层类型入口：

• modules/react/package.json 中"types": "dist/index.d.ts"，exports字段的"."条件里也配置了"types": "./dist/index.d.ts"；
• modules/layers/package.json 同样声明"types": "dist/index.d.ts"；
• 聚合入口 modules/main/package.json（包名为deck.gl）同样通过"types": "dist/index.d.ts"暴露类型。

这意味着 TypeScript 解析@deck.gl/react、@deck.gl/layers或deck.gl时，会直接命中dist/index.d.ts，而无需借助@types/*之类的第三方声明包。

类型定义的源头在源码中：例如 modules/layers/src/index.ts 从各 Layer 实现文件里export type出ArcLayerProps、GeoJsonLayerProps、TextLayerProps、PathLayerProps等全部图层属性类型；modules/react/src/index.ts 则导出DeckGLRef、DeckGLProps等 React 绑定相关类型。这些src目录下的类型声明会随发布流程被打包进dist/index.d.ts，形成你导入时看到的最终类型。

常用的 v9 官方类型一览

DeckGLProps与DeckGLRef是 React 集成中最常引用的两个类型，其真实定义见 modules/react/src/deckgl.ts：

// DeckGL React 组件 props（对基类 DeckProps 做了裁剪并补充 React 专属字段） export type DeckGLProps<ViewsT extends ViewOrViews = null> = Omit< DeckProps<ViewsT>, 'width' | 'height' | 'gl' | 'parent' | 'canvas' | '_customRender' > & { Deck?: typeof Deck; width?: string | number; height?: string | number; children?: React.ReactNode | DeckGLRenderCallback; ref?: React.Ref<DeckGLRef<ViewsT>>; ContextProvider?: React.Context<DeckGLContextValue>['Provider']; }; // 通过 ref 暴露 Deck 实例与拾取方法 export type DeckGLRef<ViewsT extends ViewOrViews = null> = { deck?: Deck<ViewsT>; pickObjectAsync: Deck['pickObjectAsync']; pickObjectsAsync: Deck['pickObjectsAsync']; pickObject: Deck['pickObject']; pickObjects: Deck['pickObjects']; pickMultipleObjects: Deck['pickMultipleObjects']; };

由定义可见，DeckGLProps通过Omit屏蔽了基类DeckProps中与 React 接管生命周期相冲突的字段（如外部传入的gl、canvas、parent等），并补上了width/height（支持字符串或数字）、children以及ContextProvider等 React 特性；DeckGLRef则把 Deck 实例和pickObject/pickObjects/pickMultipleObjects等拾取 API 一并暴露给 ref，方便在事件回调或副作用中调用。

各图层属性类型同样可以从源码定位：例如GeoJsonLayerProps定义于 modules/layers/src/geojson-layer/geojson-layer.ts，ScatterplotLayerProps定义于 modules/layers/src/scatterplot-layer/scatterplot-layer.ts，其泛型参数（如GeoJsonLayerProps<DataT>）让data、getFillColor等访问器函数的入参也能获得精确推断。

如果你使用deck.gl聚合包（modules/main/src/index.ts），所有子模块的类型也会被统一 re-export，包括DeckProps、LayerProps、PickingInfo、MapViewState及各图层*LayerProps，方便从单一入口消费全部类型。

deck.gl v8：使用typed预览入口接入官方类型

v8 时代（v8.8 起）deck.gl 以「公开预览」的形式发布官方类型，但它不会默认暴露在包根，而是通过一个typed子路径入口提供，属于 opt-in（主动选择）式的接入。这样设计的目的是防止尚不完善的类型声明破坏既有 TypeScript 应用的编译。

迁移步骤：把包名替换为/typed后缀

假设你的应用当前是这样导入的：

import {DeckGL} from '@deck.gl/react'; import {GeoJsonLayer} from '@deck.gl/layers';

只需把包名替换为@deck.gl/<模块名>/typed：

import DeckGL from '@deck.gl/react/typed'; import {GeoJsonLayer} from '@deck.gl/layers/typed';

注意@deck.gl/react/typed默认导出的DeckGL组件不带花括号；@deck.gl/layers/typed仍保留命名导出。

同样可以按需导入附加的类型定义：

import type {DeckGLRef} from '@deck.gl/react/typed'; import type {GeoJsonLayerProps} from '@deck.gl/layers/typed';

迁移注意事项

• 工作仍在进行中：v8 的 typed 导出属于预览性质，可能存在不完整或待修正的类型；
• 默认不暴露的原因：官方刻意让类型在 v8 中保持 opt-in，避免类型错误破坏现有 TypeScript 应用；
• 版本路线图：官方明确说明，typed入口将在整个 8.x 系列中持续保留，并自 v9.0 起直接暴露在包根（即上文所述的开箱即用方案）；
• 升级到 v9 后，应把@deck.gl/<module>/typed恢复为@deck.gl/<module>，同时将import DeckGL from ...的默认导入改回import {DeckGL} from ...的命名导入。

旧版本（v8.8 之前）：第三方类型库@danmarshall/deckgl-typings

如果你仍在使用 v8.8 之前的 deck.gl 版本，官方尚未提供任何内置类型，此时社区维护的@danmarshall/deckgl-typings是可行的替代方案。

版本对应关系

根据你的 deck.gl 版本选择配套的 deckgl-typings 主版本：

安装与声明合并

以 deck.gl 7.x 为例，安装对应主版本的类型包：

npm install @danmarshall/deckgl-typings@^3.0.0

然后在源码目录中新建一个声明文件（如deckgl.d.ts），内容如下：

import * as DeckTypings from "@danmarshall/deckgl-typings" declare module "deck.gl" { export namespace DeckTypings {} }

其原理是利用 TypeScript 的声明合并（declaration merging）机制，在deck.gl模块的声明空间中并入第三方类型库的命名空间，从而让import * as Deck from 'deck.gl'获得补全后的类型。

旧方案的使用注意

• 该库由社区维护，与官方发布节奏存在天然的时间差，新版本 deck.gl 上线初期可能暂无配套类型；
• 它主要面向旧的deck.gl单一聚合包，如果你已经在用@deck.gl/core、@deck.gl/layers等细分包，请优先考虑升级到 v8.8+ 使用官方typed入口，或直接升级到 v9；
• 在向 v9 迁移时，记得删除该声明文件与@danmarshall/deckgl-typings依赖，改回官方原生类型。

如何选择适合你的类型方案

结合版本与项目现状，可以按以下决策路径选择：

1. v9.0 及以上：直接使用官方类型，import {DeckGL} from '@deck.gl/react'即自带类型，无需任何额外配置；需要组件 props 或 ref 类型时使用import type引入DeckGLProps、DeckGLRef、GeoJsonLayerProps等；
2. v8.8 ~ v8.x：把导入路径替换为@deck.gl/<module>/typed，享受官方预览类型，待升级 v9 后再移除/typed后缀；
3. v8.8 之前：通过@danmarshall/deckgl-typings按版本对应表接入社区类型；有条件的项目建议直接升级到 v9，以获得最完整、最稳定的类型体验。

小结

deck.gl 的 TypeScript 支持经历了「第三方类型库（5.x~8.x 早期）→ v8 官方预览类型（typed入口，8.8+）→ v9 官方一等公民类型（包根直出）」三个阶段。当前仓库（v9.4.0-beta.4）的源码与发布配置已全面验证 v9 方案的成熟度：所有模块的package.json均内置dist/index.d.ts类型入口，DeckGLProps、DeckGLRef、各图层*LayerProps等类型在 modules/react/src 与 modules/layers/src 中均有完整定义并经 modules/main/src/index.ts 统一对外导出。无论你是新项目选型还是老项目迁移，都可以按本文的版本对应关系与迁移步骤，快速获得编译期安全保障。

【免费下载链接】deck.glWebGL2 powered visualization framework项目地址: https://gitcode.com/GitHub_Trending/de/deck.gl