@movk/maplibre 1.0.0

package/dist/runtime/utils/tianditu-administrative.js

@@ -0,0 +1,48 @@
+import { getJson, TIANDITU_ENDPOINTS, TiandituError } from "./tianditu-request.js";
+function parseWktMultiPolygon(wkt) {
+  const inner = wkt.replace(/^\s*MULTIPOLYGON\s*\(\(\(/i, "").replace(/\)\)\)\s*$/, "");
+  return inner.split(/\)\)\s*,\s*\(\(/).map(
+    (polygon) => polygon.split(/\)\s*,\s*\(/).map(
+      (ring) => ring.split(",").map((pair) => {
+        const [lng, lat] = pair.trim().split(/\s+/).map(Number);
+        return [lng, lat];
+      })
+    )
+  );
+}
+function centerPoint(center) {
+  return [center.lng, center.lat];
+}
+function toDivision(district, includeBoundary) {
+  const division = {
+    name: district.name,
+    code: district.gb,
+    level: district.level,
+    center: centerPoint(district.center)
+  };
+  if (includeBoundary && district.boundary) {
+    division.boundary = { type: "MultiPolygon", coordinates: parseWktMultiPolygon(district.boundary) };
+  }
+  if (Array.isArray(district.children)) {
+    division.children = district.children.map((child) => ({
+      name: child.name,
+      code: child.gb,
+      level: child.level,
+      center: centerPoint(child.center)
+    }));
+  }
+  return division;
+}
+export async function administrative(keyword, options, tk) {
+  const includeBoundary = options.boundary ?? true;
+  const data = await getJson(TIANDITU_ENDPOINTS.administrative, {
+    keyword,
+    childLevel: String(options.childLevel ?? 0),
+    extensions: String(includeBoundary)
+  }, tk);
+  if (data.status !== void 0 && data.status !== 200) {
+    throw new TiandituError(data.status, data.message ?? "\u5929\u5730\u56FE\u884C\u653F\u533A\u5212\u67E5\u8BE2\u5931\u8D25");
+  }
+  const districts = data.data?.district;
+  return Array.isArray(districts) ? districts.map((district) => toDivision(district, includeBoundary)) : [];
+}

package/dist/runtime/utils/tianditu-client.d.ts

@@ -0,0 +1,30 @@
+import type { AdministrativeDivision, AdministrativeOptions, GeocodePoint, LocateOptions, Poi, ReverseGeocodeResult, RouteOptions, RouteResult, SearchParams, SearchResult } from '../types';
+/** 天地图 Web 服务客户端；tk 在创建时注入一次，各方法无需重复传递。 */
+export interface TiandituClient {
+    /** 地名搜索：一个入口覆盖 7 种 queryType，输出按 resultType 判别归一化。 */
+    search: (params: SearchParams) => Promise<SearchResult>;
+    /**
+     * 地名精确定位：适用于“把一个地标/地名解析为最佳匹配点”场景（与通用 search 不同，
+     * 未传 bounds 时会自动利用天地图返回的行政区建议二次收窄范围、并对同名结果做精确匹配优先排序）。
+     */
+    locate: (keyword: string, options?: LocateOptions) => Promise<SearchResult>;
+    /** 周边 POI 搜索：给定中心点 + 半径检索附近兴趣点。 */
+    searchNearby: (keyword: string, center: [number, number], options?: {
+        radius?: number;
+        count?: number;
+        start?: number;
+    }) => Promise<Poi[]>;
+    /** 正地理编码：结构化地址→精确坐标点。 */
+    geocode: (address: string) => Promise<GeocodePoint | undefined>;
+    /** 逆地理编码：WGS84 坐标点→结构化地址。 */
+    reverseGeocode: (point: [number, number]) => Promise<ReverseGeocodeResult | undefined>;
+    /** 行政区划查询：中心点、边界轮廓、下级行政区。 */
+    administrative: (keyword: string, options?: AdministrativeOptions) => Promise<AdministrativeDivision[]>;
+    /** 驾车/步行路线规划：真实道路路径与距离/时长。 */
+    route: (origin: [number, number], destination: [number, number], options?: RouteOptions) => Promise<RouteResult>;
+}
+/** 创建天地图 Web 服务客户端，绑定 tk 后返回各接口方法。 */
+export declare function createTianditu(options: {
+    tk: string;
+}): TiandituClient;
+export { TiandituError } from './tianditu-request';

