@arcgis/core/support/BasemapStyle.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

import type Accessor from "../core/Accessor.js";

export interface BasemapStyleProperties extends Partial<Pick<BasemapStyle, "apiKey" | "id" | "language" | "places" | "serviceUrl" | "worldview">> {}

/**
 * The style of the basemap from the [basemap styles service (v2)](https://developers.arcgis.com/rest/basemap-styles/).
 * The basemap styles service is a ready-to-use location service that serves vector and image tiles representing geographic features around the world.
 *
 * You can use the basemap styles service to display:
 * - Streets and navigation styles
 * - Imagery, oceanic, and topographic styles
 * - Creative styles such as nova and blue print
 * - Localized place labels
 * - Places with styles - _since 4.29_
 * - Worldview boundaries - _since 4.29_
 *
 * > [!CAUTION]
 * >
 * > Use of the basemap style service requires authentication via an [API key](https://developers.arcgis.com/javascript/latest/references/core/config/#Config-apiKey) or [user authentication](https://developers.arcgis.com/javascript/latest/secure-resources/#user-authentication). To learn more about API keys,
 * > see the [API keys](https://developers.arcgis.com/documentation/mapping-apis-and-services/security/api-keys/) section in the Esri Developer documentation.
 *
 * @since 4.28
 * @see [Basemap styles service (v2)](https://developers.arcgis.com/rest/basemap-styles/)
 * @see [Basemap.style](https://developers.arcgis.com/javascript/latest/references/core/Basemap/#style)
 * @see [Tutorial - Change the basemap style](https://developers.arcgis.com/javascript/latest/tutorials/change-the-basemap-style/)
 * @see [Tutorial - Change the basemap language](https://developers.arcgis.com/javascript/latest/tutorials/change-the-basemap-language/)
 * @see [Sample - Basemap worldview](https://developers.arcgis.com/javascript/latest/sample-code/basemap-worldview/)
 * @see [Sample - Basemap places](https://developers.arcgis.com/javascript/latest/sample-code/basemap-places/)
 * @example
 * const basemap = new Basemap({
 *   style: new BasemapStyle({
 *     id: "arcgis/human-geography",
 *     language: "es" // place labels will be displayed in spanish
 *   })
 * })
 */
export default class BasemapStyle extends Accessor {
  constructor(properties?: BasemapStyleProperties);
  /**
   * An authorization string used to access a resource or service.
   * [API keys](https://developers.arcgis.com/documentation/security-and-authentication/api-key-authentication/) are generated and managed in the portal.
   * An API key is tied explicitly to an ArcGIS account; it is also used to monitor service usage.
   * Setting a fine-grained API key on a specific class overrides the [global API key](https://developers.arcgis.com/javascript/latest/references/core/config/#Config-apiKey).
   *
   * @since 4.31
   */
  accessor apiKey: string | null | undefined;
  /**
   * The id of the basemap style. The values are of the form `{provider}/{style}`, for example `arcgis/navigation`.
   * See [Basemap styles -> Requests](https://developers.arcgis.com/rest/basemap-styles/#requests) for the full list of available styles.
   *
   * @see [Basemap styles](https://developers.arcgis.com/rest/basemap-styles/#requests)
   * @see [Tutorial - Change the basemap style](https://developers.arcgis.com/javascript/latest/tutorials/change-the-basemap-style/)
   * @example
   * // sets the basemap to the ArcGIS navigation night style
   * basemap.style = {
   *   id: "arcgis/navigation-night"
   * }
   *
   * // sets the basemap to the ArcGIS outdoor style
   * basemap.style.id = "arcgis/outdoor";
   */
  accessor id: string | null | undefined;
  /**
   * The language of the place labels in the basemap style.
   * Choose from a variety of [supported languages](https://developers.arcgis.com/rest/basemap-styles/languages/), including `global` and `local`.
   *
   * If not set, the app's current [locale](https://developers.arcgis.com/javascript/latest/references/core/intl/#getLocale) is used.
   * If the app's locale is not supported by the service, the language will fall back to `"global"`.
   *
   * @see [Tutorial - Change the basemap language](https://developers.arcgis.com/javascript/latest/tutorials/change-the-basemap-language/)
   * @see [Supported languages](https://developers.arcgis.com/rest/basemap-styles/languages/)
   * @example
   * // basemap place labels will in spanish
   * basemap.style = {
   *   id: "arcgis/outdoor",
   *   language: "es"
   * }
   *
   * // basemap style will use the names of places in their local language (e.g. "Lisboa" for Lisbon)
   * basemap.style.language = "local";
   */
  accessor language: string | null | undefined;
  /**
   * Indicates whether to display [places](https://developers.arcgis.com/javascript/latest/references/core/rest/places/) with the basemap style.
   * Only supported with the `arcgis/navigation` and `arcgis/navigation-night` styles.
   *
   * @since 4.29
   * @see [Basemap places](https://developers.arcgis.com/documentation/mapping-apis-and-services/maps/basemap-places/)
   * @see [Sample - Basemap places](https://developers.arcgis.com/javascript/latest/sample-code/basemap-places/)
   * @example
   * const basemapWithPlaces = new Basemap({
   *   style: new BasemapStyle({
   *     id: "arcgis/navigation",
   *     places: "all"
   *   })
   * })
   */
  accessor places: "none" | "all" | "attributed" | null | undefined;
  /**
   * The [URL](https://developers.arcgis.com/rest/basemap-styles/#service-url) to the basemap styles service.
   *
   * @default "https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2"
   */
  accessor serviceUrl: string;
  /**
   * Displays country boundaries and labels based on a specific view of a country.
   * Choose from a variety of [supported worldviews](https://developers.arcgis.com/rest/basemap-styles/worldview/).
   *
   * Worldviews can only be specified for `arcgis` basemap styles.
   * When a specific worldview is chosen, it is possible for some place labels to change language.
   * However, when a specific [language](https://developers.arcgis.com/javascript/latest/references/core/support/BasemapStyle/#language) is provided, it will take priority over the language changes associated with the worldview.
   *
   * @since 4.29
   * @see [Supported worldviews](https://developers.arcgis.com/rest/basemap-styles/worldview/)
   * @see [Sample - Basemap worldview](https://developers.arcgis.com/javascript/latest/sample-code/basemap-worldview/)
   * @example
   * const moroccoBasemap = new Basemap({
   *   style: new BasemapStyle({
   *     id: "arcgis/streets",
   *     worldview: "morocco",
   *     language: "ar"
   *   })
   * })
   */
  accessor worldview: string | null | undefined;
}