feat: 增强 ArcFlowLayer/RouteLayer 能力并同步文档与构建配置

- ArcFlowLayer/RouteLayer: 扩展能力、改进示例
- core: 导出更新、统一三份 vite 配置
- site: 同步 ArcFlow 示例、BuiltinGlyphs demo 清理无效图标
- docs: 更新 route-layer / aimap / getting-started 文档
- skills: 同步 SKILL.md 与 composite-layers 参考

Author: lzxue

packages/core/src/components/CompositeLayer/ArcFlowLayer.tsx

@@ -1,7 +1,9 @@
-import React, { useMemo } from 'react';
+import React, { useCallback, useMemo, useState } from 'react';
 import type { LayerSchema, LayerEventPayload, AnimateConfig } from '../../schema/types';
 import { LineLayer } from '../Layer/LineLayer';
 import { PointLayer } from '../Layer/PointLayer';
+import { Tooltip } from '../Interaction/Tooltip';
+import { Popup } from '../Interaction/Popup';
 
 /**
  * 弧线形态
@@ -100,6 +102,10 @@ export interface ArcFlowLayerProps {
   nodePulse?: boolean;
 
   // ===== 交互 =====
+  /** 是否在 hover 弧线时显示 Tooltip，默认 true */
+  showTooltip?: boolean;
+  /** 是否在点击节点时显示 Popup，默认 true */
+  showNodePopup?: boolean;
   /** hover 高亮色 */
   activeColor?: string;
   /** 弧线 hover 事件 */