package/dist/runtime/utils/tianditu-client.js

@@ -0,0 +1,17 @@
+import { administrative } from "./tianditu-administrative.js";
+import { geocode, reverseGeocode } from "./tianditu-geocoder.js";
+import { route } from "./tianditu-route.js";
+import { locate, search, searchNearby } from "./tianditu-search.js";
+export function createTianditu(options) {
+  const { tk } = options;
+  return {
+    search: (params) => search(params, tk),
+    locate: (keyword, opts) => locate(keyword, opts ?? {}, tk),
+    searchNearby: (keyword, center, opts) => searchNearby(keyword, center, opts ?? {}, tk),
+    geocode: (address) => geocode(address, tk),
+    reverseGeocode: (point) => reverseGeocode(point, tk),
+    administrative: (keyword, opts) => administrative(keyword, opts ?? {}, tk),
+    route: (origin, destination, opts) => route(origin, destination, opts ?? {}, tk)
+  };
+}
+export { TiandituError } from "./tianditu-request.js";

package/dist/runtime/utils/tianditu-geocoder.d.ts

@@ -0,0 +1,5 @@
+import type { GeocodePoint, ReverseGeocodeResult } from '../types';
+/** 正地理编码：把结构化地址（「北京市海淀区莲花池西路 28 号」）解析为精确坐标点，无结果或低置信度返回 undefined。 */
+export declare function geocode(address: string, tk: string): Promise<GeocodePoint | undefined>;
+/** 逆地理编码：把一个 WGS84 坐标点反查为结构化地址（「这是哪里」），无结果返回 undefined。 */
+export declare function reverseGeocode(point: [number, number], tk: string): Promise<ReverseGeocodeResult | undefined>;

package/dist/runtime/utils/tianditu-geocoder.js

@@ -0,0 +1,37 @@
+import { getJson, TIANDITU_ENDPOINTS, TiandituError } from "./tianditu-request.js";
+function assertNotError(status, msg) {
+  if (status === "404") throw new TiandituError("404", msg ?? "\u5929\u5730\u56FE\u5730\u7406\u7F16\u7801\u5931\u8D25");
+}
+const MIN_GEOCODE_SCORE = 60;
+export async function geocode(address, tk) {
+  const data = await getJson(
+    TIANDITU_ENDPOINTS.geocoder,
+    { ds: JSON.stringify({ keyWord: address }) },
+    tk
+  );
+  assertNotError(data.status, data.msg);
+  if (data.status !== "0" || !data.location) return void 0;
+  if (data.location.score !== void 0 && data.location.score < MIN_GEOCODE_SCORE) return void 0;
+  const location = [Number(data.location.lon), Number(data.location.lat)];
+  return { location, level: data.location.level || void 0, score: data.location.score };
+}
+export async function reverseGeocode(point, tk) {
+  const [lon, lat] = point;
+  const data = await getJson(
+    TIANDITU_ENDPOINTS.geocoder,
+    { postStr: JSON.stringify({ lon, lat, ver: 1 }), type: "geocode" },
+    tk
+  );
+  assertNotError(data.status, data.msg);
+  if (data.status !== "0" || !data.result?.formatted_address) return void 0;
+  const c = data.result.addressComponent ?? {};
+  return {
+    formattedAddress: data.result.formatted_address,
+    // 直辖市 city 为空串，用 province 兜底
+    province: c.province || void 0,
+    city: c.city || c.province || void 0,
+    county: c.county || void 0,
+    road: c.road || void 0,
+    poi: c.poi || void 0
+  };
+}

package/dist/runtime/utils/tianditu-request.d.ts

@@ -0,0 +1,20 @@
+export declare const TIANDITU_ENDPOINTS: {
+    readonly search: "https://api.tianditu.gov.cn/v2/search";
+    readonly geocoder: "https://api.tianditu.gov.cn/geocoder";
+    readonly administrative: "https://api.tianditu.gov.cn/v2/administrative";
+    readonly drive: "https://api.tianditu.gov.cn/drive";
+};
+/** 天地图接口返回异常状态码时抛出；无数据/空结果不属于此类，按空值正常返回。 */
+export declare class TiandituError extends Error {
+    /** 天地图状态码（检索 infocode、地理编码 status、行政区 status 或 HTTP 状态码） */
+    readonly code: number | string;
+    constructor(code: number | string, message: string);
+}
+/** 发起 GET 请求并按 JSON 解析。HTTP 非 2xx 抛 TiandituError。 */
+export declare function getJson<T>(endpoint: string, params: Record<string, string>, tk: string): Promise<T>;
+/** 发起 GET 请求并返回原始文本（驾车规划返回 XML）。HTTP 非 2xx 抛 TiandituError。 */
+export declare function getText(endpoint: string, params: Record<string, string>, tk: string): Promise<string>;
+/** 解析天地图 "经度,纬度" 字符串为坐标点（未做坐标系转换）。 */
+export declare function parseLngLat(text: string): [number, number];
+/** 将坐标点格式化为天地图 "经度,纬度" 字符串。 */
+export declare function formatLngLat(point: [number, number]): string;

