BIMFlux引擎

接入指南

本文将详细介绍 SDK 的引入与初始化方式，帮助开发者快速搭建开发环境。

环境要求

在开始集成 SDK 前，请确保开发环境满足以下要求，以保证引擎功能正常运行：

  • 浏览器支持：
    • 基础 ES Module 引入：Chrome 61+、Edge 61+、Firefox 60+、Safari 15.0+
    • 结合 Import Maps 引入：Chrome 89+、Edge 89+、Firefox 108+、Safari 15.4+
  • 开发工具：
    • 原生集成：无需构建工具，直接通过浏览器运行
    • 构建工具集成：支持 ESM 模块的构建工具（如 Vite 4.0+、Webpack 5.0+、Rollup 2.0+ 等）
  • 依赖说明：
    • SDK 已包含自身样式，无需单独导入样式文件

现代浏览器原生集成

基础 ESM 方式

基础 ESM 方式是现代浏览器中最直接的集成方式，通过完整的 CDN 路径直接引入 ESM 模块，无需任何额外配置。该方式的优势是简单直观，无需理解模块映射规则，适合快速上手或场景简单的项目。

详细步骤：

  1. 创建 HTML 基础结构 首先创建一个标准的 HTML 文件，在 <head> 标签中引入 SDK 的样式文件，在 <body> 标签中定义用于承载 BIM 场景的容器：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>基础 ESM 方式示例</title>
  <!-- 引入 SDK 样式文件，确保场景UI正常显示 -->
  <link rel="stylesheet" href="https://cdn.dtbim.cn/SDK/latest/sdk.css" >
</head>
<body>
  <!-- 场景容器：宽高设置为占满整个视口 -->
  <div id="app" style="width: 100vw; height: 100vh; margin: 0; padding: 0; overflow: hidden;"></div>
</body>
</html>
  1. 引入并初始化 SDK 在 <body> 标签末尾添加 <script type="module"> 标签，通过完整 CDN 路径引入 SDK 和 UI 组件，并初始化场景：
<script type="module">
  // 从 CDN 加载完整的 SDK 模块，通过命名空间 bimflux 访问所有功能
  import * as bimflux from "https://cdn.dtbim.cn/SDK/latest/sdk.es.js";
  // 引入 UI 组件，组件会自动注册到全局
  import "https://cdn.dtbim.cn/ui-next/latest/index.js";
  // 等待页面 DOM 加载完成后初始化场景
  document.addEventListener("DOMContentLoaded", () => {
    // 初始化场景核心实例
  const scene = new bimflux.Scene("app"); 
  });
</script>

Import Maps 方式

Import Maps 是现代浏览器原生支持的模块映射机制，允许开发者为模块定义别名，从而简化导入路径。这种方式适合需要引入多个模块、或希望代码更简洁易维护的场景，尤其在大型原生项目中能显著提升代码可读性。

详细步骤

  1. 创建 HTML 结构并配置 Import Maps 在 <head> 标签中添加 <script type="importmap"> 标签，定义 SDK 和 UI 组件的别名，同时引入 SDK 样式文件：
  <!DOCTYPE html>
  <html lang="zh-CN">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Import Maps 方式示例</title>
    <!-- 配置 Import Maps：定义模块别名与实际路径的映射关系 -->
    <script type="importmap">
      {
        "imports": {
          // 为 SDK 定义别名
          "@bimflux/sdk": "https://cdn.dtbim.cn/SDK/latest/sdk.es.js",
          // 为 UI 组件定义别名
          "@bimflux/ui": "https://cdn.dtbim.cn/ui-next/latest/index.js"
        }
      }
    </script>
    <!-- 引入 SDK 样式文件 -->
    <link rel="stylesheet" href="https://cdn.dtbim.cn/SDK/latest/sdk.css" >
  </head>
  <body>
    <!-- 场景容器：宽高设置为占满整个视口 -->
    <div id="app" style="width: 100vw; height: 100vh; margin: 0; padding: 0; overflow: hidden;"></div>
  </body>
  </html>
  1. 通过别名引入并初始化 SDK 在 <script type="module"> 标签中，使用 Import Maps 定义的别名替代完整 CDN 路径，简化导入代码：
  <script type="module">
    // 通过别名全量引入 SDK
    import * as bimflux from "@bimflux/sdk";
    // 通过别名引入 UI 组件
    import "@bimflux/ui";
    // 等待页面 DOM 加载完成后初始化场景
    document.addEventListener("DOMContentLoaded", () => {
      // 初始化场景核心实例
    const scene = new bimflux.Scene("app"); 
    });
  </script>

