Measurement

测量微件对多个测量工具进行分组和管理，并允许您使用 activeTool 属性在它们之间轻松切换。这些工具对应于 2D（AreaMeasurement2D、DistanceMeasurement2D）和 3D（AreaMeasurement3D、DirectLineMeasurement3D）中的面积和距离的测量微件。

此微件遵循复合模式，允许开发人员配置 UI 以最好地满足其特定要求。测量工具、位置和图标都可以配置，这为与选项卡式界面或其他自定义 UI 一起使用提供了极大的灵活性。

对于 2D MapViews，将以大地测量方式计算地理坐标系和 web 墨卡托的距离。对于非 Web 墨卡托投影坐标系，将以平面方式对距离执行计算，这些距离最大为微件的 ViewModel 的 geodesicDistanceThreshold 属性所定义的阈值距离。将以大地测量方式计算等于和超过阈值的距离。默认情况下，阈值设置为 100km。

对于 3D SceneViews，计算距离的模式为 euclidean 或 geodesic。在 euclidean 模式下，距离在 ECEF 坐标系中以直线形式进行测量。在 geodesic 模式下，距离在 WGS84 椭圆体上以测地线的形式进行测量。

另请参阅：

示例：

// Add the measurement widget to the upper right hand corner
// with the distance tool active
const map = new Map({
  basemap: "tianditu-vector"
});

const view = new MapView({
  container: "viewDiv",
  map: map,
  center: [-71.69, 43.76],
  zoom: 15
});

const measurement = new Measurement({
  view: view,
  activeTool: "distance"
});
view.ui.add(measurement, "top-right");

// Switch between area and distance measurement
function switchTool() {
 const tool = measurement.activeTool === "distance" ? "area" : "distance";
 measurement.activeTool = tool;
}

构造函数

new Measurement(properties)

参数：

properties Object

optional

有关可能传递到构造函数中的所有属性的列表，请参阅属性。

属性概述

可以设置、检索或侦听任何属性。请参阅使用属性主题。

显示继承的属性

隐藏继承的属性

类型	描述	类：
String	更多详情指定要显示的当前测量工具。	更多详情	Measurement
AreaMeasurement2D\|AreaMeasurement3D\|DirectLineMeasurement3D\|DistanceMeasurement2D	更多详情指定要显示的当前测量工具。	更多详情	Measurement
SystemOrAreaUnit	更多详情单位制（英制、公制）或用于显示面积值的特定单位。	更多详情	Measurement
String\|HTMLElement	更多详情表示包含微件的 DOM 元素的 ID 或节点。	更多详情	Widget
String	更多详情类的名称。	更多详情	Accessor
String	更多详情微件的默认 CSS 图标类。	更多详情	Measurement
String	更多详情创建微件时分配给微件的唯一 ID。	更多详情	Widget
String	更多详情微件的默认标注。	更多详情	Measurement
SystemOrLengthUnit	更多详情单位制（英制、公制）或用于显示距离值的特定单位。	更多详情	Measurement
MapView\|SceneView	更多详情对 MapView 或 SceneView 的引用。	更多详情	Measurement
MeasurementViewModel	更多详情此微件的视图模型。	更多详情	Measurement
Boolean	更多详情指示微件是否可见。	更多详情	Widget

属性详细信息

activeTool String

指定要显示的当前测量工具。设置其值将 area 激活面积测量工具，并且该工具适用于 MapView 和 SceneView。要在 MapView 中测量距离，请将该属性设置为 distance，在 SceneView 中将其设置为 direct-line。如果未设置此属性，则不会显示微件。

可能值："area"|"distance"|"direct-line"

默认值：null

示例：

// To create the Measurement widget with SceneView's direct-line tool active.
const measurement = new Measurement({
  view: view,
  activeTool: "direct-line"
});

// To switch between direct line and area measurement tools
function switchTool() {
 const tool = measurement.activeTool === "direct-line" ? "area" : "direct-line";
 measurement.activeTool = tool;
}

activeWidget AreaMeasurement2D|AreaMeasurement3D|DirectLineMeasurement3D|DistanceMeasurement2Dreadonly

当前正在使用的测量微件。使用此属性可访问活动微件。

默认值：null

示例：

// Print the active widget to the console.
const measurement = new Measurement({
  view: view,
  activeTool: "distance"
});
view.ui.add(measurement, "top-right");
console.log("Active Widget: ", measurement.activeWidget);

areaUnit SystemOrAreaUnit