package/dist/runtime/utils/tianditu-request.js

@@ -0,0 +1,42 @@
+export const TIANDITU_ENDPOINTS = {
+  search: "https://api.tianditu.gov.cn/v2/search",
+  // 正/逆地理编码共用此路径（无 /v2），通过 type/ds 参数区分
+  geocoder: "https://api.tianditu.gov.cn/geocoder",
+  administrative: "https://api.tianditu.gov.cn/v2/administrative",
+  // 驾车/步行规划，返回 XML
+  drive: "https://api.tianditu.gov.cn/drive"
+};
+export class TiandituError extends Error {
+  /** 天地图状态码（检索 infocode、地理编码 status、行政区 status 或 HTTP 状态码） */
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "TiandituError";
+    this.code = code;
+  }
+}
+async function buildUrl(endpoint, params, tk) {
+  const url = new URL(endpoint);
+  for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);
+  url.searchParams.set("tk", tk);
+  return url;
+}
+export async function getJson(endpoint, params, tk) {
+  const url = await buildUrl(endpoint, params, tk);
+  const res = await fetch(url);
+  if (!res.ok) throw new TiandituError(res.status, `\u5929\u5730\u56FE\u8BF7\u6C42\u5931\u8D25\uFF1AHTTP ${res.status}`);
+  return await res.json();
+}
+export async function getText(endpoint, params, tk) {
+  const url = await buildUrl(endpoint, params, tk);
+  const res = await fetch(url);
+  if (!res.ok) throw new TiandituError(res.status, `\u5929\u5730\u56FE\u8BF7\u6C42\u5931\u8D25\uFF1AHTTP ${res.status}`);
+  return await res.text();
+}
+export function parseLngLat(text) {
+  const [lng, lat] = text.trim().split(",").map(Number);
+  return [lng, lat];
+}
+export function formatLngLat(point) {
+  return `${point[0]},${point[1]}`;
+}

package/dist/runtime/utils/tianditu-route.d.ts

@@ -0,0 +1,3 @@
+import type { RouteOptions, RouteResult } from '../types';
+/** 驾车/步行路线规划：返回真实道路路径与真实距离/时长。未找到路线抛 TiandituError。 */
+export declare function route(origin: [number, number], destination: [number, number], options: RouteOptions, tk: string): Promise<RouteResult>;

package/dist/runtime/utils/tianditu-route.js

@@ -0,0 +1,40 @@
+import { formatLngLat, getText, parseLngLat, TIANDITU_ENDPOINTS, TiandituError } from "./tianditu-request.js";
+const STYLE_MAP = {
+  "fastest": "0",
+  "shortest": "1",
+  "avoid-highway": "2",
+  "walking": "3"
+};
+function tag(xml, name) {
+  return new RegExp(`<${name}>([\\s\\S]*?)</${name}>`).exec(xml)?.[1];
+}
+export async function route(origin, destination, options, tk) {
+  const postStr = {
+    orig: formatLngLat(origin),
+    dest: formatLngLat(destination),
+    style: STYLE_MAP[options.mode ?? "fastest"]
+  };
+  if (options.waypoints?.length) {
+    postStr.mid = options.waypoints.map(formatLngLat).join(";");
+  }
+  const xml = await getText(TIANDITU_ENDPOINTS.drive, { postStr: JSON.stringify(postStr), type: "search" }, tk);
+  const routelatlon = tag(xml, "routelatlon");
+  if (!routelatlon) throw new TiandituError("no-route", "\u5929\u5730\u56FE\u672A\u8FD4\u56DE\u8DEF\u7EBF");
+  const path = {
+    type: "LineString",
+    coordinates: routelatlon.trim().replace(/;$/, "").split(";").map(parseLngLat)
+  };
+  const simple = /<simple>([\s\S]*?)<\/simple>/.exec(xml)?.[1] ?? "";
+  const guides = [...simple.matchAll(/<strguide>([\s\S]*?)<\/strguide>/g)].map((m) => m[1].trim());
+  const mapinfo = /<mapinfo>([\s\S]*?)<\/mapinfo>/.exec(xml)?.[1] ?? "";
+  const centerRaw = tag(mapinfo, "center");
+  const scaleRaw = tag(mapinfo, "scale");
+  return {
+    distanceKm: Number(tag(xml, "distance") ?? 0),
+    durationMinutes: Math.round(Number(tag(xml, "duration") ?? 0) / 60 * 10) / 10,
+    path,
+    summary: guides.length ? guides.join(" ") : void 0,
+    center: centerRaw ? parseLngLat(centerRaw) : void 0,
+    scale: scaleRaw ? Number(scaleRaw.trim()) : void 0
+  };
+}

