ArcGIS Pro Python 实战指南

字段计算器 & 标注表达式 完全手册

──────────────────────────────

基于 ArcGIS Pro 3.x | 适用 ArcPy / Python 3

2026年7月

目录

第一章ArcGIS Pro Python 基础知识

•ArcPy 简介 | 环境设置 | 常用模块 | 游标操作 | 列表与描述 | 错误处理 | 性能优化

第二章字段计算器（Field Calculator）

•概述 | 基本语法 | Python 代码块 | 实战案例 | 常见问题

第三章标注（Labeling）

•概述 | Python 标注表达式 | Arcade 标注表达式 | ArcPy 标注操作 | 实战案例

附录 A快速参考

•字段类型 | 常用坐标系 WKID | ArcPy 快捷命令 | 在线资源

第一章ArcGIS Pro Python 基础知识

1.1ArcPy 简介

ArcPy 是 Esri 在 ArcGIS 10.0 引入的 Python 站点包，它取代了旧的 arcgisscripting 模块，提供了更丰富、更 Pythonic 的 API。在 ArcGIS Pro 中，ArcPy 基于 Python 3，支持所有地理处理工具的直接调用。

ArcPy 的核心功能包括：

•地理处理工具调用：调用 ArcGIS Pro 中所有工具箱中的工具

•数据访问模块 (arcpy.da)：高性能游标操作，支持搜索、插入、更新

•制图模块 (arcpy.mp)：地图文档和布局的自动化操作

•空间分析模块 (arcpy.sa)：栅格分析与建模

•网络分析模块 (arcpy.nax)：网络分析功能

•图表模块 (arcpy.charts)：数据可视化制图

在 ArcGIS Pro 中运行 Python 的三种方式

1.2环境设置

ArcPy 环境设置用于控制地理处理工具的全局行为，包括工作空间、输出坐标系、处理范围等。正确的环境设置是脚本稳定运行的基础。

工作空间设置

import arcpy

# 设置工作空间（默认数据读取/写入位置）

arcpy.env.workspace = r"C:\Data\Project.gdb"

# 临时工作空间（中间结果的存储位置）

arcpy.env.scratchWorkspace = r"C:\Data\Scratch.gdb"

# 允许覆盖已有输出（避免因文件存在而报错）

arcpy.env.overwriteOutput = True

坐标系与范围设置

# 输出坐标系（所有输出将投影到此坐标系）

arcpy.env.outputCoordinateSystem = arcpy.SpatialReference(4490)# CGCS2000 地理坐标系

# 处理范围

arcpy.env.extent = "MAXOF"# 输入数据的并集范围

# arcpy.env.extent = "MINOF"# 输入数据的交集范围

# arcpy.env.extent = arcpy.Extent(104.0, 30.5, 104.5, 31.0)# 自定义范围

# 栅格处理参数

arcpy.env.cellSize = 30# 输出像元大小

arcpy.env.cellSizeProjectionMethod = "CONVERT_UNITS"# 单位转换

# 并行处理（提高大数据处理速度）

arcpy.env.parallelProcessingFactor = "75%"

👉 提示：设置坐标系时，中国地区一般使用 CGCS2000 (WKID 4490) 地理坐标系，或根据分带选择对应的投影坐标系，如 CGCS2000_3_Degree_GK_Zone_35 (WKID 4523)。

1.3常用模块一览

1.4游标操作（Cursor）

游标是 ArcPy 中最常用的数据访问方式。ArcGIS Pro 使用 arcpy.da 模块（Data Access）提供的游标，相比旧版游标性能更好、功能更强。

SearchCursor —— 读取数据

import arcpy

# 基本读取：遍历所有要素

with arcpy.da.SearchCursor(fc, ["NAME", "AREA", "SHAPE@"]) as cursor:

forrow in cursor:

name,area, geom = row

print(f"{name}:{area:.2f} 平方米")

# 带条件筛选（SQL WHERE 子句）

with arcpy.da.SearchCursor(

parcels,["OWNER", "LANDUSE"],

where_clause="LANDUSE= '0101' AND AREA > 500"

) as cursor:

forrow in cursor:

print(f"{row[0]}:{row[1]}")

# 几何令牌（避免加载完整几何，只取需要的信息）

with arcpy.da.SearchCursor(points, ["SHAPE@XY", "SHAPE@X", "SHAPE@Y"]) as cursor:

forrow in cursor:

print(f"坐标:({row[0][0]:.6f}, {row[0][1]:.6f})")

# 常用几何令牌：

