CanvasHandle
What a ref on <Canvas> gives you.
Methods
hitTest()
hitTest(
x: number,
y: number,
options?: HitTestOptions): HitTestResult[];The nodes under a canvas-space point, topmost first.
Answered natively from the geometry the renderer is drawing this frame, so
it follows animated values rather than the last committed props, and it
inverse-transforms through each <Group> the same way the renderer
transforms forward.
Only nodes carrying a useNode() handle can be named, so a hit on an
unnamed node reports node: null - the path is still there if you want
to tell two anonymous hits apart.
Parameters
x
number
y
number
options?
Returns
redraw()
redraw(): void;Force a frame without a React commit. Only needed for state the scene
points at rather than holds - an image handle re-pointed at new pixels, say.
A NodeHandle.set already redraws on its own.
Returns
void
save()
save(path: string, options?: SnapshotOptions): Promise<void>;The same readback, encoded and written to path natively. The image bytes
never enter JS, so a large canvas costs nothing on the JS heap.
Parameters
path
string
options?
Returns
Promise<void>
setViewport()
setViewport(viewport: object): void;Move the root viewport - the zoom/pan the renderer owns.
One native write and a redraw: no React render, no scene recommit, no wire
traffic, because the transform sits above the whole draw program. That is
the entire point of it over a <Group transform>, which re-encodes the
scene on every tick.
Omitted fields keep their current value, so setViewport({ zoom: 2 })
pans nowhere. A non-finite x/y or a non-positive zoom is ignored as
a whole rather than collapsing the scene.
hitTest follows it: a hit at (10, 10) under zoom: 2 reports the node at
scene (5, 5), and snapshot() reads back the zoomed frame.
The path a gesture should use: it costs one native write per tick, with no
React render and no scene re-encode. The viewport prop is the same write
driven from a commit instead.
Parameters
viewport
x?
number
y?
number
zoom?
number
Returns
void
snapshot()
snapshot(options?: SnapshotOptions): Promise<Snapshot>;Read the canvas back into memory. Resolves with an ArrayBuffer, never a
base64 string. iOS wraps the encoded native buffer without copying;
Android copies the temporary JNI buffer into Nitro-owned memory once.
The readback is issued on the render thread inside a frame it forces, and the encode runs on a worker, so the animation loop keeps its cadence. Rejects (rather than resolving a black frame) if the canvas has no surface yet or is unmounted before the frame lands.
Parameters
options?
Returns
Promise<Snapshot>