AnnotatedRegionLayers 返回相对于裁剪区域的局部位置

AnnotatedRegionLayers在注释搜索中返回的局部位置已更改为相对于裁剪区域而不是图层。这使局部位置更有意义且更可靠，但会破坏直接执行注释搜索并使用局部位置的代码。

注释是在渲染阶段分配给屏幕上区域的元数据。使用位置搜索注释会提供包含该位置的上下文信息。它们用于检测鼠标事件和应用栏的主题。

当 localPosition 首次添加到搜索结果中时，它被定义为相对于拥有该注释的图层，事实证明这是一个设计错误。图层的偏移量毫无意义且不可靠。例如，如果变换矩阵是简单的平移，Transform 小部件会在同一图层上绘制带有偏移量的图形；如果矩阵是非平凡的，则会推送一个专用的 TransformLayer。前一种情况保留了之前的坐标原点（例如，应用程序的左上角），而后一种情况会移动位置原点，因为它位于新图层上。这两种情况可能不会产生明显的视觉差异，因为额外的图层可能只是一个 99% 的缩放比例，尽管注释搜索返回不同的结果。为了使这个局部位置可靠，我们必须选择一个结果来坚持。

AnnotatedRegionLayer 返回的 localPosition 现在是它接收到的局部位置减去 offset，其中 offset 是裁剪区域相对于图层的位置。

class AnnotatedRegionLayer<T> extends ContainerLayer {
  @override
  bool findAnnotations<S>(AnnotationResult<S> result, Offset localPosition, { required bool onlyFirst }) {
    ...
    if (/* shouldAddAnnotation */) {
      result.add(AnnotationEntry<S>(
        annotation: typedValue,
        // 原来是：
        // localPosition: localPosition,
        localPosition: localPosition - offset,
      ));
    }
    ...
  }
}

从概念上讲，这改变了 AnnotatedRegionLayer.offset 和 size 的定义方式。它们过去表示“限制注释搜索的裁剪矩形”，而现在它们共同表示“注释对象的区域”。

正在积极使用此局部位置的代码可能直接与图层交互，因为使用渲染对象或小部件已使此结果不可靠。为了保留之前的行为，您可以重新实现 AnnotatedRegionLayer 以返回不减去偏移量的局部位置。

包含于版本：1.15.2
稳定版本：1.17

API 文档：

• AnnotatedRegionLayer
• AnnotationEntry

相关问题：

• 问题 #49568

相关 PR：

• 使注释的 localPosition 相对于对象

除非另有说明，否则本网站上的文档反映的是 Flutter 的最新稳定版本。页面最后更新于 2025-01-30。 查看源代码 或 报告问题。