构建工具集成

对于中大型项目或需要复杂工程化管理的场景，推荐使用构建工具集成 SDK。构建工具能提供模块打包、代码压缩、环境变量管理等功能，同时支持通过别名简化导入路径，提升开发效率。

Vite 集成

Vite 是一款基于 ESM 的前端构建工具，对原生 ESM 支持友好，无需额外配置即可直接导入远程 CDN 模块，适合快速开发现代前端项目。

详细步骤：

  1. 创建 Vite 项目（若未创建） 打开终端，执行以下命令创建一个基础 Vite 项目（以 Vue 模板为例，也可选择 React/Vanilla 等框架模板）：
# 创建项目
npm create vite@latest bimflux-vite-project -- --template vue
# 进入项目目录
cd bimflux-vite-project
# 安装依赖
npm install
  1. 配置 Vite 别名（可选但推荐） 为简化导入路径，修改项目根目录下的 vite.config.js 文件，添加 bimflux 模块的别名配置：
// vite.config.js
import { defineConfig } from "vite";
export default defineConfig({
  // 模块解析配置：定义别名
  resolve: {
    alias: {
      // 为 SDK 配置别名
      "@bimflux/sdk": "https://cdn.dtbim.cn/SDK/latest/sdk.es.js",
      // 为 UI 组件配置别名
      "@bimflux/ui": "https://cdn.dtbim.cn/ui-next/latest/index.js",
      // 为 SDK 样式文件配置别名
      "@bimflux/style": "https://cdn.dtbim.cn/SDK/latest/sdk.css"
    }
  }
});
  1. 修改 HTML 模板 编辑项目根目录下的 index.html，引入项目入口脚本：
  <!DOCTYPE html>
  <html lang="en">
  <head>
    <meta charset="UTF-8">
    <link rel="icon" type="image/svg+xml" href="/vite.svg">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Vite + bimflux</title>
  </head>
  <body>
    <!-- 场景容器：宽高设置为占满整个视口 -->
    <div id="app" style="width: 100vw; height: 100vh; margin: 0; padding: 0; overflow: hidden;"></div>
    <!-- 引入项目入口脚本 -->
    <script type="module" src="/src/main.js"></script>
  </body>
  </html>
  1. 引入并初始化 SDK 编辑 src/main.js 文件，通过别名（或完整路径）引入 SDK 并初始化：
  // src/main.js
  // 引入 SDK（通过别名）
  import * as bimflux from "@bimflux/sdk";
  // 引入 UI 组件（通过别名）
  import "@bimflux/ui";
  // 引入 SDK 样式文件（通过别名）
  import "@bimflux/style";
  // 等待页面 DOM 加载完成后初始化场景
  document.addEventListener("DOMContentLoaded", () => {
    // 初始化场景核心实例
    const scene = new bimflux.Scene("app"); 
  });

Webpack 集成

Webpack 是一款功能全面的前端构建工具，支持处理各种资源和模块类型，适合复杂项目的工程化管理。Webpack 5+ 对 ESM 模块支持完善，可直接导入远程 CDN 模块。

详细步骤：

  1. 创建 Webpack 项目（若未创建） 打开终端，执行以下命令初始化项目并安装 Webpack 相关依赖：
# 创建项目目录并进入
mkdir bimflux-webpack-project && cd bimflux-webpack-project
# 初始化 npm 项目
npm init -y
# 安装 Webpack 核心依赖
npm install webpack webpack-cli webpack-dev-server --save-dev
# 安装 HTML 插件和样式加载器
npm install html-webpack-plugin style-loader css-loader --save-dev
  1. 配置 Webpack 在项目根目录创建 webpack.config.js 文件，配置入口、出口、模块解析规则及插件：
// webpack.config.js
const path = require("path");
const HtmlWebpackPlugin = require("html-webpack-plugin");

