@kayahr/etchmap
    Preparing search index...

    Class MapComponent

    Standalone interactive raster-tile map component which owns its corresponding custom element.

    The component provides the programmatic map API. It owns a continuous camera, DPR-aware Canvas, interaction controller, tile cache and renderer, and exactly one MapElement. Add the element returned by getElement to the document to display the map.

    Index
    constructor
    attributionPrefix cacheSize center coverViewport devicePixelRatio height maxZoom minZoom nativeHeight nativeWidth onDraw source width zoom
    fitPoints getElement invalidate projectPoint projectPolygon projectPolyline setView setZoomRange unproject

    • Creates a new map component with its own map element.

      Parameters

      Returns MapComponent

      Any exception raised by the configured projection while establishing the initial center.

      Error When the browser cannot provide a 2D Canvas context or hybrid construction violates the one-to-one component/element relationship.

      RangeError When cache capacity, load concurrency, source geometry, coverage, zoom limits or zoom are invalid.

      TypeError When the tile source is malformed.

    • get attributionPrefix(): string | false

      Trusted HTML displayed before the tile-source attribution.

      Returns string | false

      Current attribution prefix, or false when omitted.

    • set attributionPrefix(attributionPrefix: string | false | null): void

      Changes the HTML displayed before the tile-source attribution.

      The string is inserted as trusted HTML without sanitization. It must never contain untrusted input.

      Parameters

      • attributionPrefix: string | false | null

        New trusted HTML, false to omit the prefix, or null to restore the default linked Powered by EtchMap prefix.

      Returns void

    • get cacheSize(): number

      Maximum number of ready tile images retained in memory.

      Returns number

      Positive tile-cache capacity.

    • set cacheSize(cacheSize: number): void

      Changes the tile-cache limit and starts with a fresh cache.

      Parameters

      • cacheSize: number

        Positive integer number of ready tile images to retain.

      Returns void

      RangeError When cacheSize is not a positive integer.

    • get center(): Point

      Current center in source coordinates.

      Returns Point

      Center interpreted by the current tile source projection.

      Any exception raised by the configured inverse projection.

    • set center(center: Point | null): void

      Changes the center in source coordinates immediately and stops active camera motion.

      Parameters

      • center: Point | null

        New center interpreted by the current tile source projection, or null to use the center of its tile coverage.

      Returns void

      Any exception raised by the configured projection.

    • get coverViewport(): boolean

      Whether the effective minimum zoom is raised until the tile coverage fills the viewport.

      Returns boolean

      true while viewport coverage constrains the minimum zoom.

    • set coverViewport(coverViewport: boolean): void

      Enables or disables the viewport-cover zoom constraint.

      Parameters

      • coverViewport: boolean

        Whether tile coverage must fill the viewport.

      Returns void

    • get devicePixelRatio(): number

      Current device pixel ratio used for drawing.

      Returns number

      Number of Canvas device pixels per exposed CSS pixel.

    • get height(): number

      Logical map height in CSS pixels.

      Returns number

      Height used by the drawing context and projection helpers.

    • get maxZoom(): number

      Maximum continuous view zoom.

      Returns number

      Explicit map maximum, or the current source maximum when no override is configured.

    • set maxZoom(maxZoom: number | null): void

      Changes the maximum continuous view zoom.

      Parameters

      • maxZoom: number | null

        New map maximum, or null to follow the current tile source maximum.

      Returns void

      RangeError When the resolved range is not finite or its minimum is greater than its maximum.

    • get minZoom(): number

      Minimum continuous view zoom before applying the optional viewport-cover constraint.

      Returns number

      Explicit map minimum, or the current source minimum when no override is configured.

    • set minZoom(minZoom: number | null): void

      Changes the minimum continuous view zoom.

      Parameters

      • minZoom: number | null

        New map minimum, or null to follow the current tile source minimum.

      Returns void

      RangeError When the resolved range is not finite or its minimum is greater than its maximum.

    • get nativeHeight(): number

      Native map height in device pixels.

      Returns number

      Canvas backing-store height.

    • get nativeWidth(): number

      Native map width in device pixels.

      Returns number

      Canvas backing-store width.

    • get onDraw(): MapDrawCallback | null

      Callback invoked synchronously after drawing the map.

      Returns MapDrawCallback | null

      Current callback, or null when no custom drawing is configured.

    • set onDraw(onDraw: MapDrawCallback | null): void

      Sets the callback invoked after drawing the map.

      Changing the callback invalidates the current map contents.

      Parameters

      • onDraw: MapDrawCallback | null

        Callback to invoke after each produced map frame, or null to remove it.

      Returns void

    • get source(): Readonly<TileSource>

      Current normalized tile source.

      Returns Readonly<TileSource>

      Immutable tile-source view with every optional setting resolved.

    • set source(source: TileSource | undefined): void

      Changes the tile source immediately, resets the tile cache and stops active camera motion.

      Parameters

      • source: TileSource | undefined

        New tile source, or undefined to restore the default OpenStreetMap source.

      Returns void

      Any exception raised while converting the retained center through a configured projection.

      RangeError When tile geometry, coverage or zoom limits are invalid or exceed safe integer coordinates.

      TypeError When the URL or projection is invalid.

    • get width(): number

      Logical map width in CSS pixels.

      Returns number

      Width used by the drawing context and projection helpers.

    • get zoom(): number

      Current continuous zoom level.

      Returns number

      Zoom clamped to the current map and viewport limits.

    • set zoom(zoom: number | null): void

      Changes the continuous zoom immediately around the viewport center and stops active camera motion.

      Parameters

      • zoom: number | null

        New continuous zoom level, or null to restore the automatic initial zoom.

      Returns void

      RangeError When zoom is not finite.

    • Centers and zooms the map so all specified source-coordinate points fit into the viewport.

      The fit uses the shortest horizontal span for a wrapping source. Existing map, source and viewport zoom constraints remain in effect, so sufficiently restrictive constraints can prevent the complete requested area or margin from becoming visible.

      Parameters

      • points: readonly Point[]

        Non-empty collection of points interpreted by the current tile-source projection.

      • options: FitPointsOptions = {}

        Optional animation, viewport margin and operation-specific maximum zoom.

      Returns void

      Any exception raised by the configured projection.

      RangeError When no points are supplied, the viewport has no area, the margin is negative, non-finite or leaves no usable area, or maxZoom is not finite.

    • Returns the custom element owned by this component.

      Returns MapElement

      Fixed map element belonging exclusively to this component.

    • Invalidates the current map contents and schedules a redraw for the next animation frame.

      Repeated invalidations before the scheduled frame are combined into a single redraw.

      Returns void

    • Projects one source-coordinate point and provides a clipped viewport-edge position when it is outside.

      Parameters

      • position: Point

        Point in source coordinates.

      • Optionaloptions: PointProjectionOptions & { wrapCopies?: false }

        Viewport margin with horizontal world-copy expansion disabled.

      Returns Point | ClippedPoint

      Nearest projected point, enriched with a clipped position when it is outside the margin-adjusted viewport bounds.

      Any exception raised by the configured projection.

      RangeError When the margin is not finite or a negative margin collapses the viewport.

    • Projects every visible horizontal world copy of a source-coordinate point without clipping.

      Parameters

      • position: Point

        Point in source coordinates.

      • options: PointProjectionOptions & { wrapCopies: true }

        Viewport options with horizontal world-copy expansion enabled.

      Returns Point[]

      Visible projected copies in viewport-relative CSS pixels.

      Any exception raised by the configured projection.

      RangeError When the margin is not finite or a negative margin collapses the viewport.

    • Projects either one nearest or every visible horizontal world copy of a source-coordinate point.

      Parameters

      Returns Point | ClippedPoint | Point[]

      Nearest potentially clipped point or all visible copies, according to options.wrapCopies.

      Any exception raised by the configured projection.

      RangeError When the margin is not finite or a negative margin collapses the viewport.

    • Projects every visible horizontal world copy of a polygon and clips them to the viewport.

      Parameters

      • points: readonly Point[]

        Polygon vertices in source coordinates. An explicit duplicate closing point is optional.

      • options: PathProjectionOptions = {}

        Path interpolation and clipping-margin options. Natural edge interpolation is the default.

      Returns Point[][]

      Visible clipped polygons in viewport-relative CSS pixels, one array per horizontal world copy.

      Any exception raised by the configured projection or natural-line interpolator.

      RangeError When the margin is not finite or a negative margin collapses the viewport.

    • Projects every visible horizontal world copy of a polyline and clips it to the viewport.

      Parameters

      • points: readonly Point[]

        Ordered polyline vertices in source coordinates.

      • options: PathProjectionOptions = {}

        Path interpolation and clipping-margin options. Natural edge interpolation is the default.

      Returns Point[][]

      Separate visible clipped polyline runs in viewport-relative CSS pixels across all visible horizontal world copies.

      Any exception raised by the configured projection or natural-line interpolator.

      RangeError When the margin is not finite or a negative margin collapses the viewport.

    • Sets the source-coordinate center and zoom atomically and stops active camera motion.

      Parameters

      • center: Point | null

        New center interpreted by the current tile source projection, or null to use the center of its tile coverage.

      • zoom: number

        New continuous zoom level, clamped to the current source and viewport limits.

      Returns void

      Any exception raised by the configured projection.

      RangeError When zoom is not finite.

    • Changes both continuous view-zoom limits atomically.

      Map limits are independent of native tile LOD and may extend beyond the current source limits. Passing null for a limit makes it follow the corresponding current tile-source limit.

      Parameters

      • minZoom: number | null

        New map minimum, or null to follow the source minimum.

      • maxZoom: number | null

        New map maximum, or null to follow the source maximum.

      Returns void

      RangeError When the resolved range is not finite or its minimum is greater than its maximum.

    • Converts a viewport-relative CSS-pixel position into source coordinates.

      Parameters

      • position: Point

        Viewport-relative position in CSS pixels.

      Returns Point

      Corresponding point interpreted by the current tile source projection.

      Any exception raised by the configured inverse projection.

    Settings
    Member Visibility

    On This Page
    Constructors
    Accessors
    Methods