AnnotatedRegionLayers 返回相对于裁剪区域的局部坐标

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

注解是在渲染阶段分配给屏幕区域的元数据。通过位置搜索注解可以获得包含该位置的上下文信息。它们用于检测鼠标事件和应用程序栏的主题。

当 localPosition 最初添加到搜索结果时，它被定义为相对于拥有注解的图层，结果证明这是一个设计错误。与图层的偏移量没有意义且不可靠。例如，如果变换矩阵只是一个简单的平移，Transform widget 会在同一个图层上绘制并带有偏移量；如果矩阵不是平凡的，它会推送一个专用的 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,
        // Used to be:
        // localPosition: localPosition,
        localPosition: localPosition - offset,
      ));
    }
    ...
  }
}

概念上，这改变了 AnnotatedRegionLayer.offset 和 size 的定义方式。它们以前的意思是“限制注解搜索的裁剪矩形”，而现在它们共同表示“注解对象所处的区域”。

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

登陆版本：1.15.2
稳定版本: 1.17

API 文档

• AnnotatedRegionLayer
• AnnotationEntry

相关问题

• Issue #49568

相关 PR

• 使注解的 localPosition 相对于对象