Ruler module

Displays a ruler on the map and allows you to determine the distance between points and the area of the described shape. This module only provides the calculation of the distance and the display of the geodetic line between the reference points. The display of markers and their signatures is determined on the user's side.

Usage

When creating a ruler on a map, you need to specify an array of reference points (points), the type of ruler (type), geometry parameters (geometry), a preview point view (previewPoint), and a callback function that creates new reference points (point).

The current status of the point, as well as functions (onDelete, onDragMove, and others), are passed from the callback function, which should be called whenever any action is taken on the point. Points are updated when any of the following events occur: a point is changed, points are added or deleted, the ruler type is changed, or the editable flag is toggled.

The ruler also provides a set of callbacks to common events that you can subscribe to: onUpdate to receive notifications about each update of the ruler, onUpdateStart to start editing the ruler, onUpdateEnd to indicate the end of editing.

Ruler API

type (RulerType) – type of ruler. ruler – line that measures the distance. planimeter - polygon that measures the area
points (LngLat[]) – ruler reference points
editable (boolean) – flag that the ruler can be edited (by default, true).
geometry (RulerGeometry) – object with parameters for the feature geometry on the map
- style(DrawingStyle) – styles for the line and polygon
source (string) – name for the ruler's data source (by default, ymaps3-ruler)
zIndex (number) – base zIndex for the ruler layer (by default, 2600). For more information, see the Ruler layers section
onUpdate (UpdateCommonFn) – callback function, when updating the ruler. Returns the total measurements (the length of the entire ruler in meters or the area of the entire ruler in square meters) and the ruler points (LngLat[])
onUpdateStart (UpdateStartFn) – callback function when the ruler update starts. To work correctly, you need to pass onDragStart events to the ruler
onUpdateEnd (UpdateEndFn) – callback function when the ruler update ends. To work correctly, you need to pass onDragEnd events to the ruler
previewPoint – preview point to display when hovering over the ruler line. There are differences in different versions:
- vanilla – HTMLElement
- react – ReactElement
- vue – named slot previewPoint
point – callback that gets the values at this point and returns the point. For more information, see Point rendering section. The return value has the following differences:
- vanilla – return YMapEntity<RenderPointArgs> entity
- react – return ReactElement
- vue – named slot point

Ruler layers

The points and geometry of the ruler are displayed on the inner layers. This is necessary in order to correctly arrange the order of points, geometries and the blocking layer:

blocking layer – added only if the prop is editable === true. The zIndexof the layer is equal to_props.zIndex
geometry layer - displays the feature geometry. The zIndex of the layer is equal to _props.zIndex + 0.1
points layer - displays the points. The zIndex of the layer is equal to _props.zIndex + 0.2

Ruler layers have a zIndex between _props.zIndex and _props.zIndex + 1 and are a non-public API.

Since the markers are created on the user's side, we give the data source id to the outside so that the markers are added to this particular layer.

Point rendering

The ruler points are rendered using the callback point. As arguments, come an object with parameters for rendering:

state – current state of the point
- index (number) – index of the point in the ruler (0-based)
- totalCount (number) – total number of points in the ruler
- coordinates (LngLat) – current coordinates of the point
- measurements (Measurements) – measurement values at this point
- editable (boolean) – flag that the ruler can be edited
- source (string) – data source id to which the marker should be added
onDragMove(coordinates: LngLat) – a callback to be called when moving a point
onDragStart(coordinates: LngLat) – a callback to be called at the beginning of the point movement
onDragEnd(coordinates: LngLat) – a callback to be called at the end of the point movement
onDelete() - a callback to be called if the point is to be deleted

The behavior of markers is configured on the user's side, so you need to send information through the callback about what has changed at the point.

The measurement (Measurements) values differ from the type of tape measure:

If the type is ruler
- type - 'ruler'
- distance - distance in meters between the starting point and the current position
- segmentDistance - distance in meters between the previous point and the current point
- totalDistance - total length of the tape measure in meters
If the type is planimeter
- type – 'planimeter'
- area - area of the figure is in square meters.

The previewPoint does not require any specific movement settings. Instead, you simply need to provide an HTML element that will be used as a placeholder for the preview.

