---
title: "GeoDjango 表单 API"
version: 4.2
locale: zh-hans
source: https://docs.djangoproject.com/zh-hans/4.2/ref/contrib/gis/forms-api/
canonical: https://djangodocs.dev/zh-hans/4.2/ref/contrib/gis/forms-api/
---
# GeoDjango 表单 API

GeoDjango 提供了一些专门的表单字段和小部件，以便在地图上可视化显示和编辑地理位置数据。默认情况下，它们使用由 [NASA](https://www.earthdata.nasa.gov/) 提供的基本 WMS 图层，并由 [OpenLayers](https://openlayers.org/) 驱动的地图。

## 字段参数

除了常规的 [表单字段参数](/zh-hans/4.2/ref/forms/fields/#core-field-arguments) 之外，GeoDjango 表单字段还接受以下可选参数。

### `srid`

#### `Field.srid`

这是字段值应该转换为的 SRID 代码。例如，如果地图小部件的 SRID 与您的应用程序或数据库通常使用的 SRID 不同，该字段将自动将输入值转换为该 SRID。

### `geom_type`

#### `Field.geom_type`

通常情况下，您不应该设置或更改该属性，它应该根据字段类进行设置。它与 OpenGIS 标准的几何名称相匹配。

## 表单字段类

### `GeometryField`

#### `class GeometryField`

### `PointField`

#### `class PointField`

### `LineStringField`

#### `class LineStringField`

### `PolygonField`

#### `class PolygonField`

### `MultiPointField`

#### `class MultiPointField`

### `MultiLineStringField`

#### `class MultiLineStringField`

### `MultiPolygonField`

#### `class MultiPolygonField`

### `GeometryCollectionField`

#### `class GeometryCollectionField`

## 表单部件

GeoDjango 表单小部件允许您在可视地图上显示和编辑地理数据。请注意，目前没有任何可用的小部件支持 3D 几何形状，因此对于这种类型的数据，几何字段将使用 `Textarea` 小部件作为回退。

### 表单属性

GeoDjango 的小部件是基于模板的，因此它们的属性大部分与其他 Django 小部件的属性不同。

#### `BaseGeometryWidget.geom_type`

OpenGIS 几何类型，通常由表单字段设置。

#### `BaseGeometryWidget.map_height`

#### `BaseGeometryWidget.map_width`

小部件地图的高度和宽度（默认为 400x600）。

> **Deprecated since Django 4.2**
>
> Deprecated since version 4.2: `map_height` 和 `map_width` 属性已被弃用，请使用 CSS 来调整地图小部件的大小。

#### `BaseGeometryWidget.map_srid`

地图使用的 SRID 代码（默认为 4326）。

#### `BaseGeometryWidget.display_raw`

布尔值，指定是否可见一个文本区域输入框，显示当前几何形状的序列化表示，主要用于调试目的（默认为 `False`）。

#### `BaseGeometryWidget.supports_3d`

指示小部件是否支持编辑 3D 数据的属性（默认为 `False`）。

#### `BaseGeometryWidget.template_name`

用于呈现地图小部件的模板。

您可以以与任何其他 Django 小部件相同的方式传递小部件属性。例如：

```
from django.contrib.gis import forms

class MyGeoForm(forms.Form):
    point = forms.PointField(widget=forms.OSMWidget(attrs={"display_raw": True}))
```

### 部件类

`BaseGeometryWidget`

#### `class BaseGeometryWidget`

这是一个包含子类所需逻辑的抽象基础小部件。您不能直接将此小部件用于几何字段。请注意，GeoDjango 小部件的呈现是基于一个模板的，该模板由 [`template_name`](#django.contrib.gis.forms.widgets.BaseGeometryWidget.template_name) 类属性指定。

`OpenLayersWidget`

#### `class OpenLayersWidget`

这是所有 GeoDjango 表单字段默认使用的小部件。`template_name` 是 `gis/openlayers.html`。

`OpenLayersWidget` 和 [`OSMWidget`](#django.contrib.gis.forms.widgets.OSMWidget) 使用托管在 `cdn.jsdelivr.net` 内容传递网络上的 `ol.js` 文件。您可以子类化这些小部件，以便在内部 `Media` 类的 `js` 属性中指定您自己的 `ol.js` 文件版本（请参阅 [资源作为静态定义](/zh-hans/4.2/topics/forms/media/#assets-as-a-static-definition)）。

`OSMWidget`

#### `class OSMWidget`

这个小部件使用 OpenStreetMap 基础图层来显示地理对象。属性包括：

#### `template_name`

`gis/openlayers-osm.html`

#### `default_lat`

#### `default_lon`

默认的中心纬度和经度分别是 `47` 和 `5`，这是法国东部的一个位置。

#### `default_zoom`

默认的地图缩放级别是 `12`。

关于 JavaScript 文件托管的注意事项也适用于 [`OpenLayersWidget`](#django.contrib.gis.forms.widgets.OpenLayersWidget)。另请参阅关于地图瓦片的 `https` 访问的 [FAQ 答案](https://help.openstreetmap.org/questions/10920/how-to-embed-a-map-in-my-https-site)。