@arcgis/map-components
Version:
ArcGIS Map Components
511 lines (510 loc) • 27.6 kB
TypeScript
/// <reference path="../../index.d.ts" />
import type Graphic from "@arcgis/core/Graphic.js";
import type Point from "@arcgis/core/geometry/Point.js";
import type LocatorSearchSource from "@arcgis/core/widgets/Search/LocatorSearchSource.js";
import type LayerSearchSource from "@arcgis/core/widgets/Search/LayerSearchSource.js";
import type Collection from "@arcgis/core/core/Collection.js";
import type PopupTemplate from "@arcgis/core/PopupTemplate.js";
import type Portal from "@arcgis/core/portal/Portal.js";
import type { SearchViewModelEvents, SearchViewModelSelectResultEvent, SearchViewModelState } from "@arcgis/core/widgets/Search/SearchViewModel.js";
import type { ArcgisReferenceElement, IconName } from "../types.js";
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { SuggestResult, SuggestResults, SearchResponse, SuggestResponse, SupportedSearchSource, SourcesHandler, SearchResults, SearchResult } from "@arcgis/core/widgets/Search/types.js";
import type { ActiveMenu } from "./types.js";
import type { T9nMeta } from "@arcgis/lumina/controllers";
import type { MapViewOrSceneView } from "@arcgis/core/views/MapViewOrSceneView.js";
import type { GoToOverride } from "@arcgis/core/widgets/support/types.js";
/**
* The Search component provides a way to perform search operations on locator service(s), map/feature service feature layer(s), SceneLayers with an associated feature layer,
* BuildingComponentSublayer with an associated feature layer, GeoJSONLayer, CSVLayer, OGCFeatureLayer, and/or table(s). If using a locator with a geocoding service, the
* `findAddressCandidates` operation is used, whereas queries are used on feature layers.
*
* By default, the Search component uses the ArcGIS World Geocoding Service via this URL: `https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer`.
* If a global apiKey is present, the Search component uses this URL: `https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer`. If an apiKey
* is present on the LocatorSearchSource, then the Search component uses the URL defined by the LocatorSearchSource.url property.
*
* For popups, we recommend using either [popup-component-enabled](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-map/#popupComponentEnabled),
* or adding the [arcgis-popup](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-popup/) to your view components as a best practice.
*
* The Search component sets the view on the Search result. The level of detail (LOD) at the center of the view depends on the data source, with higher quality data
* sources returning extents closer to the `feature` obtained from the search. To manually define the scale of the view at the Search result, use the `zoomScale` property
* of the LocatorSearchSource or LayerSearchSource. Search component results are typically sorted according to their relevance to the search and their relative importance.
* However, when the scale of the MapView or SceneView is less than or equal to 300,000, the operations support prioritization of candidates based on their distance from a
* specified point (the center of the view) by passing in the `location parameter`. Features closest to the input location show up higher in the list of results.
* This behavior can be changed by using the localSearchDisabled property.
*
* Starting with version `5.1`, on [@arcgisSelectResult](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-search/#event-arcgisSelectResult) the selected search result 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.
*
* @see [Sample - Search component with multiple sources](https://developers.arcgis.com/javascript/latest/sample-code/search-component-multisource/)
* @see [Sample - Search component with custom source](https://developers.arcgis.com/javascript/latest/sample-code/search-component-customsource/)
* @since 4.28
*/
export abstract class ArcgisSearch extends LitElement {
/**
* The current active menu of the Search component.
*
* @default "none"
*/
accessor activeMenu: ActiveMenu;
/**
* The [sources](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-search/#sources) object currently selected. Can be either a
* [LayerSearchSource](https://developers.arcgis.com/javascript/latest/references/core/widgets/Search/LayerSearchSource/) or a [LocatorSearchSource](https://developers.arcgis.com/javascript/latest/references/core/widgets/Search/LocatorSearchSource/).
*
* @default null
*/
get activeSource(): null | undefined | (LayerSearchSource | LocatorSearchSource);
/**
* The selected source's index. This value is `-1` when all sources are selected.
*
* @default 0
*/
accessor activeSourceIndex: number;
/**
* String value used as a hint for input text when searching on multiple sources. See
* the image below to view the location and style of this text in the context of the component.
*
* 
*
* @default "Find address or place"
*/
accessor allPlaceholder: string | null | undefined;
/**
* The combined collection of [defaultSources](https://developers.arcgis.com/javascript/latest/references/core/widgets/Search/SearchViewModel/#defaultSources)
* and [sources](https://developers.arcgis.com/javascript/latest/references/core/widgets/Search/SearchViewModel/#sources).
* The [defaultSources](https://developers.arcgis.com/javascript/latest/references/core/widgets/Search/SearchViewModel/#defaultSources)
* displays first in the Search UI.
*
* @since 4.8
*/
get allSources(): Collection<SupportedSearchSource>;
/**
* 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-search/#destroy) method when you are done to
* prevent memory leaks.
*
* @default false
*/
accessor autoDestroyDisabled: boolean;
/**
* Indicates whether to automatically navigate to the selected result. If `true`, will not automatically navigate to the selected result.
*
* @default false
*/
accessor autoNavigateDisabled: boolean;
/**
* By default, the component will automatically select and zoom to the first geocoded result. When `true`, the
* [findAddressCandidates](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm)
* operation will still geocode the input string, but the top result will not be selected. To work with the
* geocoded results, you can set up a [@arcgisSearchComplete](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-search/#event-arcgisSearchComplete) event handler and get the results
* through the event object.
*
* @default false
*/
accessor autoSelectDisabled: boolean;
/**
* A read-only property that is a [Collection](https://developers.arcgis.com/javascript/latest/references/core/core/Collection/)
* of [LayerSearchSource](https://developers.arcgis.com/javascript/latest/references/core/widgets/Search/LayerSearchSource/)
* and/or [LocatorSearchSource](https://developers.arcgis.com/javascript/latest/references/core/widgets/Search/LocatorSearchSource/). This property
* may contain [ArcGIS Portal](https://enterprise.arcgis.com/en/portal/)
* [locators](https://doc.esri.com/en/arcgis-enterprise/latest/administer/geocode-services.html)
* and any web map or web scene [configurable search sources](http://doc.arcgis.com/en/arcgis-online/create-maps/configure-feature-search.htm).
* Web maps or web scenes may contain
* [map](https://developers.arcgis.com/javascript/latest/references/core/layers/MapImageLayer/)/[feature](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/) service feature
* layer(s), and/or [table(s)](https://developers.arcgis.com/javascript/latest/references/core/webdoc/applicationProperties/SearchTable/) as sources.
*
* This property is used to populate the Search UI if the [sources](https://developers.arcgis.com/javascript/latest/references/core/widgets/Search/SearchViewModel/#sources) property is not set.
*
* @since 4.8
*/
get defaultSources(): Collection<SupportedSearchSource>;
/**
* When true, the component is visually withdrawn and cannot receive user interaction.
*
* @default false
*/
accessor disabled: boolean;
/**
* 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 | null | undefined;
/**
* Icon which represents the component.
* Typically used when the component is controlled by another component (e.g. by the Expand component).
*
* @default "search"
* @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/)
*/
accessor icon: IconName;
/**
* When `true`, will not include [defaultSources](https://developers.arcgis.com/javascript/latest/references/core/widgets/Search/SearchViewModel/#defaultSources) in the Search UI.
*
* @default false
*/
accessor includeDefaultSourcesDisabled: boolean | SourcesHandler;
/** The component's default label. */
accessor label: string | undefined;
/**
* When `true`, will disable location services within the component.
*
* 
*
* **Note:**
* The use of this property is only supported on secure origins.
* To use it, switch your application to a secure origin, such as HTTPS.
* Note that localhost is considered "potentially secure" and can be used for easy testing in browsers that supports
* [Window.isSecureContext](https://developer.mozilla.org/docs/Web/API/isSecureContext#browser_compatibility)
* (currently Chrome and Firefox).
*
* @default false
*/
accessor locationDisabled: boolean;
/**
* The maximum number of results returned by the component if not specified by the source.
*
* @default 6
*/
accessor maxResults: number;
/**
* The maximum number of suggestions returned by the component if not specified by the source.
*
* If working with the default
* [ArcGIS Online Geocoding service](https://developers.arcgis.com/rest/geocode/api-reference/overview-world-geocoding-service.htm),
* the default remains at `5`.
*
* @default 6
*/
accessor maxSuggestions: number;
/**
* Replace localized message strings with your own strings.
*
* _**Note**: Individual message keys may change between releases._
*/
accessor messageOverrides: {
componentLabel?: string | undefined;
searchButtonTitle?: string | undefined;
placeholder?: string | undefined;
searchIn?: string | undefined;
all?: string | undefined;
allPlaceholder?: string | undefined;
locateError?: string | undefined;
untitledResult?: string | undefined;
untitledSource?: string | undefined;
noResults?: string | undefined;
noResultsFound?: string | undefined;
noResultsFoundForValue?: string | undefined;
showMoreResults?: string | undefined;
hideMoreResults?: string | undefined;
searchResult?: string | undefined;
moreResultsHeader?: string | undefined;
useCurrentLocation?: string | undefined;
resultSelected?: string | undefined;
};
/** @internal */
protected messages: {
componentLabel: string;
searchButtonTitle: string;
placeholder: string;
searchIn: string;
all: string;
allPlaceholder: string;
locateError: string;
untitledResult: string;
untitledSource: string;
noResults: string;
noResultsFound: string;
noResultsFoundForValue: string;
showMoreResults: string;
hideMoreResults: string;
searchResult: string;
moreResultsHeader: string;
useCurrentLocation: string;
resultSelected: string;
} & T9nMeta<{
componentLabel: string;
searchButtonTitle: string;
placeholder: string;
searchIn: string;
all: string;
allPlaceholder: string;
locateError: string;
untitledResult: string;
untitledSource: string;
noResults: string;
noResultsFound: string;
noResultsFoundForValue: string;
showMoreResults: string;
hideMoreResults: string;
searchResult: string;
moreResultsHeader: string;
useCurrentLocation: string;
resultSelected: string;
}>;
/**
* The minimum number of characters needed for the search if not specified by the source.
*
* @default 3
*/
accessor minSuggestCharacters: number;
/**
* By default, the graphic can be clicked to display a [Popup](https://developers.arcgis.com/javascript/latest/references/core/widgets/Popup/).
* When `true`, disables displaying the [Popup](https://developers.arcgis.com/javascript/latest/references/core/widgets/Popup/) on feature click.
*
* @default false
*/
accessor popupDisabled: boolean;
/**
* A customized [PopupTemplate](https://developers.arcgis.com/javascript/latest/references/core/PopupTemplate/) for the selected feature.
* Note that any [templates](https://developers.arcgis.com/javascript/latest/references/core/PopupTemplate/)
* defined on [allSources](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-search/#allSources) take precedence over those defined directly on the template.
*/
accessor popupTemplate: PopupTemplate | 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.
*
* @since 4.8
*/
accessor portal: Portal | null | undefined;
/**
* 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;
/**
* The graphic used to highlight the resulting feature or location.
*
* **Note:**
* A graphic will be placed in the View's
* [graphics](https://developers.arcgis.com/javascript/latest/references/core/views/View/#graphics)
* for [layer](https://developers.arcgis.com/javascript/latest/references/core/views/layers/LayerView/)
* that do not support the `highlight` method.
*/
get resultGraphic(): Graphic | null | undefined;
/**
* If `true`, the [resultGraphic](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-search/#resultGraphic) will not display at the
* location of the selected feature.
*
* @default false
*/
accessor resultGraphicDisabled: boolean;
/** An array of objects, each containing a [SearchResult](https://developers.arcgis.com/javascript/latest/references/core/widgets/Search/types/#SearchResult) from the search. */
get results(): Array<SearchResults> | null | undefined;
/**
* By default, the "All" option is displayed by default to search all sources:
*
* 
*
* When `true`, no option to search all sources at once is available:
*
* 
*
* @default false
*/
accessor searchAllDisabled: boolean;
/** The value of the search box input text string. */
accessor searchTerm: string;
/**
* The result selected from a search.
*
* @see [SearchResult](https://developers.arcgis.com/javascript/latest/references/core/widgets/Search/types/#SearchResult)
* @see [select()](https://developers.arcgis.com/javascript/latest/references/core/widgets/Search/SearchViewModel/#select)
*/
get selectedResult(): SearchResult | null | undefined;
/**
* The Search component may be used to search features in a
* [map](https://developers.arcgis.com/javascript/latest/references/core/layers/MapImageLayer/)/[feature](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/) service feature
* layer(s), [SceneLayers](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/) with an associated feature layer,
* [BuildingComponentSublayer](https://developers.arcgis.com/javascript/latest/references/core/layers/buildingSublayers/BuildingComponentSublayer/) with an associated feature layer,
* [GeoJSONLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/GeoJSONLayer/), [CSVLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/CSVLayer/) or
* [OGCFeatureLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/OGCFeatureLayer/), or [table](https://developers.arcgis.com/javascript/latest/references/core/webdoc/applicationProperties/SearchTable/),
* or geocode locations with a [locator](https://developers.arcgis.com/javascript/latest/references/core/rest/locator/). The `sources` property defines the sources from which
* to search for the [view](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-search/#view) specified by the Search component instance. There are two types of sources:
*
* * [LayerSearchSource](https://developers.arcgis.com/javascript/latest/references/core/widgets/Search/LayerSearchSource/)
* * [LocatorSearchSource](https://developers.arcgis.com/javascript/latest/references/core/widgets/Search/LocatorSearchSource/)
*
* Any combination of these sources may be used
* together in the same instance of the Search component.
*
* **Note:** Feature layers created from client-side graphics are not supported.
*
* @example
* // Default sources[] when sources is not specified
* [
* {
* url: "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer",
* singleLineFieldName: "SingleLine",
* outFields: ["Addr_type"],
* name: "ArcGIS World Geocoding Service",
* placeholder: "Adresse",
* resultSymbol: {
* type: "picture-marker", // autocasts as new PictureMarkerSymbol()
* url: this.basePath + "/images/search/search-symbol-32.png",
* size: 24,
* width: 24,
* height: 24,
* xoffset: 0,
* yoffset: 0
* }
* }
* ]
* @example
* // Example of multiple sources[]
* let sources = [
* {
* url: "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer",
* singleLineFieldName: "SingleLine",
* name: "Custom Geocoding Service",
* placeholder: "Search Geocoder",
* maxResults: 3,
* maxSuggestions: 6,
* suggestionsEnabled: false,
* minSuggestCharacters: 0
* }, {
* layer: new FeatureLayer({
* url: "https://services.arcgis.com/DO4gTjwJVIJ7O9Ca/arcgis/rest/services/GeoForm_Survey_v11_live/FeatureServer/0",
* outFields: ["*"]
* }),
* searchFields: ["Email", "URL"],
* displayField: "Email",
* exactMatch: false,
* outFields: ["*"],
* name: "Point FS",
* placeholder: "example: esri",
* maxResults: 6,
* maxSuggestions: 6,
* suggestionsEnabled: true,
* minSuggestCharacters: 0
* },
* {
* layer: new FeatureLayer({
* outFields: ["*"]
* });
* placeholder: "esri",
* name: "A FeatureLayer",
* prefix: "",
* suffix: "",
* maxResults: 1,
* maxSuggestions: 6,
* exactMatch: false,
* searchFields: [], // defaults to FeatureLayer.displayField
* displayField: "", // defaults to FeatureLayer.displayField
* minSuggestCharacters: 0
* }
* ];
* @example
* let sources = [{ ... }, { ... }, { ... }]; // array of sources
* searchViewModel.sources = sources;
*
* // Add to source(s)
* searchViewModel.sources.push({ ... }); // new source
*/
accessor sources: Collection<SupportedSearchSource>;
/**
* The current state of the component.
*
* @default "ready"
* @since 4.8
*/
get state(): SearchViewModelState;
/**
* An array of results from the [suggest()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-search/#suggest).
*
* This is available if working with a 10.3 or greater geocoding service that has [suggest capability
* loaded](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-suggest.htm) or a
* 10.3 or greater feature layer that supports pagination, i.e. `supportsPagination = true`.
*/
get suggestions(): Array<SuggestResults> | null | undefined;
/**
* If `true`, disables suggestions for the component.
*
* This is only available if working with a 10.3 or greater geocoding service that has [suggest capability
* loaded](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-suggest.htm) or a 10.3 or greater feature layer that supports pagination, i.e. `supportsPagination = true`.
*
* @default false
*/
accessor suggestionsDisabled: boolean;
/**
* When true, disables rendering in the top layer (above overlays and modals).
* This can be useful for controlling stacking context in complex UI layouts.
*
* @default false
* @since 5.0
*/
accessor topLayerDisabled: 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-search component will be associated with a map or scene component rather than using the `view` property.
*/
accessor view: MapViewOrSceneView | null | undefined;
/**
* Clears the current searchTerm, search results, suggest results, graphic, and graphics layer.
* It also hides any open menus.
*/
clear(): void;
/** Permanently destroy the component. */
destroy(): Promise<void>;
/**
* Depending on the sources specified, search() queries the feature layer(s) and/or performs
* address matching using any specified [locator(s)](https://developers.arcgis.com/javascript/latest/references/core/rest/locator/) and
* returns any applicable results.
*
* @param searchItem
*/
search(searchItem?: Graphic | null | undefined | number[] | Point | SuggestResult | string): Promise<null | undefined | SearchResponse>;
/** Brings focus to the component's text input. */
setFocus(): Promise<void>;
/**
* Performs a suggest() request on the active Locator. It also uses the current value of
* the component or one that is passed in.
*
* Suggestions are available if working with a 10.3 or greater geocoding service that has
* [suggest capability
* loaded](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-suggest.htm) or a 10.3 or greater feature layer that supports pagination, i.e.
* `supportsPagination = true`.
*
* @param query
*/
suggest(query?: string): Promise<null | undefined | SuggestResponse>;
/** 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>;
/** Fires when a result is cleared from the input box or a new result is selected. */
readonly arcgisSearchClear: import("@arcgis/lumina").TargetedEvent<this, SearchViewModelEvents["search-clear"]>;
/** Fires when the [search()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-search/#search) method is called and returns its results. */
readonly arcgisSearchComplete: import("@arcgis/lumina").TargetedEvent<this, SearchResponse>;
/** Fires when the [search()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-search/#search) method starts. */
readonly arcgisSearchStart: import("@arcgis/lumina").TargetedEvent<this, SearchViewModelEvents["search-start"]>;
/** Fires when a search result is selected. */
readonly arcgisSelectResult: import("@arcgis/lumina").TargetedEvent<this, SearchViewModelSelectResultEvent>;
/** Fires when the [suggest()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-search/#suggest) method is called and returns its results. */
readonly arcgisSuggestComplete: import("@arcgis/lumina").TargetedEvent<this, SearchViewModelEvents["suggest-complete"]>;
/** Fires when the [suggest()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-search/#suggest) method starts. */
readonly arcgisSuggestStart: import("@arcgis/lumina").TargetedEvent<this, SearchViewModelEvents["suggest-start"]>;
readonly "@eventTypes": {
arcgisPropertyChange: ArcgisSearch["arcgisPropertyChange"]["detail"];
arcgisReady: ArcgisSearch["arcgisReady"]["detail"];
arcgisSearchClear: ArcgisSearch["arcgisSearchClear"]["detail"];
arcgisSearchComplete: ArcgisSearch["arcgisSearchComplete"]["detail"];
arcgisSearchStart: ArcgisSearch["arcgisSearchStart"]["detail"];
arcgisSelectResult: ArcgisSearch["arcgisSelectResult"]["detail"];
arcgisSuggestComplete: ArcgisSearch["arcgisSuggestComplete"]["detail"];
arcgisSuggestStart: ArcgisSearch["arcgisSuggestStart"]["detail"];
};
}