deck.gl 如何使用 widgets 模块为可视化界面添加缩放、指北针等交互控件【免费下载链接】deck.glWebGL2 powered visualization framework项目地址: https://gitcode.com/GitHub_Trending/de/deck.gl如果你的 deck.gl 可视化页面只有裸的 canvas用户就只能靠鼠标手势控制视图。deck.gl/widgets模块在 canvas 之外提供了一组现成的 UI 控件ZoomWidget放大/缩小、CompressWidget之外的指北针CompassWidget显示方位角与俯仰角并支持点击复位、ScreenshotWidget截图下载、FullscreenWidget全屏切换等通过Deck实例的widgets属性即可挂载。该模块自 deck.gl v9.0 起提供ZoomWidget、CompassWidget、FullscreenWidget为 v9.0ScreenshotWidget自 v9.2zoomStep参数自 v9.4因此需要 deck.gl 9.x 版本。安装与引入安装依赖npm install deck.gl/core deck.gl/widgets也可以在package.json中直接安装完整包deck.gl。在代码中必须同时引入控件样式表deck.gl/widgets/stylesheet.css否则控件没有外观import {Deck} from deck.gl/core; import {ZoomWidget, CompassWidget} from deck.gl/widgets; import deck.gl/widgets/stylesheet.css;把控件挂到 Deck 实例控件以数组形式传给Deck的widgets属性。下面的例子在页面左上角placement默认值top-left放置缩放控件和指北针控件parent指向页面中一个已存在的容器元素import {Deck} from deck.gl/core; import {ZoomWidget, CompassWidget} from deck.gl/widgets; import deck.gl/widgets/stylesheet.css; new Deck({ parent: document.getElementById(deck-root), initialViewState: { longitude: -122.4, latitude: 37.8, zoom: 11, pitch: 45, bearing: 30 }, controller: true, widgets: [ new ZoomWidget({placement: top-left}), new CompassWidget({placement: top-left}) ] });placement可选top-left、top-right、bottom-left、bottom-right、fill用于决定控件在视图内的停靠位置。在 React 项目中同样的控件作为DeckGL的子组件传入import React from react; import {DeckGL, ZoomWidget, CompassWidget} from deck.gl/react; import deck.gl/widgets/stylesheet.css; function App() { return ( DeckGL initialViewState{{longitude: 0, latitude: 52, zoom: 4}} controller ZoomWidget placementtop-left / CompassWidget placementtop-left / /DeckGL ); }验证方式页面渲染后容器左上角应出现对应的按钮鼠标悬停时显示控件的提示文字v9.5 起内置主题化 tooltip。各控件的参数与验证ZoomWidget缩放控件点击放大、-缩小每次按zoomStep改变缩放级别支持 Map 视图和 Globe 视图。常用参数orientation按钮方向默认vertical可选horizontalzoomStep每次点击的缩放增量默认1v9.4 起提供transitionDuration缩放过渡时长毫秒默认200zoomAxis默认all可选X、Y仅在当前视图是OrthographicView时生效onZoom点击回调参数为{viewId, delta, zoom}其中delta为1放大或-1缩小zoom为新的缩放级别。用这个回调打印参数是确认控件确实驱动了视图变化的最直接方式。CompassWidget指北针控件指北针实时显示当前视图的bearing方位角和pitch俯仰角支持MapView和GlobeView。交互规则点击一次将bearing复位为 0再点击第二次将pitch复位为 0。回调onReset会收到{viewId, bearing, pitch}其中bearing为新值 0若bearing原本就是 0 则pitch为 0。验证方式先用initialViewState设置非零的pitch: 45, bearing: 30如上文示例点击指北针两次点击后视图应回到正北、无俯仰的状态。ScreenshotWidget截图控件v9.2 起点击控件后浏览器会将当前 deck.gl 画布截图并下载到用户的下载文件夹。常用参数filename下载文件名默认screenshot.pngimageFormat默认image/png浏览器还可能支持image/jpeg、image/webp、image/avifonCapture允许应用接管截图逻辑用于集成更高级的截图模块。注意文档明确的边界只截取 deck.gl 画布本身画布上下层的 HTML 元素不在截图内例如非交错式底图和控件本身都不会被截到。验证方式点击后在浏览器下载目录中出现对应文件默认名为screenshot.png。FullscreenWidget全屏控件可选点击控件进入或退出全屏默认将地图容器元素设为全屏container参数可指定其他兼容的 DOM 元素。onFullscreenChange(fullscreen)回调在状态变化时触发可用于记录状态。多视图下指定控件归属多视图场景中带 UI 的控件可以通过viewId绑定到具体视图控件会相对该视图定位并且只响应该视图内的事件viewId为null默认时控件位于共享的 widget 根容器接收所有视图的事件。new Deck({ views: [ new MapView({id: left-map}), new MapView({id: right-map}) ], widgets: [ new FullscreenWidget({placement: top-right}), new ZoomWidget({viewId: left-map}), new GimbalWidget({viewId: right-map}) ] });一个容易踩的坑deck.gl 要求每个控件的id唯一默认id基于控件类型。同一类型出现两个实例比如两个ZoomWidget时必须给至少一个显式设置id例如new ZoomWidget({id: tokyo-zoom, viewId: tokyo})。另外默认容器中的控件会被视图级控件覆盖显示同一视图内多个控件注意用不同的placement错开。主题与样式内置控件支持深色和浅色两套外观。跟随系统主题的一种写法import {DarkGlassTheme, LightGlassTheme} from deck.gl/widgets; const prefersDarkScheme window.matchMedia((prefers-color-scheme: dark)); const widgetTheme prefersDarkScheme.matches ? DarkGlassTheme : LightGlassTheme; new Deck({ widgets: [ new ZoomWidget({style: widgetTheme}), new CompassWidget({style: widgetTheme}) ] });主题对整个 deck 实例全局生效不能为不同视图指定不同主题。更细粒度的外观调整走 CSS 变量.deck-widget选择器作用于所有控件.deck-widget-fullscreen这类选择器只作用于指定类型style属性或自定义 class 可以只作用于单个实例。常用变量包括--button-size默认28px、--widget-margin默认12px、--button-background等。每个控件还有专属的图标变量例如缩放控件的--icon-zoom-in/--icon-zoom-out、指北针的--icon-compass可替换为自己的 SVG Data Url。限制与排查要点版本要求widgets 模块整体来自 v9.0ScreenshotWidget来自 v9.2zoomStep来自 v9.4tooltip 主题化来自 v9.5在 8.x 及以下版本中不存在该模块。控件不显示确认引入了deck.gl/widgets/stylesheet.css且parent指向的容器真实存在、有尺寸。zoomAxis只对OrthographicView生效在普通MapView上设置X或Y没有效果。同一类型多个控件未设置唯一id时deck.gl 无法在渲染调用之间匹配控件需要显式传id。截图控件不截取画布外的 HTML 内容和控件本身这是文档明确的行为不是 bug。完整控件清单、自定义控件写法继承Widget类并实现onRenderHTML、onRedraw以及样式变量全表可继续参考 widgets 模块总览、Widget 基类文档、样式指南 和 tooltip 文档。【免费下载链接】deck.glWebGL2 powered visualization framework项目地址: https://gitcode.com/GitHub_Trending/de/deck.gl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考