package/dist/runtime/utils/tianditu-search.d.ts

@@ -0,0 +1,15 @@
+import type { LocateOptions, Poi, SearchParams, SearchResult } from '../types';
+/** 地名搜索：一个入口覆盖天地图 7 种 queryType，输出按 resultType 判别归一化。 */
+export declare function search(params: SearchParams, tk: string): Promise<SearchResult>;
+/** 周边 POI 搜索：给定中心点 + 半径检索附近兴趣点，直接返回 POI 列表。 */
+export declare function searchNearby(keyword: string, center: [number, number], options: {
+    radius?: number;
+    count?: number;
+    start?: number;
+}, tk: string): Promise<Poi[]>;
+/**
+ * 地名精确定位：全国范围模糊检索命中量大时排序质量会骤降（如关键词带省市前缀），
+ * 天地图会随结果附带一个行政区建议（suggestedDistrict）；若调用方未显式指定 bounds，
+ * 自动用该建议行政区重新检索一次以收窄范围、提升排序精度，最终对同名结果做精确匹配优先排序。
+ */
+export declare function locate(keyword: string, options: LocateOptions, tk: string): Promise<SearchResult>;

package/dist/runtime/utils/tianditu-search.js

@@ -0,0 +1,183 @@
+import { formatLngLat, getJson, parseLngLat, TIANDITU_ENDPOINTS, TiandituError } from "./tianditu-request.js";
+const CHINA_BOUNDS = [73.66, 3.86, 135.05, 53.55];
+const QUERY_TYPE = {
+  normal: 1,
+  inView: 2,
+  nearby: 3,
+  polygon: 10,
+  district: 12,
+  category: 13,
+  statistics: 14
+};
+function boundsToMapBound(bounds) {
+  return `${bounds[0]},${bounds[1]},${bounds[2]},${bounds[3]}`;
+}
+function boundFromString(text) {
+  const [minx, miny, maxx, maxy] = text.split(",").map(Number);
+  return [minx, miny, maxx, maxy];
+}
+function toPoi(raw) {
+  return {
+    name: raw.name,
+    address: raw.address || void 0,
+    phone: raw.phone || void 0,
+    location: parseLngLat(raw.lonlat),
+    poiType: raw.poiType,
+    hotPointID: raw.hotPointID || void 0,
+    province: raw.province || void 0,
+    city: raw.city || void 0,
+    county: raw.county || void 0,
+    typeCode: raw.typeCode || void 0,
+    typeName: raw.typeName || void 0,
+    source: raw.source || void 0,
+    distance: raw.distance || void 0
+  };
+}
+function toStatistics(raw) {
+  return {
+    count: raw.count ?? 0,
+    adminCount: raw.adminCount ?? 0,
+    priorityCities: (raw.priorityCitys ?? []).map((city) => ({
+      name: city.name,
+      count: city.count ?? 0,
+      adminCode: String(city.adminCode ?? ""),
+      location: parseLngLat(city.lonlat)
+    }))
+  };
+}
+function toArea(raw) {
+  return {
+    name: raw.name,
+    adminCode: String(raw.adminCode ?? ""),
+    level: raw.level ?? 0,
+    location: parseLngLat(raw.lonlat.replace(/[{}]/g, "")),
+    bound: raw.bound ? boundFromString(raw.bound) : void 0
+  };
+}
+function toSuggestion(raw) {
+  return {
+    type: raw.type ?? 0,
+    keyword: raw.keyword ?? "",
+    admins: raw.admins ?? []
+  };
+}
+function extractSuggestedDistrict(prompt) {
+  const admin = prompt?.find((p) => p.type === 4)?.admins?.[0];
+  return admin ? { name: admin.adminName, code: String(admin.adminCode) } : void 0;
+}
+function toLines(raw) {
+  return raw.map((line) => ({ name: line.name, uuid: line.uuid, stationNum: line.stationNum }));
+}
+function buildPostStr(params) {
+  const post = {
+    queryType: QUERY_TYPE[params.type],
+    start: params.start ?? 0,
+    count: params.count ?? 10
+  };
+  if ("keyword" in params && params.keyword) post.keyWord = params.keyword;
+  if (params.dataTypes) post.dataTypes = params.dataTypes;
+  if (params.show) post.show = params.show;
+  switch (params.type) {
+    case "normal":
+      post.mapBound = boundsToMapBound(params.bounds);
+      post.level = params.level;
+      if (params.specify) post.specify = params.specify;
+      break;
+    case "inView":
+      post.mapBound = boundsToMapBound(params.bounds);
+      post.level = params.level;
+      break;
+    case "nearby":
+      post.pointLonlat = formatLngLat(params.center);
+      post.queryRadius = params.radius;
+      break;
+    case "polygon":
+      post.polygon = params.polygon.map((point) => formatLngLat(point)).join(",");
+      break;
+    case "district":
+      post.specify = params.specify;
+      break;
+    case "category":
+      post.specify = params.specify;
+      post.mapBound = boundsToMapBound(params.bounds);
+      break;
+    case "statistics":
+      post.specify = params.specify;
+      break;
+  }
+  return post;
+}
+function normalize(data) {
+  switch (data.resultType) {
+    case 1:
+      return {
+        kind: "poi",
+        count: data.count ?? data.pois?.length ?? 0,
+        pois: (data.pois ?? []).map(toPoi),
+        suggestedDistrict: extractSuggestedDistrict(data.prompt)
+      };
+    case 2:
+      return { kind: "statistics", statistics: toStatistics(data.statistics ?? {}) };
+    case 3:
+      if (data.area) return { kind: "area", area: toArea(data.area) };
+      break;
+    case 4:
+      if (data.prompt?.[0]) return { kind: "suggestion", suggestion: toSuggestion(data.prompt[0]) };
+      break;
+    case 5:
+      return { kind: "line", lines: toLines(data.lineData ?? []) };
+  }
+  const info = data.status?.infocode;
+  if (info !== void 0 && info !== 1e3 && info !== 3001) {
+    throw new TiandituError(info, data.status?.cndesc ?? "\u5929\u5730\u56FE\u68C0\u7D22\u5931\u8D25");
+  }
+  return { kind: "empty" };
+}
+function normalizeCategories(data) {
+  const categories = Object.entries(data).map(([name, raw]) => ({
+    name,
+    count: raw.count ?? 0,
+    pois: (raw.pois ?? []).map(toPoi)
+  }));
+  return { kind: "categories", categories };
+}
+export async function search(params, tk) {
+  const data = await getJson(
+    TIANDITU_ENDPOINTS.search,
+    { postStr: JSON.stringify(buildPostStr(params)), type: "query" },
+    tk
+  );
+  return "resultType" in data || "status" in data ? normalize(data) : normalizeCategories(data);
+}
+export async function searchNearby(keyword, center, options, tk) {
+  const result = await search({
+    type: "nearby",
+    keyword,
+    center,
+    radius: options.radius ?? 5e3,
+    count: options.count,
+    start: options.start
+  }, tk);
+  return result.kind === "poi" ? result.pois : [];
+}
+function prioritizeExactMatch(pois, keyword) {
+  return [...pois].sort((a, b) => Number(b.name === keyword) - Number(a.name === keyword));
+}
+export async function locate(keyword, options, tk) {
+  const autoNarrow = !options.bounds;
+  const first = await search({
+    type: "normal",
+    keyword,
+    bounds: options.bounds ?? CHINA_BOUNDS,
+    level: options.level ?? 10,
+    count: options.count
+  }, tk);
+  if (first.kind !== "poi") return first;
+  if (autoNarrow && first.suggestedDistrict && first.pois.length > 0) {
+    const narrowed = await search({ type: "district", specify: first.suggestedDistrict.code, keyword, count: options.count }, tk);
+    if (narrowed.kind === "poi" && narrowed.pois.length > 0) {
+      return { ...narrowed, pois: prioritizeExactMatch(narrowed.pois, keyword) };
+    }
+  }
+  return { ...first, pois: prioritizeExactMatch(first.pois, keyword) };
+}

