box = QtWidgets.QMessageBox(self)
box.setWindowTitle(u'删除业务区域')
box.setText(u'该业务区域有{}个图幅，是否删除？'.format(count))
confirm = box.addButton(u'确认', QtWidgets.QMessageBox.YesRole)   # 返回按钮对象
box.addButton(u'取消', QtWidgets.QMessageBox.NoRole)
box.exec_()                                   # 模态阻塞，等用户选择
if box.clickedButton() is confirm:            # 用按钮对象判断点了哪个
    ...

def classFactory(iface):
    from .map_protect import mapProtect
    return mapProtect(iface)

# GIS 类：从 qgis.core / qgis.gui 按名导入
from qgis.core import QgsFeature, QgsProject, QgsVectorLayer
from qgis.gui import QgsFileWidget

# Qt 类：永远从 qgis.PyQt 走，不要直接 import PyQt5
# （QGIS 自带的 PyQt5 与系统 pip 装的很可能不是同一套）
from qgis.PyQt.QtCore import QVariant, QSettings
from qgis.PyQt.QtWidgets import QAction, QDialog, QFileDialog
from qgis.PyQt import uic

layer.startEditing()
layer.addFeature(feature)          # 此期间用 layer 的方法而不是 provider 的
layer.deleteFeature(fid)
layer.changeAttributeValue(fid, field_idx, value)
if layer.commitChanges():          # 提交落盘
    ...
else:
    layer.rollBack()               # 回滚全部未提交修改

# 打开图层文件
# 数据源路径（文件路径或连接字符串）、图层名称、数据提供者名称
layer = QgsVectorLayer(r'D:\\data\\layer.shp', '基准图幅', 'ogr')
if not layer.isValid():
    print('打开失败：路径错/编码坏/被占用')

# 内存图层（临时数据，URI 语法定义字段）
mem = QgsVectorLayer('Polygon?crs=EPSG:4326&field=NAME:string(50)&field=CODE:string(20)',
                     '临时区域', 'memory')

# 数据库 URI（PostGIS 示例）
pg = QgsVectorLayer('dbname=mydb host=localhost table=sheets (geom) sql=', 'sheets', 'postgres')

# 全量遍历
for feature in layer.getFeatures():
    print(feature['NAME'], feature.id())

# 表达式过滤（服务端/ provider 侧下推，大图层远快于 Python 里 if）
request = QgsFeatureRequest().setFilterExpression('"NAME" = \'East\'')
for feature in layer.getFeatures(request):
    ...

# 只要部分字段（省内存）——传入字段名列表
request = QgsFeatureRequest().setSubsetOfAttributes(['NAME', 'CODE'], layer.fields())

# 不要几何，只统计属性时
request = QgsFeatureRequest().setFlags(QgsFeatureRequest.NoGeometry)  # 不要几何
request = QgsFeatureRequest().setNoAttributes() # 连属性都不要

value = feature['NAME']        # 按字段名（推荐，自动处理字段索引）
value = feature[0]             # 按字段索引
attrs = feature.attributes()   # 整行属性 list（本项目 _delete_from_layer 用它按索引取值）

from qgis.core import NULL
if feature['NAME'] == NULL or not feature['NAME']:   # 两种都覆盖
    ...

fields = layer.fields()

# 遍历字段信息（本项目多处使用这个推导式）
names = [f.name() for f in layer.fields()]        # region_editor.py · _layer_field_indexes

# 按名查索引（不存在返回 -1，务必判断）
idx = fields.indexFromName('NAME')                # region_importer.py · _output_fields

# 单个字段的元信息
f = fields.field('NAME')      # 或 fields.at(idx)
f.name(), f.type(), f.length(), f.precision()

# 只挑某类型的字段（自动识别编号字段时用，region_importer.py · _detect_code_field）
string_fields = [f.name() for f in layer.fields() if f.type() == QVariant.String]

out_fields = QgsFields()
for field in base_layer.fields():
    out_fields.append(field)   # QgsFields.append 会拷贝
region_field = QgsField('NAME', QVariant.String)
region_field.setLength(50)   # shp 必须给长度，否则默认 255 会被截断告警
out_fields.append(region_field)

feature = QgsFeature(fields)                 # 传入 QgsFields 决定属性结构
feature.setGeometry(base_feature.geometry()) # 复制另一要素的几何
feature.setAttributes([                      # 顺序、数量必须与 fields 完全一致
    base_feature[f] if f in base_field_names
    else (region_name if f == 'NAME' else None)
    for f in field_names])

geom = QgsGeometry.fromWkt('POLYGON((0 0, 1 0, 1 1, 0 0))')  # WKT 构造
geom.asWkt()                # 导出 WKT
geom.area()                 # 面积（图层 CRS 单位，不是自动投影后的）
geom.boundingBox()          # QgsRectangle 外接矩形
geom.intersects(other)      # 相交判断
geom.contains(point)        # 包含
geom.isGeosValid()          # 有效性检查
centroid = geom.centroid()  # 质心，返回 QgsGeometry（点）

point = feature.geometry().asPoint()   # 单点图层
point.x(), point.y()

project = QgsProject.instance()

project.addMapLayer(layer)                       # 图层进工程（含图层树）
project.addMapLayer(layer, addToLegend=False)    # 只注册不进图层树
project.removeMapLayer(layer.id())               # 移除（按 id，不是 name！）
project.mapLayers()                              # {图层id: QgsVectorLayer} dict
project.mapLayersByName('layer-name')               # 按名字找，返回列表
project.layerTreeRoot()                          # 图层树（控制顺序/分组）
project.fileName()                               # 工程文件路径，未保存为 ''
project.transformContext()                       # 写文件时要传
project.crs()                                    # 工程坐标系

def find_layer_on_path(path):
    normalized = os.path.abspath(path)
    for layer in list(QgsProject.instance().mapLayers().values()):
        try:
            source = layer.source().split('|')[0]   # 去掉 '|subset=...' 等后缀
            if source and os.path.abspath(source) == normalized:
                return layer
        except Exception:
            continue
    return None

QgsProject.instance().layersAdded.connect(callback)     # 参数：[QgsMapLayer, ...]
QgsProject.instance().layersRemoved.connect(callback)   # 参数：[图层id(str), ...]

layer.selectionChanged.connect(callback) # 回调参数：(选中的 fid 集合, 取消选中的 fid 集合, 是否整表重选)

from qgis.core import (QgsCategorizedSymbolRenderer, QgsFillSymbol, QgsRendererCategory)

categories = []
for index, region in enumerate(regions):
    color = REGION_COLORS[index % len(REGION_COLORS)]
    symbol = QgsFillSymbol.createSimple({
        'color': '0,0,0,0',          # 填充 RGBA，全 0 = 透明
        'outline_color': color,      # 边框色 '#FF0000'
        'outline_width': '0.4',      # 线宽（毫米）
    })
    # QgsRendererCategory(分类值, 符号, 图例文字)
    categories.append(QgsRendererCategory(region['NAME'], symbol, region['NAME']))

layer.setRenderer(QgsCategorizedSymbolRenderer('NAME', categories))  # 参数：分类字段名
layer.triggerRepaint()

result = layer.saveDefaultStyle()    # 写 <数据源同名>.qml，重开文件自动带样式
# 返回 (状态消息: str, 成功标志: bool) 
ok = result[1] if isinstance(result, tuple) else not result
msg = result[0] if isinstance(result, tuple) else result

layer.loadDefaultStyle()             # 从 .qml 恢复
qml, ok = layer.exportNamedStyle()   # 取样式 QML 字符串（也可 loadNamedStyle(path)）