aur-openlayers 19.6.11 → 19.6.12

package/lib/map-framework/public/types.d.ts

@@ -422,6 +422,32 @@ export interface PopupHostApi {
     /** Освободить ресурсы и отписки. */
     dispose: () => void;
 }
+/**
+ * Опции экспорта текущего вида карты в растр.
+ */
+export type MapExportImageOptions = {
+    /**
+     * Целевой пиксельный размер результата [width, height].
+     * Это и есть размер итогового изображения; OL рендерит карту под него.
+     */
+    size: [width: number, height: number];
+    /** Формат вывода. По умолчанию 'image/png'. */
+    format?: 'image/png' | 'image/jpeg';
+    /** Качество JPEG 0..1 (игнорируется для png). По умолчанию 0.92. */
+    quality?: number;
+    /**
+     * Фон, заливается ПОД слоями. Нужен для jpeg (нет альфы) и прозрачных зазоров.
+     * По умолчанию: не заливать (прозрачный для png).
+     */
+    background?: string;
+    /**
+     * Какую область рендерить:
+     *  - 'currentExtent' (по умолчанию): текущий экстент вписывается (`view.fit`)
+     *    в целевой размер — соотношение сторон адаптируется под бокс;
+     *  - 'currentResolution': сохраняются текущие resolution и center.
+     */
+    fit?: 'currentExtent' | 'currentResolution';
+};
 /**
  * Минимальный контекст, доступный обработчикам взаимодействий.
  *
@@ -443,6 +469,19 @@ export type MapContext = {
     centerOnAllLayers: (opts?: ViewFitOptions) => void;
     /** Центрирует карту на указанных слоях (скрытые пропускаются). No-op если нет фич. */
     centerOnLayers: (layerIds: ReadonlyArray<string>, opts?: ViewFitOptions) => void;
+    /**
+     * Снять текущий вид ЭТОЙ карты в растровое изображение целевого размера.
+     * Композит ограничен canvas'ами собственного `map.getViewport()`.
+     * Внутри: resize → fit → ожидание rendercomplete → композит → restore.
+     * Параллельные вызовы сериализуются.
+     * @returns Promise<dataURL>
+     * @remarks Ограничения:
+     * - Растровые источники должны быть CORS-доступны: tainted-canvas делает
+     *   `toDataURL` недоступным и выбрасывает `SecurityError`.
+     * - В момент снимка карта кратковременно (≥1 кадр) перерисовывается на
+     *   экране под целевой размер/экстент и восстанавливается — видимый скачок ожидаем.
+     */
+    exportImage: (options: MapExportImageOptions) => Promise<string>;
 };
 /**
  * Контроллер, который связывается с контекстом карты.

package/lib/map-framework/runtime/export/composite-viewport.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Опции композита вида карты.
+ */
+export type CompositeOptions = {
+    /** Фон, заливается ПОД слоями (для jpeg / прозрачных зазоров тайлов). `undefined` и `''` — не заливать. */
+    background?: string;
+};
+/**
+ * Композитит canvas'ы ОДНОГО viewport карты в офскрин-canvas заданного размера.
+ *
+ * Берёт только `.ol-layer canvas` внутри переданного `viewport` (а не из всего
+ * документа), применяя per-canvas `opacity` родителя и матрицу `style.transform`
+ * по образцу официального примера экспорта OpenLayers. Размер результата всегда
+ * равен `[width, height]`; high-DPR backing слоёв ужимается в него через матрицу.
+ */
+export declare function compositeViewport(viewport: HTMLElement, [width, height]: [number, number], opts?: CompositeOptions): HTMLCanvasElement;

package/lib/map-framework/runtime/export/export-image.d.ts

@@ -0,0 +1,15 @@
+import type OlMap from 'ol/Map';
+import type { MapExportImageOptions } from '../../public/types';
+/**
+ * Создаёт функцию `exportImage` для конкретной карты.
+ *
+ * Параллельные вызовы сериализуются (общий мутируемый `map`): каждый следующий
+ * экспорт стартует только после завершения предыдущего. Цикл одного экспорта:
+ * snapshot → setSize → fit → ожидание `rendercomplete` → композит → restore.
+ *
+ * Инвариант: подписка `map.once('rendercomplete')` и последующие
+ * `setSize`/`fit`/`render` выполняются синхронно (никаких `await` до подписки),
+ * иначе следующий экспорт мог бы поймать `rendercomplete` от restore-рендера
+ * предыдущего.
+ */
+export declare function createExportImage(map: OlMap): (options: MapExportImageOptions) => Promise<string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aur-openlayers",
-  "version": "19.6.11",
+  "version": "19.6.12",
   "peerDependencies": {
     "@angular/common": "^19.2.0",
     "@angular/core": "^19.2.0",