package/dist/runtime/utils/tianditu.d.ts

@@ -0,0 +1,21 @@
+import type { RasterSourceSpecification } from '@maplibre/maplibre-gl-style-spec';
+/** 天地图图层类型：vec 矢量底图、img 影像底图、ter 地形、cva 矢量注记、cia 影像注记、cta 地形注记 */
+export type TiandituLayerType = 'vec' | 'img' | 'ter' | 'cva' | 'cia' | 'cta';
+/** 取底图对应的注记图层类型；注记类型自身或无对应时返回 undefined。 */
+export declare function tiandituAnnotationFor(base: TiandituLayerType): TiandituLayerType | undefined;
+export interface TiandituSourceOptions {
+    /** 天地图 token（tk）；缺省时回退到运行时配置 maplibre.tk */
+    tk?: string;
+    /**
+     * 瓦片尺寸
+     * @defaultValue 256
+     */
+    tileSize?: number;
+    /**
+     * 子域名数量（t0..t{n-1}）
+     * @defaultValue 8
+     */
+    subdomains?: number;
+}
+/** 生成天地图球面墨卡托（EPSG:3857）栅格数据源规格，可直接用于 MaplibreSource。 */
+export declare function tiandituRasterSource(layer: TiandituLayerType, options?: TiandituSourceOptions): RasterSourceSpecification;

