globle_3d

一个基于 WebGL 的 3D 地球可视化组件，灵感来源于 卡巴斯基网络威胁实时地图。

✨ 特性

• 🌍 3D 地球渲染：支持球体（globe）和平面（flat）两种视角模式
• 🚀 流畅动画：飞线动画、自动旋转、飞行演示等丰富的动画效果
• 🗺️ 地理数据：内置全球国家/地区数据和中国省级行政单位数据
• 🎨 高度可定制：支持自定义颜色、标签、交互行为等
• 📱 响应式设计：支持桌面端和移动端，自动适配小部件模式
• 💪 TypeScript：完整的 TypeScript 类型定义
• 📦 零依赖渲染：着色器和地理数据内置，无需额外资源

🚀 快速开始

安装

npm install globle_3d

资源文件

安装后需要复制资源文件到项目目录：

cp -rf node_modules/globle_3d/assets ./assets

资源文件包含必要的纹理图片，用于地图渲染。

基础使用

import { globle_init } from 'globle_3d';

const canvas = document.getElementById('canvas') as HTMLCanvasElement;

const globle = globle_init({
    canvas,
    quality: 'high',
    view_mode: 'globe',
    showMapLabels: true,
    data_fetcher: async () => {
        // 返回飞线数据
        return [
            {
                from: '15644',  // 来源地区编码（省级行政单位）
                to: '15663',    // 目标地区编码
                flow: 100,      // 流量值
                type: 0         // 飞线类型（可选）
            }
        ];
    },
    onInit: (gl, env) => {
        console.log('初始化完成');
    },
    onPopupCountry: (country) => {
        if (country) {
            console.log('选中国家:', country.name);
        }
    }
});

预览图：

📖 API 文档

globle_init(options: InitOptions)

初始化 3D 地球组件。

必需参数

• canvas (HTMLCanvasElement): 用于渲染的 canvas 元素
• data_fetcher (() => Promise<FlowDataItem[]>): 数据获取函数，返回飞线数据数组

可选参数

完整配置选项请参考 src/globle/interface.ts

渲染配置

• quality ('high' | 'low'): 渲染质量，默认 'high'

  • high: 高质量渲染，启用抗锯齿
  • low: 低质量渲染，提升性能

• view_mode ('globe' | 'flat'): 视角模式，默认 'globe'

  • globe: 3D 球体视图
  • flat: 2D 平面视图（墨卡托投影）

交互配置

• is_widget (boolean): 是否为小部件模式，默认 false

  • true: 小部件模式，禁用交互事件，自动适配尺寸
  • false: 完整模式，支持所有交互功能

• allowInteraction (boolean): 是否允许鼠标/触摸交互，默认 true

数据配置

• systems (string[]): 飞线类型颜色数组，默认 ['38b349', 'ed1c24', 'f26522', '0087f4', 'ec008c', 'fbf267']

  • 每个颜色对应一种飞线类型，使用十六进制颜色值（不含 #）

• center ({ name: string, coord?: [number, number] }): 地图中心点

  • name: 国家/地区名称或省级行政单位名称
  • coord: 可选，自定义坐标 [经度, 纬度]

显示配置

• showMapLabels (boolean): 是否显示地区名称标签，默认 true

• labelShowSize (number): 最小字体显示阈值，默认 5

  • 值越小，显示的国家/地区名称越多
  • 默认值约显示国土面积全球前十的国家

• showCountryPopup (boolean): 是否支持选择国家弹出，默认 false

动画配置

• demoEnabled (boolean): 是否启用自动旋转效果，默认 false

• demoFlightEnabled (boolean): 是否启用飞行演示效果，默认 false

资源配置

• resource_baseurl (string): 资源文件路径前缀，默认 '/assets/'

地图元素配置

• USE_GRID (boolean): 是否加载球体网格，默认 true
• USE_MAP (boolean): 是否加载完整地图，默认 true
• USE_LINES (boolean): 是否加载边境线，默认 true
• USE_COAST (boolean): 是否加载海岸线，默认 true
• USE_BORDER (boolean): 是否加载网格线，默认 true
• USE_MARKER (boolean): 是否显示中心点标记，默认 false

回调函数

• onInit ((gl: WebGLRenderingContext, env: Env) => void): 初始化完成回调

• onFail ((err: Error) => void): 初始化失败回调（如 WebGL 不支持）

• onPopupCountry ((country: FaceCountry | null, setup_connector_line?: Function) => void): 国家选择回调

  • country: 选中的国家信息，null 表示取消选择
  • setup_connector_line: 可选，用于绘制连接线的函数

• onStateChange ((state: AnimationState) => void): 动画状态变化回调

• onViewModeChange ((mode: ViewMode) => void): 视角模式变化回调

返回对象方法

初始化后返回的对象包含以下方法：

• set_view(mode: ViewMode): 切换视角模式

  globle.set_view('flat');  // 切换到平面视图
  globle.set_view('globe'); // 切换到球体视图

• set_demo(enabled: boolean): 启用/禁用演示模式

  globle.set_demo(true);  // 启用自动旋转
  globle.set_demo(false); // 禁用演示

• set_popup_country(country: FaceCountry | null): 设置弹出显示的国家

• highlightCountries(getColor: Function): 高亮指定国家

  globle.highlightCountries((countries) => {
      return countries.map((country, index) => {
          if (country.iso2 === 'CN') {
              return {
                  index,
                  country,
                  color: [1, 0, 0] // RGB 颜色值 [0-1]
              };
          }
          return null;
      });
  });

• locateTo(code: string, change_marker?: boolean, reset_zoom?: boolean): 定位到指定地区

  globle.locateTo('15644', true, true); // 定位到广东省

📝 数据格式

FlowDataItem

飞线数据项接口：

interface FlowDataItem {
    /** 来源: 省级行政单位编码（来自 provinces.json） */
    from: string;
    /** 目标: 省级行政单位编码 */
    to: string;
    /** 流量值 */
    flow: number;
    /** 飞线类型（可选，对应 systems 数组索引） */
    type?: number;
}

🛠️ 开发

构建

npm run build

开发模式

npm run dev

构建地理数据

npm run build:globle

📦 技术栈

• TypeScript: 类型安全的开发体验
• WebGL: 高性能 3D 渲染
• gl-matrix: 矩阵和向量运算
• ESModule: 标准模块系统

🔄 主要改进

相比原始卡巴斯基地图代码，本项目进行了以下优化：

• ✅ 全部改写为标准 ESModule 模块，封装所有全局变量方法
• ✅ 使用 TypeScript 重写，添加完善的接口定义和类型检查
• ✅ 删除所有非 canvas 渲染部分组件，保留接口支持外部关联
• ✅ 优化入口参数，提供更多详细配置选项
• ✅ 着色器代码内置，无需额外引入
• ✅ 全球国家/地区 GeoJSON 数据内置，无需额外引入
• ✅ 添加中国省级行政单位数据，与全球国家保持同一级别展示
• ✅ 添加国家高亮函数配置功能

📄 许可证

MIT

👤 作者

shy2850