reader.viewport
The reader.viewport reference: its size and page size at each layout, whether it shows a spread, its scale while zoomed, and whether it is moving.
The reference for reader.viewport, the element that frames what the reader
shows. The viewport guide explains how to use it: what it is
for, how to resize it, spread mode, and the absolute and relative viewports.
The viewport is measured at the start of each layout of the reader:
- when the reader is mounted;
- when you call
reader.layout(); - when the container the reader is mounted into changes size, unless
layoutAutoResizeisfalse, see My book does not resize with my screen; - when a setting that moves the pages changes, such as
spreadMode, the page turn mode or direction, or the page margins.
Its size, its page size and whether it shows a spread change only then. A spine item that finishes loading lays the items out again, but does not measure the viewport.
A layout runs only while the viewport has a size, see
.isSized$. While the container is hidden, under
display: none for example, it measures 0 by 0: the book keeps its last
layout, and a layout asked for meanwhile runs once the container is shown
again, see
My reader is hidden in a tab or an Activity.
.value
Section titled “.value”{ element: HTMLElement isSpread: boolean pageSize: { width: number; height: number } width: number height: number}The state of the latest layout, read synchronously.
| Field | Meaning |
|---|---|
element |
The viewport's element: a div with the data-prose-reader-viewport attribute, inside the container the reader is mounted into. It holds the pages, and a zoom transforms it |
width, height |
The size of the element in CSS pixels at the last layout, from its clientWidth and clientHeight, which leave out a scrollbar and ignore a transform. This is the absolute viewport |
isSpread |
Whether two pages share the viewport: the spreadMode setting, resolved against the viewport's size and the book. See Spread mode |
pageSize |
The size of one page: the viewport's size, or half its width in a spread |
Before the reader is first laid out, the state is a placeholder: width,
height and both sides of pageSize are 1, and isSpread is false.
.state$
Section titled “.state$”Observable<typeof reader.viewport.value>The state as soon as you subscribe, then the state of every layout, changed or not. See Reactive state.
.watch()
Section titled “.watch()”type ViewportState = typeof reader.viewport.value
watch<K extends keyof ViewportState>(key: K): Observable<ViewportState[K]>watch<K extends keyof ViewportState>(keys: K[]): Observable<Pick<ViewportState, K>>See Reactive state.
.layout$
Section titled “.layout$”Observable<void>Emits each time the viewport is measured for a layout, right after the state of
that layout. The book is not laid out yet: reader.layout$ emits once its pages
are. Both complete when the reader is destroyed.
.pageSize
Section titled “.pageSize”{ width: number; height: number }The size of one page at the last layout, the same as .value.pageSize.
Renderers size their pages from it, as the PDF and audio enhancers do.
.absoluteViewport
Section titled “.absoluteViewport”{ width: number; height: number }The size the book is laid out for: the width and height of the last layout.
Navigation and pagination compute with it, see
Absolute vs Relative viewport.
.relativeViewport
Section titled “.relativeViewport”{ width: number; height: number }The area the viewport shows once transformed, such as by a zoom: the absolute
viewport divided by .scaleFactor. Zoomed out to half the size, it is twice as
large as the absolute viewport. Which part of the book it shows:
.getVisibleSlice().
.scaleFactor
Section titled “.scaleFactor”numberThe scale the viewport is rendered at: its rendered width over its layout
width, both measured when you read it. 2 when zoomed in to twice the size,
0.5 when zoomed out to half, and 1 when the viewport is not transformed or
has no rendered size.
Measuring the element
Section titled “Measuring the element”These measure the viewport's element as it is now, not as it was at the last
layout. Each reads its clientWidth and clientHeight, which can make the
browser compute styles and layout. The element has a size when both are above
0. Hidden, as under display: none, or out of the document, it measures 0 by
0, and has none. So has an element with a width but no height, such as in a
container that is not given one.
.isSized$
Section titled “.isSized$”Observable<boolean>Whether the element has a size: measured as soon as you subscribe, then each time a resize changes it, as when its container is hidden or shown. It completes when the reader is destroyed.
Each subscription observes the element with its own resize observer. A
browser reports a resize at its next rendering update, so a hide just made
reads false from .hasSize() before it does here.
The reader works only while the element has a size:
- every layout of the spine waits for one. A layout running when the element loses its size stops, and starts again once it has one;
- the reader starts no load or unload of the documents of spine items. A document loaded with no size has no layout either, and the browser does not request its fonts: an HTML document already loading waits for a size before it counts as loaded;
- a navigation waits for one, since a target such as a cfi names a place in a document that has no layout. If several wait, only the last one runs.
reader.viewport.isSized$.subscribe((isSized) => { // false while the container is hidden}).hasSize()
Section titled “.hasSize()”() => booleanWhether the element has a size now.
.hasNewSizeSinceLayout()
Section titled “.hasNewSizeSinceLayout()”() => booleanWhether the element has a size, and not the one of the last layout, so that
laying out again would change anything. With layoutAutoResize: "container",
the reader lays out for a resize of its container only when this is true: a
container hidden, then shown again at the size it had, needs no layout.
What it shows
Section titled “What it shows”.getVisibleSlice()
Section titled “.getVisibleSlice()”(position: SpinePosition | UnboundSpinePosition) => DOMRectThe part of the book the viewport shows while the book is at position, in the
same coordinates, its transform included: what the screen shows. The reader
loads the spine items it shows, with the ones it preloads around them.
position is the spine position at the viewport's top-left corner, where a
navigation puts it, such as the one
reader.navigation.position$ gives.
Untransformed, the slice is the absolute viewport at the position. Transformed,
it is the relative viewport, from wherever the transform
takes the viewport's corner, measured on the page:
- a paginated zoom scales the viewport around its center, so zoomed out the
slice reaches past the absolute viewport on every side, and the slice
follows the viewport where
reader.zoom.move()moves it; - a scrolled zoom scales the viewport from its top and scrolls to keep its center, which moves the navigation: the slice starts at the position's height.
reader.navigation.position$.subscribe((position) => { // the part of the book on screen, zoom included const { x, y, width, height } = reader.viewport.getVisibleSlice(position)})The spine items it shows are the ones whose places overlap it. While a layout
is pending, those places can still move:
reader.spine.isLayoutCurrent() says when
they won't.
Spreads
Section titled “Spreads”.wouldSpreadAt()
Section titled “.wouldSpreadAt()”(size: { width: number; height: number }) => booleanWhether a viewport of this size would show two pages side by side, for the
current book and spreadMode setting. It is the rule every layout applies to
the viewport's own size, so it tells what a rotation or a resize would show
before it happens. .value.isSpread is what is shown now. The guide's
Spread mode uses it to anticipate a rotation.
Whether the viewport moves
Section titled “Whether the viewport moves”Two streams on the reader itself, rather than on reader.viewport, say whether
the viewport is moving.
reader.viewportState$
Section titled “reader.viewportState$”Observable<"free" | "busy">The same state as
reader.navigation.navigationState$:
"busy" while the viewport moves, while a navigation lock is held, and while
the reader restores the navigation after one is released, "free" otherwise.
It replays the current state when you subscribe.
reader.viewportState$.subscribe((state) => { // "busy" while a page turns, "free" once it has landed})reader.viewportFree$
Section titled “reader.viewportFree$”Observable<"free">Emits each time the viewport becomes free, and at once if it is free when you subscribe. The reader waits for it before it loads or unloads the document of a spine item. Do the same with work that should not run while a page turns:
import { first } from "rxjs"
reader.viewportFree$.pipe(first()).subscribe(() => { // the viewport is not moving})A layout that only the loads of spine items ask for waits longer: until the viewport has stayed free for 50 ms, see Layout.