Vanilla

When rendering a point using vanilla, the callback function should return an entity with the specified arguments. Updating the object (.update()) takes place within the rendering process, so it is essential to maintain consistency between passes.

A simplified example of rendering in vanilla is as follows:

// Ruler point entity
class RulerPoint extends ymaps3.YMapComplexEntity<RenderPointArgs> {
  constructor(props: RenderPointArgs) {
    super(props);

    const point = document.createElement('div');
    // Customizing the look of a point

    /**
     * the abstract delete button, when clicked, calls the callback onDelete
     * so that the roulette inside deletes this point
     */
    const deleteButton = document.createElement('button');
    deleteButton.addEventListener('click', () => this._props.onDelete());

    const {coordinates, editable, source} = this._props.state;

    this._pointMarker = new YMapMarker(
      {
        coordinates, // current coordinates of the point
        draggable: editable, // "draggable" only if the ruler can be edited
        source, // data source id to which the marker should be added
        onDragMove: this._props.onDragPoint // callback when moving a point
      },
      point // html element point
    );
    this.addChild(this._pointMarker);
  }

  protected _onUpdate(props: Partial<RenderPointArgs>): void {
    // updating a point when its state changes
    if (props.state !== undefined) {
      const {coordinates, editable, source} = props.state;

      this._pointMarker.update({coordinates, draggable: editable, source});

      // abstract verification that the point is at the end of the ruler, for example.
      if (props.state.index === props.state.totalCount - 1) {
        // ...
      }
    }
  }
}

const previewPoint = document.createElement('div');
// ... setting up a preview point

const ruler = new YMapRuler({
  points: RULER_COORDINATES,
  type: 'ruler',
  previewPoint,
  geometry: {lineStyle: FEATURE_LINE_STYLE, polygonStyle: FEATURE_POLYGON_STYLE},
  point: (params: RenderPointArgs) => new RulerPoint(props)
});

React

When rendering a point in React, the function should return a ReactElement. The point is then updated by the same function. The returned element will be added as a child of the <YMapRuler/> component.

Here is a similar simplified example of how to render in React:

const RulerPoint = ({state, onDragPoint, onDelete}: RenderPointArgs) => {
  const onDragMove = React.useCallback((coordinates) => {
    onDragPoint(coordinates);
  }, []);

  const onDeletePoint = React.useCallback(() => {
    onDelete();
  }, []);

  return (
    <YMapMarker
      coordinates={state.coordinates}
      source={state.source}
      draggable={state.editable}
      onDragMove={onDragMove}
    >
      <div className="point"></div>
    </YMapMarker>
  );
};

const App = () => {
  const [geometry] = React.useState({lineStyle: FEATURE_LINE_STYLE, polygonStyle: FEATURE_POLYGON_STYLE});

  const onRender = React.useCallback(({state, onDelete, onDragPoint}: RenderPointArgs) => {
    return <RulerPoint state={state} onDragPoint={onDragPoint} onDelete={onDelete} />;
  }, []);

  return (
    <YMapRuler
      points={RULER_COORDINATES}
      type={'ruler'}
      point={onRender}
      geometry={geometry}
      previewPoint={<div className="preview-point"></div>}
    />
  );
};

Vue

When rendering a point in Vue, the named slot point is used. The update takes place in the same named slot

A similar simplified example to demonstrate rendering in vue:

const RulerPoint = Vue.defineComponent({
  name: 'RulerPoint',
  props: {
    state: Object as TVue.PropType<RenderPointArgs['state']>,
    onDragPoint: Function as TVue.PropType<RenderPointArgs['onDragPoint']>,
    onDelete: Function as TVue.PropType<RenderPointArgs['onDelete']>
  },
  setup(props) {
    const onDragMove = (coordinates) => {
      props.onDragPoint(coordinates);
    };
    const onDeletePoint = () => {
      props.onDelete();
    };
    return {onDragMove, onDeletePoint};
  },
  template: `
    <YMapMarker
        :coordinates="state.coordinates"
        :draggable="state.editable"
        :source="state.source"
        :onDragMove="onDragMove">
        <div class="point"></div>
    </YMapMarker>`
});

