QGIS表达式中所使用的变量为符号化参数的设置、查询构建和数据更新等领域提供了“令人兴奋的各种可能性（the exciting possibilities variables unlock）”。表达式虽然强大，但目前缺乏系统的资料，中文资料更是少之又少，学习曲线非常陡峭，使得大多数人对其望而却步。
本文按照变量的作用域，从全局变量开始，逐级展开，力图提供变量使用说明的同时，更突出变量的使用范围和上下文环境，以帮助进一步理解变量的使用方法和注意事项。
QGIS中的变量遵从层级结构，类似css的继承规则，根据作用范围的大小，变量可以分为全局变量、工程变量、地图变量、图层变量、打印布局变量、地图集变量、上下文变量等。
本文在整理时，力求全面覆盖QGIS目前所有变量，然而，由于变量使用范围广泛，不仅QGIS核心可以定义变量，第三方提供的插件和算法也可以根据需要定义与自己插件或算法相关的变量，所以，本文难以做到100%全部覆盖。另外，在撰写说明的过程中，由于水平有限，难免存在理解不到位的地方，希望大家发现时不吝指正。
如果想进一步了解表达式相关知识，可以扩展阅读以下几篇推文：
全局变量在整个QGIS程序范围内均可以用于构建表达式，且其变量取值相同。例如对于全局变量“@qgis_os_name”，无论是在更新字段时，还是在筛选要素时，打开表达式构建器，都能看到变量列表中存在该变量，且取值均为当前操作系统名称，即“windows”。
全局变量的查看和设置方法为：点击菜单【设置】->【选项】，打开全局选项设置对话框，切换到【变量】标签页，可以看到QGIS所有的全局变量，也可以在此处点击下方的【+】添加自定义全局变量。
变量名 | 说明 | 举例 |
qgis_locale | QGIS当前使用的本地化语言环境 | 中文为'zh-Hans' |
qgis_os_name | 操作系统名称 | 'windows’, 'linux’ 或 'osx’ |
qgis_platform | QGIS产品平台 | 'desktop’或 'server’ |
qgis_release_name | 当前QGIS发行版名称 | 'Hannover'（版本名通常为召开社区会议的地点名称） |
qgis_short_version | 当前QGIS版本号 | '3.16' |
qgis_version | 当前QGIS版本字符串，由版本号+发行版名称组成 | '3.16.7-Hannover' |
qgis_version_no | 当前QGIS内部版本号 | 31607 |
user_account_name | 当前用户的操作系统账户名称 |
|
user_full_name | 当前用户的操作系统用户名（若可用） |
|
工程变量是一系列与工程设置有关的变量集合，在本工程范围内均可使用。点击菜单【工程】->【属性…】，打开属性对话框，切换到【变量】标签页，即可看到当前所有变量及其取值，也可以在属性对话框点击下方的【+】添加自定义的工程变量。
变量名 | 说明 | 举例 |
project_abstract | 工程描述信息，读取自工程元数据，可在工程属性中设置，默认为空 | '’ |
project_area_units | 工程面积单位，用于计算几何面积 | '平方米' |
project_author | 工程的作者信息，读取自工程元数据，可在工程属性中设置 | '吴建玲' |
project_basename | 当前工程文件的基本名称（不包含文件路径和扩展名） | 'sheng-2015-pop' |
project_creation_date | 当前工程的创建日期，读取自工程元数据，Datetime型 | <日期时间：2021-06-10 12:10:44> |
project_crs | 工程的坐标参照系代号 | 'EPSG:3857' |
project_crs_arconym | 工程坐标参照系的缩写 | 'merc'，等同于坐标参照系'EPSG:3857' |
project_crs_definition | 工程坐标参照系的完整定义，目前返回Proj4格式 |
|
project_crs_description | 工程坐标参照系的名称 | 'WGS 84 / Pseudo-Mercator' |
project_crs_ellipsoid | 工程坐标参照系的椭球体代码 | 'EPSG:7030' |
project_crs_proj4 | Proj4格式的工程坐标参照系 |
|
project_crs_wkt | WKT (well known text)格式表示的工程坐标参照系 |
|
project_distance_units | 当前工程的长度单位，用于计算长度 | '米’ |
project_ellipsoid | 当前工程的椭球体，在计算大地测量面积和大地测量几何图形长度时使用 | 'PARAMETER:6378245:6356863.01877304725348949' |
project_filename | 当前工程文件名，包含扩展名 | 'sheng-2015-pop.qgz' |
project_folder | 当前工程的文件夹路径 | 'E:\temp\Sheng_POP' |
project_home | 当前工程的根目录，通常与工程文件目录相同，可以在浏览器面板（Browse Panel）中设置 | 'E:\temp\Sheng_POP' |
project_identifier | 工程标识符，读取自工程元数据，默认为空字符串 |
|
project_keywords | 工程关键字，读取自工程元数据，字典型（dict），默认为空 |
|
project_last_saved | 工程最后保存的日期/时间，Datetime型 | <日期时间：2021-06-10 12:10:44> |
project_path | 当前工程的完整路径，包含文件名和扩展名 |
|
project_title | 工程标题，读取自工程元数据，默认为空字符串 |
|
project_units | 工程坐标参照系的单位 | '米' |
当QGIS主窗口加载了图层（地图数据）后，可以在符号化设置、要素选择和属性表操作中看到图层变量，图层变量的作用范围与该图层的存在周期相同。
在图层面板中右键点击图层->【属性】，切换到【变量】标签页，即可看到当前图层变量及其取值。点击下方的【+】按钮可以添加自定义图层变量。
变量名 | 说明 | 举例 |
layer | 当前激活的图层对象 | <地图图层> |
layer_id | 当前激活图层的ID | 'sheng_POP_f3dd262a_182c_4553_967a_e5b5a8f2dfd4' |
layer_ids | 当前工程打开的所有图层ID数组，数据类型为list | 如[ 'OpenStreetMap_e2f701ac_8687_43c2_b7bf_e01aec5e9937', 'n… ] |
layer_name | 当前激活图层的图层名 | 'sheng_POP' |
layers | 当前工程打开的所有图层数组，数据类型为list | [ <地图图层> ] |
通过点击菜单【工程】->【新建打印布局】，可进入打印布局窗口。打印布局相关的变量位于【布局】标签页的下方，在整个打印布局窗口中均可使用。
具体变量的含义为：
变量名 | 说明 | 举例 |
layout_dpi | 打印分辨率 (DPI)，默认为300DPI |
|
layout_name | 打印布局名称 | '布局1' |
layout_numpages | 打印布局总页数 | 1 |
layout_page | 打印布局中当前项的页码 | 2 |
layout_pageheight | 打印布局中当前页面的高度（以mm为单位） | 841 |
layout_pagewidth | 打印布局中当前页面的宽度（以mm为单位） | 1189 |
在打印布局窗口，点击菜单【地图集】->【地图集设置】，将在右侧打开地图集设置面板，勾选“生成地图集”复选框后，点击表达式按钮，即可看到一些列以“atlas”开头的变量，此为地图集设置相关变量，其作用范围是：启用“生成地图集”选项后方可以使用。
变量名 | 说明 | 举例 |
atlas_feature | 当前地图集要素 (数据类型：feature 对象) | '<要素：-9223372036854775808>’ |
atlas_featureid | 当前地图集要素ID | 2 |
atlas_featurenumber | 当前地图集要素数量 | 4 |
atlas_filename | 如果输出地图集，当前地图的输出文件名 | 'output_4' |
atlas_geometry | 当前地图集要素几何图形对象 |
|
atlas_layerid | 创建地图集所使用的图层ID | 'sheng_POP_f3dd262a_182c_4553_967a_e5b5a8f2dfd4' |
atlas_layername | 当前地图集所使用的图层名 | 'sheng_POP' |
atlas_pagename | 当前地图集的页面名称，显示在页面左上角 | '吉林' |
atlas_totalfeatures | 地图集中要素总数量 | 4461 |
当空白的打印纸张添加了布局元素，即可使用布局元素相关变量访问其属性，因此，布局元素变量的使用范围是：布局元素存在的周期均可使用。
变量名 | 说明 | 举例 |
item_id | 打印布局中布局元素的ID，不强制取值唯一 | '地图 2' |
item_uuid | 打印布局中布局元素的UUID，全局唯一 | '{dd0427db-020b-4c2f-a34f-938ec58b390b}' |
在打印布局窗口中选中地图后，添加网格，即可访问网格设置相关的变量。
变量名 | 说明 | 举例 |
grid_axis | 返回当前网格注记的坐标轴 | x为经度，y为纬度 |
grid_number | 网格注记文字内容 |
|
在打印布局添加图例（lengend）元素后，图例相关变量即可访问使用。
变量名 | 说明 | 举例 |
legend_column_count | 图例的列数，默认是1 |
|
legend_filter_by_map | 图例内容是否按地图过滤，布尔型，默认为false，表示不过滤 |
|
legend_filter_out_atlas | 图例内容是否按地图集要素范围过滤，布尔型，默认false，表示不过滤 |
|
legend_split_layers | 是否允许将图层中的图例分割为多个列，默认不分割。 |
|
legend_title | 图例标题 |
|
legend_wrap_string | 用于控制图例文字换行的字符 | 例如，换行符为'：’，那么当图例的文字中有'：’，则替换成换行 |
地图主窗口激活且有图层数据时，地图相关变量可以在构建表达式时使用。
变量名 | 说明 | 举例 |
map_crs | 地图的坐标参照系 | “EPSG:4326” |
map_crs_acronym | 当前地图参照系CRS的缩写 | 'merc' |
map_crs_definition | 当前地图参照系的完整定义 | '+proj=merc +a=6378137 +b=6378137 +lat_ts=0 +lon_0=0 +x_0=0 +…' |
map_crs_description | 地图坐标参照系全称 | 'WGS 84 / Pseudo-Mercator' |
map_crs_ellipsoid | 当前地图坐标参照系的椭球体缩写 | 'EPSG:7030' |
map_crs_proj4 | Proj4格式定义的地图坐标参照系 | '+proj=merc +a=6378137 +b=6378137 +lat_ts=0 +lon_0=0 +x_0=0 +…' |
map_crs_wkt | WKT格式定义的当前地图坐标参照系 |
|
map_extent | 返回地图当前范围的几何图形，通常为当前地图窗口的矩形 |
|
map_extent_center | 当前地图中心点 |
|
map_extent_height | 以地图单位表示的当前地图高度 |
|
map_extent_width | 以地图单位表示的当前地图宽度 |
|
map_id | 地图ID，对于地图主窗口，ID为'canvas’，对于打印布局中的地图，则地图ID等于地图元素ID（item ID） |
|
map_layer_ids | 地图中可见图层的ID字段列表 |
|
map_layers | 地图中可见图层对象列表 |
|
map_rotation | 地图旋转角度，默认为0，由状态栏中“旋转角度”参数控制 |
|
map_scale | 当前地图比例 |
|
map_units | 地图量算单位 |
|
打开图层对应属性表，使用表达式过滤要素或者使用字段计算器，即可看到属性表相关的变量。
变量名 | 说明 | 举例 |
row_number | 当前行号，在属性表中可见 | 1 |
符号相关变量用于控制或者获取符号化相关的参数。在【图层样式】->【符号化】->【图层符号】（symbol layer），选择调整符号图层的任意属性，使用【由数据定义重载】打开表达式构建对话框即可看到。
变量名 | 说明 | 举例 |
symbol_angle | 用于渲染要素的符号角度（仅适用于标记符号（Marker symbol）） |
|
symbol_color | 渲染要素所使用的符号颜色 |
|
symbol_count | 在布局图例中显示该符号渲染的要素数量 |
|
symbol_id | 符号的内部标识符（ID），仅在布局图例中可见 |
|
symbol_label | 符号标签，通常为用户输入，用于说明该符号代表的要素情况，默认系统自动生成与地图主窗口中的图层图例一致 |
|
symbol_layer_count | 一个符号所包含的符号图层（symbol layer）的总数 |
|
symbol_layer_index | 当前符号图层索引值 |
|
symbol_marker_column | 点的列号（仅对点图案填充有效） |
|
symbol_marker_row | 点的行号（仅对点图案填充有效） |
|
在模型构建器中，可以使用地理处理相关变量构建表达式。
变量名 | 说明 | 举例 |
algorithm_id | 处理工具箱中的算法唯一标识符（ID） |
|
model_path | 当前模型的完整路径（包括文件名，若模型嵌在工程中则为工程的完整路径） | '/home/wujl/文档/qgis-model/mymodel.model3' |
model_folder | 包含当前模型的文件夹（如果模型嵌入到工程中，则为工程文件夹） | '/home/wujl/文档/qgis-model' |
model_name | 当前模型的名称，不含路径和扩展名 | 'mytestmodel' |
model_group | 当前模型的群组 | 'custom' |
fullextent_maxx | 当前画布范围最大x值（包括所有图层）。如，180（度，地理坐标系） | 180 |
fullextent_maxy | 当前画布范围最大y值（包括所有图层）（如，90度，地理坐标系） | 90 |
fullextent_minx | 当前画布范围最小x值（包括所有图层）。如，-180（度，地理坐标系） | -180 |
fullextent_miny | 当前画布范围最小y值（包括所有图层）。如，-90（度，地理坐标系） | -90 |
点击【工具栏】->【时态】按钮，启用时态控件后，相关变量即出现在表达式构建对话框的变量列表中。
变量名 | 说明 | 举例 |
animation_start_time | 动画开始时间 (数据类型：datetime) | '<日期时间：2021-06-09 02:00:00>’ |
animation_interval | 动画持续总时长，通过animation_end_time减去animation_start_time得到，(数据类型：interval值，时间间隔单位可以为：年、月、周、天、小时、分钟或秒) | '<间隔：8.08333天>’ |
animation_end_time | 动画结束时间 (数据类型：datetime) | '<日期时间：2021-06-01 00:00:00>’ |
frame_duration | 每个动画帧的持续时间（数据类型：interval） |
|
frame_number | 动画播放期间当前帧编号 |
|
frame_rate | 动画播放期间每秒的帧数 |
|
map_end_time | 在时态动画中地图结束显示的时间，数据类型为Datatime，超过该时间点，当前地图将不显示 |
|
map_interval | 在时态动画中，地图持续显示的时间间隔，数据类型为：interval（时间间隔） |
|
map_start_time | 在时态动画中地图开始显示的时间，数据类型为Datatime，超过该时间点且在结束时间之前，地图处于可见状态 |
|
在属性表中选择要素、添加/编辑要素、查询要素时，跟数据库一样，QGIS程序需要维护一个当前记录的指针，用表单上下文变量来表示。
右键点击图层打开图层【属性】->【属性表单】->【表达式】可以看到对应变量。
变量名 | 说明 | 举例 |
current_feature | 表示当前正在表单或表格行中编辑的要素，可以在表单/行上下文中用于过滤相关要素。 |
|
current_geometry | 表示表单或表格行中当前正在编辑的要素的几何图形，可以在表单/行上下文中用于过滤相关要素。 |
|
form_mode | 表单的用途，例如AddFeatureMode，SingleEditMode，MultiEditMode，SearchMode，AggregateSearchMode或IdentifyMode作为字符串。 |
|
以上为QGIS表达式中变量的相关说明，希望对大家使用QGIS表达式有所帮助。