# SHAPE@XY-> (x, y) 元组

# SHAPE@X-> x 坐标

# SHAPE@Y-> y 坐标

# SHAPE@JSON-> JSON 字符串

# SHAPE@WKT-> WKT 文本

# SHAPE@AREA-> 面积

# SHAPE@LENGTH -> 长度

InsertCursor —— 写入数据

fields = ["SHAPE@XY", "NAME", "TYPE", "HEIGHT"]

with arcpy.da.InsertCursor(output_fc, fields) as cursor:

#插入单条记录

cursor.insertRow([(104.0657,30.6574), "点1", "控制点", 15.5])

#从另一个数据源批量插入

fordata in source_data:

cursor.insertRow(data)

UpdateCursor —— 更新数据

# 更新字段值（面积换算）

with arcpy.da.UpdateCursor(fc, ["AREA_MU", "SHAPE@AREA"]) as cursor:

forrow in cursor:

row[0]= row[1] / 666.67# 平方米转亩

cursor.updateRow(row)

# 条件删除

with arcpy.da.UpdateCursor(

buildings,["STATUS"],

where_clause="STATUS= '已拆除'"

) as cursor:

forrow in cursor:

cursor.deleteRow()

# 注意：使用 with 语句可以自动释放数据锁，避免 "数据被独占锁占用" 错误

1.5列表与描述

# 列出当前工作空间中的所有要素类

fcs = arcpy.ListFeatureClasses()

fcs = arcpy.ListFeatureClasses("*村*", "Polygon")# 名称过滤 + 类型过滤

# 列出栅格

rasters = arcpy.ListRasters()

# 列出字段

fields = arcpy.ListFields(fc)

for f in fields:

print(f"{f.name}({f.type})")# 输出字段名和类型

# 获取数据描述

desc = arcpy.Describe(fc)

print(f"几何类型: {desc.shapeType}")# Point/Polyline/Polygon

print(f"坐标系:{desc.spatialReference.name}")

print(f"路径:{desc.path}")

# 检查数据是否存在

if arcpy.Exists(r"C:\Data\test.shp"):

print("文件存在")

1.6错误处理

良好的错误处理能让脚本在出错时给出有意义的信息，而不是直接崩溃。

try:

arcpy.env.workspace= r"C:\Data\Project.gdb"

arcpy.env.overwriteOutput= True

#执行地理处理

result= arcpy.analysis.Buffer("roads", "roads_buffer", "500 Meters")

#检查执行结果

ifresult.maxSeverity == 0:

count= int(arcpy.management.GetCount("roads_buffer").getOutput(0))

print(f"成功生成{count} 个缓冲区")

else:

print(f"警告:{result.getMessages(1)}")

except arcpy.ExecuteError:

#ArcPy 工具执行错误

print(f"ArcPy错误: {arcpy.GetMessages(2)}")

except ImportError:

print("缺少必要的Python 模块")

except Exception as e:

print(f"未知错误:{e}")

finally:

#清理操作

print("脚本执行完毕")

1.7性能优化技巧

第二章字段计算器（Field Calculator）

2.1概述

字段计算器是 ArcGIS Pro 中最常用的数据操作工具之一，它允许用户通过表达式来更新属性表中的字段值。Python 3 是字段计算器的默认解析器，支持完整的 Python 语法和内置函数。

字段计算器可以在以下位置使用：

•属性表右键 > 计算字段 (Calculate Field)

•地理处理工具：数据管理工具 > 字段 > 计算字段

•Python 脚本：arcpy.management.CalculateField()

•模型构建器中的"计算值"工具

2.2基本语法

在字段计算器中，使用 ! 号来引用字段值。基本格式为：

!字段名!# 引用当前要素的字段值

!字段名![n]# 引用字段值的第 n 个字符（字符串切片）

简单表达式示例

# 1. 直接赋值

表达式: 100

说明:所有行设置为固定值 100

# 2. 字段间计算

表达式: !AREA_SQM! / 666.67

说明:将 Area_SQM 字段除以 666.67，结果写入目标字段

# 3. 数学运算

表达式: !PRICE! * !QUANTITY!

说明:价格乘以数量

# 4. 字符串拼接

表达式: !FAMILY_NAME! + !GIVEN_NAME!

表达式: f"{!PROVINCE!}-{!CITY!}-{!COUNTY!}"

说明:合并多个文本字段

# 5. 几何属性

表达式: !SHAPE.area!

表达式: !SHAPE.length!

表达式: !SHAPE.centroid.X!

