@arcgis/map-components
Version:
ArcGIS Map Components
641 lines (640 loc) • 26.9 kB
TypeScript
/// <reference path="../../index.d.ts" />
import type FileLink from "@arcgis/core/widgets/Print/FileLink.js";
import type CustomTemplate from "@arcgis/core/widgets/Print/CustomTemplate.js";
import type PortalItem from "@arcgis/core/portal/PortalItem.js";
import type TemplateOptions from "@arcgis/core/widgets/Print/TemplateOptions.js";
import type MapView from "@arcgis/core/views/MapView.js";
import type Collection from "@arcgis/core/core/Collection.js";
import type SpatialReference from "@arcgis/core/geometry/SpatialReference.js";
import type Portal from "@arcgis/core/portal/Portal.js";
import type { SubmitEvent, CompleteEvent } from "@arcgis/core/widgets/Print/PrintViewModel.js";
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { ArcgisReferenceElement, HeadingLevel } from "../types.js";
import type { Formats } from "./types.js";
import type { CollectionChangeEvent } from "@arcgis/core/core/Collection.js";
import type { T9nMeta } from "@arcgis/lumina/controllers";
import type { Formats as Formats2, Layouts, TemplateCustomTextElements, State } from "@arcgis/core/widgets/Print/types.js";
/**
* The Print component connects your application with a [printing service](https://doc.esri.com/en/arcgis-enterprise/latest/administer/configure-the-portal-to-print-maps.html) to allow the map to be printed.
* It takes advantage of server-side, high-quality, full cartographic print functionality using the ExportWebMap service of ArcGIS,
* which can be configured with custom layout templates. One is provided that shows the map only, while another provides a layout with legend, etc.
* The Print component works with the [print](https://developers.arcgis.com/javascript/latest/references/core/rest/print/) module, which generates a printer-ready version of the map.
*
* The Print component uses the ArcGIS Online print service by default, but it can be configured to use a custom print service with the [printServiceUrl](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-print/#printServiceUrl) property.
* The component can preserve map scale or map extent in the printout. By default, the map extent is preserved. Use
* [TemplateOptions.scaleEnabled](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/TemplateOptions/#scaleEnabled) to preserve scale instead.
*
* The Print component prints a localized date for all [layouts](https://developers.arcgis.com/javascript/latest/references/core/rest/support/PrintTemplate/#layout)
* except `map-only`. If using a custom print service, then `customTextElements` are supported for each print
* template. Values found there will be populated in the Print component under `Advanced options`. These values can
* be overwritten in the Print component UI, or programmatically using the
* [templateCustomTextElements](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-print/#templateCustomTextElements) property.
*
* For more information about printing with the `MAP_ONLY` layout, please see
* [exportOptions](https://developers.arcgis.com/javascript/latest/references/core/rest/support/PrintTemplate/#exportOptions).
*
* **Known limitations**
*
* See [print](https://developers.arcgis.com/javascript/latest/references/core/rest/print/) for a detailed list of known limitations.
*
* ```html
* <arcgis-map item-id="45725ba7d9fb47a0925398919b13d1fa">
* <arcgis-print slot="top-right"></arcgis-print>
* </arcgis-map>
* ```
*
* ```js
* // get a reference to the component
* const components = document.querySelectorAll("arcgis-print");
*
* const portal = new Portal({
* url: "https://user.maps.arcgis.com/sharing",
* authMode: "immediate",
* authorizedCrossOriginDomains: ["https://user.maps.arcgis.com"],
* });
*
* components.forEach((component) => {
* component.portal = portal;
* });
* ```
*
* @since 4.28
*/
export abstract class ArcgisPrint extends LitElement {
/**
* Specify the print output file format(s) that the user can select based on the options available from the print service.
* This property can take a string value or an array of string values.
*
* When this value is "all" (default value), all the print service formats are available to be used.
* When an array of string values is used, only those values that match the options available from the print service will be used.
* If none of the input string values match those available from the print service, `allowedFormats` will fallback to default behavior.
*
* @default "all"
* @since 4.15
* @see [TemplateOptions#format](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/TemplateOptions/#format)
* @example
* const print = new Print({
* view: view,
* printServiceUrl: url
* });
*
* print.viewModel.allowedFormats = ["jpg", "png8", "png32"];
*
* view.ui.add(print, {position: "top-right"});
*/
accessor allowedFormats: Formats2;
/**
* Specifies the print output file format(s) that the user can select when saving the exported map printout.
* This property can take a string value or an array of string values.
*/
accessor allowedFormatsForSaving: Formats | undefined;
/**
* Specify the print output layout(s) that the user can select based on the options available from the print service.
* This property can take a string value or an array of string values.
*
* When this value is "all" (default value), all the print service layouts are available to be used.
* When an array of string values is used, only those values that match the options available from the print service will be used.
* If none of the input string values match those available from the print service, `allowedLayouts` will fallback to default behavior.
*
* @default "all"
* @since 4.15
* @see [TemplateOptions.layout](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/TemplateOptions/#format)
* @example
* const print = new Print({
* view: view,
* printServiceUrl: url
* });
*
* print.viewModel.allowedLayouts = ["a3-landscape", "a3-portrait"];
*
* view.ui.add(print, {position: "top-right"});
*/
accessor allowedLayouts: Layouts;
/**
* If true, the component will not be destroyed automatically when it is
* disconnected from the document. This is useful when you want to move the
* component to a different place on the page, or temporarily hide it. If this
* is set, make sure to call the [destroy()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-print/#destroy) method when you are done to
* prevent memory leaks.
*
* @default false
*/
accessor autoDestroyDisabled: boolean;
/**
* Indicates whether to automatically populate the author field in the print layout advanced options
* with the username of the current portal user.
*
* This only takes effect if there is a portal with a signed-in user assigned to the [portal](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-print/#portal) property.
*
* @default false
* @since 5.0
*/
accessor autoPopulateAuthor: boolean;
/**
* Indicates whether or not to include [defaultTemplates](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/PrintViewModel/#defaultTemplates).
*
* @default false
*/
accessor excludeDefaultTemplates: boolean;
/**
* Indicates whether or not to include templates from an organization's portal.
*
* @default false
*/
accessor excludeOrganizationTemplates: boolean;
/**
* The collection of links exported from the Print component.
*
* @since 4.33
*/
accessor exportedLinks: Collection<FileLink>;
/**
* This option allows passing extra parameters (in addition to [templateOptions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-print/#templateOptions)) to the print (export webmap) requests.
*
* @since 4.20
*/
accessor extraParameters: Record<string, any> | null | undefined;
/**
* Indicates the heading level to use for the "Exported files" text where users can
* access the exported map printout. By default, this text is rendered
* as a level 3 heading (e.g. `<h3>Exported files</h3>`). Depending on the component's placement
* in your app, you may need to adjust this heading for proper semantics. This is
* important for meeting accessibility standards.
*
* @default 3
*/
accessor headingLevel: HeadingLevel;
/**
* Indicates whether the advanced options section in the Print component UI is hidden.
*
* @default false
* @since 5.0
*/
accessor hideAdvancedOptions: boolean;
/**
* @default false
* @internal
*/
accessor hideFeatureAttributes: boolean;
/**
* Indicates whether the component's header is hidden.
*
* @default false
*/
accessor hideHeader: boolean;
/**
* @default false
* @internal
*/
accessor hideIncludeTables: boolean;
/**
* Icon which represents the component.
* Typically used when the component is controlled by another component (e.g. by the Expand component).
*
* @default "print"
* @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/)
*/
accessor icon: string | undefined;
/** The component's default label. */
accessor label: string | undefined;
/**
* Replace localized message strings with your own strings.
*
* _**Note**: Individual message keys may change between releases._
*/
accessor messageOverrides: {
componentLabel?: string | undefined;
title?: string | undefined;
fileName?: string | undefined;
titlePlaceHolder?: string | undefined;
fileNamePlaceHolder?: string | undefined;
formatDefaultOption?: string | undefined;
fileFormatTitle?: string | undefined;
layoutTitle?: string | undefined;
layoutDefaultOption?: string | undefined;
scale?: string | undefined;
scaleLabel?: string | undefined;
reset?: string | undefined;
author?: string | undefined;
copyright?: string | undefined;
legend?: string | undefined;
lock?: string | undefined;
swap?: string | undefined;
panelToggle?: string | undefined;
advancedOptions?: string | undefined;
width?: string | undefined;
height?: string | undefined;
dpi?: string | undefined;
attribution?: string | undefined;
northArrow?: string | undefined;
scaleBar?: string | undefined;
outSpatialReference?: string | undefined;
datumTransformations?: string | undefined;
invalidWkid?: string | undefined;
layoutTab?: string | undefined;
mapOnlyTab?: string | undefined;
printPreview?: string | undefined;
browseTemplates?: string | undefined;
untitled?: string | undefined;
pending?: string | undefined;
ready?: string | undefined;
linkReady?: string | undefined;
errorMessage?: string | undefined;
exportWebMapError?: string | undefined;
exportWebMapCIMError?: string | undefined;
exportedLinksList?: string | undefined;
sceneViewError?: string | undefined;
noViewError?: string | undefined;
serviceError?: string | undefined;
export?: string | undefined;
delete?: string | undefined;
options?: string | undefined;
exportDescription?: string | undefined;
noExportedFiles?: string | undefined;
exportsTab?: string | undefined;
selectTemplate?: string | undefined;
selectTemplateDescription?: string | undefined;
exportHint?: string | undefined;
template?: string | undefined;
"a3-landscape"?: string | undefined;
"a3-portrait"?: string | undefined;
"a4-landscape"?: string | undefined;
"a4-portrait"?: string | undefined;
"letter-ansi-a-landscape"?: string | undefined;
"letter-ansi-a-portrait"?: string | undefined;
"tabloid-ansi-b-landscape"?: string | undefined;
"tabloid-ansi-b-portrait"?: string | undefined;
defaultTemplates?: string | undefined;
organizationTemplates?: string | undefined;
chooseTemplate?: string | undefined;
templateList?: string | undefined;
generatingExport?: string | undefined;
consumesCredits?: string | undefined;
credits?: string | undefined;
templatesNoLongerAvailable?: string | undefined;
templatesNoLongerAvailableDescription?: string | undefined;
myTemplates?: string | undefined;
saveExportToMyContent?: string | undefined;
saveAs?: string | undefined;
openItem?: string | undefined;
forceFeatureAttributes?: string | undefined;
includeTables?: string | undefined;
scaleBarUnit?: string | undefined;
dynamicLegend?: string | undefined;
loading?: string | undefined;
miles?: string | undefined;
kilometers?: string | undefined;
meters?: string | undefined;
feet?: string | undefined;
yards?: string | undefined;
"nautical-miles"?: string | undefined;
milesAndKilometers?: string | undefined;
feetAndMeters?: string | undefined;
outOfCredits?: string | undefined;
outOfCreditsDescription?: string | undefined;
customerService?: string | undefined;
contactCustomerService?: string | undefined;
restrictedStatus?: string | undefined;
restrictedStatusDescription?: string | undefined;
suspendedStatus?: string | undefined;
suspendedStatusDescription?: string | undefined;
};
/** @internal */
protected messages: {
componentLabel: string;
title: string;
fileName: string;
titlePlaceHolder: string;
fileNamePlaceHolder: string;
formatDefaultOption: string;
fileFormatTitle: string;
layoutTitle: string;
layoutDefaultOption: string;
scale: string;
scaleLabel: string;
reset: string;
author: string;
copyright: string;
legend: string;
lock: string;
swap: string;
panelToggle: string;
advancedOptions: string;
width: string;
height: string;
dpi: string;
attribution: string;
northArrow: string;
scaleBar: string;
outSpatialReference: string;
datumTransformations: string;
invalidWkid: string;
layoutTab: string;
mapOnlyTab: string;
printPreview: string;
browseTemplates: string;
untitled: string;
pending: string;
ready: string;
linkReady: string;
errorMessage: string;
exportWebMapError: string;
exportWebMapCIMError: string;
exportedLinksList: string;
sceneViewError: string;
noViewError: string;
serviceError: string;
export: string;
delete: string;
options: string;
exportDescription: string;
noExportedFiles: string;
exportsTab: string;
selectTemplate: string;
selectTemplateDescription: string;
exportHint: string;
template: string;
"a3-landscape": string;
"a3-portrait": string;
"a4-landscape": string;
"a4-portrait": string;
"letter-ansi-a-landscape": string;
"letter-ansi-a-portrait": string;
"tabloid-ansi-b-landscape": string;
"tabloid-ansi-b-portrait": string;
defaultTemplates: string;
organizationTemplates: string;
chooseTemplate: string;
templateList: string;
generatingExport: string;
consumesCredits: string;
credits: string;
templatesNoLongerAvailable: string;
templatesNoLongerAvailableDescription: string;
myTemplates: string;
saveExportToMyContent: string;
saveAs: string;
openItem: string;
forceFeatureAttributes: string;
includeTables: string;
scaleBarUnit: string;
dynamicLegend: string;
loading: string;
miles: string;
kilometers: string;
meters: string;
feet: string;
yards: string;
"nautical-miles": string;
milesAndKilometers: string;
feetAndMeters: string;
outOfCredits: string;
outOfCreditsDescription: string;
customerService: string;
contactCustomerService: string;
restrictedStatus: string;
restrictedStatusDescription: string;
suspendedStatus: string;
suspendedStatusDescription: string;
} & T9nMeta<{
componentLabel: string;
title: string;
fileName: string;
titlePlaceHolder: string;
fileNamePlaceHolder: string;
formatDefaultOption: string;
fileFormatTitle: string;
layoutTitle: string;
layoutDefaultOption: string;
scale: string;
scaleLabel: string;
reset: string;
author: string;
copyright: string;
legend: string;
lock: string;
swap: string;
panelToggle: string;
advancedOptions: string;
width: string;
height: string;
dpi: string;
attribution: string;
northArrow: string;
scaleBar: string;
outSpatialReference: string;
datumTransformations: string;
invalidWkid: string;
layoutTab: string;
mapOnlyTab: string;
printPreview: string;
browseTemplates: string;
untitled: string;
pending: string;
ready: string;
linkReady: string;
errorMessage: string;
exportWebMapError: string;
exportWebMapCIMError: string;
exportedLinksList: string;
sceneViewError: string;
noViewError: string;
serviceError: string;
export: string;
delete: string;
options: string;
exportDescription: string;
noExportedFiles: string;
exportsTab: string;
selectTemplate: string;
selectTemplateDescription: string;
exportHint: string;
template: string;
"a3-landscape": string;
"a3-portrait": string;
"a4-landscape": string;
"a4-portrait": string;
"letter-ansi-a-landscape": string;
"letter-ansi-a-portrait": string;
"tabloid-ansi-b-landscape": string;
"tabloid-ansi-b-portrait": string;
defaultTemplates: string;
organizationTemplates: string;
chooseTemplate: string;
templateList: string;
generatingExport: string;
consumesCredits: string;
credits: string;
templatesNoLongerAvailable: string;
templatesNoLongerAvailableDescription: string;
myTemplates: string;
saveExportToMyContent: string;
saveAs: string;
openItem: string;
forceFeatureAttributes: string;
includeTables: string;
scaleBarUnit: string;
dynamicLegend: string;
loading: string;
miles: string;
kilometers: string;
meters: string;
feet: string;
yards: string;
"nautical-miles": string;
milesAndKilometers: string;
feetAndMeters: string;
outOfCredits: string;
outOfCreditsDescription: string;
customerService: string;
contactCustomerService: string;
restrictedStatus: string;
restrictedStatusDescription: string;
suspendedStatus: string;
suspendedStatusDescription: string;
}>;
/**
* The [spatial reference](https://developers.arcgis.com/javascript/latest/references/core/geometry/SpatialReference/) used to render the printed map on the server.
*
* @since 4.33
*/
accessor outSpatialReference: SpatialReference | null | undefined;
/**
* It is possible to search a specified portal instance's [locator services](https://doc.esri.com/en/arcgis-enterprise/latest/administer/configure-portal-to-geocode-addresses.html).
* Use this property to set this [ArcGIS Portal](https://enterprise.arcgis.com/en/portal/) instance to search.
* This is especially helpful when working with a [custom template](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/CustomTemplate/).
*
* If this property is set, it is not necessary to set the [printServiceUrl](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-print/#printServiceUrl) property.
*
* @since 4.18
* @see [CustomTemplate](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/CustomTemplate/)
*/
accessor portal: Portal;
/**
* The URL of the REST endpoint of the Export Web Map Task.
* Defaults to the ArcGIS Online print service if this property is not specified.
* If the [portal](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-print/#portal) property is set, this property will use the portal's print service URL.
*/
accessor printServiceUrl: string | null | undefined;
/**
* By passing the `id` of the Map or Scene component into this property, you can position components from the `@arcgis/map-components`
* package anywhere in the DOM while still maintaining a connection to the Map or Scene.
*
* See [Associate components with a Map or Scene component](https://developers.arcgis.com/javascript/latest/programming-patterns/#associate-components-with-a-map-or-scene-component).
*/
accessor referenceElement: ArcgisReferenceElement | string | undefined;
/**
* The initial state of the print area toggle in the Print component UI.
* When set to `true`, the print area toggle is enabled by default.
* When set to `false`, the print area toggle is disabled by default.
*
* @default false
* @since 4.30
* @see [Print component](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-print/)
*/
accessor showPrintAreaEnabled: boolean;
/**
* Indicates whether to show the "Save As" option in the Print component UI.
*
* @default false
* @internal
*/
accessor showSaveAs: boolean | undefined;
/**
* The state of the Print component.
*
* @default "disabled"
*/
get state(): State;
/**
* An object containing an array of `customTextElements` name-value pair objects
* for each print template in a custom print service. Use this property to update
* the text for custom text elements on the page layout.
*
* The Print component calls the `Get Layout Templates Info` task on the GPServer
* to discover possible `customTextElements` values for each template. The name of
* the task must match `Get Layout Templates Info`, templates must be published
* with `customTextElements`, and values must be strings. Values found there will be
* populated in the Print component under `Advanced options`. These values can be
* overwritten in the Print component UI, or programmatically using this property.
* To list all print templates available on the print service to see
* see which templates were published with `customTextElements`, use the
* [effectiveTemplateCustomTextElements](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/PrintViewModel/#effectiveTemplateCustomTextElements)
* property.
*
* @since 4.22
* @example
* const printViewModel = new PrintViewModel({
* view: view,
* // specify your custom print service
* printServiceUrl: "",
* // `customTextElements` are defined per print template
* // this example has one template with `customTextElements`
* templateCustomTextElements: {
* // if there were more applicable templates, then we would
* // create another object with the template name containing
* // an array of more name-value pairs
* "Portrait_TextElements": [
* // the possible values are defined in the print service
* { "headquarters": "Tampa, Florida" },
* { "division": "NFC South" },
* { "founded": "1976" }
* ]
* }
* });
*/
accessor templateCustomTextElements: TemplateCustomTextElements | null | undefined;
/**
* Defines the layout template options used by the Print component to generate the print page.
*
* @since 4.33
*/
get templateOptions(): TemplateOptions;
set templateOptions(value: Partial<TemplateOptions>);
/**
* The view associated with the component.
* > **Note:** The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this `view` property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-print component will be associated with a map or scene component rather than using the `view` property.
*/
accessor view: MapView | null | undefined;
/**
* Adds a portal item to a collection of browse templates available in the Print component UI.
*
* @param portalItem - The portal item to add.
* @returns Resolves when the portal template has been added.
* @since 5.0
*/
addPortalTemplate(portalItem: PortalItem): Promise<void>;
/** Permanently destroy the component. */
destroy(): Promise<void>;
"@setterTypes": {
templateOptions?: Partial<TemplateOptions>;
};
/**
* Emitted when the collection of browse templates changes.
*
* @since 5.0
*/
readonly arcgisBrowseTemplatesChange: import("@arcgis/lumina").TargetedEvent<this, CollectionChangeEvent<CustomTemplate>>;
/** Emitted when the component is complete. */
readonly arcgisComplete: import("@arcgis/lumina").TargetedEvent<this, CompleteEvent>;
/** Emitted when the value of a property is changed. Use this to listen to changes to properties. */
readonly arcgisPropertyChange: import("@arcgis/lumina").TargetedEvent<this, { name: "state"; }>;
/** Emitted when the component associated with a map or scene view is ready to be interacted with. */
readonly arcgisReady: import("@arcgis/lumina").TargetedEvent<this, void>;
/**
* Emitted when the user saves an exported map printout.
*
* @since 5.0
*/
readonly arcgisSaveAs: import("@arcgis/lumina").TargetedEvent<this, FileLink>;
/** Emitted when the component is submitted. */
readonly arcgisSubmit: import("@arcgis/lumina").TargetedEvent<this, SubmitEvent>;
readonly "@eventTypes": {
arcgisBrowseTemplatesChange: ArcgisPrint["arcgisBrowseTemplatesChange"]["detail"];
arcgisComplete: ArcgisPrint["arcgisComplete"]["detail"];
arcgisPropertyChange: ArcgisPrint["arcgisPropertyChange"]["detail"];
arcgisReady: ArcgisPrint["arcgisReady"]["detail"];
arcgisSaveAs: ArcgisPrint["arcgisSaveAs"]["detail"];
arcgisSubmit: ArcgisPrint["arcgisSubmit"]["detail"];
};
}