package/dist/runtime/utils/tianditu.js

@@ -0,0 +1,26 @@
+import { getMaplibreConfig } from "../domains/map/config.js";
+import { logger } from "./logger.js";
+import { wmtsRasterSource } from "./wmts.js";
+const ANNOTATION_MAP = {
+  vec: "cva",
+  img: "cia",
+  ter: "cta"
+};
+export function tiandituAnnotationFor(base) {
+  return ANNOTATION_MAP[base];
+}
+export function tiandituRasterSource(layer, options = {}) {
+  const tk = options.tk ?? getMaplibreConfig().tk;
+  if (!tk) logger.warn("Tianditu token (tk) is missing; tiles may fail to load.");
+  const count = options.subdomains ?? 8;
+  const subdomains = Array.from({ length: count }, (_, i) => String(i));
+  return wmtsRasterSource({
+    url: `https://t{s}.tianditu.gov.cn/${layer}_w/wmts`,
+    layer,
+    tileMatrixSet: "w",
+    subdomains,
+    tileSize: options.tileSize ?? 256,
+    attribution: "\xA9 \u5929\u5730\u56FE",
+    params: { tk: tk ?? "" }
+  });
+}

package/dist/runtime/utils/wms.d.ts

@@ -0,0 +1,43 @@
+import type { RasterSourceSpecification } from '@maplibre/maplibre-gl-style-spec';
+export interface WmsSourceOptions {
+    /** WMS 服务基础地址（GetMap 端点） */
+    url: string;
+    /** 图层 LAYERS（逗号分隔多层） */
+    layers: string;
+    /**
+     * WMS 版本；1.3.0 用 CRS、否则用 SRS
+     * @defaultValue '1.1.1'
+     */
+    version?: string;
+    /**
+     * 图片格式 FORMAT
+     * @defaultValue 'image/png'
+     */
+    format?: string;
+    /**
+     * 是否透明 TRANSPARENT
+     * @defaultValue true
+     */
+    transparent?: boolean;
+    /**
+     * 样式 STYLES
+     * @defaultValue ''
+     */
+    styles?: string;
+    /**
+     * 坐标参考系
+     * @defaultValue 'EPSG:3857'
+     */
+    crs?: string;
+    /**
+     * 瓦片尺寸（WIDTH/HEIGHT）
+     * @defaultValue 256
+     */
+    tileSize?: number;
+    /** 版权信息 */
+    attribution?: string;
+    /** 透传查询参数 */
+    params?: Record<string, string | undefined>;
+}
+/** 构造 WMS GetMap 栅格数据源规格；maplibre 用 {bbox-epsg-3857} 占位符按瓦片请求。 */
+export declare function wmsRasterSource(options: WmsSourceOptions): RasterSourceSpecification;

package/dist/runtime/utils/wms.js

