---
title: "测量对象"
version: 6.0
locale: zh-hans
source: https://docs.djangoproject.com/zh-hans/6.0/ref/contrib/gis/measure/
canonical: https://djangodocs.dev/zh-hans/6.0/ref/contrib/gis/measure/
---
# 测量对象

[`django.contrib.gis.measure`](#module-django.contrib.gis.measure) 模块包含了方便表示距离和面积单位的对象。[^1] 具体来说，它实现了两个对象，[`Distance`](#django.contrib.gis.measure.Distance) 和 [`Area`](#django.contrib.gis.measure.Area) —— 这两个对象都可以通过分别使用 [`D`](#django.contrib.gis.measure.D) 和 [`A`](#django.contrib.gis.measure.A) 的便捷别名来访问。

## 例如

[`Distance`](#django.contrib.gis.measure.Distance) objects may be instantiated using a keyword argument
indicating the context of the units. In the example below, two different
distance objects are instantiated in units of kilometers (`km`) and miles
(`mi`):

```pycon
>>> from django.contrib.gis.measure import D, Distance
>>> d1 = Distance(km=5)
>>> print(d1)
5.0 km
>>> d2 = D(mi=5)  # `D` is an alias for `Distance`
>>> print(d2)
5.0 mi
```

要进行转换，访问首选单位属性以获取转换后的距离数量：

```pycon
>>> print(d1.mi)  # Converting 5 kilometers to miles
3.10685596119
>>> print(d2.km)  # Converting 5 miles to kilometers
8.04672
```

此外，可以在距离对象之间执行算术操作：

```pycon
>>> print(d1 + d2)  # Adding 5 miles to 5 kilometers
13.04672 km
>>> print(d2 - d1)  # Subtracting 5 kilometers from 5 miles
1.89314403881 mi
```

两个 [`Distance`](#django.contrib.gis.measure.Distance) 对象相乘将产生一个 [`Area`](#django.contrib.gis.measure.Area) 对象，它使用单位的平方：

```pycon
>>> a = d1 * d2  # Returns an Area object.
>>> print(a)
40.2336 sq_km
```

要确定单位的属性缩写是什么，可以使用 `unit_attname` 类方法：

```pycon
>>> print(Distance.unit_attname("US Survey Foot"))
survey_ft
>>> print(Distance.unit_attname("centimeter"))
cm
```

## 支持的单位

| 单位属性 | 全名或别名 |
| --- | --- |
| `km` | Kilometre, Kilometer |
| `mi` | Mile |
| `m` | Meter, Metre |
| `yd` | Yard |
| `ft` | Foot, Foot (International) |
| `survey_ft` | U.S. Foot, US survey foot |
| `inch` | Inches |
| `cm` | Centimeter |
| `mm` | Millimetre, Millimeter |
| `um` | Micrometer, Micrometre |
| `british_ft` | British foot (Sears 1922) |
| `british_yd` | British yard (Sears 1922) |
| `british_chain_sears` | British chain (Sears 1922) |
| `indian_yd` | Indian yard, Yard (Indian) |
| `sears_yd` | Yard (Sears) |
| `clarke_ft` | Clarke's Foot |
| `chain` | Chain |
| `chain_benoit` | Chain (Benoit) |
| `chain_sears` | Chain (Sears) |
| `british_chain_benoit` | British chain (Benoit 1895 B) |
| `british_chain_sears_truncated` | British chain (Sears 1922 truncated) |
| `gold_coast_ft` | Gold Coast foot |
| `link` | 链接 |
| `link_benoit` | Link (Benoit) |
| `link_sears` | Link (Sears) |
| `clarke_link` | Clarke's link |
| `fathom` | Fathom |
| `rod` | Rod |
| `furlong` | Furlong, Furrow Long |
| `nm` | Nautical Mile |
| `nm_uk` | Nautical Mile (UK) |
| `german_m` | German legal metre |

> **Note**
>
> [`Area`](#django.contrib.gis.measure.Area) 的属性与 [`Distance`](#django.contrib.gis.measure.Distance) 的属性相同，只是它们以 `sq_` 为前缀（面积单位是平方单位）。例如，`Area(sq_m=2)` 创建一个表示两平方米的 [`Area`](#django.contrib.gis.measure.Area) 对象。

除了带有 `sq_` 前缀的单位外，以下单位也支持 [`Area`](#django.contrib.gis.measure.Area)：

| 单位属性 | 全名或别名 |
| --- | --- |
| `ha` | 公顷 |

## 测量 API

### `Distance`

#### `class Distance(**kwargs)`

要初始化一个距离对象，请传递一个关键字，该关键字对应于所需的 [单位属性名称](#supported-units) 并设置所需的值。例如，以下代码创建一个表示 5 英里的距离对象：

```pycon
>>> dist = Distance(mi=5)
```

#### `__getattr__(unit_att)`

返回与给定单位属性对应的距离值。例如：

```pycon
>>> print(dist.km)
8.04672
```

#### `classmethod unit_attname(unit_name)`

返回给定完整单位名称的距离单位属性名称。例如：

```pycon
>>> Distance.unit_attname("Mile")
'mi'
```

#### `class D`

[`Distance`](#django.contrib.gis.measure.Distance) 类的别名。

### `Area`

#### `class Area(**kwargs)`

要初始化一个面积对象，请传入一个与所需的 [单位属性名称](#supported-units) 对应的关键字，并设置所需的值。例如，以下代码创建了一个表示 5 平方英里的面积对象：

```pycon
>>> a = Area(sq_mi=5)
```

#### `__getattr__(unit_att)`

返回与给定单位属性对应的面积值。例如：

```pycon
>>> print(a.sq_km)
12.949940551680001
```

#### `classmethod unit_attname(unit_name)`

返回给定完整单位名称的面积单位属性名称。例如：

```pycon
>>> Area.unit_attname("Kilometer")
'sq_km'
```

#### `class A`

[`Area`](#django.contrib.gis.measure.Area) 类的别名。

**脚注**

[^1]: [Robert Coup](https://koordinates.com/) 是度量对象的初始作者，受到了 [geopy](https://github.com/geopy/geopy/) 中 Brian Beck 的工作以及 Geoff Biggs 在机器人领域的维度单位方面的博士研究的启发。