pit-gis-frame-webgl-web

v0.0.2

Published

9 days ago

> 基于 **Lit + Web Components + SuperMap3D** 的三维 GIS 组件库与演示工程。

0High
0Medium
0Low

chendm

pit-gis-frame-webgl-web

基于 Lit + Web Components + SuperMap3D 的三维 GIS 组件库与演示工程。

pit-gis-frame-webgl-web 旨在把原有 GIS 业务能力沉淀为一套与宿主框架低耦合、可独立集成、可持续迁移的 Web Components 方案。项目目前已具备主地图容器、图层控制、标绘、卷帘、分屏、压平管理、场景设置、自定义漫游等核心能力，并保留了对复杂业务扩展的接入空间。

为什么值得关注

框架无关：以 Custom Elements 为交付形态，可集成到原生 HTML、Vue、React 或其他宿主环境
核心与 UI 解耦：GIS 逻辑沉淀在 packages/gis-core，基础 UI 能力沉淀在 packages/pit-ui
Light DOM 友好：组件不启用 Shadow DOM，便于业务项目直接覆盖样式
支持运行时注入：可通过 configure() 注入 request、message、getProjectId 等依赖
适合迁移式重构：保留原有复杂 GIS 场景的对接能力，方便从历史项目平滑迁移

能力概览

当前项目已支持或部分支持以下能力：

三维场景初始化与加载
图层控制 / 标绘图层控制
默认视角 / 视角保存
距离、面积、高度测量
坐标查询
场景设置
地图底图切换
地表透明 / 一键地表透明
卷帘 / 分屏
自定义漫游
压平管理 / 压平模式
三维标绘 / 标绘图例 / 新增标绘
模型开挖 / 模型裁剪 / 模型压平 / 模型还原

项目状态

项目处于持续迁移与工程化完善阶段，主干功能已具备较强可用性，适合：

内部业务系统集成
组件化封装输出
历史 GIS 工程去框架化改造

当前仍建议在正式对外发布前重点验证以下能力：

快照相关面板
FPF 漫游面板
图层拉高面板
个别历史交互细节在迁移后的行为一致性

换句话说：主线路已经能跑，支线还值得再精修一下。

技术栈

组件模型：Web Components
渲染层：Lit
构建工具：Vite
请求库：axios
GIS 引擎：SuperMap3D（由业务侧或静态资源提供）

快速开始

环境要求

Node.js 18+
npm 9+
可访问的 SuperMap3D 静态资源
可联调的后端 GIS 服务

安装依赖

npm install

准备 SuperMap3D 静态资源

请确保以下资源存在：

public/Build/SuperMap3D/
public/Build/SuperMap3D/Widgets/widgets.css
public/Build/SuperMap3D/SuperMap3D.js
public/Build/SuperMap3D/ThirdParty/Workers/MGIS_SuperMap3D/MGIS_SuperMap3D.js

若缺少上述资源，主组件将无法正常初始化。

配置本地代理

开发环境下，项目会将 /api 请求代理到后端服务。

当前配置位于 vite.config.js：

代理前缀：/api
目标地址：server.proxy['/api'].target

开始联调前，请根据实际后端环境调整该地址。

启动开发服务器

npm run dev

默认示例页面：

http://localhost:5173/：主 GIS 示例页
http://localhost:5173/pit-gis-toolbar-demo.html：工具栏联动示例
http://localhost:5173/pit-ui-demo.html：基础 UI 组件示例

构建发布产物

npm run build

构建后将输出库模式产物到 dist/，包含 ES / UMD 格式脚本与样式文件，适合集成到宿主项目中。

5 分钟接入示例

1. 页面引入

<link rel="stylesheet" href="/Build/SuperMap3D/Widgets/widgets.css" />
<script src="/Build/SuperMap3D/SuperMap3D.js"></script>
<script src="/Build/SuperMap3D/ThirdParty/Workers/MGIS_SuperMap3D/MGIS_SuperMap3D.js"></script>