@@ -0,0 +1,30 @@
+export function wmsRasterSource(options) {
+  const version = options.version ?? "1.1.1";
+  const crs = options.crs ?? "EPSG:3857";
+  const size = options.tileSize ?? 256;
+  const crsKey = version === "1.3.0" ? "CRS" : "SRS";
+  const query = /* @__PURE__ */ new Map([
+    ["SERVICE", "WMS"],
+    ["REQUEST", "GetMap"],
+    ["VERSION", version],
+    ["LAYERS", options.layers],
+    ["STYLES", options.styles ?? ""],
+    ["FORMAT", options.format ?? "image/png"],
+    ["TRANSPARENT", String(options.transparent ?? true).toUpperCase()],
+    [crsKey, crs],
+    ["WIDTH", String(size)],
+    ["HEIGHT", String(size)],
+    ["BBOX", "{bbox-epsg-3857}"]
+  ]);
+  for (const [key, value] of Object.entries(options.params ?? {})) {
+    if (value !== void 0) query.set(key, value);
+  }
+  const qs = Array.from(query, ([k, v]) => `${k}=${v}`).join("&");
+  const url = `${options.url}${options.url.includes("?") ? "&" : "?"}${qs}`;
+  return {
+    type: "raster",
+    tiles: [url],
+    tileSize: size,
+    ...options.attribution ? { attribution: options.attribution } : {}
+  };
+}

package/dist/runtime/utils/wmts.d.ts

@@ -0,0 +1,35 @@
+import type { RasterSourceSpecification } from '@maplibre/maplibre-gl-style-spec';
+export interface WmtsSourceOptions {
+    /** WMTS 服务基础地址（GetTile 端点）；含 {s} 时配合 subdomains 展开多 host */
+    url: string;
+    /** 图层标识 LAYER */
+    layer: string;
+    /**
+     * 瓦片矩阵集 TILEMATRIXSET（球面墨卡托 EPSG:3857）
+     * @defaultValue 'w'
+     */
+    tileMatrixSet?: string;
+    /**
+     * 样式 STYLE
+     * @defaultValue 'default'
+     */
+    style?: string;
+    /**
+     * 瓦片格式 FORMAT
+     * @defaultValue 'tiles'
+     */
+    format?: string;
+    /** 子域名列表，替换 url 中的 {s} 展开为多条 tiles */
+    subdomains?: string[];
+    /**
+     * 瓦片尺寸
+     * @defaultValue 256
+     */
+    tileSize?: number;
+    /** 版权信息 */
+    attribution?: string;
+    /** 透传查询参数（如 { tk } 等鉴权参数） */
+    params?: Record<string, string | undefined>;
+}
+/** 构造 WMTS GetTile（KVP）栅格数据源规格，可直接用于 MaplibreSource。 */
+export declare function wmtsRasterSource(options: WmtsSourceOptions): RasterSourceSpecification;

package/dist/runtime/utils/wmts.js

@@ -0,0 +1,29 @@
+function buildTileUrl(base, options) {
+  const query = /* @__PURE__ */ new Map([
+    ["SERVICE", "WMTS"],
+    ["REQUEST", "GetTile"],
+    ["VERSION", "1.0.0"],
+    ["LAYER", options.layer],
+    ["STYLE", options.style ?? "default"],
+    ["TILEMATRIXSET", options.tileMatrixSet ?? "w"],
+    ["FORMAT", options.format ?? "tiles"],
+    ["TILEMATRIX", "{z}"],
+    ["TILEROW", "{y}"],
+    ["TILECOL", "{x}"]
+  ]);
+  for (const [key, value] of Object.entries(options.params ?? {})) {
+    if (value !== void 0) query.set(key, value);
+  }
+  const qs = Array.from(query, ([k, v]) => `${k}=${v}`).join("&");
+  return `${base}${base.includes("?") ? "&" : "?"}${qs}`;
+}
+export function wmtsRasterSource(options) {
+  const { subdomains } = options;
+  const tiles = subdomains?.length && options.url.includes("{s}") ? subdomains.map((s) => buildTileUrl(options.url.replace("{s}", s), options)) : [buildTileUrl(options.url, options)];
+  return {
+    type: "raster",
+    tiles,
+    tileSize: options.tileSize ?? 256,
+    ...options.attribution ? { attribution: options.attribution } : {}
+  };
+}

package/dist/types.d.mts

@@ -0,0 +1,5 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'
+
+export * from '../dist/runtime/types/index.js'