mahal_map 1.6.17 → 1.6.18

package/README.md

@@ -149,11 +149,11 @@ interface IMahalMapOptions {
 | `lang`                | `"tj" \| "ru"`          | Язык стандартного стиля. `tj` оставляет URL только с `token`, `ru` добавляет `lang=ru`.             |
 | `center`              | `[number, number]`      | Центр карты в формате `[lng, lat]`.                                                                 |
 | `zoom`                | `number`                | Начальный zoom.                                                                                     |
-| `pitch`               | `number`                | Начальный наклон камеры (нужен для 3D-вида).                                                        |
+| `pitch`               | `number`                | Начальный наклон камеры (нужен для 3D-вида). Если не задан и `enable3D` включен — авто `58` (при `pitch: 0` экструзия зданий не видна, камера смотрит строго сверху). |
 | `bearing`             | `number`                | Начальный поворот камеры.                                                                           |
 | `autoAddVectorSource` | `boolean`               | Использует встроенный vector style и блокирует смену стандартного стиля через `setStyle`.           |
 | `engine`               | `"legacy" \| "3d"`     | Переключатель движка карты. `"legacy"` (по умолчанию) — старые стили mtile.gram.tj. `"3d"` — новая платформа GramMaps (navi.gram.tj) с пресетами стиля и Maps3D. |
-| `enable3D`             | `boolean`              | Подключает детальные 3D-здания (Maps3D). Работает только при `engine: "3d"`.                        |
+| `enable3D`             | `boolean`              | Подключает детальные 3D-здания (Maps3D). Работает только при `engine: "3d"`. По умолчанию `true` для `engine: "3d"` — передайте `false`, чтобы отключить. |
 | `base`                 | `string`               | Домен платформы GramMaps для `engine: "3d"`. По умолчанию `https://navi.gram.tj`.                  |
 | `preset`               | `string`               | Имя пресета стиля GramMaps (напр. `"standard-night"`) для `engine: "3d"`. По умолчанию `road-urban-lab-v2`/`standard-night` в зависимости от `theme`. |
 | `maps3d`               | `object`               | Доп. опции Maps3D слоя: `traffic`, `minZoom`, `lodBias`, `memoryBudget`, `maskReplaced`, `typeReplacements`. |
@@ -214,19 +214,25 @@ MahalMap.getMaps3DLayer(map);
 
 ### 3D-здания
 
+`Maps3D` рисует процедурные 3D-здания (three.js) вместо плоской `fill-extrusion` стиля: фаска кромок, вертикальный градиент и базовый цвет берутся из стиля, окна — из `metadata` пресета. При `engine: "3d"` слой создаётся и `attach`-ится к карте автоматически (`enable3D` по умолчанию `true`) — вручную поднимать `new Maps3D(...)` не нужно, только если требуется отдельный кастомный инстанс:
+
+```ts
+const layer = new Maps3D({ apiKey, base, buildings: true });
+await layer.attach(map); // attach асинхронный, дожидается load карты сам
+```
+
 Тема (окна/свет) приходит из `metadata` пресета стиля и применяется автоматически при `map.setStyle()` — пересоздавать слой не нужно. Ручные сеттеры перебивают её:
 
 ```ts
 const layer = map.getMaps3DLayer();
 
-layer?.setBuildingsEnabled(false); // 3D-здания ⇄ штатные здания стиля
-
 const b = layer?.buildings;
 b?.setWindowStyle(7); // тип окна 0..9 (сетка, лента, curtain wall, ...)
-b?.setWindowDepth(0.85);
+b?.setWindowDepth(0.85); // глубина ниши окна 0..1 (реальная геометрия вблизи)
 b?.setWindowColor("#6b9ed1");
 b?.setWindowFrameColor("#f2f2f4");
-b?.setEdgeRadius(1.2);
+b?.setEdgeRadius(1.2); // скругление кромок, м
+// Свет обычно НЕ задают руками — его несёт metadata стиля, сеттеры её перебивают
 b?.setSunIntensity(3.2);
 b?.setAmbient(0.76);
 b?.setSky(0.91);
@@ -238,6 +244,26 @@ layer?.onBuildingClick((info) => {
 });
 ```
 
+#### Вкл/выкл 3D-здания на лету
+
+Переключение 3D-здания ⇄ штатные здания стиля, без пересоздания карты:
+
+```ts
+layer?.setBuildingsEnabled(false); // напрямую через слой
+```
+
+Либо через обёртку `MahalMap` — она же умеет пересоздать слой, если его не было (`enable3D: false` при создании):
+
+```ts
+const map = MahalMap.getInstance("map");
+
+map.toggle3DBuildings(false); // выкл
+map.toggle3DBuildings(true);  // вкл обратно
+
+// статик-версия и SDK-фасад (mahal_map/sdk) работают так же
+MahalMap.toggle3DBuildings(map, false);
+```
+
 ### Пробки
 
 ```ts
@@ -469,6 +495,8 @@ MahalMap.setLanguage(map, "ru");
 MahalMap.setCenter(map, [69.624024, 40.279687]);
 MahalMap.setZoom(map, 14);
 MahalMap.addMarker(map, marker);
+MahalMap.getMaps3DLayer(map);
+MahalMap.toggle3DBuildings(map, false);
 MahalMap.destroy(map);
 ```
 
@@ -506,6 +534,8 @@ MahalMap.setZoom(map, 14);
 | `setCenter(instance, center)`  | Меняет центр карты.                                |
 | `setZoom(instance, zoom)`      | Меняет zoom карты.                                 |
 | `addMarker(instance, marker)`  | Добавляет маркер.                                  |
+| `getMaps3DLayer(instance)`     | Возвращает инстанс слоя Maps3D (только `engine: "3d"`). |
+| `toggle3DBuildings(instance, enabled)` | Вкл/выкл детальные 3D-здания на лету (только `engine: "3d"`). |
 | `destroy(instance)`            | Полностью удаляет карту.                           |
 | `loadKeyFromScriptUrl()`       | Читает `apikey` из URL SDK скрипта.                |
 | `loadLanguageFromScriptUrl()`  | Читает `lang` из URL SDK скрипта.                  |

package/dist/index.d.mts

@@ -262,6 +262,12 @@ declare class MahalMap {
     getMaps3DLayer(): IMaps3DLayer | undefined;
     /** Вкл/выкл детальные 3D-здания (Maps3D). Работает только для engine: "3d". */
     toggle3DBuildings(enabled: boolean): void;
+    /**
+     * Прячет/показывает нативные здания стиля GramMaps ("building-3d" и любые fill-extrusion /
+     * fill+source-layer=building), не задевая слои самого Maps3D. Нужно, иначе плоский слой стиля
+     * рисуется поверх процедурных 3D-зданий и визуально их перекрывает.
+     */
+    private setNativeBuildingsVisible;
     setCenter(center: [number, number]): void;
     setZoom(zoom: number): void;
     destroy(): void;

package/dist/index.d.ts

@@ -262,6 +262,12 @@ declare class MahalMap {
     getMaps3DLayer(): IMaps3DLayer | undefined;
     /** Вкл/выкл детальные 3D-здания (Maps3D). Работает только для engine: "3d". */
     toggle3DBuildings(enabled: boolean): void;
+    /**
+     * Прячет/показывает нативные здания стиля GramMaps ("building-3d" и любые fill-extrusion /
+     * fill+source-layer=building), не задевая слои самого Maps3D. Нужно, иначе плоский слой стиля
+     * рисуется поверх процедурных 3D-зданий и визуально их перекрывает.
+     */
+    private setNativeBuildingsVisible;
     setCenter(center: [number, number]): void;
     setZoom(zoom: number): void;
     destroy(): void;