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,
        // Used to be:
        // localPosition: localPosition,
        localPosition: localPosition - offset,
      ));
    }
    ...
  }
}

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

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

已在版本: 1.15.2 中发布
稳定版本: 1.17

API 文档

• AnnotatedRegionLayer
• AnnotationEntry

相关问题

• 问题 #49568

相关 PR

• 将 Annotation 的 localPosition 设为相对于对象