mahal_map 1.6.18 → 1.6.19
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +69 -68
- package/dist/index.d.mts +8 -0
- package/dist/index.d.ts +8 -0
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +3 -3
- package/dist/index.mjs.map +1 -1
- package/dist/mahal_map.sdk.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -141,22 +141,22 @@ interface IMahalMapOptions {
|
|
|
141
141
|
}
|
|
142
142
|
```
|
|
143
143
|
|
|
144
|
-
| Параметр | Тип | Описание
|
|
145
|
-
| --------------------- | ----------------------- |
|
|
146
|
-
| `container` | `string \| HTMLElement` | ID контейнера или DOM-элемент. Если не передан, используется `"map"`.
|
|
147
|
-
| `style` | `string` | Пользовательский URL стиля MapLibre. Если передан, `theme`, `lang` и map token не меняют URL стиля.
|
|
148
|
-
| `theme` | `"dark" \| "light"` | Тема стандартного стиля. По умолчанию используется `light`.
|
|
149
|
-
| `lang` | `"tj" \| "ru"` | Язык стандартного стиля. `tj` оставляет URL только с `token`, `ru` добавляет `lang=ru`.
|
|
150
|
-
| `center` | `[number, number]` | Центр карты в формате `[lng, lat]`.
|
|
151
|
-
| `zoom` | `number` | Начальный zoom.
|
|
144
|
+
| Параметр | Тип | Описание |
|
|
145
|
+
| --------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
146
|
+
| `container` | `string \| HTMLElement` | ID контейнера или DOM-элемент. Если не передан, используется `"map"`. |
|
|
147
|
+
| `style` | `string` | Пользовательский URL стиля MapLibre. Если передан, `theme`, `lang` и map token не меняют URL стиля. |
|
|
148
|
+
| `theme` | `"dark" \| "light"` | Тема стандартного стиля. По умолчанию используется `light`. |
|
|
149
|
+
| `lang` | `"tj" \| "ru"` | Язык стандартного стиля. `tj` оставляет URL только с `token`, `ru` добавляет `lang=ru`. |
|
|
150
|
+
| `center` | `[number, number]` | Центр карты в формате `[lng, lat]`. |
|
|
151
|
+
| `zoom` | `number` | Начальный zoom. |
|
|
152
152
|
| `pitch` | `number` | Начальный наклон камеры (нужен для 3D-вида). Если не задан и `enable3D` включен — авто `58` (при `pitch: 0` экструзия зданий не видна, камера смотрит строго сверху). |
|
|
153
|
-
| `bearing` | `number` | Начальный поворот камеры.
|
|
154
|
-
| `autoAddVectorSource` | `boolean` | Использует встроенный vector style и блокирует смену стандартного стиля через `setStyle`.
|
|
155
|
-
| `engine`
|
|
156
|
-
| `enable3D`
|
|
157
|
-
| `base`
|
|
158
|
-
| `preset`
|
|
159
|
-
| `maps3d`
|
|
153
|
+
| `bearing` | `number` | Начальный поворот камеры. |
|
|
154
|
+
| `autoAddVectorSource` | `boolean` | Использует встроенный vector style и блокирует смену стандартного стиля через `setStyle`. |
|
|
155
|
+
| `engine` | `"legacy" \| "3d"` | Переключатель движка карты. `"legacy"` (по умолчанию) — старые стили mtile.gram.tj. `"3d"` — новая платформа GramMaps (navi.gram.tj) с пресетами стиля и Maps3D. |
|
|
156
|
+
| `enable3D` | `boolean` | Подключает детальные 3D-здания (Maps3D). Работает только при `engine: "3d"`. По умолчанию `true` для `engine: "3d"` — передайте `false`, чтобы отключить. |
|
|
157
|
+
| `base` | `string` | Домен платформы GramMaps для `engine: "3d"`. По умолчанию `https://navi.gram.tj`. |
|
|
158
|
+
| `preset` | `string` | Имя пресета стиля GramMaps (напр. `"standard-night"`) для `engine: "3d"`. По умолчанию `road-urban-lab-v2`/`standard-night` в зависимости от `theme`. |
|
|
159
|
+
| `maps3d` | `object` | Доп. опции Maps3D слоя: `traffic`, `minZoom`, `lodBias`, `memoryBudget`, `maskReplaced`, `typeReplacements`. |
|
|
160
160
|
|
|
161
161
|
### Новый 3D-движок (GramMaps / Maps3D)
|
|
162
162
|
|
|
@@ -201,14 +201,14 @@ MahalMap.getMaps3DLayer(map);
|
|
|
201
201
|
|
|
202
202
|
Передаются в `MahalMap.create({ maps3d: {...} })` при `engine: "3d"`:
|
|
203
203
|
|
|
204
|
-
| Опция
|
|
205
|
-
|
|
|
206
|
-
| `traffic`
|
|
207
|
-
| `minZoom`
|
|
208
|
-
| `lodBias`
|
|
209
|
-
| `memoryBudget`
|
|
210
|
-
| `maskReplaced`
|
|
211
|
-
| `typeReplacements` | `boolean`
|
|
204
|
+
| Опция | Тип | По умолч. | Описание |
|
|
205
|
+
| ------------------ | ------------------------------------------------ | --------- | ------------------------------------------------------------------------- |
|
|
206
|
+
| `traffic` | `boolean \| { raster?, rasterMaxZoom?, graph? }` | `false` | Слой пробок. `raster: true` — картинкой с сервера вместо векторного слоя. |
|
|
207
|
+
| `minZoom` | `number` | `16` | Зум появления детальных 3D. |
|
|
208
|
+
| `lodBias` | `number` | `1` | `0` — всегда lod0 (детальный), `1` — lod1 на дальних зумах. |
|
|
209
|
+
| `memoryBudget` | `number` | `30` | Сколько моделей держать в сцене одновременно. |
|
|
210
|
+
| `maskReplaced` | `boolean` | `true` | Прятать заменённые OSM-объекты (`anchor=replace`). |
|
|
211
|
+
| `typeReplacements` | `boolean` | `true` | Рисовать замены по типу (`natural=tree` → 3D-дерево и т.п.). |
|
|
212
212
|
|
|
213
213
|
`buildings: true` включается автоматически при `enable3D: true` — переопределять не нужно, если только не требуется передать сам объект опций.
|
|
214
214
|
|
|
@@ -258,7 +258,7 @@ layer?.setBuildingsEnabled(false); // напрямую через слой
|
|
|
258
258
|
const map = MahalMap.getInstance("map");
|
|
259
259
|
|
|
260
260
|
map.toggle3DBuildings(false); // выкл
|
|
261
|
-
map.toggle3DBuildings(true);
|
|
261
|
+
map.toggle3DBuildings(true); // вкл обратно
|
|
262
262
|
|
|
263
263
|
// статик-версия и SDK-фасад (mahal_map/sdk) работают так же
|
|
264
264
|
MahalMap.toggle3DBuildings(map, false);
|
|
@@ -285,9 +285,9 @@ const layer = map.getMaps3DLayer();
|
|
|
285
285
|
|
|
286
286
|
layer?.setMinZoom(15);
|
|
287
287
|
layer?.setObjectsLight({ sun: 1.8, ambient: 0.45, sky: 1.1, exposure: 1.15 });
|
|
288
|
-
await layer?.refresh();
|
|
289
|
-
await layer?.clearCache();
|
|
290
|
-
layer?.destroy?.();
|
|
288
|
+
await layer?.refresh(); // перечитать модели после правок
|
|
289
|
+
await layer?.clearCache(); // сбросить IndexedDB-кеш ассетов
|
|
290
|
+
layer?.destroy?.(); // отцепить слой (также вызывается автоматически в map.destroy())
|
|
291
291
|
```
|
|
292
292
|
|
|
293
293
|
`map.destroy()` / `MahalMap.destroy(map)` сами вызывают `destroy()`/`remove()` у Maps3D слоя, если он был подключен — отдельно чистить не нужно.
|
|
@@ -520,25 +520,25 @@ MahalMap.setZoom(map, 14);
|
|
|
520
520
|
|
|
521
521
|
Доступные функции карты в browser SDK:
|
|
522
522
|
|
|
523
|
-
| Функция
|
|
524
|
-
|
|
|
525
|
-
| `create(options)`
|
|
526
|
-
| `onReady(container, callback)`
|
|
527
|
-
| `getInstance(container)`
|
|
528
|
-
| `hasInstance(container)`
|
|
529
|
-
| `removeInstance(container)`
|
|
530
|
-
| `getMap(instance)`
|
|
531
|
-
| `getCamera(instance)`
|
|
532
|
-
| `setStyle(instance, theme)`
|
|
533
|
-
| `setLanguage(instance, lang)`
|
|
534
|
-
| `setCenter(instance, center)`
|
|
535
|
-
| `setZoom(instance, zoom)`
|
|
536
|
-
| `addMarker(instance, marker)`
|
|
537
|
-
| `getMaps3DLayer(instance)`
|
|
523
|
+
| Функция | Описание |
|
|
524
|
+
| -------------------------------------- | ------------------------------------------------------------- |
|
|
525
|
+
| `create(options)` | Создает карту. Требует `apikey` в URL SDK скрипта. |
|
|
526
|
+
| `onReady(container, callback)` | Выполняет callback после загрузки карты. |
|
|
527
|
+
| `getInstance(container)` | Возвращает инстанс карты. |
|
|
528
|
+
| `hasInstance(container)` | Проверяет наличие инстанса. |
|
|
529
|
+
| `removeInstance(container)` | Удаляет инстанс из реестра. |
|
|
530
|
+
| `getMap(instance)` | Возвращает нативный MapLibre Map. |
|
|
531
|
+
| `getCamera(instance)` | Возвращает CameraController. |
|
|
532
|
+
| `setStyle(instance, theme)` | Переключает тему стандартного стиля. |
|
|
533
|
+
| `setLanguage(instance, lang)` | Переключает язык стандартного стиля. |
|
|
534
|
+
| `setCenter(instance, center)` | Меняет центр карты. |
|
|
535
|
+
| `setZoom(instance, zoom)` | Меняет zoom карты. |
|
|
536
|
+
| `addMarker(instance, marker)` | Добавляет маркер. |
|
|
537
|
+
| `getMaps3DLayer(instance)` | Возвращает инстанс слоя Maps3D (только `engine: "3d"`). |
|
|
538
538
|
| `toggle3DBuildings(instance, enabled)` | Вкл/выкл детальные 3D-здания на лету (только `engine: "3d"`). |
|
|
539
|
-
| `destroy(instance)`
|
|
540
|
-
| `loadKeyFromScriptUrl()`
|
|
541
|
-
| `loadLanguageFromScriptUrl()`
|
|
539
|
+
| `destroy(instance)` | Полностью удаляет карту. |
|
|
540
|
+
| `loadKeyFromScriptUrl()` | Читает `apikey` из URL SDK скрипта. |
|
|
541
|
+
| `loadLanguageFromScriptUrl()` | Читает `lang` из URL SDK скрипта. |
|
|
542
542
|
|
|
543
543
|
## CameraController
|
|
544
544
|
|
|
@@ -741,9 +741,10 @@ measureTool.start("distance");
|
|
|
741
741
|
MapLibre GL проверяет `paint`-свойства слоя и не понимает `var(--primary)` — только hex/rgb. Если в приложении цвета живут в CSS-переменных (тема light/dark), резолвьте их в реальное значение перед передачей в `style`:
|
|
742
742
|
|
|
743
743
|
```ts
|
|
744
|
-
const primary =
|
|
745
|
-
.
|
|
746
|
-
|
|
744
|
+
const primary =
|
|
745
|
+
getComputedStyle(document.documentElement)
|
|
746
|
+
.getPropertyValue("--primary")
|
|
747
|
+
.trim() || "#278960";
|
|
747
748
|
|
|
748
749
|
const measureTool = new MeasureTool(map, {
|
|
749
750
|
style: { lineColor: primary, pointStrokeColor: primary, fillColor: primary },
|
|
@@ -754,29 +755,29 @@ const measureTool = new MeasureTool(map, {
|
|
|
754
755
|
|
|
755
756
|
### Конструктор: `new MeasureTool(map, options?)`
|
|
756
757
|
|
|
757
|
-
| Опция
|
|
758
|
-
|
|
|
759
|
-
| `mode`
|
|
760
|
-
| `sourceIdPrefix`
|
|
761
|
-
| `style`
|
|
762
|
-
| `icons`
|
|
763
|
-
| `labels`
|
|
764
|
-
| `onChange`
|
|
765
|
-
| `onCloseRequest`
|
|
758
|
+
| Опция | Тип | Описание |
|
|
759
|
+
| ---------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
760
|
+
| `mode` | `"distance" \| "area"` | Режим по умолчанию. По умолчанию `"distance"`. |
|
|
761
|
+
| `sourceIdPrefix` | `string` | Префикс id source/layer на карте. По умолчанию генерируется уникальный (`"mahal-measure-1"`, `"mahal-measure-2"`, ...) — так несколько инструментов на одной карте не конфликтуют. Задайте явно, если нужен предсказуемый id. |
|
|
762
|
+
| `style` | `MeasureStyleOptions` | Цвета и размеры точек/линий/заливки/бейджа. |
|
|
763
|
+
| `icons` | `MeasureIcons` | SVG-иконки `trash` / `close` / `check` для бейджей. |
|
|
764
|
+
| `labels` | `MeasureLabels` | Подписи единиц: `meters`, `kilometers`, `squareMeters`, `squareKilometers`. |
|
|
765
|
+
| `onChange` | `(state: MeasureState) => void` | Вызывается при любом изменении: новая точка, drag, смена режима и т.д. |
|
|
766
|
+
| `onCloseRequest` | `() => void` | Вызывается по клику на ✕ в бейджике активной фигуры — решение "выключить инструмент" остается за приложением. |
|
|
766
767
|
|
|
767
768
|
### Методы
|
|
768
769
|
|
|
769
|
-
| Метод
|
|
770
|
-
|
|
|
771
|
-
| `start(mode?)`
|
|
772
|
-
| `stop()`
|
|
773
|
-
| `setMode(mode)`
|
|
774
|
-
| `finishDraft()`
|
|
775
|
-
| `removeShape(shapeId)`
|
|
776
|
-
| `removePoint(shapeId, pointId)`
|
|
777
|
-
| `clearAll()`
|
|
778
|
-
| `getState()`
|
|
779
|
-
| `destroy()`
|
|
770
|
+
| Метод | Описание |
|
|
771
|
+
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
|
772
|
+
| `start(mode?)` | Включает инструмент и начинает/продолжает рисование в указанном режиме. |
|
|
773
|
+
| `stop()` | Выключает инструмент, прячет активный бейдж. Сохраненные фигуры остаются на карте. |
|
|
774
|
+
| `setMode(mode)` | Переключает режим. Если фигура уже рисуется — её точки сохраняются, меняется только тип (линия ⇄ полигон), как в Яндекс.Картах. |
|
|
775
|
+
| `finishDraft()` | Завершает текущую фигуру (если валидна — от 2 точек для линии, от 3 для полигона) и начинает новую. |
|
|
776
|
+
| `removeShape(shapeId)` | Удаляет фигуру (черновик или уже сохраненную) целиком. |
|
|
777
|
+
| `removePoint(shapeId, pointId)` | Удаляет одну точку фигуры. |
|
|
778
|
+
| `clearAll()` | Удаляет все фигуры и черновик. |
|
|
779
|
+
| `getState()` | Возвращает текущий `MeasureState` (снимок, без подписки). |
|
|
780
|
+
| `destroy()` | Полностью снимает слои, обработчики и DOM-бейджи. Вызывать при размонтировании. |
|
|
780
781
|
|
|
781
782
|
### Взаимодействие на карте
|
|
782
783
|
|
package/dist/index.d.mts
CHANGED
|
@@ -36,10 +36,13 @@ interface IMaps3DLayerOptions {
|
|
|
36
36
|
typeReplacements?: boolean;
|
|
37
37
|
}
|
|
38
38
|
interface IMaps3DBuildingsController {
|
|
39
|
+
setWindows?(enabled: boolean): void;
|
|
40
|
+
setWindowMinZoom?(zoom: number): void;
|
|
39
41
|
setWindowStyle(style: number): void;
|
|
40
42
|
setWindowDepth(depth: number): void;
|
|
41
43
|
setWindowColor(color: string): void;
|
|
42
44
|
setWindowFrameColor(color: string): void;
|
|
45
|
+
setWindowGlow?(value: number): void;
|
|
43
46
|
setEdgeRadius(radius: number): void;
|
|
44
47
|
setSunIntensity(value: number): void;
|
|
45
48
|
setAmbient(value: number): void;
|
|
@@ -230,6 +233,9 @@ declare class MahalMap {
|
|
|
230
233
|
private presetIsExplicit;
|
|
231
234
|
private maps3dCtor?;
|
|
232
235
|
private maps3dLayer?;
|
|
236
|
+
private maps3dLayerReady;
|
|
237
|
+
private maps3dLayerAttachPending;
|
|
238
|
+
private buildingsEnabled;
|
|
233
239
|
private constructor();
|
|
234
240
|
private static getInstanceKey;
|
|
235
241
|
private static normalizeLanguage;
|
|
@@ -262,6 +268,8 @@ declare class MahalMap {
|
|
|
262
268
|
getMaps3DLayer(): IMaps3DLayer | undefined;
|
|
263
269
|
/** Вкл/выкл детальные 3D-здания (Maps3D). Работает только для engine: "3d". */
|
|
264
270
|
toggle3DBuildings(enabled: boolean): void;
|
|
271
|
+
private attachMaps3DLayer;
|
|
272
|
+
private applyMaps3DBuildingMode;
|
|
265
273
|
/**
|
|
266
274
|
* Прячет/показывает нативные здания стиля GramMaps ("building-3d" и любые fill-extrusion /
|
|
267
275
|
* fill+source-layer=building), не задевая слои самого Maps3D. Нужно, иначе плоский слой стиля
|
package/dist/index.d.ts
CHANGED
|
@@ -36,10 +36,13 @@ interface IMaps3DLayerOptions {
|
|
|
36
36
|
typeReplacements?: boolean;
|
|
37
37
|
}
|
|
38
38
|
interface IMaps3DBuildingsController {
|
|
39
|
+
setWindows?(enabled: boolean): void;
|
|
40
|
+
setWindowMinZoom?(zoom: number): void;
|
|
39
41
|
setWindowStyle(style: number): void;
|
|
40
42
|
setWindowDepth(depth: number): void;
|
|
41
43
|
setWindowColor(color: string): void;
|
|
42
44
|
setWindowFrameColor(color: string): void;
|
|
45
|
+
setWindowGlow?(value: number): void;
|
|
43
46
|
setEdgeRadius(radius: number): void;
|
|
44
47
|
setSunIntensity(value: number): void;
|
|
45
48
|
setAmbient(value: number): void;
|
|
@@ -230,6 +233,9 @@ declare class MahalMap {
|
|
|
230
233
|
private presetIsExplicit;
|
|
231
234
|
private maps3dCtor?;
|
|
232
235
|
private maps3dLayer?;
|
|
236
|
+
private maps3dLayerReady;
|
|
237
|
+
private maps3dLayerAttachPending;
|
|
238
|
+
private buildingsEnabled;
|
|
233
239
|
private constructor();
|
|
234
240
|
private static getInstanceKey;
|
|
235
241
|
private static normalizeLanguage;
|
|
@@ -262,6 +268,8 @@ declare class MahalMap {
|
|
|
262
268
|
getMaps3DLayer(): IMaps3DLayer | undefined;
|
|
263
269
|
/** Вкл/выкл детальные 3D-здания (Maps3D). Работает только для engine: "3d". */
|
|
264
270
|
toggle3DBuildings(enabled: boolean): void;
|
|
271
|
+
private attachMaps3DLayer;
|
|
272
|
+
private applyMaps3DBuildingMode;
|
|
265
273
|
/**
|
|
266
274
|
* Прячет/показывает нативные здания стиля GramMaps ("building-3d" и любые fill-extrusion /
|
|
267
275
|
* fill+source-layer=building), не задевая слои самого Maps3D. Нужно, иначе плоский слой стиля
|