@supermapgis/clientx

@supermapgis/clientx 是基于WebGL/WebGPU技术实现的二三维一体化GIS网络客户端开发平台，依托统一API融合二维和三维能力，深度对接SuperMap iServer服务，打造流畅统一的交互体验，可快速构建无插件、跨系统、跨设备、跨浏览器的二三维一体化WebGIS应用。

主要特性

• 双渲染后端：同时支持WebGL与WebGPU
• 跨平台：无需安装任何浏览器插件，主流浏览器即可运行，一次开发，即可在多操作系统、多设备上直接复用
• 全功能：无缝对接SuperMap iServer发布的多种服务，兼容S3M 3D Tiles、WMTS、MVT等标准格式，支持接入地图、影像、地形、倾斜摄影三维模型、BIM、3DGS、精模、场数据、体数据等多类型数据、提供丰富的二三维空间分析与查询能力
• 源码级发布：以 ESM 源码（SourceRelease/）形式提供，支持打包器按需加载与tree-shaking
• TypeScript 类型：内置 .d.ts 类型定义，开发体验友好

安装

npm install @supermapgis/clientx

注意： 需在项目根目录 package.json 中配置 overrides 固定依赖版本，避免安装异常版本：

"overrides": {
  "@zip.js/zip.js": "2.7.57",
  "xlsx": "https://cdn.sheetjs.com/xlsx-0.19.3/xlsx-0.19.3.tgz"
}

快速上手

import * as ClientX from '@supermapgis/clientx';

const viewer = new ClientX.Viewer('Container', {});

工程化集成（推荐）

SDK 运行时依赖 WASM、Worker、Widget CSS 等静态资源（位于 Build/ClientX/），并通过 window.SUPERMAP3D_BASE_URL 定位资源。推荐使用官方构建插件：Vite 项目接入后零配置即可使用；Webpack 项目只需按示例补充少量构建配置，其余静态资源代理、复制等工作由插件自动完成。

Vite 项目

npm install @supermapgis/vite-plugin-loadsdk -D

// vite.config.js
import { defineConfig } from 'vite';
import SuperMapLoadSDKVitePlugin from '@supermapgis/vite-plugin-loadsdk';

export default defineConfig({
  base: './',
  plugins: [SuperMapLoadSDKVitePlugin({ target: 'clientx' })],
});

常用配置项：

| 配置项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | target | 'clientx' \| 'iclient3d' | 'clientx' | 目标 SDK 包 | | baseUrl | string | 自动计算 | 覆盖 SUPERMAP3D_BASE_URL，未设置时根据 vite base 自动计算（部署到 CDN 时可指定） | | isAddWidgetCSS | boolean | true | 是否自动注入 Widget CSS link 标签 | | staticAssets | object | { filter: false, keepFiles: [] } | 静态资源复制控制；filter: true 时仅拷贝 keepFiles（glob 规则）匹配的文件，减小产物体积 |

Webpack 项目

npm install @supermapgis/webpack-plugin-loadsdk -D

// webpack.config.js
const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
const SuperMapLoadSDKWebpackPlugin = require('@supermapgis/webpack-plugin-loadsdk');

module.exports = (env, argv) => ({
  entry: './src/index.js',
  output: {
    filename: 'bundle/bundle.js',
    chunkFilename: 'bundle/[name].[contenthash:8].js',
    assetModuleFilename: 'assets/[contenthash][ext][query]',
    publicPath: argv.mode === 'development' ? '/' : './',
    path: path.resolve(__dirname, 'dist'),
    clean: true,
  },
  module: {
    rules: [
      { test: /\.css$/, use: ['style-loader', 'css-loader'] },
      { test: /\.(wasm|hdr|ktx2|terrain|glb|gltf|png|jpg|svg|xml|json)$/, type: 'asset/resource' },
      // SourceRelease 的 import 路径省略了 .js 扩展名，需关闭 fullySpecified 兼容
      { test: /\.m?js$/, resolve: { fullySpecified: false } },
    ],
    // 禁用 AMD 解析，避免 sprintfjs 的 "define cannot be used indirect" 错误
    parser: { javascript: { amd: false } },
  },
  plugins: [
    new HtmlWebpackPlugin({ template: './index.html' }),
    new SuperMapLoadSDKWebpackPlugin({ target: 'clientx' }),
  ],
  devServer: {
    // devServer.static 必须配置，插件在其上追加 SDK 资源目录映射
    static: { directory: path.resolve(__dirname, 'dist') },
    hot: true,
    port: 8085,
    open: true,
  },
  resolve: {
    mainFields: ['module', 'browser', 'main'],
    symlinks: false,
  },
  experiments: {
    asyncWebAssembly: true,
  },
});