<pit-gis-super-map
  id="gisMap"
  need-api="/api"
  tool-bar-visible
  style="width:100%;height:100vh;"
></pit-gis-super-map>

<script type="module" src="/src/index.js"></script>

2. 注入运行时依赖

import { createRequest } from '/src/utils/request.js';

const map = document.getElementById('gisMap');

map.gisInitParameter = {
  navigation: false,
  scene3DOnly: true,
  animation: true,
  selectionIndicator: true,
};

const showMessage = (msg, type) => {
  console.log(`[${type}]`, msg);
};

map.configure({
  getProjectId: () => 'your-project-id',
  request: createRequest({
    token: 'your-token',
    message: showMessage,
  }),
  message: showMessage,
});

3. 监听事件

map.addEventListener('onInitGis', () => {
  console.log('GIS 初始化完成');
});

map.addEventListener('onSceneViewLoaded', () => {
  console.log('场景加载完成');
});

map.addEventListener('onSceneLeftClick', (event) => {
  console.log('场景左键点击', event.detail);
});

map.addEventListener('onLayerControlLoaded', (event) => {
  console.log('图层控制加载完成', event.detail);
});

对外暴露的核心内容

主组件

项目对外注册的核心组件为：

pit-gis-super-map

它负责：

初始化 SuperMap3D 容器
接收属性与业务注入配置
绑定 GIS 场景事件
管理右键菜单与属性弹窗
协调各类业务面板显隐
向宿主暴露统一的交互方法

入口导出

src/index.js 在注册组件的同时导出以下符号：

| 导出项 | 说明 | | --- | --- | | pitGisGetConfigInfo | 获取 GIS 配置对象 | | PIT_GIS_TOOL_TYPE | GIS 工具栏类型常量 | | pitGis | 核心 GIS API 句柄 | | PitButton | pit-ui 按钮组件类 | | PitInput | pit-ui 输入组件类 | | PitDialog | pit-ui 对话框组件类 | | PitTree | pit-ui 树组件类 | | PitForm | pit-ui 表单组件类 | | PitFormItem | pit-ui 表单项组件类 |

主组件 API 概览

属性（Properties / Attributes）

| 属性名 | 类型 | 对应 attribute | 说明 | | --- | --- | --- | --- | | needApi | String | need-api | 接口前缀 | | toolBarVisible | Boolean | tool-bar-visible | 是否显示工具栏 | | gisInitParameter | Object | - | GIS 初始化参数 | | hiddenToolbar | Array | - | 需要隐藏的工具项 | | extendTool | Array | - | 扩展工具栏项 | | extendERMenu | Array | - | 实体右键扩展菜单 | | extendLRMenu | Array | - | 图层右键扩展菜单 | | extendQueryLayer | Object | - | 图层扩展查询 | | extendQueryDrawing | Object | - | 标绘扩展查询 | | extendQueryCustomizeRoam | Object | - | 自定义漫游扩展查询 | | extendQueryRoam | Object | - | 漫游扩展查询 | | extendQuerySnapshot | Object | - | 快照扩展查询 | | extendQueryFlatten | Object | - | 压平扩展查询 |

复杂对象建议通过 DOM property 赋值，而不是字符串 attribute。

事件（CustomEvent）

| 事件名 | 说明 | | --- | --- | | onInitGis | GIS 初始化完成 | | onSceneViewLoaded | 场景视图加载完成 | | onSceneLeftClick | 场景左键点击 | | onLayerControlLoaded | 图层控制数据加载完成 | | onPlottingControlLoaded | 标绘控制数据加载完成 | | onExtendEntityInfo | 扩展实体信息事件 | | onExtendRMenuClick | 扩展右键菜单项点击 |

方法（Methods）

