dom-to-image-more
Version:
Generates an image from a DOM node using HTML5 canvas and SVG
97 lines (70 loc) • 8.79 kB
Markdown
# `impl` reference
Everything hanging off `domtoimage.impl` is an **internal implementation surface**,
exposed only so the unit tests (and a few advanced integrations) can reach the moving
parts. It is **not** part of the stable public API (`toSvg`, `toPng`, `toJpeg`, `toBlob`,
`toCanvas`, `toPixelData`) and may change between releases without notice.
```js
domtoimage.impl;
```
| Member | Kind | Summary |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `util` | object | Low-level helpers (type guards, geometry, URL/resource fetching). Documented separately in [UTILS.md](UTILS.md). |
| `fontFaces` | object | Discovers `@font-face` web fonts and inlines them as `data:` URLs. |
| `images` | object | Inlines `<img>` and SVG `<image>` sources and CSS `background`/`background-image`/`mask` URLs. |
| `inliner` | object | The URL-rewriting engine shared by `fontFaces` and `images`. |
| `urlCache` | array | Per-render cache of fetched resources, keyed by URL. |
| `options` | object | The **live, resolved** options for the current/last render. |
| `copyOptions` | function | Merges caller options over the defaults into `impl.options`. |
| `resetUrlCache` | function | Clears `urlCache`. Called at the start/end of a render; exposed for tests/advanced callers driving the helpers directly. |
---
## `impl.options`
The resolved options object that the render pipeline actually reads. It is **not** the
object you pass to `toPng(node, options)` — that one is normalized by `copyOptions`
(filling in defaults for anything omitted) and the result is stored here. Inspecting it
after a call shows the effective configuration that was used.
See the **Rendering options** section of the [README](../README.md#rendering-options) for
the full list of fields and their defaults.
## `impl.copyOptions(options)`
`(options: object) => void`
Normalizes `options` against the library defaults and writes the result into
`impl.options`. Every option is copied through an explicit
`typeof options.x === 'undefined' ? default : options.x` check, so passing `{}` restores
the full default configuration. Called automatically at the start of each top-level
render; exposed mainly so tests can set up `impl.options` directly when exercising helpers
like `util.getAndEncode` in isolation.
---
## `impl.fontFaces`
Produced by `newFontFaces()`.
| Member | Signature | Summary |
| ---------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resolveAll()` | `() => Promise<string>` | Reads every web-font `@font-face` rule, inlines its `src` URLs as `data:` URLs, and resolves to the concatenated CSS text (newline-joined) ready to drop into a single `<style>`. |
| `impl.readAll()` | `() => Promise<WebFont[]>` | Scans `document.styleSheets`, keeps only `@font-face` rules whose `src` needs processing, and returns one _web font_ object per rule. Stylesheets whose `cssRules` can't be read (e.g. cross-origin) are skipped with a logged error. |
Each _web font_ object returned by `readAll()` exposes:
- `resolve()` → `Promise<string>` — inline this rule's URLs and return its rewritten
`cssText`.
- `src()` → `string` — the raw `src` property value of the rule.
## `impl.images`
Produced by `newImages()`.
| Member | Signature | Summary |
| ------------------------ | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inlineAll(node)` | `(node: Node) => Promise<…>` | Recursively walks `node`, inlining the CSS `background`/`background-image`/`mask` URLs on every element, replacing HTML `<img>` `src` values with `data:` URLs, and inlining SVG `<image>` `href`/`xlink:href`. Non-element nodes pass through untouched. |
| `impl.newImage(element)` | `(element: HTMLImageElement) => { inline(get?) }` | Wraps a single image element. `inline(get?)` fetches `element.src` (via `get`, defaulting to `util.getAndEncode`) and swaps in the resulting `data:` URL; already-`data:` sources are left as-is. |
## `impl.inliner`
Produced by `newInliner()`. The shared engine that finds `url(...)` references in CSS text
and rewrites them to inlined `data:` URLs. Used by both `fontFaces` and `images`.
| Member | Signature | Summary |
| ------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inlineAll(string, baseUrl?, type?, get?)` | `(string, baseUrl?, type?, get?) => Promise<string>` | Finds every non-`data:` `url(...)` in `string`, fetches each (passing `type` to `getAndEncode`), and returns the CSS with those URLs replaced by `data:` URLs. Returns the input unchanged when there is nothing to inline. |
| `shouldProcess(string)` | `(string) => boolean` | `true` if `string` contains at least one `url(...)` reference. |
| `impl.readUrls(string)` | `(string) => string[]` | Extracts the URL values from every `url(...)` in `string`, excluding ones that are already `data:` URLs. |
| `impl.inline(string, url, baseUrl?, type?, get?)` | `(string, url, baseUrl?, type?, get?) => Promise<string>` | Inlines a single `url`: resolves it against `baseUrl` (if given), fetches it (passing `type` to `getAndEncode`), and replaces every `url(...)` occurrence of it in `string`. |
| `impl.urlAsRegex(urlValue)` | `(urlValue) => RegExp` | Builds the (escaped) global regex that matches `url("urlValue")` with optional quotes. |
## `impl.urlCache`
An array used by the resource fetch core (behind `util.getAndEncode` and
`util.getResourceText`) to dedupe and cache fetches within a render. Each entry is
`{ url: string, promise: Promise | null }`; repeat requests for the same URL share the
same in-flight/settled promise. It is cleared at the start/end of each render (and via
`impl.resetUrlCache()`), so each capture fetches fresh.
---
> For the `util` helpers (`isHTMLElement`, `width`, `getAndEncode`, `resolveUrl`, `uid`,
> …), see [UTILS.md](UTILS.md).