注意： resolve、parser、experiments、devServer 等配置插件不会自动注入，需按上例手动配置（尤其 devServer.static，缺失会导致静态资源 404）。

常用配置项：

| 配置项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | target | 'clientx' \| 'iclient3d' | 'clientx' | 目标 SDK 包 | | baseUrl | string | 自动计算 | 覆盖 SUPERMAP3D_BASE_URL，dev 用 /ClientX/，build 用 ./ClientX/ | | isAddWidgetCSS | boolean | true | 是否自动注入 Widget CSS link 标签 | | preventDebug | boolean | true | dev 模式禁用 SDK 源码调试（关闭 source map）；排查问题时可设为 false | | staticAssets | object | { filter: false, keepFiles: [] } | 静态资源复制控制，同 Vite 插件 |

插件自动完成的工作

| 工作 | Vite 插件 | Webpack 插件 | | --- | --- | --- | | 静态资源代理（/ClientX/ → node_modules/@supermapgis/clientx/Build/ClientX/） | dev / preview 服务器中间件 | 追加到 devServer.static | | 设置 window.SUPERMAP3D_BASE_URL | 自动注入 HTML | 自动注入 bundle | | 注入 Widget CSS | 自动（受 isAddWidgetCSS 控制） | 自动（受 isAddWidgetCSS 控制） | | resolve.mainFields | 自动配置为 ['module', 'browser', 'main'] | 需手动配置（见上方示例） | | CJS / Node.js fs 兼容 | optimizeDeps 预打包 + fs 空模块别名 | resolve.fallback（fs: false、path: false） | | 构建后复制静态资源 | Assets、Workers、ThirdParty、Widgets、language、ReactiveWidgets、SkyAtmosphereSystem（全量或按 glob 过滤） | 同左 |

Webpack 插件还额外处理：悬空 import / bare import 空模块回退、混淆导出名不一致降级为警告、路径大小写规范化、dev 模式防调试保护（preventDebug）。

用户代码

插件配置完成后，业务代码无需任何手动设置：

// 全量导入
import * as ClientX from '@supermapgis/clientx';
const viewer = new ClientX.Viewer('Container', {});

// 按需导入（利用 tree-shaking 减小产物体积）
import { Viewer, Cartesian3 } from '@supermapgis/clientx';
const viewer = new Viewer('Container', {});
const c3 = Cartesian3.fromDegrees(116.45, 39.91, 5);

依赖更新后页面未生效时，清除构建缓存后重启：Vite 删除 node_modules/.vite 并执行 npm run dev -- --force；Webpack 删除 node_modules/.cache。

完整配置项与实现原理详见：

• @supermapgis/vite-plugin-loadsdk
• @supermapgis/webpack-plugin-loadsdk

包结构说明

| 目录/文件 | 说明 | | --- | --- | | SourceRelease/ClientX.js | ESM 源码入口（main / module / exports） | | SourceRelease/ClientX.d.ts | TypeScript 类型定义入口 | | Build/ClientX/ | 运行时静态资源：WASM、Worker 脚本、纹理、Widget CSS、语言包等 | | LICENSE.md | 许可证与第三方组件声明 |

文档与示例

• 在线示例与文档：https://www.supermapol.com/webgl/web/index.html

License

Apache-2.0。本项目包含的第三方组件及其许可证声明详见 LICENSE.md。