@@ -162,6 +168,8 @@ export function ArcFlowLayer({
   nodeSize = 4,
   nodeSizeRange,
   nodePulse = false,
+  showTooltip = true,
+  showNodePopup = true,
   activeColor = '#FFD93D',
   onArcHover,
   onArcClick,
@@ -247,6 +255,49 @@ export function ArcFlowLayer({
   // 节点颜色
   const resolvedNodeColor = nodeColor ?? color;
 
+  // 内置 Tooltip 状态（hover 弧线）
+  const [tooltipState, setTooltipState] = useState<{
+    visible: boolean; lng: number; lat: number; from: string; to: string; weight: number;
+  }>({ visible: false, lng: 0, lat: 0, from: '', to: '', weight: 0 });
+
+  const handleArcHoverInternal = useCallback((payload: LayerEventPayload) => {
+    onArcHover?.(payload);
+    if (!showTooltip) return;
+    const f = payload.feature;
+    if (!f) return;
+    setTooltipState({
+      visible: true,
+      lng: payload.lng,
+      lat: payload.lat,
+      from: String(f.fromName ?? ''),
+      to: String(f.toName ?? ''),
+      weight: Number(f[weightField] ?? 0),
+    });
+  }, [onArcHover, showTooltip, weightField]);
+
+  const handleArcMouseLeave = useCallback(() => {
+    setTooltipState((prev) => ({ ...prev, visible: false }));
+  }, []);
+
+  // 内置 Popup 状态（点击节点）
+  const [popupState, setPopupState] = useState<{
+    visible: boolean; lng: number; lat: number; name: string; degree: number;
+  }>({ visible: false, lng: 0, lat: 0, name: '', degree: 0 });
+
+  const handleNodeClickInternal = useCallback((payload: LayerEventPayload) => {
+    onNodeClick?.(payload);
+    if (!showNodePopup) return;
+    const f = payload.feature;
+    if (!f) return;
+    setPopupState({
+      visible: true,
+      lng: payload.lng,
+      lat: payload.lat,
+      name: String(f.name ?? ''),
+      degree: Number(f.degree ?? 0),
+    });
+  }, [onNodeClick, showNodePopup]);
+
   return (
     <>
       {/* 弧线层 */}
@@ -264,7 +315,8 @@ export function ArcFlowLayer({
         animate={animateConfig}
         active={activeColor ? { color: activeColor } : false}
         style={arcStyle}
-        onMouseMove={onArcHover}
+        onMouseMove={handleArcHoverInternal}
+        onMouseLeave={handleArcMouseLeave}
         onClick={onArcClick}
       />
 
@@ -285,7 +337,34 @@ export function ArcFlowLayer({
           }}
           animate={nodePulse ? { enable: true, speed: 0.6 } : undefined}
           active={activeColor ? { color: activeColor } : false}
-          onClick={onNodeClick}
+          onClick={handleNodeClickInternal}
+        />
+      )}
+
+      {/* 内置 Tooltip — hover 弧线时展示 */}
+      {showTooltip && tooltipState.visible && (
+        <Tooltip
+          longitude={tooltipState.lng}
+          latitude={tooltipState.lat}
+          visible
+          variant="dark"
+          items={[
+            { label: '起点', value: tooltipState.from },
+            { label: '终点', value: tooltipState.to },
+            { label: '流量', value: tooltipState.weight },
+          ]}
+        />
+      )}
+
+      {/* 内置 Popup — 点击节点时展示 */}
+      {showNodePopup && popupState.visible && (
+        <Popup
+          longitude={popupState.lng}
+          latitude={popupState.lat}
+          content={`<div style="min-width:80px"><div style="font-weight:700;font-size:13px;margin-bottom:4px">${popupState.name || '节点'}</div><div style="font-size:12px;color:#64748b">连接数: ${popupState.degree}</div></div>`}
+          closeButton
+          size="compact"
+          onClose={() => setPopupState((prev) => ({ ...prev, visible: false }))}
         />
       )}
     </>

packages/core/src/components/CompositeLayer/RouteLayer.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback, useMemo, useState } from 'react';
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type { LayerEventPayload } from '../../schema/types';
 import { LineLayer } from '../Layer/LineLayer';
 import { PointLayer } from '../Layer/PointLayer';
@@ -41,6 +41,29 @@ export interface RouteSegment {
   width?: number;
 }
 
+/** 路径类型 */
+export type RouteType = 'straight' | 'arc' | 'walking' | 'cycling' | 'driving' | 'transit';
+
+/** 交通路线查询参数 */
+export interface RouteQueryParams {
+  origin: [number, number];
+  destination: [number, number];
+  waypoints?: [number, number][];
+  routeType: 'walking' | 'cycling' | 'driving' | 'transit';
+}
+
+/** 交通路线查询结果 */
+export interface RouteQueryResult {
+  /** 完整路径坐标 */
+  path: [number, number][];
+  /** 分段路径（可选，如返回多段路况着色路径） */
+  segments?: RouteSegment[];
+  /** 途中补充站点（可选，如公交换乘站） */
+  stops?: RouteStop[];
+  /** 路线信息 */
+  info?: { distance?: number; duration?: number; description?: string };
+}
+
 export interface RouteLayerProps {
   /** 路径坐标 — 完整线坐标或分段 */
   path?: [number, number][];
@@ -49,6 +72,14 @@ export interface RouteLayerProps {
   /** 途经点列表 */
   stops?: RouteStop[];
 
+  // ===== 路径模式 =====
+  /** 路径类型，默认 'straight' */
+  routeType?: RouteType;
+  /** 路线查询回调 — routeType 为 walking/cycling/driving/transit 时使用 */
+  onRouteQuery?: (params: RouteQueryParams) => Promise<RouteQueryResult>;
+  /** 路线查询完成回调 */
+  onRouteResult?: (result: RouteQueryResult) => void;
+
   // ===== 路径视觉 =====
   /** 路径颜色，默认 '#2563eb' */
   color?: string;
@@ -122,6 +153,9 @@ export function RouteLayer({
   path,
   segments,
   stops = [],
+  routeType = 'straight',
+  onRouteQuery,
+  onRouteResult,
   color = '#2563eb',
   lineWidth = 4,
   opacity = 0.9,
@@ -143,46 +177,84 @@ export function RouteLayer({
   onPathClick,
   onStopClick,
 }: RouteLayerProps) {
+  // 交通路线查询结果
+  const [routeQueryResult, setRouteQueryResult] = useState<RouteQueryResult | null>(null);
+  const queryVersionRef = useRef(0);
+
+  const isTransportMode = routeType === 'walking' || routeType === 'cycling' || routeType === 'driving' || routeType === 'transit';
+
+  useEffect(() => {
+    if (!isTransportMode || !onRouteQuery || stops.length < 2) {
+      setRouteQueryResult(null);
+      return;
+    }
+    const origin: [number, number] = [stops[0].lng, stops[0].lat];
+    const destination: [number, number] = [stops[stops.length - 1].lng, stops[stops.length - 1].lat];
+    const waypoints: [number, number][] = stops.length > 2
+      ? stops.slice(1, -1).map((s) => [s.lng, s.lat])
+      : [];
+
+    const version = ++queryVersionRef.current;
+    onRouteQuery({ origin, destination, waypoints: waypoints.length > 0 ? waypoints : undefined, routeType })
+      .then((result) => {
+        if (queryVersionRef.current !== version) return;
+        setRouteQueryResult(result);
+        onRouteResult?.(result);
+      })
+      .catch(() => {
+        if (queryVersionRef.current !== version) return;
+        setRouteQueryResult(null);
+      });
+  }, [isTransportMode, onRouteQuery, stops, routeType]);
+
+  // 实际使用的路径和分段数据
+  const effectivePath = isTransportMode && routeQueryResult ? routeQueryResult.path : path;
+  const effectiveSegments = isTransportMode && routeQueryResult?.segments ? routeQueryResult.segments : segments;
+  const extraStops = isTransportMode && routeQueryResult?.stops ? routeQueryResult.stops : [];
+
+  // 线形状：arc 模式用 'arc'，其余用 'line'
+  const lineShape = routeType === 'arc' ? 'arc' : 'line';
+
   // 构建路径 GeoJSON
   const pathGeoJSON = useMemo(() => {
-    if (segments && segments.length > 0) {
+    if (effectiveSegments && effectiveSegments.length > 0) {
       return {
         type: 'FeatureCollection' as const,
-        features: segments.map((seg, idx) => ({
+        features: effectiveSegments.map((seg, idx) => ({
           type: 'Feature' as const,
           properties: { color: seg.color || color, width: seg.width || lineWidth, index: idx },
           geometry: { type: 'LineString' as const, coordinates: seg.coordinates },
         })),
       };
     }
-    if (path && path.length > 1) {
+    if (effectivePath && effectivePath.length > 1) {
       return {
         type: 'FeatureCollection' as const,
         features: [{
           type: 'Feature' as const,
           properties: { color, width: lineWidth },
-          geometry: { type: 'LineString' as const, coordinates: path },
+          geometry: { type: 'LineString' as const, coordinates: effectivePath },
         }],
       };
     }
     return null;
-  }, [path, segments, color, lineWidth]);
+  }, [effectivePath, effectiveSegments, color, lineWidth]);
 
   // 发光层 GeoJSON（同路径但宽度更大）
-  const hasSegmentColors = segments && segments.some((s) => s.color);
+  const hasSegmentColors = effectiveSegments && effectiveSegments.some((s) => s.color);
 
   // 途经点数据（增加序号和类型）
   // 自动补全路径起终点：如果 stops 中没有覆盖 path 的首尾坐标，则自动添加
   const stopsWithIndex = useMemo(() => {
-    const effectivePath = path ?? (segments && segments.length > 0
-      ? [...segments[0].coordinates.slice(0, 1), ...segments[segments.length - 1].coordinates.slice(-1)]
+    const effectivePathForStops = effectivePath ?? (effectiveSegments && effectiveSegments.length > 0
+      ? [...effectiveSegments[0].coordinates.slice(0, 1), ...effectiveSegments[effectiveSegments.length - 1].coordinates.slice(-1)]
       : null);
 
-    let merged = [...stops];
+    let merged = [...stops, ...extraStops];
 
-    if (effectivePath && effectivePath.length >= 2) {
-      const [startLng, startLat] = effectivePath[0];
-      const [endLng, endLat] = effectivePath[effectivePath.length - 1];
+    if (effectivePathForStops && effectivePathForStops.length >= 2) {
+      const [startLng, startLat] = effectivePathForStops[0];
+      const [endLng, endLat] = effectivePathForStops[effectivePathForStops.length - 1];
       const hasStart = stops.some((s) => Math.abs(s.lng - startLng) < 1e-6 && Math.abs(s.lat - startLat) < 1e-6);
       const hasEnd = stops.some((s) => Math.abs(s.lng - endLng) < 1e-6 && Math.abs(s.lat - endLat) < 1e-6);
 
@@ -205,7 +277,7 @@ export function RouteLayer({
       indexLabel: String(stop.index ?? idx + 1),
       markerColorValue: stop.markerColor ?? resolveMarkerColor(stop.type ?? (idx === 0 ? 'start' : idx === merged.length - 1 ? 'end' : 'waypoint')),
     }));
-  }, [stops, path, segments, color, stopColor, endColor]);
+  }, [stops, extraStops, effectivePath, effectiveSegments, color, stopColor, endColor]);
 
   const resolvedStopIconMap = useMemo(() => {
     if (stopRenderer !== 'icon') return undefined;
@@ -248,10 +320,10 @@ export function RouteLayer({
         <LineLayer
           source={pathGeoJSON}
           sourceType="geojson"
-          shape="line"
+          shape={lineShape}
           color={hasSegmentColors ? undefined : color}
           colorField={hasSegmentColors ? 'color' : undefined}
-          colorValues={hasSegmentColors ? segments!.map((s) => s.color || color) : undefined}
+          colorValues={hasSegmentColors ? effectiveSegments!.map((s) => s.color || color) : undefined}
           size={lineWidth * 2.5}
           style={{ opacity: 0.15 }}
         />
@@ -261,13 +333,13 @@ export function RouteLayer({
       <LineLayer
         source={pathGeoJSON}
         sourceType="geojson"
-        shape="line"
+        shape={lineShape}
         color={hasSegmentColors ? undefined : color}
         colorField={hasSegmentColors ? 'color' : undefined}
-        colorValues={hasSegmentColors ? segments!.map((s) => s.color || color) : undefined}
+        colorValues={hasSegmentColors ? effectiveSegments!.map((s) => s.color || color) : undefined}
         size={hasSegmentColors ? undefined : lineWidth}
         sizeField={hasSegmentColors ? 'width' : undefined}
-        sizeValues={hasSegmentColors ? segments!.map((s) => s.width || lineWidth) : undefined}
+        sizeValues={hasSegmentColors ? effectiveSegments!.map((s) => s.width || lineWidth) : undefined}
         style={{ opacity }}
         active={activeColor ? { color: activeColor } : false}
         onClick={onPathClick}

packages/core/src/index.ts

@@ -131,7 +131,7 @@ export type { SatelliteLayerProps, SatelliteProvider } from './components/Compos
 export { ArcFlowLayer } from './components/CompositeLayer/ArcFlowLayer';
 export type { ArcFlowLayerProps, ArcFlowDataItem, ArcShape, ArcColorMode } from './components/CompositeLayer/ArcFlowLayer';
 export { RouteLayer } from './components/CompositeLayer/RouteLayer';
-export type { RouteLayerProps, RouteStop, RouteSegment } from './components/CompositeLayer/RouteLayer';
+export type { RouteLayerProps, RouteStop, RouteSegment, RouteType, RouteQueryParams, RouteQueryResult } from './components/CompositeLayer/RouteLayer';
 export { TiffRasterLayer } from './components/CompositeLayer/TiffRasterLayer';
 export type { TiffRasterLayerProps, RampColors, RasterRenderMode } from './components/CompositeLayer/TiffRasterLayer';
 

packages/core/vite.config.cjs.ts

@@ -15,6 +15,7 @@ export default defineConfig({
   },
   build: {
     emptyOutDir: false,
+    assetsInlineLimit: 0,
     lib: {
       entry: resolve(__dirname, 'src/index.ts'),
       name: 'aimapui',

packages/core/vite.config.iife.ts

@@ -13,6 +13,7 @@ export default defineConfig({
   },
   build: {
     emptyOutDir: false,
+    assetsInlineLimit: 0,
     lib: {
       entry: resolve(__dirname, 'src/index.ts'),
       name: 'AimapUI',

packages/core/vite.config.ts

@@ -24,6 +24,7 @@ export default defineConfig({
   },
   build: {
     emptyOutDir: false,
+    assetsInlineLimit: 0,
     lib: {
       entry: resolve(__dirname, 'src/index.ts'),
       name: 'aimapui',