@arcgis/map-components

/// <reference path="../../index.d.ts" /> import type Bookmark from "@arcgis/core/webmap/Bookmark.js"; import type Collection from "@arcgis/core/core/Collection.js"; import type SceneView from "@arcgis/core/views/SceneView.js"; import type MapView from "@arcgis/core/views/MapView.js"; import type { ReadonlyArrayOrCollection } from "@arcgis/core/core/Collection.js"; import type { ArcgisReferenceElement, IconName, HeadingLevel, GoToOverride } from "../types.js"; import type { BookmarkOptions, BookmarkEditEvent, BookmarkSelectEvent, BookmarksState } from "./types.js"; import type { PublicLitElement as LitElement } from "@arcgis/lumina"; import type { T9nMeta } from "@arcgis/lumina/controllers"; /** * The Bookmarks component allows end users to quickly navigate to a particular area of interest. * It displays a list of [bookmarks](https://developers.arcgis.com/javascript/latest/references/core/webmap/Bookmark/), * which are typically defined inside the [WebMap](https://developers.arcgis.com/javascript/latest/references/core/WebMap/#bookmarks). * * Each bookmark may contain the following properties: `name`, `thumbnail`, `viewpoint` (defines rotation, scale, and target geometry), and `timeExtent`. * When a bookmark with a timeExtent is selected, the [arcgis-map.timeExtent](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-map/#timeExtent) of the Map will be set to the timeExtent of the selected bookmark. * To disable time capability in the Bookmarks component, set [timeDisabled](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-bookmarks/#timeDisabled) to `true`. * * Starting with version `5.1`, on [@arcgisBookmarkSelect](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-bookmarks/#event-arcgisBookmarkSelect) the selected bookmark's name is announced to assistive technologies. Visit the [Accessibility guide](https://developers.arcgis.com/javascript/latest/accessibility/#assistive-technologies) to learn more * about live announcements supporting more audiences. * * The Bookmarks component can be used to create, edit, reorder, and delete bookmarks. * To enable these features, set the following properties to `true`: * [showAddBookmarkButton](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-bookmarks/#showAddBookmarkButton), [showEditBookmarkButton](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-bookmarks/#showEditBookmarkButton), and [dragEnabled](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-bookmarks/#dragEnabled). * * **Note:** Bookmarks are supported in a 3D [Scene](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/) only if they come from a [WebMap](https://developers.arcgis.com/javascript/latest/references/core/WebMap/#bookmarks) or are provided manually from [bookmarks](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-bookmarks/#bookmarks). [Presentation](https://developers.arcgis.com/javascript/latest/references/core/webscene/Presentation/) provides a similar experience for [WebScenes](https://developers.arcgis.com/javascript/latest/references/core/webscene/Presentation/). * * @since 4.28 * @see [Sample - Bookmarks component](https://developers.arcgis.com/javascript/latest/sample-code/bookmarks/) */ export abstract class ArcgisBookmarks extends LitElement { /** * 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-bookmarks/#destroy) method when you are done to * prevent memory leaks. * * @default false */ accessor autoDestroyDisabled: boolean; /** * A collection of [Bookmark](https://developers.arcgis.com/javascript/latest/references/core/webmap/Bookmark/)s. These are typically defined inside of a [WebMap](https://developers.arcgis.com/javascript/latest/references/core/WebMap/#bookmarks), but can also be defined manually, as shown in the code snippet below. * * @example * ```js * const bookmarksElement = document.querySelector("arcgis-bookmarks"); * // define bookmarks manually * bookmarksElement.bookmarks = [ * new Bookmark({ * name: "Angeles National Forest", * viewpoint: { * targetGeometry: { * type: "extent", * spatialReference: { * wkid: 102100 * }, * xmin: -13139131.948889678, * ymin: 4047767.23531948, * xmax: -13092887.54677721, * ymax: 4090610.189673263 * } * } * }), * new Bookmark({ * name: "Crystal Lake", * viewpoint: { * targetGeometry: { * type: "extent", * spatialReference: { * wkid: 102100 * }, * xmin: -13125852.551697943, * ymin: 4066904.1101411926, * xmax: -13114291.451169826, * ymax: 4077614.8487296384 * }, * rotation: 90 * } * }) * ]; */ get bookmarks(): Collection<Bookmark>; set bookmarks(value: ReadonlyArrayOrCollection<Bookmark>); /** * Indicates whether a component is closed. When `true`, the component will be hidden. * * @default false */ accessor closed: boolean; /** * Specifies how new bookmarks will be created if [showAddBookmarkButton](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-bookmarks/#showAddBookmarkButton) is set to `true`. * Can be used to enable or disable taking screenshots or capturing the bookmark's viewpoint based on the current * view when a bookmark is created. * * @example * ```js * const bookmarksElement = document.querySelector("arcgis-bookmarks"); * bookmarksElement.showAddBookmarkButton = true; * bookmarksElement.defaultCreateOptions = { * // whenever a new bookmark is created, a 100x100 px * // screenshot of the view will be taken and the rotation, scale, and extent * // of the view will not be set as the viewpoint of the new bookmark * takeScreenshot: true, * captureViewpoint: false, * captureTimeExtent: false, // the time extent will not be saved in the bookmark * screenshotSettings: { * width: 100, * height: 100 * } * }; * ``` */ get defaultCreateOptions(): BookmarkOptions; set defaultCreateOptions(value: Partial<BookmarkOptions>); /** * Specifies how bookmarks will be edited, if [showEditBookmarkButton](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-bookmarks/#showEditBookmarkButton) is set to `true`. * Can be used to enable or disable taking screenshots or capturing the bookmark's viewpoint based on the current * view when a bookmark is edited. */ get defaultEditOptions(): BookmarkOptions; set defaultEditOptions(value: Partial<BookmarkOptions>); /** * When true, the component is visually withdrawn and cannot receive user interaction. * * @default false */ accessor disabled: boolean; /** * Indicates if a Bookmark is able to be dragged in order to update its position in the list. * * @default false * @since 4.29 */ accessor dragEnabled: boolean; /** * Defines the text used as a placeholder when [showFilter](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-bookmarks/#showFilter) is set to `true`. * * @default "" * @since 4.29 */ accessor filterPlaceholder: string; /** * Defines the text used to filter the bookmarks when [showFilter](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-bookmarks/#showFilter) is set to `true`. * * @default "" * @since 4.29 */ accessor filterText: string; /** * This function provides the ability to override either the [arcgis-map.goTo()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-map/#goTo) or [arcgis-scene.goTo()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#goTo) methods. * * @since 4.33 * @example * ```js * component.goToOverride = function(view, goToParams) { * goToParams.options = { * duration: updatedDuration * }; * return view.goTo(goToParams.target, goToParams.options); * }; * ``` */ accessor goToOverride: GoToOverride | undefined; /** * Indicates the heading level to use for the message "No bookmarks" when no bookmarks * are available. By default, this message is rendered * as a level 2 heading (e.g. `<h2>No bookmarks</h2>`). 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 2 * @see [Heading Elements](https://developer.mozilla.org/docs/Web/HTML/Element/Heading_Elements) * @since 4.34 * @example * ```js * // "No bookmarks" will render as an <h3> * bookmarksElement.headingLevel = 3; * ``` */ accessor headingLevel: HeadingLevel; /** * Indicates whether the thumbnail associated with the bookmark is hidden. * * @default false * @since 4.30 */ accessor hideThumbnail: boolean; /** * Indicates whether the time (`h:m:s`) displayed next to the date is hidden if the bookmark has a time extent defined. * * @default false * @since 4.30 */ accessor hideTime: boolean; /** * Icon which represents the component. * Typically used when the component is controlled by another component (e.g. by the Expand component). * * @default "bookmark" * @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/) */ accessor icon: IconName; /** 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._ * * @since 4.34 */ accessor messageOverrides: { addBookmark?: string | undefined; bookmarkSelected?: string | undefined; goToBookmark?: string | undefined; includeTimeExtent?: string | undefined; noBookmarksHeading?: string | undefined; noBookmarksDescription?: string | undefined; title?: string | undefined; titlePlaceholder?: string | undefined; invalidTitle?: string | undefined; addingBookmark?: string | undefined; invalidImageUrl?: string | undefined; imageUrlPlaceholder?: string | undefined; imageUrlTooltip?: string | undefined; thumbnail?: string | undefined; screenshot?: string | undefined; updateThumbnail?: string | undefined; none?: string | undefined; url?: string | undefined; timeExtent?: string | undefined; startDate?: string | undefined; endDate?: string | undefined; componentLabel?: string | undefined; add?: string | undefined; untitled?: string | undefined; edit?: string | undefined; loading?: string | undefined; delete?: string | undefined; cancel?: string | undefined; save?: string | undefined; }; /** @internal */ protected messages: Partial<{ addBookmark: string; bookmarkSelected: string; goToBookmark: string; includeTimeExtent: string; noBookmarksHeading: string; noBookmarksDescription: string; title: string; titlePlaceholder: string; invalidTitle: string; addingBookmark: string; invalidImageUrl: string; imageUrlPlaceholder: string; imageUrlTooltip: string; thumbnail: string; screenshot: string; updateThumbnail: string; none: string; url: string; timeExtent: string; startDate: string; endDate: string; componentLabel: string; add: string; untitled: string; edit: string; loading: string; delete: string; cancel: string; save: string; }> & T9nMeta<{ addBookmark: string; bookmarkSelected: string; goToBookmark: string; includeTimeExtent: string; noBookmarksHeading: string; noBookmarksDescription: string; title: string; titlePlaceholder: string; invalidTitle: string; addingBookmark: string; invalidImageUrl: string; imageUrlPlaceholder: string; imageUrlTooltip: string; thumbnail: string; screenshot: string; updateThumbnail: string; none: string; url: string; timeExtent: string; startDate: string; endDate: string; componentLabel: string; add: string; untitled: string; edit: string; loading: string; delete: string; cancel: string; save: string; }>; /** * By assigning the `id` attribute of the Map or Scene component to this property, you can position a child component 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; /** * Indicates whether to display the button to add a new bookmark. * * @default false * @since 4.30 */ accessor showAddBookmarkButton: boolean; /** * Indicates whether to display the close button. * * @default false * @since 4.30 */ accessor showCloseButton: boolean; /** * Indicates whether to display the collapse button. * * @default false * @since 4.30 */ accessor showCollapseButton: boolean; /** * Indicates whether to display the button to edit a bookmark. * * @default false * @since 4.30 */ accessor showEditBookmarkButton: boolean; /** * Indicates whether to display the bookmark filter. * * @default false * @since 4.30 */ accessor showFilter: boolean; /** * Indicates whether to display the heading. * * @default false * @since 4.30 */ accessor showHeading: boolean; /** * The current state of the component. * * @default "ready" */ get state(): BookmarksState; /** * Indicates whether to disable the time capability of the Bookmarks component. * * @default false * @since 4.34 */ accessor timeDisabled: boolean; /** * 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-bookmarks component will be associated with a map or scene component rather than using the `view` property. */ accessor view: MapView | SceneView | undefined; /** Permanently destroy the component. */ destroy(): Promise<void>; /** * Zoom to a specific bookmark. * * @param bookmark * @since 4.34 */ goTo(bookmark: Bookmark): Promise<void>; "@setterTypes": { bookmarks?: ReadonlyArrayOrCollection<Bookmark>; defaultCreateOptions?: Partial<BookmarkOptions>; defaultEditOptions?: Partial<BookmarkOptions>; }; /** * Fires when a [Bookmark](https://developers.arcgis.com/javascript/latest/references/core/webmap/Bookmark/) is edited. * * @since 4.34 * @example * ```js * // once an edit has been made, enable the "Save Webmap" button * // to allow the user to save their changes * bookmarksElement.addEventListener("arcgisBookmarkEdit", (event) => { * saveBtn.disabled = false; * }); * ``` */ readonly arcgisBookmarkEdit: import("@arcgis/lumina").TargetedEvent<this, BookmarkEditEvent>; /** * Fires when a [Bookmark](https://developers.arcgis.com/javascript/latest/references/core/webmap/Bookmark/) is selected. * * @since 4.34 * @example * ```html * <arcgis-expand expanded> * <arcgis-bookmarks></arcgis-bookmarks> * </arcgis-expand> * * <script> * const bookmarksElement = document.querySelector("arcgis-bookmarks"); * const expandElement = document.querySelector("arcgis-expand"); * * // collapses the associated Expand component * // when a bookmark is selected * bookmarksElement.addEventListener("arcgisBookmarkSelect", (event) => { * expandElement.expanded = false; * }); * </script> * ``` */ readonly arcgisBookmarkSelect: import("@arcgis/lumina").TargetedEvent<this, BookmarkSelectEvent>; /** Emitted when the component's close button is clicked. */ readonly arcgisClose: import("@arcgis/lumina").TargetedEvent<this, void>; /** 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>; readonly "@eventTypes": { arcgisBookmarkEdit: ArcgisBookmarks["arcgisBookmarkEdit"]["detail"]; arcgisBookmarkSelect: ArcgisBookmarks["arcgisBookmarkSelect"]["detail"]; arcgisClose: ArcgisBookmarks["arcgisClose"]["detail"]; arcgisPropertyChange: ArcgisBookmarks["arcgisPropertyChange"]["detail"]; arcgisReady: ArcgisBookmarks["arcgisReady"]["detail"]; }; }