单位制（英制、公制）或用于显示面积值的特定单位。可能的值为：metric、imperial、square-inches、square-feet、square-us-feet、square-yards、square-miles、square-meters、square-kilometers、acres、ares、hectares。

示例：

// To create the Measurement widget that displays area in square US feet
const measurement = new Measurement({
  view: view,
  activeTool: "area",
  unit: "square-us-feet"
});

// To display the current measurement unit
console.log("Current unit: ", measurement.unit);

container String|HTMLElement inherited

表示包含微件的 DOM 元素的 ID 或节点。此属性只能设置一次。以下示例是使用微件时的所有有效用例。

示例：

// Create the HTML div element programmatically at runtime and set to the widget's container
const basemapGallery = new BasemapGallery({
  view: view,
  container: document.createElement("div")
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

// Specify an already-defined HTML div element in the widget's container

const basemapGallery = new BasemapGallery({
  view: view,
  container: basemapGalleryDiv
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

// HTML markup
<body>
  <div id="viewDiv"></div>
  <div id="basemapGalleryDiv"></div>
</body>

// Specify the widget while adding to the view's UI
const basemapGallery = new BasemapGallery({
  view: view
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

declaredClass Stringreadonly inherited

类的名称。声明的类名格式为 geoscene.folder.className。

iconClass Stringreadonly

微件的默认 CSS 图标类。

id String inherited

创建微件时分配给构件的唯一 ID。如果未由开发人员设置，它将默认为容器 ID，或者如果不存在，则将自动生成。

label String

微件的默认标注。每当微件由另一个微件控制（例如展开）时，此属性都很有用。

linearUnit SystemOrLengthUnit

单位制（英制、公制）或用于显示距离值的特定单位。可能的值为：metric, imperial, inches, feet, us-feet, yards, miles, nautical-miles, meters, kilometers.

示例：

// To create the Measurement widget that displays distance in yards
const measurement = new Measurement({
  view: view,
  activeTool: "distance",
  linearUnit: "yards"
});

// To display the current measurement unit
console.log('Current linear unit: ', measurement.linearUnit);

view MapView|SceneView

对 MapView 或 SceneView 的引用。设置此选项可将微件链接到特定视图。

示例：

// To create the Measurement widget for SceneView with the direct-line tool active.
const measurement = new Measurement({
  view: sceneView,
  activeTool: "direct-line"
});

viewModel MeasurementViewModelautocast

此微件的视图模型。这是一个包含控制此微件行为的所有逻辑（属性和方法）的类。请参阅 MeasurementViewModel 类以访问微件上的所有属性和方法。

示例：

// Intialize a measurement widget using the view model.
const measurement = new Measurement({
  viewModel: {
    view: view,
    activeTool: "distance",
    unit: "yards"
  }
});

visible Boolean inherited

指示微件是否可见。

如果 false，则该微件将不再呈现在 web 文档中。这可能会影响文档中其他元素或微件的布局。例如，如果此微件是与视图 UI 右上角关联的三个微件中的第一个，则当此微件变为不可见时，其他微件将重新定位。有关详细信息，请参阅 "none" 的 CSS 显示值。

默认值：true

示例：

// Hides the widget in the view
widget.visible = false;

方法概述

显示继承的方法

隐藏继承的方法

返回类型	描述	类：
String	更多详情用于为微件的 `class` 属性构建值的实用程序方法。	更多详情	Widget
	更多详情删除所有测量微件和关联的图形。	更多详情	Measurement
	更多详情销毁微件实例。	更多详情	Widget
Boolean	更多详情在实例上发出事件。	更多详情	Widget
Boolean	更多详情指示实例上是否存在与提供的事件名称匹配的事件侦听器。	更多详情	Widget
Boolean	更多详情 `isFulfilled()` 可用于验证是否满足类的创建实例（已解决或已拒绝）。	更多详情	Widget
Boolean	更多详情 `isRejected()` 可用于验证创建类的实例是否被拒绝。	更多详情	Widget
Boolean	更多详情 `isResolved()` 可用于验证是否解析了类的创建实例。	更多详情	Widget
Object	更多详情在实例上注册事件处理程序。	更多详情	Widget
	更多详情微件拆解助手。	更多详情	Widget
	更多详情此方法主要由开发人员在实现自定义微件时使用。	更多详情	Widget
Object	更多详情此方法主要由开发人员在实现自定义微件时使用。	更多详情	微件
	更多详情立即将微件渲染给 DOM。	更多详情	Widget
	更多详情此方法主要由开发人员在实现自定义微件时使用。	更多详情	Widget
	更多详情启动活动测量微件的新测量。	更多详情	Measurement
Promise	更多详情 `when()` 可以在创建类的实例后利用。	更多详情	Widget

方法详细信息

classes(classNames){String}inherited

用于为微件的 class 属性构建值的实用程序方法。这有助于简化 CSS 类设置。

参数：

classNames String|String []|Object

repeatable

类名称

类型	说明
String	计算的类名。

另请参阅：

指南 - 微件开发（渲染）

示例：

// .tsx syntax showing how to set CSS classes while rendering the widget

render() {
  const dynamicIconClasses = {
    [CSS.myIcon]: this.showIcon,
    [CSS.greyIcon]: !this.showIcon
  };

  return (
    <div class={classes(CSS.root, CSS.mixin, dynamicIconClasses)} />
  );
}

clear()

删除所有测量微件和关联的图形。

destroy()inherited

销毁微件实例。

emit(type, event){Boolean}inherited

在实例上发出事件。仅当创建此类的子类时，才应使用此方法。

参数：

type String

事件的名称。

event Object

optional

事件负载。

类型	说明
Boolean	`true` 如果听取了侦听者的通知

hasEventListener(type){Boolean}inherited

指示实例上是否存在与提供的事件名称匹配的事件侦听器。

参数：

type String

事件的名称。

类型	说明
Boolean	如果类支持输入事件，则返回 true。

isFulfilled(){Boolean}inherited 起始版本：GeoScene API for JavaScript 4.19

isFulfilled() 可用于验证是否满足类的创建实例（已解决或已拒绝）。如果已完成，将返回 true。

类型	说明
Boolean	指示是否已完成创建类的实例（已解决或已拒绝）。

isRejected(){Boolean}inherited 起始版本：GeoScene API for JavaScript 4.19

isRejected() 可用于验证创建类的实例是否被拒绝。如果被拒绝，将返回 true。

类型	说明
Boolean	指示创建类的实例是否已被拒绝。

isResolved(){Boolean}inherited 起始版本：GeoScene API for JavaScript 4.19

isResolved() 可用于验证是否解析了类的创建实例。如果被解析，将返回 true。

类型	说明
Boolean	指示是否已解析创建类的实例。

on(type, listener){Object}inherited

在实例上注册事件处理程序。调用此方法将事件与侦听器挂钩。

参数：

type String|String []

要侦听的事件或事件数组。

listener Function

事件激发时要调用的函数。

类型说明

Object

返回具有 remove() 方法的事件处理程序，应调用该方法以停止侦听事件。

属性	类型	说明
remove	Function	调用时，从事件中删除侦听器。

示例：

view.on("click", function(event){
  // event is the event handle returned after the event fires.
  console.log(event.mapPoint);
});

own(handles)inherited

微件拆解助手。当微件被销毁时，添加到其中的任何句柄都将自动删除。

参数：

handles WatchHandle|WatchHandle []

在微件被销毁后标记为删除的句柄。

postInitialize()inherited

此方法主要由开发人员在实现自定义微件时使用。在微件准备好进行渲染后执行。

render(){Object}inherited

此方法主要由开发人员在实现自定义微件时使用。它必须由子类实现以进行渲染。

类型	说明
Object	渲染的虚拟节点。

renderNow()inherited

立即将微件渲染给 DOM。

scheduleRender()inherited

此方法主要由开发人员在实现自定义微件时使用。计划微件渲染。此方法对于影响 UI 的更改很有用。

startMeasurement()

启动活动测量微件的新测量。

示例：

const measurement = new Measurement({
  view: view,
  activeTool: "distance"
});

function measure () {
  measurement.startMeasurement();
}

measure();

when(callback, errback){Promise}inherited 起始版本：GeoScene API for JavaScript 4.19

when() 可以在创建类的实例后利用。此方法采用两个输入参数：callback 函数和 errback 函数。在类的实例加载时执行 callback。如果类的实例无法加载，则执行 errback。

参数：

callback Function

optional

解析 promise 时要调用的函数。

errback Function

optional

promise 失败时要执行的函数。

类型	说明
Promise	返回回调结果的新 promise，`callback` 结果可用于链接其他函数。

示例：

// Although this example uses the BasemapGallery widget, any class instance that is a promise may use when() in the same way
let bmGallery = new BasemapGallery();
bmGallery.when(function(){
  // This function will execute once the promise is resolved
}, function(error){
  // This function will execute if the promise is rejected due to an error
});

GeoScene API for JavaScript参考手册

构造函数

属性概述

属性详细信息

方法概述

方法详细信息