设置 TypeScript 环境

本指南提供了一些设置 TypeScript 开发环境以与 GeoScene API for JavaScript 一起使用的基本步骤。重点是使用 @geoscene/core ES 模块。这不是 TypeScript 教程。强烈建议您查看 TypeScript 教程材料和入门页面。

使用 TypeScript 有很多优点。它的主要功能是在代码运行之前识别类型错误，这通常称为静态类型检查。这样做的好处是在构建应用程序解决问题时节省时间和生产力。

如果您在没有框架的独立项目中使用 TypeScript，则安装 TypeScript 的推荐方法是使用 Node 和 npm。包管理器 npm 用于安装各种库和工具。

确保使用 npm install -g typescript 全局安装 TypeScript。这将安装一个名为 tsc 的命令行工具，用于编译您的 TypeScript 代码。然后，可以使用 tsc -v 检查是否安装了 TypeScript，它应告诉您已安装的 TypeScript 版本。

文件夹结构

以下是基本 TypeScript 应用程序的示例文件夹结构：

root-folder/
  index.html
  package.json
  tsconfig.json
  src/
    main.ts

我们将在本指南中介绍其中几个文件。

安装 GeoScene API for JavaScript

当您在本地 npm install API 时，TypeScript 类型定义包含在模块中：

npm install @geoscene/core

构建应用程序

创建 Web 页面

第一步是创建 index.html，下面是一个基本示例。

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no"/>
    <title>GeoScene JS API 4.23 TypeScript Demo</title>
    <style>
      html,
      body,
      #viewDiv {
        padding: 0;
        margin: 0;
        height: 100%;
        width: 100%;
      }
    </style>
    <link rel="stylesheet" href="https://js.geoscene.cn/4.23/@geoscene/core/assets/geoscene/themes/light/main.css">
  </head>
  <body>
    <div id="viewDiv"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

请注意，<script> 标记指向 main.ts 源文件，而非 .js 文件。这是因为在构建过程中，该文件将从 TypeScript 转换为 JavaScript。

配置 CSS

此示例使用 GeoScene CDN 上托管的 CSS。确保 CSS URL 指向正确的 API 版本。

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

如果您需要使用本地托管的 CSS，请参阅在本地管理资产文档。根据要求，您还可以在项目的主样式表或组件级别设置 CSS。

在设置 #viewDiv 样式时，根据您的要求调整属性，例如：

#viewDiv {
  padding: 0;
  margin: 0;
  height: 100%;
  width: 100%;
}

首个 TypeScript 文件

以下是基本 TypeScript 文件的示例。API 的类型是自动推断的，您不需要为每个声明设置类型注释。例如，在以下代码片段中，变量 map 被推断为 Map 类型。GeoSceneMap 只是引用 Map 类的默认导出的变量名称，名称对输入没有影响。

import GeoSceneMap from "@geoscene/core/Map";
import MapView from "@geoscene/core/views/MapView";

const map = new GeoSceneMap({
  basemap: "tianditu-vector"
});

const view = new MapView({
  map: map,
  container: "viewDiv",
  center: [-118.244, 34.052],
  zoom: 12
});

view.when(() => {
  console.log("Map is loaded");
})

由于 TypeScript 的限制，自动转换在非 TypeScript 应用程序中效果最佳。自动转换将 JavaScript 对象转换为 GeoScene API for JavaScript 类类型，而无需显式导入这些类。如果您已在使用 API，而没有任何 TypeScript 构建错误，则无需进行任何更改。了解有关使用自动转换的更多信息。

编译

tsconfig

在将 TypeScript 编译为 JavaScript 之前，您需要配置 TypeScript 编译器。您可以通过创建 tsconfig.json 来执行此操作。如果在安装项目时创建了 tsconfig.json 文件，则建议检查所有设置。

以下是不使用自定义 API 微件的应用程序的 tsconfig.json 的小型示例：

{
  {
  "compilerOptions": {
    "esModuleInterop": true,
    "lib": ["ES2020", "DOM"],
    "module": "ES2020",
    "moduleResolution": "Node",
    "resolveJsonModule": true,
    "sourceMap": true,
    "strict": true,
    "target": "ES2020"
  },
  "include": ["./src"]
}

如果您还在构建自定义微件，则需要一些额外设置，例如本示例中的设置：

{
  {
  "compilerOptions": {
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "importHelpers": true,
    "jsx": "react",
    "jsxFactory": "tsx",
    "lib": ["ES2020", "DOM"],
    "module": "ES2020",
    "moduleResolution": "Node",
    "noImplicitAny": true,
    "preserveConstEnums": true,
    "resolveJsonModule": true,
    "sourceMap": true,
    "strict": true,
    "suppressImplicitAnyIndexErrors": true,
    "target": "ES2020"
  },
  "include": ["./src"]
}

tsconfig.json 的选项与传递给 TypeScript 编译器的 options 相同。无需过多介绍，需要注意的重要选项如下：

compilerOptions.esModuleInterop - 如果为 true，则允许使用 import 语法，例如 import x from 'xyz'。
compilerOptions.module - 这是用于编译代码的模块系统。在此示例中，我们将输出编译为针对 ES6 或更高版本的 ES 模块。
compilerOptions.target - 这会将输出设置为将支持的 JavaScript 功能的最低版本。ES2019 适用于所有支持的浏览器。
include - 要编译的 .ts 文件数组。您还可以使用 glob 模式，例如 "src/**/*"。

有关更多详细信息，请参阅 tsconfig.json 文档。

编译

如果您使用的是启用 TypeScript 的框架，则在构建应用程序时会自动编译这些类型。

如果您在独立应用程序中使用带有 API AMD CDN 模块的 TypeScript，请在应用程序的根目录中运行 tsc 或 tsc -w 以监视文件更改。

您现在可以开始编写 TypeScript 应用程序了。

编辑器

用于编写 TypeScript 的一个常用编辑器是 Visual Studio Code。Code 具有强大的 TypeScript 集成，可以帮助您构建应用程序。

附加信息

请参阅这些链接以获取更多信息：

上一主题使用 AMD 模块构建下一主题自定义微件基础知识