弧线 Arc

弧线（Arc）用于在地图上绘制两点之间的弧线，通过一个途经点（passedPoint）确定弧线的弯曲方向和程度。

本文档介绍 Arc 的创建与样式配置。

创建 Arc

Arc(
  id: 'a1',
  start: const LatLng(39.90, 116.39),
  end: const LatLng(39.94, 116.43),
  passedPoint: const LatLng(39.93, 116.40), // 途经点，弧线经过此点
  color: const Color(0xFF2196F3),
  width: 6,
)

添加到地图：

TencentMap(
  arcs: {arc},
  ...
)

---

Arc 参数

参数	类型	默认值	说明
id	String?	自动生成	唯一标识
start	LatLng	必填	弧线起点
end	LatLng	必填	弧线终点
passedPoint	LatLng?	必填	途经点（弧线经过此点）
width	double	5.0	弧线宽度（逻辑像素）
color	Color	Color(0xFF000000)	弧线颜色
strokeWidth	double	0.0	描边宽度（逻辑像素）
strokeColor	Color	Color(0x00000000)	描边颜色
showArrow	bool	false	是否显示箭头
arrowGap	double?	null	箭头间距
displayLevel	int	2	显示层级（0=道路之上, 1=建筑之上, 2=标注之上）
visible	bool	true	是否可见
zIndex	int	0	堆叠顺序

---

途经点说明

passedPoint（途经点）决定弧线的形状：

• 途经点在起点和终点的连线上方 → 弧线向上弯曲
• 途经点在连线下方 → 弧线向下弯曲
• 途经点离连线越远 → 弧线弯曲程度越大

// 向北弯曲的弧线
Arc(
  start: const LatLng(39.90, 116.39),
  end: const LatLng(39.90, 116.43),
  passedPoint: const LatLng(39.92, 116.41), // 在连线上方
  color: const Color(0xFFFF5722),
  showArrow: true,
)

---

声明式更新

基本原理

Arc 通过 Set<Arc> 以声明式方式管理。插件在 Widget 重建时自动 diff 新旧两个 Set，计算出增/删/改三类变更并推送到原生层：

• diff 按 id 索引：内部用 Map<String, Arc> 索引，不依赖 Set 的 hashCode
• 属性比较用 ==：Arc 重写了 ==，比较 start/end/passedPoint/width/color/visible 等全部业务属性
• 对象不可变：Arc 是 @immutable，修改属性必须用 copyWith 创建新对象

推荐用法：Map 管理 + Set 传入

final Map<String, Arc> _arcs = {};

// 添加
_arcs['a1'] = Arc(
  id: 'a1',
  start: const LatLng(39.90, 116.39),
  end: const LatLng(39.94, 116.43),
  passedPoint: const LatLng(39.93, 116.40),
  color: const Color(0xFF2196F3),
);

// 更新（必须 copyWith，不能原地改字段）
_arcs['a1'] = _arcs['a1']!.copyWith(color: Colors.red);

// 删除
_arcs.remove('a1');

// 传入 Widget
TencentMap(arcs: Set<Arc>.of(_arcs.values));

哪些情况会导致更新不触发

错误写法	原因	正确写法
在同一 Set 上 add copyWith 后的对象：_arcs.add(a.copyWith(color: Colors.red))	hashCode 仅基于 id（相同），但 == 为 false（属性不同）→ Set 同时保留新旧两个对象 → diff 按 id 索引只取最后一个，行为不可预测	创建全新 Set，或用 Map 管理
两个 Arc 用同一个 id	diff 按 id 索引成 Map 时后者覆盖前者 → 变更丢失	确保每个 Arc 有唯一 id（不传 id 时自动生成）
修改了 State 变量但没调 setState	Widget 不重建 → didUpdateWidget 不触发 → diff 不执行	必须在 setState 内修改变量

提示：Arc 没有 onTap 回调，无需考虑回调变更不触发的问题。