Vue.createApp({
  setup() {
    return {RULER_COORDINATES, FEATURE_LINE_STYLE, FEATURE_POLYGON_STYLE};
  },
  template: `
    <YMapRuler
        :points="RULER_COORDINATES"
        :geometry="{lineStyle: FEATURE_LINE_STYLE, polygonStyle: FEATURE_POLYGON_STYLE}"
        type="ruler">

        <!-- Named slot for point render -->
        <template #point="{state, onDragPoint, onDelete}">
            <RulerPoint
                :state="state"
                :onDragPoint="onDragPoint"
                :onDelete="onDelete" />
        </template>

        <!-- Named slot for preview point -->
        <template #previewPoint>
            <div class="preview-point"></div>
        </template>
    </YMapRuler>`
});

Class: YMapRuler

Entity that aggregates multiple Entities but looks basic from the outside.

Type Param

Root Entity Class.

Example

type YMapSomeComplexEntityProps = {
 name?: string;
};
const defaultProps = {
 name: 'entity'
};
class YMapSomeComplexEntity extends YMapComplexEntity<YMapSomeComplexEntityProps, typeof defaultProps> {
 static defaultProps = defaultProps;
 private _someEntity?: YMapSomeEntity; // YMapSomeEntity extends GenericEntity
 protected _onAttach(): void {
     this._someEntity = new YMapSomeEntity();
     this.addChild(this._someEntity); // add someEntity as children
     // ...
 }
 // ...
}

Constructors

constructor

new YMapRuler(props)

Parameters

Name	Type
`props`	`YMapRulerProps`

Overrides

YMapComplexEntity.constructor

Properties

[optionsKeyVuefy]

static [optionsKeyVuefy]: CustomVuefyOptions<YMapRulerCommon, {
	editable?: boolean;
	geometry: RulerGeometry;
	onUpdate?: UpdateCommonFn;
	onUpdateEnd?: UpdateEndFn;
	onUpdateStart?: UpdateStartFn;
	points: LngLat[];
	source?: string;
	type: RulerType;
	zIndex?: number 
}>

[overrideKeyReactify]

static [overrideKeyReactify]: CustomReactify<YMapRuler, ForwardRefExoticComponent<{
	editable?: boolean;
	geometry: RulerGeometry;
	key?: Key;
	onUpdate?: UpdateCommonFn;
	onUpdateEnd?: UpdateEndFn;
	onUpdateStart?: UpdateStartFn;
	point: (`params`: RenderPointCommonArgs) => ReactElement<any, string | JSXElementConstructor<any>>;
	points: LngLat[];
	previewPoint: ReactElement<any, string | JSXElementConstructor<any>>;
	ref?: Ref<YMapRulerCommon>;
	source?: string;
	type: RulerType;
	zIndex?: number 
}>>

[overrideKeyVuefy]

static [overrideKeyVuefy]: CustomVuefyFn<YMapRulerCommon, {
	editable?: boolean;
	geometry: RulerGeometry;
	onUpdate?: UpdateCommonFn;
	onUpdateEnd?: UpdateEndFn;
	onUpdateStart?: UpdateStartFn;
	points: LngLat[];
	source?: string;
	type: RulerType;
	zIndex?: number 
}>

defaultProps

static defaultProps: Readonly<{}>

Accessors

parent

get parent(): YMapComplexEntity<unknown, {}>

Get parent entity.

Name	Type	Description
`Props`	`Props`	Type of input props of the Entity.
`DefaultProps`	extends `Object` = {}	Type of default input props of the Entity.
`Root`	extends `GenericRootEntity`<`unknown`> = `GenericRootEntity`<`unknown`>	Root Entity Class.

Name	Type	Description
`props`	`Props`	The value of input props.
`options?`	`ComplexOptions`<`Root`>	Optional options object.

Name	Type
`props`	`Props`
`children?`	`GenericEntity`<`unknown`, {}, `Root`>[]
`options?`	`Omit`<`ComplexOptions`<`Root`>, `"children"`>