表达式: !SHAPE.centroid.Y!

说明:获取要素的几何属性

# 6. 日期计算

表达式: datetime.datetime.now()

说明:填入当前日期时间

2.3Python 代码块（Code Block）

当计算逻辑比较复杂（条件判断、字典映射、循环等）时，可以使用"代码块"（Code Block）来定义自定义函数，然后在表达式中调用。

语法结构

# 代码块中定义函数

代码块:

def my_function(param1, param2):

#这里是自定义逻辑

returnresult

# 表达式中调用

表达式: my_function(!字段A!, !字段B!)

实例1：地类编码转名称

# 传入的代码块

code_block = '''

def get_landuse_name(code):

"""将编码转换为地类名称"""

names= {

"0101":"水田",

"0102":"水浇地",

"0103":"旱地",

"0201":"果园",

"0202":"茶园",

"0301":"乔木林地",

"0302":"竹林地",

"0601":"工业用地",

"0602":"采矿用地",

"0701":"城镇住宅用地",

"0702":"农村宅基地",

}

returnnames.get(code, "未分类")

'''

# 表达式

expression = "get_landuse_name(!DLBM!)"

# ArcPy 调用

arcpy.management.CalculateField(

fc,"DLMC", expression, "PYTHON3", code_block

)

实例2：条件判断（多分类）

code_block = '''

def classify_area(area):

"""根据面积大小分类"""

ifarea is None:

return"未知"

elifarea < 100:

return"微小地块"

elifarea < 500:

return"小型地块"

elifarea < 2000:

return"中型地块"

elifarea < 10000:

return"大型地块"

else:

return"超大型地块"

'''

expression = "classify_area(!SHAPE.area!)"

arcpy.management.CalculateField(fc, "AREA_CLASS", expression, "PYTHON3", code_block)

实例3：字符串处理

code_block = '''

def clean_name(raw_name):

"""清理地名：去除空格、统一格式"""

ifraw_name is None:

return""

#去除首尾空格

result= raw_name.strip()

#替换多个空格为单个

importre

result= re.sub(r'\s+', ' ', result)

#统一全角/半角括号

result= result.replace('(', '（').replace(')', '）')

returnresult

'''

expression = "clean_name(!PLACE_NAME!)"

实例4：计算几何中心坐标

code_block = '''

def get_center_x(geom):

"""获取面要素中心点X 坐标"""

ifgeom and geom.area > 0:

returnround(geom.centroid.X, 6)

return0.0

def get_center_y(geom):

"""获取面要素中心点Y 坐标"""

ifgeom and geom.area > 0:

returnround(geom.centroid.Y, 6)

return0.0

'''

arcpy.management.CalculateField(fc, "CENTER_X", "get_center_x(!SHAPE!)", "PYTHON3", code_block)

arcpy.management.CalculateField(fc, "CENTER_Y", "get_center_y(!SHAPE!)", "PYTHON3", code_block)

实例5：累计编号（使用全局变量技巧）

code_block = '''

counter = 0

def auto_number():

"""自动递增生成编号"""

globalcounter

counter+= 1

#格式化为 4 位数字，如 0001, 0002...

returnf"{counter:04d}"

'''

expression = "auto_number()"

# 注意：代码块中计数的持久性取决于数据量和小数点精度等因素，

# 较大数据量建议使用 arcpy.da.UpdateCursor 替代

2.4字段计算器在 ArcPy 中的完整用法

import arcpy

fc = r"C:\Data\Project.gdb\parcels"

# 方式1：简单表达式（单行）

arcpy.management.CalculateField(fc, "AREA_MU", "!SHAPE.area! / 666.67", "PYTHON3")

# 方式2：带代码块的表达式

code = '''

def get_status(landuse_code):

codes= ["0101", "0102", "0103"]

return"耕地" if landuse_code in codes else "非耕地"

'''

arcpy.management.CalculateField(

fc,"CATEGORY",# 目标字段

"get_status(!DLBM!)",#表达式

"PYTHON3",#表达式类型

code#代码块

)

# 方式3：批量计算多个字段

calculations = [

("AREA_HA","!SHAPE.area! / 10000", None),

("IS_VALID","1", None),

("LABEL","clean_name(!NAME!)", "def clean_name(n):\nreturn n.strip() if n else ''"),

]

for target, expr, cb in calculations:

arcpy.management.CalculateField(fc,target, expr, "PYTHON3", cb or "")

2.5常见问题与注意事项

第三章标注（Labeling）

3.1概述