module.exports = {
  // 入口文件
  entry: "./src/main.js",
  // 模块处理规则
  module: {
    rules: [
      // 处理 CSS 文件（用于加载 SDK 样式）
      {
        test: /\.css$/,
        use: [
          "style-loader", // 将 CSS 注入到 DOM 中
          "css-loader"    // 解析 CSS 文件
        ],
        // 允许加载 CDN 中的 CSS 文件
        include: (modulePath) => {
          return modulePath.includes("cdn.dtbim.cn") || modulePath.includes("src");
        }
      }
    ]
  },
  // 模块解析配置
  resolve: {
    // 配置别名
    alias: {
      "@bimflux/sdk": "https://cdn.dtbim.cn/SDK/latest/sdk.es.js",
      "@bimflux/ui": "https://cdn.dtbim.cn/ui-next/latest/index.js",
      "@bimflux/style": "https://cdn.dtbim.cn/SDK/latest/sdk.css"
    },
    // 支持的文件扩展名
    extensions: [".js"]
  },
  // 插件配置
  plugins: [
    // 生成 HTML 文件并自动注入打包后的脚本
    new HtmlWebpackPlugin({
      template: "./public/index.html", // HTML 模板路径
      title: "Webpack 集成示例" // 页面标题
    })
  ],
  // 模式：开发环境（开发环境不压缩代码，保留调试信息）
  mode: "development"
};
  1. 创建 HTML 模板 在项目根目录创建 public 文件夹，新建 index.html 作为模板：
<!-- public/index.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title><%= htmlWebpackPlugin.options.title %></title>
</head>
<body>
  <!-- BIM 场景容器：ID 为 "app" -->
  <div id="app" style="width: 100vw; height: 100vh; margin: 0; padding: 0; overflow: hidden;"></div>
</body>
</html>
  1. 引入并初始化 SDK 在项目根目录创建 src 文件夹，新建 main.js 作为入口文件：
// src/main.js
// 引入 SDK（通过别名）
import * as bimflux from "@bimflux/sdk";
// 引入 UI 组件（通过别名）
import "@bimflux/ui";
// 引入 SDK 样式文件（通过别名）
import "@bimflux/style";

// 等待 DOM 加载完成后初始化场景
  document.addEventListener("DOMContentLoaded", () => {
    // 初始化场景核心实例
    const scene = new bimflux.Scene("app"); 
  });

自定义 Loader 集成

对于需要高度定制化加载逻辑或特殊网络环境的场景，可以使用自定义 Loader 方式集成 SDK。这种方式允许开发者完全控制 SDK 的加载过程，包括错误重试、加载进度显示、条件加载等功能。

详细步骤：

  1. 创建自定义 Loader 函数 在项目中创建一个自定义 Loader 函数，封装 SDK 的加载逻辑：
// utils/bimfluxLoader.js
export const useBimfluxLoader = async () => {
  return new Promise((resolve, reject) => {
    // 对于webpack 项目，可添加 webpackIgnore 注释避免 webpack 处理该导入
    import(/* webpackIgnore: true */ "https://cdn.dtbim.cn/SDK/latest/sdk.es.js")
      .then((module) => {
        resolve(module);
      })
      .catch((error) => {
        // 处理加载失败
        console.error("bimflux SDK 加载失败:", error);
        reject(error);
      });
  });
};
  1. 在主应用中使用自定义 Loader 在应用中使用自定义 Loader 函数加载 SDK：
// main.js
import { useBimfluxLoader } from './utils/bimfluxLoader';
useBimfluxLoader()
  .then((bimflux) => {
    // 等待 DOM 加载完成后初始化场景
    document.addEventListener("DOMContentLoaded", () => {
      // 初始化场景核心实例
      const scene = new bimflux.Scene("app");
      // 其他初始化代码...
    });
  })
  .catch((error) => {
    console.error('BIM 引擎加载失败:', error);
  });

兼容性处理

由于 bimflux SDK 基于现代 Web 标准开发，在旧浏览器中可能存在兼容性问题。以下针对不同兼容性场景提供解决方案：

ESM 兼容性处理

不支持 ESM 的浏览器：

  • Internet Explorer（所有版本）
  • Chrome < 61、Edge < 61、Firefox < 60、Safari < 10.1

解决方案一：浏览器检测与降级提示

通过 type="module" 和 nomodule 标签区分浏览器，对不支持 ESM 的浏览器显示友好提示，引导用户升级：

<!-- 支持 ESM 的浏览器会执行此脚本 -->
<script type="module">
  console.log("当前浏览器支持 ESM，可正常运行 SDK");
</script>