| 方法名 | 说明 | | --- | --- | | configure(opts) | 注入 request、message、getProjectId 等运行时依赖 | | getPitGis() | 获取核心 GIS API 句柄 | | handleChangeSideBar(key) | 响应业务工具栏点击 | | changeToolBarVisible(val) | 切换工具栏显示状态 | | changeToolBarVisble(val) | changeToolBarVisible 的兼容拼写 | | changePlottingControlVisible(val) | 打开或关闭标绘控制面板 | | addPlottingControlData(val) | 新增标绘数据 | | deletePlottingControlData(detailId) | 删除标绘数据 |

更完整的中文 API 说明见 docs/API.md。

请求适配

项目通过 src/utils/request.js 提供与业务环境兼容的请求封装，默认支持：

自动注入 Authorization token
GET 请求将 data 转为 params
自动追加时间戳参数防缓存
按 { code, data, msg } 结构处理业务响应
以 code === "00000" 作为成功标记

如果你的后端响应结构不同，可按需调整 createRequest() 的实现。

项目结构

pit-gis-frame-webgl-web/
├─ docs/                       # 迁移说明、主题文档、API 文档
├─ packages/
│  ├─ gis-core/                # GIS 核心逻辑
│  └─ pit-ui/                  # 基础 UI 组件
├─ public/
│  ├─ Build/SuperMap3D/        # SuperMap3D 静态资源
│  └─ images/                  # 标绘与业务图片资源
├─ src/
│  ├─ components/              # 主业务组件与子组件
│  ├─ utils/request.js         # 业务请求适配
│  ├─ index.css                # 全局样式
│  └─ index.js                 # 组件注册入口
├─ index.html                  # 主 GIS 示例页
├─ pit-gis-toolbar-demo.html   # GIS 工具栏联动示例
├─ pit-ui-demo.html            # pit-ui 独立演示页
├─ pit-ui-demo-app.js          # pit-ui 演示逻辑
├─ vite.config.js              # Vite 开发与构建配置
└─ package.json                # 根包配置

仓库模块说明

`packages/gis-core`

GIS 领域核心能力，包含：

场景初始化
图层管理
标绘能力
漫游能力
压平管理
弹窗与右键菜单
业务 API 封装

`packages/pit-ui`

基础 UI 组件库，可独立使用，当前主要包括：

pit-button
pit-input
pit-dialog
pit-tree
pit-form
pit-tab-pane
pit-tabs
pit-color-picker
pit-slider

文档索引

docs/API.md：中文 API 文档
docs/MIGRATION_PHASE1.md：基础设施迁移说明
docs/MIGRATION_PHASE2.md：属性 / 事件 / 方法映射说明
docs/MIGRATION_PHASE3.md：基础 UI 组件迁移说明
docs/MIGRATION_PHASE4.md：业务组件迁移说明
docs/THEME.md：主题与样式文档

常用脚本

npm run dev
npm run build
npm run preview

适用场景

该项目适合以下场景：

需要在浏览器中快速集成三维 GIS 能力的业务系统
希望以 Web Components 方式向不同宿主框架输出统一 GIS 组件
正在进行旧版 GIS 前端工程的去框架化或组件化重构

致谢

本项目基于现有 GIS 业务能力沉淀与迁移而来，并结合 Lit / Web Components 进行工程化重构。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

pit-gis-frame-webgl-web

为什么值得关注

能力概览

项目状态

技术栈

快速开始

环境要求

安装依赖

准备 SuperMap3D 静态资源

配置本地代理

启动开发服务器

构建发布产物

5 分钟接入示例

1. 页面引入

2. 注入运行时依赖

3. 监听事件

对外暴露的核心内容

主组件

入口导出

主组件 API 概览

属性（Properties / Attributes）

事件（CustomEvent）

方法（Methods）

请求适配

项目结构

仓库模块说明

packages/gis-core

packages/pit-ui

文档索引

常用脚本

适用场景

致谢

`packages/gis-core`

`packages/pit-ui`