YMapRuler

Класс YMapRuler отображает линейку на карте, позволяет определить расстояние между точками и площадь описываемой фигуры. Класс обеспечивает только расчет расстояния и отображение геодезической линии между опорными точками. Отображение маркеров и их подписей определяется на стороне пользователя.

ИспользованиеИспользование

При создании линейки на карте необходимо указать массив опорных точек (points), тип линейки (type), параметры геометрии (geometry), вид точки предварительного просмотра (previewPoint) и функцию обратного вызова, которая создает новые опорные точки (point).

Текущее состояние точки, а также функции (onDelete, onDragMove и другие) передаются из функции обратного вызова, которая должна вызываться всякий раз, когда с точкой выполняется какое-либо действие. Точки обновляются при возникновении любого из следующих событий: изменении точки, добавлении или удалении точек, изменении типа линейки или переключении флажка "Доступно для редактирования".

Линейка также предоставляет набор обратных вызовов для общих событий, на которые вы можете подписаться: onUpdate для получения уведомлений о каждом обновлении линейки, onUpdateStart для начала редактирования линейки, onUpdateEnd для указания окончания редактирования.

API линейкиAPI линейки

Слои линейкиСлои линейки

Точки и геометрия линейки отображаются на внутренних слоях. Это необходимо для того, чтобы правильно расположить порядок точек, геометрий и блокирующего слоя:

• блокирующий слой — добавляется только если prop - editable = true, zIndex слоя равен _props.zIndex + 0,1;
• слой геометрии — отображает геометрию объекта, zIndex слоя равен _props.zIndex + 0.1;
• слой точек — отображает точки, zIndex слоя равен _props.zIndex + 0.2.

Слои линейки имеют zIndex между _props.zIndex и _props.zIndex + 1 и являются закрытым API.

Поскольку маркеры создаются на стороне пользователя, мы передаем идентификатор источника данных наружу, чтобы маркеры добавлялись в этот конкретный слой.

Отрисовка точекОтрисовка точек

Точки линейки визуализируются с помощью обратного вызова point. В качестве аргументов идет объект с параметрами для визуализации:

• state — текущее состояние точки
  • index (number) — индекс точки на линейке (отсчет начинается с 0)
  • totalCount (number) — общее количество точек в линейке
  • coordinates (LngLat) — текущие координаты точки
  • measurements (Measurements) — значения измерений в этой точке
  • editable (boolean) — флаг, что линейку можно редактировать
  • source (string) — идентификатор источника данных, к которому следует добавить маркер
• onDragMove(coordinates: LngLat) — обратный вызов, вызываемый при перемещении точки
• onDragStart(coordinates: LngLat) — обратный вызов, который будет вызван в начале движения точки
• onDragEnd(coordinates: LngLat) — обратный вызов, который будет вызван в конце перемещения точки
• onDelete() — обратный вызов, который будет вызван, если точка должна быть удалена

Поведение маркеров настраивается на стороне пользователя, поэтому необходимо отправлять информацию через обратный вызов о том, что изменилось в точке.

Значения измерений (Measurements) различаются в зависимости от типа рулетки:

• если тип — ruler
  • type — ruler
  • distance — расстояние в метрах между начальной точкой и текущим положением
  • segmentDistance - расстояние в метрах между предыдущей точкой и текущей точкой
  • totalDistance — общая длина рулетки в метрах
• если тип — planimeter
  • type — planimeter
  • area — площадь рисунка указана в квадратных метрах

previewPoint не требует никаких специальных настроек движения. Вместо этого вам просто нужно предоставить элемент HTML, который будет использоваться в качестве заполнителя для предварительного просмотра.

Пример использованияПример использования

// Точечный объект линейки
class RulerPoint extends ymaps3.YMapComplexEntity<RenderPointArgs> {
  constructor(props: RenderPointArgs) {
    super(props);

    const point = document.createElement('div');
    // Настройка внешнего вида точки

    /**
     * кнопка абстрактного удаления, при нажатии на которую вызывается обратный вызов для удаления
     * таким образом, рулетка внутри удаляет этот пункт
     */
    const deleteButton = document.createElement('button');
    deleteButton.addEventListener('click', () => this._props.onDelete());

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

    this._pointMarker = new YMapMarker(
      {
        coordinates, // текущие координаты точки
        draggable: editable, // "draggable" только в том случае, если линейку можно редактировать
        source, // идентификатор источника данных, к которому следует добавить маркер
        onDragMove: this._props.onDragPoint // обратный вызов при перемещении точки
      },
      point // точка html-элемента
    );
    this.addChild(this._pointMarker);
  }

  protected _onUpdate(props: Partial<RenderPointArgs>): void {
    // обновление точки при изменении ее состояния
    if (props.state !== undefined) {
      const {coordinates, editable, source} = props.state;

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

      // абстрактная проверка того, что точка находится на конце линейки
      if (props.state.index === props.state.totalCount - 1) {
        // ...
      }
    }
  }
}

const previewPoint = document.createElement('div');
// ... настройка точки предварительного просмотра

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)
});

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>}
    />
  );
};

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>`
});

Подробный пример

КонструкторКонструктор

new YMapRuler(props)

Параметры конструктораПараметры конструктора

ПереопределяетПереопределяет

YMapComplexEntity.constructor

PropsProps

YMapRulerProps: [Omit](../../../ref/modules/ruler/#omittype-keys)<\[YMapRulerCommonProps](#YMapRulerCommonProps-props), "point"> & {
	point: (`params`: RenderPointArgs) => YMapEntity<RenderPointArgs>
}

ПараметрыПараметры

МетодыМетоды

updateupdate

update(changedProps): void

ПараметрыПараметры

ВозвращаетсяВозвращается

void

Унаследовано отУнаследовано от

YMapComplexEntity.update