标注是在地图上显示要素属性信息的文本。ArcGIS Pro 提供三种标注引擎：

3.2Python 标注表达式

Python 标注表达式与字段计算器共享相同的语法风格，使用 ! 引用字段。标注表达式的返回值必须是字符串。

基本标注表达式

# 单字段标注

表达式: [!NAME]

# 多字段组合

表达式: [!FAMILY_NAME] + [!GIVEN_NAME]

# 带分隔符的组合

表达式: [!PROVINCE] + "-" + [!CITY] + "-" + [!COUNTY]

# 换行标注（使用 \n 转义换行符）

表达式: "名称：" + [!NAME] + "\n面积：" + str(!AREA!U) + " 亩"

# 或使用 f-string 风格（Python 3）

表达式: f"{!NAME!}\n{!AREA!:.2f} 亩"

高级 Python 标注（自定义函数）

# 代码块：定义标注函数

def FindLabel([字段1], [字段2], ...):

#自定义逻辑

return标注字符串

# 示例1：地类标注（编码转名称 + 换行）

def FindLabel([DLBM], [DLMC], [AREA]):

if[DLBM] is None:

return"无数据"

#ArcGIS Pro Python 标注中，换行使用 chr(13)+chr(10) 或 "\n"

returnf"编码：{[DLBM]}\n名称：{[DLMC]}\n面积：{float([AREA]):.2f} 亩"

# 示例2：条件标注

def FindLabel([NAME], [POPULATION], [LEVEL]):

label= [NAME]

if[POPULATION]:

label+= f"\n人口：{int([POPULATION])} 人"

if[LEVEL] == "省会":

label+= "\n★ 省会城市"# ★ = ★

returnlabel

# 示例3：格式化数值

def FindLabel([PRICE], [AREA]):

unit_price= float([PRICE])# 总价

land_area= float([AREA])# 面积

ifland_area > 0:

price_per_mu= unit_price / land_area# 亩均单价

returnf"{price_per_mu:,.0f} 元/亩"

return"无数据"

👉 提示：在 ArcGIS Pro 标注表达式中，Python 换行符 \n 可能被忽略。稳妥的做法是使用 chr(13) + chr(10) 或直接在代码块中构造多行标注字符串。

3.3Arcade 标注表达式

Arcade 是 ArcGIS Pro 推荐的现代标注语言，相比 Python 标注有以下优势：

•跨平台一致：在 Pro、Web Map、移动端显示效果一致

•内置函数丰富：提供大量地理和文字处理函数

•性能更好：轻量级引擎，适合大量要素标注

•安全性：无法执行系统级操作

Arcade 基本语法

// Arcade 使用 $feature 引用要素字段

// 单字段

$feature.Name

// 多字段拼接

$feature.Province + "-" + $feature.City

// 条件判断

IIF($feature.Population > 1000000, "大城市", "中小城市")

// 字符串格式化

Concatenate(["名称:", $feature.Name, " 面积:", $feature.Area, "亩"])

// 文本换行

$feature.Name + TextFormatting.NewLine + $feature.Code

Arcade 常用函数

// 1. 条件判断

IIF(condition, true_value, false_value)

// 示例: IIF($feature.LEVEL == "省会", "省会", "地级市")

When(condition1, value1, condition2, value2, defaultValue)

// 多条件判断，类似 switch-case

// 2. 数学函数

Round($feature.Area, 2)// 四舍五入

Ceil($feature.Value)// 向上取整

Floor($feature.Value)// 向下取整

Abs($feature.Value)// 绝对值

Sqrt($feature.Value)// 平方根

// 3. 字符串函数

Left($feature.Code, 2)// 取左边2个字符

Right($feature.Code, 2)// 取右边2个字符

Mid($feature.Code, 1, 3)// 从位置1取3个字符

Lower($feature.Name)// 转小写

Upper($feature.Name)// 转大写

Trim($feature.Name)// 去除首尾空格

Replace($feature.Text, "旧","新")// 替换

// 4. 空值处理

DefaultValue($feature.Count, 0)// 如果为空则返回默认值

IsEmpty($feature.Name)// 判断是否为空

// 5. 日期函数

Year($feature.DateField)// 提取年份

Month($feature.DateField)// 提取月份

Day($feature.DateField)// 提取日

Now()// 当前日期时间

DateDiff($feature.Start, $feature.End, "days")// 日期差值

// 6. 几何函数

Area($feature, "mu")// 面积（单位可选: acres, hectares, sqm 等）

Length($feature, "km")// 长度