Name	Type
`child`	`GenericEntity`<`unknown`, {}, `Root`>
`index?`	`number`

Name	Type
`child`	`GenericEntity`<`unknown`, {}, `GenericRootEntity`<`unknown`, {}>>
`index?`	`number`

Name	Type
`rootContainer`	`HTMLElement`
`props`	`YMapProps`
`children?`	`YMapEntity`<`unknown`, {}>[]

Name	Type
`coordinates`	`LngLat`
`editable`	`boolean`
`index`	`number`
`measurements`	`Measurements`
`source`	`string`
`totalCount`	`number`

Name	Type
`TEntity`	extends `GenericEntity`<`unknown`>
`TResult`	`TResult`

Name	Type
`ctor`	`EntityConstructor`<`TEntity`>
`params`	`Object`
`params.React`	typeof `TReact`
`params.ReactDOM`	typeof `TReactDOM`
`params.ReactParent`	typeof `ReactParent`
`params.reactify`	`Object`
`params.reactify.context`	<TContext>(`context?`: `TContext`) => `TReact.Context`<`unknown`>
`params.reactify.module`	`ReactifyModule`
`params.reactify.entity`	<T>(...`args`: [ctor: T, displayName?: string]) => `T` extends `Overrided`<`T`, `TResult`> ? `TResult` : `ForwardRefExoticComponent`<`any`>

Name	Type
`TEntity`	extends `DefaultEntity`
`TExternalProps`	`EntityProps`<`TEntity`>

Name	Type
`TCtor`	extends `EntityConstructor`<`GenericEntity`<`unknown`>>
`TReactResult`	`TReactResult`

Name	Type	Description
`area`	`number`	the area of the closed line shape in square meters
`type`	typeof `TYPE_PLANIMETER`	-

Name	Type
`onDelete`	() => `void`
`onDragEnd`	`YMapMarkerEventHandler`
`onDragMove`	`YMapMarkerEventHandler`
`onDragStart`	`YMapMarkerEventHandler`
`state`	`RulerPointState`

Name	Type
`remove`	(`index`: `number`) => `void`
`update`	(`state`: `RulerPointState`) => `void`

Name	Type	Description
`distance`	`number`	the distance in meters from the first point of the line
`segmentDistance`	`number`	the distance in meters from the previous point of the line
`totalDistance`	`number`	the total distance of the line in meters
`type`	typeof `TYPE_RULER`	-

Name	Type
`TCtor`	extends `DefaultCtor`
`TProps`	`PropsFromCtor`<`TCtor`>

Name	Type
`ctor`	`TCtor`
`props?`	`VuefyPropsObject`<`TProps`> \| `VuefyPropsArray`<`TProps`>
`displayName?`	`string`

Name	Type	Description
`azimuth?`	`number`	Map rotation in radians. Can take values from -Math.PI to Math.PI
`tilt?`	`number`	Map tilt in radians. Can take values from 0 to 50 degrees (degrees * (Math.PI / 180))

Name	Type	Description
`behaviors?`	`BehaviorType`[]	Active behaviors
`camera?`	`YMapCameraRequest`	Initial camera or request to change camera with duration
`className?`	`string`	Map container css class name
`config?`	`Config`	Other configs
`copyrightsPosition?`	`YMapCopyrightsPosition`	Position of copyright on the page. Default is 'bottom right'
`hotspotsStrategy?`	`"forViewport"` \| `"forPointerPosition"`	Strategy for fetching hotspots, for whole viewport or for tiles that pointer is hovering at
`location`	`YMapLocationRequest`	Initial location or request to change location with duration
`margin?`	`Margin`	Map margins
`mode?`	`MapMode`	Map mode, 'auto' (default. Show raster tiles while vector tiles are loading), 'raster' or 'vector' (without raster preloading).
`projection?`	`Projection`	Projection used in map
`restrictMapArea?`	`LngLatBounds` \| `false`	Sets the map view area so that the user cannot move outside of this area.
`showScaleInCopyrights?`	`boolean`	Show the map scale next to copyright
`theme?`	`YMapTheme`	Theme applied to the scheme
`worldOptions?`	`WorldOptions`	Whether to repeat the world in X and Y
`zoomRange?`	`ZoomRange`	Restrict min and max map zoom
`zoomRounding?`	`ZoomRounding`	Set rounding for zoom. If `auto` is selected, zoom will be `snap` for `raster` and `smooth` for `vector` `MapMode`. Default is `auto`.
`zoomStrategy?`	`ZoomStrategy`	Zoom strategy describes if map center is bound to the zoom point or not

