PyQGIS读写要素几何与属性表
PyQGIS读写要素几何与属性表,核心做法是通过QgsVectorLayer.getFeatures()迭代要素,用feature.geometry()取几何、feature.attributes()或feature[‘字段名’]取属性;写入时优先用with edit(layer)编辑缓冲调用changeAttributeValue、changeGeometry或addFeature,再commitChanges并刷新画布。该方法适用于当前QGIS LTR 3.44系列与Latest 4.2系列的矢量层,操作前需确认dataProvider().capabilities()支持AddFeatures、ChangeAttributeValues、ChangeGeometries。直接改feature对象不会自动落盘,必须经图层或provider写回。

如何读取矢量层要素的几何与属性
读取是所有pyqgis要素操作的基础。先拿到图层对象(图层树选中、按名称查找或按路径加载),再迭代要素并提取几何与字段值。官方Cookbook矢量层章节给出了完整模式,可对照实践。
- 获取图层:layer = iface.activeLayer() 或 QgsProject.instance().mapLayersByName(‘图层名’)[0]。确认 layer.isValid() 且类型为矢量。
- 可选过滤:request = QgsFeatureRequest().setFilterExpression(‘”字段” = \’值\”) 或 setFilterRect(矩形)。性能敏感时配合 QgsSpatialIndex。
- 迭代:for feature in layer.getFeatures(request): 进入循环。
- 取几何:geom = feature.geometry()。检查 geom.isNull() 或 geom.isEmpty();用 geom.asPoint()、asPolyline()、asPolygon()、asMulti* 或 wkbType() 判断类型。
- 取属性:attrs = feature.attributes() 得到列表;或 feature[‘字段名’]、feature[字段索引]。字段定义用 layer.fields()。
- 循环通常会跳过空几何要素;用 feature.isValid() 做额外校验。
- 需要单个要素时用 layer.getFeature(fid),注意不存在的 id 会返回无效要素。
- 详细接口见 PyQGIS矢量层Cookbook(Using Vector Layers)。
如何安全写入与更新要素几何和属性
写入分两种路径:编辑缓冲(推荐,支持撤销)与直接调 dataProvider。生产脚本优先前者,避免脏数据。修改后务必更新范围并刷新。
- 检查能力:caps = layer.dataProvider().capabilities();确认含 ChangeAttributeValues、ChangeGeometries、AddFeatures 等。
- 推荐写法:with edit(layer): 内部执行 layer.changeAttributeValue(fid, 字段索引, 新值)、layer.changeGeometry(fid, 新几何)、layer.addFeature(新feature)。退出 with 自动 commit 或 rollback。
- 传统写法:layer.startEditing() → 做修改 → layer.commitChanges()(失败则 rollBack())。
- 直接 provider:provider = layer.dataProvider();provider.changeAttributeValues({fid: {索引:值}})、changeGeometryValues({fid: geom})、addFeatures([feats])。适合批量且无需撤销的场景。
- 收尾:layer.updateExtents();layer.triggerRepaint() 或 iface.mapCanvas().refresh()。若新增字段先 layer.updateFields()。
复制要素时必须显式 feat.setGeometry(源.geometry()) 和 feat.setAttributes(源.attributes()),并保证字段类型与几何类型匹配。内存层创建时需指定 geometryType 与 CRS。
几何对象的构造、访问与计算
几何全部封装在 QgsGeometry。构造后赋给要素,或对现有几何做测量与变换。面积长度默认平面计算,跨投影需椭球。
| 操作类型 | 常用方法 | 说明 |
|---|---|---|
| 构造 | fromPointXY、fromPolylineXY、fromPolygonXY、fromWkt、fromWkb | WKT/WKB 适合跨格式;点线面用对应 from* |
| 访问 | asPoint、asPolyline、asPolygon、asMulti*、parts、wkbType、type、isMultipart | 多部件用 parts() 迭代 |
| 测量 | area()、length() | 平面值;精确测量用 QgsDistanceArea.setEllipsoid 后 measureArea/measureLength |
| 赋值 | feature.setGeometry(geom) | 配合图层 changeGeometry 或 updateFeature |
- 无效几何:重建后用 geom.isGeosValid() 检查;必要时 makeValid()。
- CRS 不一致会导致测量偏差,操作前统一投影或使用椭球测量。
- 更多示例见 PyQGIS几何处理Cookbook(Geometry Handling)。

环境、版本与验收注意点
截至2026年11月,生产环境推荐 LTR 3.44.15(Solothurn),最新功能可用 Latest 4.2.3(Belém do Pará,基于 Qt6)。PyQGIS 与 QGIS 版本绑定:3.x 用 PyQt5,4.x 用 PyQt6,脚本大体兼容但插件可能需微调。控制台内可直接用 iface;独立脚本需 QgsApplication.setPrefixPath、initQgis、exitQgis,并正确设置 PYTHONPATH 与库路径。
- 编辑前确认图层可写且未只读;字段类型匹配(整型/浮点/字符串/日期)。
- 验收标准:commit 后重新 getFeatures 能读到新值;画布可见变化;geom.area()/属性值符合预期;无控制台报错。
- 性能:大批量用 provider 批量接口 + 空间索引;避免循环内反复 updateExtents。
- 安装与路径以官网安装指南为准,Windows/macOS/Linux 均提供 LTR 与 Latest 安装包。
常见问题
改了 feature[“字段”] 为什么属性表不更新?
直接改 feature 对象只改内存副本,必须 layer.updateFeature(feature) 后再 commitChanges,或放在 with edit(layer): 里用 changeAttributeValue。否则不会写回数据源。
feature.geometry() 返回空或无效怎么办?
先查 feature.isValid() 与 geom.isNull()/isEmpty()。getFeature(错误id) 会返回无效要素;用 QgsGeometry.fromWkt 或 fromWkb 重建,并确认图层几何类型一致。
算出的面积/长度和预期差很多?
geom.area()/length() 是平面计算,忽略椭球与单位。改用 QgsDistanceArea,setEllipsoid(‘WGS84’) 后调用 measureArea/measureLength,必要时 convertAreaMeasurement。
commit 后地图上看不到变化?
调用 layer.triggerRepaint() 或刷新画布;确认 isEditable() 已关闭且 capabilities 支持修改;多部件几何可先 Promote to multipart;新增字段后务必 updateFields()。
掌握 getFeatures 读取、with edit 安全写入以及 QgsGeometry 构造与椭球测量,即可完成绝大多数 pyqgis要素操作。建议在 LTR 3.44 环境先用控制台小数据验证,再封装成 Processing 脚本或插件;涉及投影与面积时统一使用 QgsDistanceArea,避免平面计算误差。