---
title: "useMeasure"
description: "测距 / 测面工具，自管 geojson 源与展示图层，turf 实时计算读数。"
seo_title: "useMeasure"
seo_description: "Distance and area measurement tool that manages its own geojson source and layers, computing live readouts with turf."
canonical_url: "https://mapbox.mhaibaraai.cn/docs/composables/use-measure"
---
# useMeasure

> 测距 / 测面工具，自管 geojson 源与展示图层，turf 实时计算读数。

## 简介

`useMeasure` 提供测距 / 测面交互：单击加点、移动预览、双击结束当前段、Esc 取消。它自管展示用的 geojson 源与图层，用 turf 实时计算并格式化读数。返回 `start` / `stop` / `clear` 控制方法与 `mode` / `active` / `result` 响应式状态。

> \[\!NOTE\]
> 
> 在 
> 
> <MapboxMap>
> 
>  子树外使用时经 
> 
> options.mapId
> 
>  指定目标地图。读数格式化复用 
> 
> formatDistance / formatArea
> 
> 。

## 用法

工具栏切换测距 / 测面，`result` 实时显示当前段读数：

```vue [UseMeasureExample.vue]
<script setup lang="ts">
const mapId = 'use-measure-demo'

const { start, stop, clear, mode, active, result } = useMeasure({ mapId })
</script>

<template>
  <div class="relative h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MapboxMap :map-id="mapId" :options="{ style: 'mapbox://styles/mapbox/light-v11', center: [116.39, 39.91], zoom: 11 }" />
    <div class="absolute left-2 top-2 z-10 flex gap-1">
      <UButton size="sm" :variant="active && mode === 'distance' ? 'solid' : 'soft'" @click="start('distance')">
        测距
      </UButton>
      <UButton size="sm" :variant="active && mode === 'area' ? 'solid' : 'soft'" @click="start('area')">
        测面
      </UButton>
      <UButton size="sm" variant="soft" :disabled="!active" @click="stop">
        结束
      </UButton>
      <UButton size="sm" color="error" variant="soft" @click="clear">
        清空
      </UButton>
    </div>
    <div v-if="result" class="absolute bottom-2 left-2 z-10 rounded bg-default/90 px-3 py-1.5 text-sm font-medium text-default ring ring-default">
      {{ result }}
    </div>
  </div>
</template>
```

## API

### `useMeasure()`

创建测量工具。

**options.mapId** (`string`): 目标地图 id；在 <MapboxMap> 子树外使用时必填。

**options.color** (`string`): 主色，默认 '#f59e0b'。

返回 `UseMeasureReturn`：

**start** (`(mode: MeasureMode) => void`): 进入测量：click 加点、mousemove 预览、dblclick 结束当前段。

**stop** (`() => void`): 退出测量交互（保留已绘结果）。

**clear** (`() => void`): 清空全部测量结果。

**mode** (`Ref<MeasureMode | undefined>`): 当前测量模式。

**active** (`Ref<boolean>`): 测量是否激活。

**result** (`Ref<string>`): 当前段（含光标预览）的格式化读数。

### `MeasureMode`

测量模式：`'distance'` | `'area'`。

## Changelog

See commit history for [src/runtime/composables/useMeasure.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/composables/useMeasure.ts).


## Sitemap

See the full [sitemap](/sitemap.md) for all pages.