Name	Type
`editable?`	`boolean`
`geometry`	`RulerGeometry`
`onUpdate?`	`UpdateCommonFn`
`onUpdateEnd?`	`UpdateEndFn`
`onUpdateStart?`	`UpdateStartFn`
`point`	`RenderPointCommon`
`points`	`LngLat`[]
`previewPoint`	`HTMLElement`
`source?`	`string`
`type`	`RulerType`
`zIndex?`	`number`

Ruler module

UsageUsage

Ruler APIRuler API

Ruler layersRuler layers

Point renderingPoint rendering

VanillaVanilla

ReactReact

VueVue

Class: YMapRulerClass: YMapRuler

ConstructorsConstructors

constructorconstructor

ParametersParameters

OverridesOverrides

PropertiesProperties

[optionsKeyVuefy][optionsKeyVuefy]

[overrideKeyReactify][overrideKeyReactify]

[overrideKeyVuefy][overrideKeyVuefy]

defaultPropsdefaultProps

AccessorsAccessors

parentparent

ReturnsReturns

Inherited fromInherited from

rootroot

ReturnsReturns

Inherited fromInherited from

MethodsMethods

updateupdate

ParametersParameters

ReturnsReturns

Inherited fromInherited from

Class: ConfigClass: Config

ConstructorsConstructors

constructorconstructor

PropertiesProperties

descriptiondescription

MethodsMethods

setApikeyssetApikeys

ParametersParameters

ReturnsReturns

setExperimentssetExperiments

ParametersParameters

ReturnsReturns

Class: Context<_TClass: Context<_T>

Type parametersType parameters

ConstructorsConstructors

constructorconstructor

Type parametersType parameters

ParametersParameters

PropertiesProperties

namename

Class: GenericComplexEntity<Props, DefaultProps, RootClass: GenericComplexEntity<Props, DefaultProps, Root>

Type parametersType parameters

ConstructorsConstructors

constructorconstructor

Type parametersType parameters

ParametersParameters

OverridesOverrides

Type parametersType parameters

ParametersParameters

OverridesOverrides

AccessorsAccessors

parentparent

ReturnsReturns

Inherited fromInherited from

rootroot

ReturnsReturns

Inherited fromInherited from

MethodsMethods

updateupdate

ParametersParameters

ReturnsReturns

Inherited fromInherited from

Class: GenericEntity<Props, DefaultProps, RootClass: GenericEntity<Props, DefaultProps, Root>

Type parametersType parameters

ConstructorsConstructors

constructorconstructor

Type parametersType parameters

ParametersParameters

AccessorsAccessors

parentparent

Usage

Ruler API

Ruler layers

Point rendering

Vanilla

React

Vue

Class: YMapRuler

Constructors

constructor

Parameters

Overrides

Properties

[optionsKeyVuefy]

[overrideKeyReactify]

[overrideKeyVuefy]

defaultProps

Accessors

parent

Returns

Inherited from

root

Returns

Inherited from

Methods

update

Parameters

Returns

Inherited from

Class: Config

Constructors

constructor

Properties

description

Methods

setApikeys

Parameters

Returns

setExperiments

Parameters

Returns

Class: Context<_T>

Type parameters

Constructors

constructor

Type parameters

Parameters

Properties

name

Class: GenericComplexEntity<Props, DefaultProps, Root>

Type parameters

Constructors

constructor

Type parameters

Parameters

Overrides

Type parameters

Parameters

Overrides

Accessors

parent

Returns

Inherited from

root

Returns

Inherited from

Methods

update

Parameters

Returns

Inherited from

Class: GenericEntity<Props, DefaultProps, Root>

Type parameters

Constructors

constructor

Type parameters

Parameters

Accessors

parent

Returns