@open-pioneer/printing
v1.7.0
Published
This package provides a UI component to export the current map view as a printable file.
Keywords
Readme
@open-pioneer/printing
This package provides a UI component and an API to export the current map view as a printable file.
The UI allows users to enter a title, to choose the page format, the page orientation, the file format, the print resolution and the scale, and to trigger the export. While the component is shown, the area of the map that will be printed is highlighted on the map.
The supported file formats are PDF and PNG. The printed map shows the current map in the middle of the page at the selected scale.
The package also provides a printing service that creates an image of the map as a canvas element or a data URL for a PNG image.
Usage
UI Component
To integrate the printing in your app, insert the following snippet and reference a map:
<Printing
map={map}
/> /* instead of passing the map, the `DefaultMapProvider` can alternatively be used */Configuring the available options
To restrict or extend the options that can be chosen by the user, pass the allowed values as props.
For example:
<Printing
map={map}
pageFormats={["a4", "a3"]}
pageOrientations={["landscape"]}
fileFormats={["pdf"]}
dpis={[150, 300]}
scales={[25000, 10000, 5000]}
/>Printing a screenshot of the map
By default, the component uses the "page" mode described above.
To print the entire map as it is currently displayed, set mode to "screenshot":
<Printing map={map} mode="screenshot" />In this mode, the user can only enter a title and choose the file format. This was the default behavior of the component prior to v1.7.0.
The props fileFormats and viewPadding are supported in both modes.
The props pageFormats, pageOrientations, dpis and scales are not supported in "screenshot" mode.
The component throws an error if one of them is set.
Printing Service
To use the printing service, inject it as following:
// build.config.mjs
import { defineBuildConfig } from "@open-pioneer/build-support";
export default defineBuildConfig({
ui: {
references: ["printing.PrintingService"]
}
});const printingService = useService<PrintingService>("printing.PrintingService");
// Triggers printing of the map model and waits for the result.
const printResult = await printingService.printMap(map);
// An HTMLCanvasElement containing an image of the map
const canvas = printResult.getCanvas();
// For convenience, an image encoded as PNG (i.e. `data:image/png;base64,...`)
const dataURL = printResult.getPNGDataURL();It is configurable whether to add an overlay element above the map or not. The default overlay blocks user interactions while the map is printing. The text content of the overlay can be overwritten by configuring a custom text.
Example:
const printResult = await printingService.printMap(map, {
blockUserInteraction: true,
overlayText: "custom text"
});To print the map at a specific scale and page size, pass the scale denominator, the print resolution in dots per inch and the page size in millimeters:
const printResult = await printingService.printMap(map, {
scale: 25000,
dpi: 300,
width: 297,
height: 210
});The map is resized and zoomed while printing and restored afterwards.
Printed elements
The printed map contains all map elements, visible layers, scale-bar and a title. If the user does not enter a title, the map is printed without title.
To prevent custom elements from showing in the printed map, add the CSS class name printing-hide to the elements.
View padding
The printing widget and the printing service will by default respect the map's current view padding (see OpenLayers View class).
This means that padded regions (a border on every side) will not be included in the printed result.
To ignore the view padding when printing the map, you can pass viewPadding: "ignore" to the printing service or the printing component.
Known issues
- Printing to PNG may not work on Safari / Chrome on iOS (see https://github.com/open-pioneer/trails-openlayers-base-packages/issues/294)
License
Apache-2.0 (see LICENSE file)
