使用 ES 模块构建

简介 ​

ES 模块是一个官方的、标准化的模块系统，用于处理现代 JavaScript，已被所有主要浏览器采用。GeoScene Maps SDK for JavaScript 的 ES 模块可通过 @geoscene/core 包从 npm 进行本地安装。

先决条件 ​

根据您的要求，可能需要各种现代构建工具，包括框架、模块捆绑器、转译器、node.js、npm 等。为了使用 @geoscene/core 模块，您应该对这些工具的工作原理有一个基本的了解。有关这些概念的介绍，请参阅下面的其他信息部分。

入门 ​

本节重点介绍将 @geoscene/core 最小安装到使用现代工具构建的现有项目中的基本步骤。

将模块安装到您的工程中：

    // Default import
    import WebMap from "@geoscene/core/WebMap.js";

    // Namespace import
    import * as projection from "@geoscene/core/geometry/projection.js";

然后使用 import 语句加载各个模块:

    // Named import
    import { load, project } from "@geoscene/core/geometry/projection.js";

每个模块的参考手册页面顶部都有关于使用哪种导入语法的指南：默认 或 命名空间。大多数模块使用默认的导入语法，如上面的 import WebMap 类示例所示。其他模块（例如，提供帮助程序函数的模块）使用类似于 import * as projection 示例的命名空间导入。根据您的风格偏好，还可以使用 named 导入来引用您需要的确切方法，而不是命名空间导入：

    // Named import using an alias
    import { load as projectionLoad, project } from "@geoscene/core/geometry/projection.js";

而且，如果您认为可能存在变量命名冲突，也可使用别名，例如，许多类使用 load() 方法：

    @import "https://js.geoscene.cn/4.29/@geoscene/core/assets/geoscene/themes/dark/main.css";

无论您使用的是 namespace 还是 named 导入，Webpack 和 rollup.js 等模块捆绑器在涉及 treeshaking 时都会以相同的方式对待它们，这是删除未使用代码以创建最小、最有效的构建的过程。

配置 CSS ​

选择一个主题，然后将代码配置为使用 GeoScene 在线资源，例如：

index.css

    {
        "script": {
            "start": "npm run copy && react-scripts start",
            "build": "npm run copy && react-scripts build",
            "copy": "ncp ./node_modules/@geoscene/core/assets ./public/assets"
        }
    }

或者，如果您正在使用本地资产，请参阅本地管理资产部分。

使用资产 ​

默认情况下，API 的资产是在运行时从 GeoScene 在线资源中提取的，无需额外配置。使用 CDN 的一个优点是 API CSS 样式不需要与本地构建捆绑在磁盘上。这些资产包括样式、图像、字体和本地化文件。此行为基于 config.assetsPath 的默认设置。

在本地管理资产 ​

如果您需要在本地管理 API 资产，可将它们从 /node_modules/@geoscene/core/assets 复制到您的项目中，然后设置 config.assetsPath 以确保正确解析资产路径。实现此目的的一种简单方法是配置在构建过程中运行的 npm 脚本。例如，使用 npm 安装 ncp，在 package.json 中配置一个脚本来复制文件夹。

以下是一个 React 示例：

package.json

    import geosceneConfig from "@geoscene/core/config.js";
    geosceneConfig.assetsPath = "./assets";

App.js

assetsPath 属性中使用的路径将根据资源在项目中的放置位置而有所不同。

    @import "@geoscene/core/assets/geoscene/themes/dark/main.css";

index.css

指定此 @import 路径的模式取决于您的框架或模块捆绑器。

    <link rel="stylesheet" href="https://js.geoscene.cn/4.29/@geoscene/core/assets/geoscene/themes/light/main.css">

    <script type="module">
        import Map from 'https://js.geoscene.cn/4.29/@geoscene/core/Map.js';

        const map = new Map({
            basemap: "tianditu-vector"
        });
    </script>

配置 Web 服务器 ​

用于开发和托管 GeoScene Maps SDK for JavaScript 的 Web 服务器托管配置将需要特定的 MIME/type 注册。

使用 ESM CDN ​

ES 模块 CDN 仅用于测试，并未针对性能进行优化。要在生产应用程序中获得最佳性能，请在本地构建 @geoscene/core 模块。以下为 HTML 和 JavaScript 示例：

index.html

    import Map from "geoscene/Map.js";
    import MapView from "geoscene/views/MapView.js";

其他信息 ​

有关详细信息，请参阅以下附加链接：

• MDN - JavaScript 模块

• MDN - 客户端工具概述

• MDN - 引入完整的工具链