Centroid($feature)// 中心点

3.4Python 标注 vs Arcade 标注 对比

3.5ArcPy 操作标注类

通过 arcpy.mp 模块可以在 Python 脚本中对图层的标注进行编程控制。

import arcpy

# 获取当前项目

aprx = arcpy.mp.ArcGISProject("CURRENT")

# 获取地图和图层

m = aprx.listMaps()[0]

lyr = m.listLayers("地类图斑")[0]

# 开启标注

lyr.showLabels = True

# 获取标注类

lblClass = lyr.listLabelClasses()[0]

# 设置标注表达式（Python）

lblClass.expression = "[DLBM] + '\\n' + [DLMC]"

lblClass.parser = "Python"

# 设置标注字体

lblClass.symbol.color = {"RGB": [0, 0, 0, 100]}# RGBA

lblClass.symbol.size = 10# 字号

# 设置标注位置

lblClass.placement = "CENTER_CENTER"# 居中放置

# 批量设置多个图层的标注

for lyr_name in ["道路", "水系", "建筑"]:

lyr= m.listLayers(lyr_name)[0]

iflyr.supports("SHOWLABELS"):

lyr.showLabels= True

3.6实战案例

案例1：地类图斑标注（编码 + 名称 + 面积）

# Python 标注 - 带代码块

def FindLabel([DLBM], [DLMC], [SHAPE_AREA]):

area_mu= float([SHAPE_AREA]) / 666.67

return(

"编码："+ str([DLBM]) +

chr(13)+ chr(10) +

"名称："+ str([DLMC]) +

chr(13)+ chr(10) +

"面积："+ f"{area_mu:.2f} 亩"

)

# 等价 Arcade 标注

$feature.DLBM +

TextFormatting.NewLine +

$feature.DLMC +

TextFormatting.NewLine +

"面积：" + Round($feature.SHAPE_AREA / 666.67, 2) + " 亩"

案例2：道路标注（分级显示不同样式）

# Python 标注

def FindLabel([ROAD_NAME], [ROAD_LEVEL]):

if[ROAD_LEVEL] in ("国道", "高速"):

return"" + [ROAD_NAME] + ""# 粗体

elif[ROAD_LEVEL] == "省道":

return"" + [ROAD_NAME] + ""# 斜体

else:

return[ROAD_NAME]# 普通样式

# ArcGIS Pro 中可用格式化标签：

#粗体斜体下划线

# ^上标_下标

#文字

#字号

#颜色

案例3：统计标注（显示计数）

# 按行政区标注地块数量

# 需要先做空间连接或属性统计

# Python 标注

def FindLabel([NAME], [COUNT]):

if[COUNT]:

returnf"{[NAME]}\n共 {int([COUNT])} 个地块"

return[NAME]

# Arcade 标注

$feature.NAME + TextFormatting.NewLine +

"共 " + Text($feature.COUNT) + " 个地块"

3.7标注格式化标签速查

附录A快速参考

A.1常用字段类型

A.2常用坐标系统 WKID

A.3ArcPy 常用快捷命令

# 获取要素数量

count = int(arcpy.management.GetCount(fc).getOutput(0))

# 获取字段唯一值

with arcpy.da.SearchCursor(fc, "LANDUSE") as cursor:

unique_values= sorted({row[0] for row in cursor if row[0] is not None})

# 计算字段总和

total = 0

with arcpy.da.SearchCursor(fc, "AREA") as cursor:

total= sum(row[0] for row in cursor if row[0] is not None)

# 创建 GDB

arcpy.management.CreateFileGDB(r"C:\Output", "NewData")

# 复制要素类

arcpy.management.CopyFeatures(source_fc, target_fc)

# 定义投影

arcpy.management.DefineProjection(fc, arcpy.SpatialReference(4490))

# 添加字段

arcpy.management.AddField(fc, "NEW_FIELD", "DOUBLE", field_alias="新字段")

A.4在线资源

ArcGIS Pro Python 官方参考：

•ArcPy 文档：https://pro.arcgis.com/en/pro-app/latest/arcpy/main/arcpy-functions.htm

•Python 标注指南：https://pro.arcgis.com/en/pro-app/latest/help/mapping/text/labeling-with-python-expressions.htm

•Arcade 标注指南：https://pro.arcgis.com/en/pro-app/latest/help/mapping/text/arcade-expressions-for-labeling.htm

•字段计算器指南：https://pro.arcgis.com/en/pro-app/latest/tool-reference/data-management/calculate-field-examples.htm

─ 全文完 ─