G

在 G 中有以下继承关系：

Document -> Node -> EventTarget

我们可以把 Document 类比成浏览器环境中的 window.document，例如在浏览器中：

它有指向 window 的引用 defaultView
通过 documentElement 访问 <html> 元素
可以通过一系列方法查询节点，例如 getElementById
通过 createElement 创建元素

我们尽可能实现了以上浏览器提供的 API。

继承自

Node

属性

nodeName

实现了 Node.nodeName，返回 'document'，在事件处理器中可用来快速判断 target，例如点击了画布的空白区域时：

canvas.addEventListener('click', (e) => {
    e.target; // Document

    if (e.target.nodeName === 'document') {
        //...
    }
});

defaultView

指向画布，例如：

canvas.document.defaultView; // canvas

https://developer.mozilla.org/en-US/docs/Web/API/Document/defaultView

documentElement

返回场景图中的根节点，在创建画布时会默认使用 Group 创建一个：

canvas.document.documentElement; // Group
canvas.document.documentElement.getBounds(); // 获取整个场景的包围盒

https://developer.mozilla.org/en-US/docs/Web/API/Document/documentElement

timeline

默认时间轴，在动画系统中使用。

https://developer.mozilla.org/zh-CN/docs/Web/API/Document/timeline

ownerDocument

返回 null

方法

由于继承自 Node，因此显然拥有了事件绑定能力：

canvas.document.addEventListener('click', () => {});

但在一些方法特别是节点操作上和 Node 有差异。

节点操作

虽然继承了 Node，但在 Document 上无法调用一些节点操作方法，正如在浏览器中调用 document.appendChild 会返回如下错误一样：

Uncaught DOMException: Failed to execute 'appendChild' on 'Node': Only one element on document allowed.

节点查询

以下节点查询方法等同于在 document.documentElement 上执行。

createElement

通常我们建议使用 new Circle() 这样的方式创建内置或者自定义图形，但我们也提供了类似 DOM CustomElementRegistry API，可以使用 document.createElement 创建完成注册的图形，因此以下写法等价：

import { Shape, Circle } from '@antv/g';

const circle = canvas.document.createElement(Shape.CIRCLE, {
    style: { r: 100 },
});

// 或者
const circle = new Circle({ style: { r: 100 } });

https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement

createElementNS

目前实现同 createElement。

elementFromPoint

当我们想知道画布中某个点上堆叠了多少个图形，除了通过交互事件，还可以通过 API 方式完成拾取。

该方法接受一组 x, y 坐标（在 Canvas 坐标系下，如果想使用其他坐标系下的坐标，请使用转换方法）为参数，返回拾取结果。

在下面的例子中，我们在 Canvas 坐标系下 [100, 100] 放置了一个半径为 100 的 Circle，在红点处拾取时会返回它：

const topMostElement = await canvas.document.elementFromPoint(20, 100); // circle1

await canvas.document.elementFromPoint(0, 0); // canvas.document.documentElement

有三点需要注意：

有别于浏览器提供的同步 API，由于部分渲染器的实现（例如 g-webgl）需要通过 GPU 方式完成拾取，因此该方法为异步
当只需要获取该点命中的最顶层的图形时，应该使用 elementFromPoint 而非 elementsFromPoint，前者在绝大部分场景下都比后者快
拾取判定遵循以下规则：
1. 超出画布视口范围（考虑到相机，并不一定等于画布范围）返回 null。
2. 图形的 interactive 属性会影响拾取。不可交互图形无法拾取。
3. 图形的 visibility 属性会影响拾取。不可见图形无法拾取。
4. 图形的 opacity 属性不会影响拾取。即使图形完全透明，依然也会被拾取到。

https://developer.mozilla.org/en-US/docs/Web/API/Document/elementFromPoint

elementsFromPoint

当目标点上有多个图形堆叠时，该方法会按照 z-index 排序后返回它们，返回结果中的第一个元素为最顶层的图形。

该方法同样接受一组 x, y 坐标作为参数。

在下面的例子中，circle2 在 circle1 之上，因此在重叠区域进行拾取两者都会出现在结果数组中，并且 circle2 在前：

const elements = await canvas.document.elementsFromPoint(150, 150); // [circle2, circle1, document.documentElement]

注意事项：

该返回结果和事件对象上的 composedPath() 的差别是，后者会在返回数组中追加 Document 和 Canvas 对象，而前者只到画布根节点为止。
超出画布视口范围返回空数组。

https://developer.mozilla.org/en-US/docs/Web/API/Document/elementsFromPoint

elementsFromBBox

区域查询特别是基于包围盒的检测在以下场景中特别适用：

脏矩形渲染中用于确定受影响区域
矩形刷选批量选中图形

此类基于包围盒的检测不需要太精确，配合内部 RBush 这样的空间索引，因此速度很快。

该方法为同步方法，接受包围盒描述 minX, minY, maxX, maxY 坐标（在 Canvas 坐标系下）：

const elements = document.elementsFromBBox(minX, minY, maxX, maxY);

注意事项：

会考虑 visibility 和 pointer-events 属性
无需考虑 WebGL / WebGPU 这样基于 GPU 的拾取实现，为同步方法
返回的元素数组按实际渲染次序排序

elementFromPointSync

elementFromPoint 的同步版本，值得注意的是，并不是所有渲染器都会实现该方法，目前仅有 g-canvas，g-svg 和 g-canvaskit 提供了对应实现：

const element = canvas.document.elementFromPoint(0, 0); // canvas.document.documentElement

elementsFromPointSync

elementsFromPoint 的同步版本，值得注意的是，并不是所有渲染器都会实现该方法，目前仅有 g-canvas，g-svg 和 g-canvaskit 提供了对应实现：

const elements = canvas.document.elementsFromPoint(150, 150); // [circle2, circle1, document.documentElement]

Document

继承自

属性