<!-- 不支持 ESM 的浏览器会执行此脚本 -->
<script nomodule>
  (function() {
    // 获取场景容器并替换为提示信息
    const container = document.getElementById("app");
    if (container) {
      container.innerHTML = `
        <div style="width: 100%; height: 100%; display: flex; flex-direction: column; align-items: center; justify-content: center; color: #e53e3e; font-family: sans-serif; padding: 2rem; text-align: center;">
          <h3>浏览器版本过低</h3>
          <p>请升级浏览器后使用（Chrome 61+/Edge 61+/Firefox 60+/Safari 10.1+）</p>
        </div>
      `;
    }
  })();
</script>

解决方案二：使用 ESM 垫片**

对于支持部分 ES6+ 语法但不支持 ESM 的浏览器，可使用 es-module-shims 库模拟 ESM 加载逻辑，使模块能正常导入：

<!-- 引入 ESM 垫片（需放在模块引入前） -->
<script async src="https://unpkg.com/es-module-shims@1.10.0/dist/es-module-shims.js"></script>
<!-- 正常引入 sdk 模块 -->
<script type="module">
  import * as bimflux from "https://cdn.dtbim.cn/SDK/latest/sdk.es.js";
  // 初始化代码...
</script>

Import Maps 兼容性处理

不支持 Import Maps 的浏览器：

  • Chrome < 89、Firefox < 108、Safari < 15.4、Edge < 89

解决方案：使用 Import Maps 垫片

es-module-shims 库同时支持模拟 Import Maps 功能，在不支持该特性的浏览器中引入垫片即可：

<!-- 引入支持 Import Maps 的垫片 -->
<script async src="https://unpkg.com/es-module-shims@1.10.0/dist/es-module-shims.js"></script>
<!-- 配置 Import Maps -->
<script type="importmap">
  {
    "imports": {
      "@bimflux/sdk": "https://cdn.dtbim.cn/SDK/latest/sdk.es.js",
      "@bimflux/ui": "https://cdn.dtbim.cn/ui-next/latest/index.js"
    }
  }
</script>
<!-- 正常导入模块 -->
<script type="module">
  import * as bimflux from "@bimflux/sdk";
  // 初始化代码...
</script>

版本说明

  • JS SDK 版本：默认通过 latest 标签获取最新稳定版，版本号可在 SDK 源码头部注释中查看
  • UI 组件版本：默认与 SDK 版本同步，通过 latest 标签获取

锁定版本（推荐生产环境）：

为避免自动更新导致的兼容性问题，生产环境建议锁定具体版本，将 CDN 路径中的 latest 替换为版本号即可：

# JS SDK 锁定版本示例
https://cdn.dtbim.cn/SDK/1.10.0/sdk.es.js

# 样式文件锁定版本示例
https://cdn.dtbim.cn/SDK/1.10.0/sdk.css

# UI 组件锁定版本示例
https://cdn.dtbim.cn/ui-next/1.10.0/index.js

请确保 JS SDK、样式文件和 UI 组件的版本保持一致，以避免版本不兼容问题。

最佳实践

错误处理

class bimfluxManager {
  private static instance: bimfluxManager
  private module: any = null

  static async getInstance() {
    if (!this.instance) {
      this.instance = new bimfluxManager()
      await this.instance.initialize()
    }
    return this.instance
  }

  private async initialize() {
    try {
      this.module = await import('https://cdn.dtbim.cn/SDK/latest/sdk.es.js')
    } catch (error) {
      console.error('bimflux SDK初始化失败:', error)
      throw new Error('无法加载bimflux SDK，请检查网络连接')
    }
  }

  getModule() {
    if (!this.module) {
      throw new Error('bimflux SDK尚未初始化')
    }
    return this.module
  }
}

性能优化

// 预加载策略
const preloadbimflux = () => {
  const link = document.createElement('link')
  link.rel = 'modulepreload'
  link.href = 'https://cdn.dtbim.cn/SDK/latest/sdk.es.js'
  document.head.appendChild(link)
}

// 在应用初始化时调用
if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', preloadbimflux)
} else {
  preloadbimflux()
}

WebTileLayerRefreshEventHandler

参数

配置要求

为了获得最佳的运行性能和用户体验，请确保您的系统满足以下配置要求。

BIMFlux AI

文档中心Document Center

客户端SDK文档

服务端API文档

更新日志

联系我们Contact Us

电子邮箱：weiya_chen@hust.edu.cn

微信公众号：NCTI-DC2022

地址：湖北省武汉市洪山区珞喻路1037号

互动讨论Interactive Discussions

DTBIM交流QQ群1：69535164

DTBIM交流QQ群2：114370227

Copyright © 2025 国家数字建造技术创新中心