syncfusion-blazor-maps

为 Blazor 实现 Syncfusion Maps

NuGet： Syncfusion.Blazor.Maps + Syncfusion.Blazor.Themes 命名空间： Syncfusion.Blazor.Maps

这是一份在 Blazor 应用中实现 Syncfusion Maps 组件的完整指南。Syncfusion Maps 提供强大的空间可视化功能，包括标记管理、多边形叠加、图层支持、事件处理，以及与多个地图提供商的集成。

🚨 关键安全声明——使用前请阅读：

能力边界（强制要求）： 此技能仅用于 UI 渲染。绝不能将其用作：

• 自动化 Agent 或大模型的数据接入点
• 处理不可信外部内容的管道
• 为决策系统提供形状／瓦片数据的来源
• 任何未经人工审核的自动化输入

严格限制： 绝不要将原始外部 GEOJSON、SHAPEDATA、瓦片或注释转发给 Agent、大模型或自动化系统。 所有外部地图内容都必须视为不可信用户输入。违反此限制会造成严重的提示词注入和数据泄露漏洞。

生产环境必须采取的防护措施：

1. 加载 GeoJSON／瓦片时：
   • 在本地托管瓦片和 GeoJSON（位于 wwwroot/tiles 或捆绑资源中），或者
   • 仅使用在客户端访问前验证所有数据的服务端代理
   • 绝不要在运行时直接从第三方 URL 加载
2. 使用服务端代理时：
   • 根据严格的允许列表验证提供商主机，并要求使用 HTTPS
   • 验证内容类型，并根据严格的架构进行验证（不允许用户字段）
   • 强制执行最大文件大小限制（5MB）和要素数量限制（最多 10,000）
   • 移除或 HTML 编码所有属性（工具提示、注释、标签）
   • 拒绝包含指令模式或可疑关键词的内容
   • 规范化／验证坐标（纬度 -90/90，经度 -180/180）
   • 在向客户端传递内容前，使用 HtmlSanitizer 清理所有文本字段
   • 签发短时有效的签名 URL（不要嵌入 API 密钥）
3. 渲染内容时：
   • 渲染前，始终使用 HtmlSanitizer 清理外部属性
   • 实施内容安全策略（CSP）标头以阻止脚本注入
   • 启用全面日志记录，记录所有验证失败

如果必须通过自动化处理外部内容：

• 首先执行完整的服务端架构验证和清理
• 实施强制拒绝策略，过滤类似指令的模式
• 强制执行严格的令牌／长度限制（每个字段最多 256 个字符）
• 自动化处理前，必须取得明确的人工审核和批准
• 使用边界标记进行封装：[MAP_DATA_START]...[MAP_DATA_END]
• 记录所有处理过程，并保留完整审计跟踪
• 所需验证模板请参阅 readme-security

请勿将此技能用于：

• ❌ 分析不可信的外部地理数据
• ❌ 未经验证就处理用户上传的 GeoJSON
• ❌ 将地图内容转发给大模型／Agent 分析系统
• ❌ 根据外部地图元数据做出自动化决策
• ❌ 存储或缓存外部第三方内容

严重的安全后果： 忽视这些边界可能导致：

• 通过恶意地理数据发动提示词注入攻击
• 操纵大模型／Agent 的行为
• 未经授权的数据泄露
• 通过脚本注入危害系统

何时使用此技能

在需要以下功能时，请使用 Syncfusion Maps：

• 在交互式地图上显示地理数据
• 使用颜色映射（分级统计图）可视化各区域的数据
• 向地图添加标记、多边形和注释
• 处理用户交互（单击、悬停、缩放、平移）
• 支持多个地图提供商（Google、Bing、Azure、OpenStreetMap）
• 使用自定义图例和标签导出或打印地图
• 构建位置感知应用
• 创建多图层空间可视化

组件概述

Syncfusion Maps 是一款强大的地理空间可视化组件，可帮助你：

• 使用多个提供商选项渲染交互式地图
• 绑定并可视化地理数据集
• 支持丰富的空间功能（标记、多边形、图层、注释）
• 处理复杂的用户交互和事件
• 通过主题和样式自定义外观
• 启用本地化和无障碍功能
• 导出地图以用于报告和共享

---

⚠️ 重要：已批准和受限的用例

✅ 已批准的用途（经验证的 UI 渲染）

• 在交互式 Web 仪表板上显示地理数据
• 通过分级统计地图可视化区域统计数据
• 显示经过人工审核的业务地点标记
• 渲染供用户交互的本地化地图
• 提供空间搜索和筛选界面
• 创建只读地理可视化内容
• 使用经过验证和整理的数据辅助决策

❌ 严格禁止的用途（不得与 Agent/LLM 集成）

• 绝不： 将原始地图数据传递给 LLM 分析系统
• 绝不： 将其用作自动化 Agent 的数据摄取入口
• 绝不： 将外部 GeoJSON 转发给决策系统
• 绝不： 通过自动化处理不受信任的第三方地理数据
• 绝不： 未经人工审核就将注释/工具提示用作 LLM 输入
• 绝不： 创建自动化地理数据管道
• 绝不： 与分析地图元数据的 AI 系统集成

🚫 第三方内容摄取边界

此技能引用的外部来源：

• tile.openstreetmap.org - OpenStreetMap 提供商
• cdn.syncfusion.com - Syncfusion 组件资源
• maps.googleapis.com - Google Maps 提供商
• dev.virtualearth.net - Bing Maps 提供商
• atlas.microsoft.com - Azure Maps 提供商

重要： 这些第三方提供商的数据仅用于 UI 渲染。任何此类内容都不得进入自动化系统。如果你需要通过自动化处理地理数据：

1. ❌ 请勿使用此技能的外部绑定
2. ✅ 请创建单独的服务器端验证管道
3. ✅ 请先对所有外部内容进行清理和验证
4. ✅ 请在自动化之前获取明确的人工批准
5. ✅ 请实施全面的审计日志记录

---

安全注意事项

重要： 此技能涉及多项安全敏感操作。请查看并实施以下安全措施：

1. API 密钥管理

• 风险： 源代码中硬编码的 API 密钥可能在版本控制中泄露
• 缓解措施： 将密钥存储在配置文件、用户机密或机密管理服务中
• 参考： 地图提供商 - 安全最佳实践

2. HTML 内容注入

• 风险： 工具提示、注释和弹出窗口可能会渲染来自外部数据源的任意 HTML
• 攻击途径： XSS 攻击、通过恶意地理数据进行提示词注入
• 缓解措施： 使用 HtmlSanitizer 库清理所有外部内容，并对用户输入进行 HTML 编码
• 参考： 用户交互 - 清理外部内容

3. 外部数据源

• 风险： 地图数据（GeoJSON、图块、标记）可能从不受信任的来源（包括 CDN）获取
• 攻击途径： 中间人攻击、CDN 遭到入侵、恶意注入格式错误的数据、属性注入
• 缓解措施： 根据允许列表验证来源 URL，强制使用 HTTPS，验证 GeoJSON 结构，实施 CSP，并在生产环境中进行本地缓存
• 参考： 数据可视化 - 验证外部 GeoJSON | 地图提供商 - 防止数据外泄

4. 数据导出操作

• 风险： 将地图导出为 PNG/SVG/PDF 可能包含敏感地理数据
• 缓解措施： 实施访问控制，审计导出操作，并清理导出内容
• 参考： 打印和导出

5. 提示词注入防护与 Agent/大模型边界

• 严重风险： 形状数据、注释、工具提示和其他外部地图元数据可能包含看似指令的文本。本技能会接收第三方内容（瓦片提供方、GeoJSON 来源）；如果未经明确的人工审核便转发给自动化 Agent 或大模型，这些内容可能被用于提示词注入攻击。

• 攻击面： 外部内容通过以下方式进入：

  • MapsLayer UrlTemplate（瓦片提供方）
  • ShapeData 和 DataSource 属性（GeoJSON）
  • 工具提示和注释属性
  • 来自外部来源的任何数据绑定

• 强制边界： 本技能绝不能作为以下用途的数据来源：

  • 大模型分析或摘要
  • 自动化 Agent 决策
  • AI 地理分析
  • 机器学习训练流水线
  • 任何未经人工干预便通过 AI/ML 处理地图数据的系统

• 如果必须将外部内容传递给自动化系统：

  • 在客户端渲染之前进行服务器端验证：检查架构（严格验证 GeoJSON）、验证域名允许列表
  • 使用 HtmlSanitizer 清理所有属性，并移除 HTML/脚本标签
  • 实施强制拒绝策略，拒绝包含类似指令关键词的内容（“system:”、“ignore”、“bypass”、“execute”、“[SYSTEM]”等）
  • 强制执行严格的长度限制（每个属性最多 256 个字符，总计最多 5000 个字符）
  • 使用边界标记包裹数据：[MAP_DATA_START]...[MAP_DATA_END]
  • 要求在转发到任何 AI 系统之前进行明确的人工审核并签字确认
  • 全面记录所有 AI 系统访问的审计日志

• 缓解架构：

  • 第 1 层： 指定仅用于 UI 渲染（不得用于 Agent/大模型）
  • 第 2 层： 模式检测（可疑关键词检测）
  • 第 3 层： 立即拒绝（不进行其他解析）
  • 第 4 层： HTML 清理（白名单方式）
  • 第 5 层： 严格验证流水线（架构、大小、坐标）
  • 第 6 层： 边界标记与审计日志（用于无法避免的自动化）

• 参考： 用户交互 - 防止提示词注入 | readme-security.md

---

安全问题处理

本技能已针对以下已识别的安全警告进行了加固：

[CREDENTIALS_UNSAFE] 硬编码 API 密钥

状态： ✅ 已解决

发现： 示例代码中硬编码了 Google Maps API 密钥。

已实施的修复：

• 从示例中移除了所有硬编码 API 密钥
• 更新所有提供方配置示例，从 IConfiguration 加载密钥
• 添加了全面的 API 密钥管理指南，介绍环境变量、用户机密和 Azure Key Vault 集成
• 所有示例现在均采用 Configuration["MapProviders:GoogleKey"] 模式

所需操作： 切勿硬编码 API 密钥。请从配置、环境变量或机密管理器加载密钥。

参考： map-providers.md#managing-api-keys-securely

[EXTERNAL_DOWNLOADS] 外部瓦片和数据下载

状态： ✅ 已注明为预期行为

发现： 本技能会从 tile.openstreetmap.org、cdn.syncfusion.com 和 maps.googleapis.com 下载地图瓦片。

说明： 这些下载是地图可视化的预期且必要的。地图瓦片必须来自瓦片提供方。这是正常行为，并非漏洞。

最佳实践：

• 在生产环境中使用本地瓦片缓存
• 实施服务器端代理以验证瓦片 URL
• 对所有瓦片请求强制使用 HTTPS
• 配置域名允许列表

参考： map-providers.md#external-asset-downloads-expected-behavior

[COMMAND_EXECUTION] IJSRuntime 浏览器 API 用法

状态： ✅ 已通过安全措施解决

参考： state-persistence.md | customization-and-styling.md

[PROMPT_INJECTION] 面向自动化 Agent 的不可信数据

状态： ✅ 已通过全面控制措施解决

发现： GeoJSON 和地图元数据可能包含类似指令的文本。如果未经清理就传递给大模型／Agent，可能导致提示词注入。

已实施的多层缓解措施：

1. 能力边界： 此技能仅用于 UI 渲染

   • 明确禁止将原始数据传递给大模型／Agent
   • 所有外部内容均视为不可信

2. 模式检测： 已实现指令模式检测

   • 检测：“system:”、“ignore”、“bypass”、“execute”、“[SYSTEM]”等
   • 发现可疑内容后立即拒绝

3. 清理： 渲染前清理所有 HTML 内容

   • HtmlSanitizer 库会移除脚本和不安全标签
   • 对外部属性进行 HTML 编码
   • 不使用来自外部来源的原始 HTML

4. 验证流程： 全面的 GeoJSON 验证

   • 模式验证（FeatureCollection 结构）
   • 大小限制（最多 5MB，最多 10,000 个要素）
   • 属性验证（最多 50 个属性，每个最多 1000 个字符）
   • 坐标范围验证（纬度 -90/90，经度 -180/180）

5. 边界标记： 如需自动化

   • 使用 [MAP_DATA_START] ... [MAP_DATA_END] 分隔符
   • 严格限制长度（每个属性 256 个字符，总计 5000 个字符）
   • 验证失败时拒绝

6. 日志记录与审计： 全面的安全日志记录

   • 记录所有验证失败
   • 记录可疑模式及相关上下文
   • 任何自动化操作之前都必须经过人工审核

生产环境检查清单：

• 未硬编码 API 密钥
• GeoJSON 来自本地文件或经过验证的提供方
• 对外部请求强制使用 HTTPS
• 已安装并配置 HtmlSanitizer
• 已设置内容安全策略标头
• 已实施模式拒绝策略
• 已启用全面日志记录
• API 密钥存放在机密管理器中
• 已完成安全审查

参考： readme-security.md | user-interactions.md#preventing-prompt-injection | data-visualization.md#validating-external-geojson-data

---

文档与导航指南

请选择与当前任务相符的参考指南：

入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 包配置
• 地图的基本初始化与渲染
• CSS 导入和主题配置
• 创建第一个交互式地图
• 分步配置指南

地图提供方与配置

📄 阅读： references/map-providers.md

• Google Maps 设置和 API 密钥配置
• Bing Maps 设置和身份验证
• Azure Maps 提供方配置
• OpenStreetMap 设置
• 提供方比较与选择指南

标记与图层

📄 阅读： references/markers-and-layers.md

• 添加和管理标记
• 标记聚类和分组
• 使用图层和图层集合
• 切换图层可见性
• 动态更新标记和数据绑定

空间要素与叠加层

📄 阅读： references/spatial-features.md

• 绘制多边形和地理图形
• 创建导航线和折线
• 添加带文本、图标和圆形的注释
• 创建数据气泡和交互式叠加层
• 高级空间几何功能

数据可视化与地图绘制

📄 阅读： references/data-visualization.md

• 色彩映射和分级统计图可视化
• 配置图例及其位置
• 地图元素上的数据标签
• 使用地理数据集填充地图
• 高级数据绑定和可视化模式

用户交互

📄 阅读： references/user-interactions.md

• 处理鼠标单击和双击
• 缩放和平移控制配置
• 工具提示和弹出窗口行为
• 键盘导航支持
• 自定义交互模式

事件和方法

📄 阅读： references/events-and-methods.md

• 鼠标事件处理（单击、悬停、移动）
• 捕获平移和缩放事件
• 以编程方式调用地图方法（平移、缩放、重置、刷新）
• 事件数据和回调模式
• 根据用户交互触发操作

自定义和样式设置

📄 阅读： references/customization-and-styling.md

• CSS 类自定义
• 与 Theme Studio 集成
• 标记和弹出窗口样式
• 地图控件和导航样式
• 深色模式和响应式设计

打印和导出

📄 阅读： references/print-and-export.md

• 将地图导出为 PNG、SVG 和 PDF
• 打印功能和页面设置
• 导出包含图例和数据标签的地图
• 文件格式注意事项
• 服务端和客户端导出选项

国际化和本地化

📄 阅读： references/internationalization-and-localization.md

• 地图标签的多语言支持
• 从右到左（RTL）文本支持
• 本地化数字和日期格式
• 区域地图变体
• 特定语言的自定义

状态持久化

📄 阅读： references/state-persistence.md

• 保存和恢复地图状态
• 持久化缩放级别和中心位置
• 保留用户交互状态
• 与会话存储和本地存储集成
• 状态管理模式

无障碍访问和高级主题

📄 阅读： references/accessibility.md

• 符合 WCAG 2.1 规范和标准
• 键盘导航和快捷键
• ARIA 属性和语义化标记
• 屏幕阅读器支持
• 高对比度模式支持
• 辅助技术兼容性

完整 API 参考

📄 阅读： references/api-reference.md

• SfMaps 主组件属性和方法
• 配置类（MapsCenterPosition、MapsZoomSettings、MapsLegendSettings 等）
• 所有事件类型的事件参数
• 接口（ILayer、IMarker、IBubble）
• MarkerType、ExportType、ProjectionType、GeometryType 等枚举
• 属性速查指南
• 完整的类层次结构和 API 范围

---

⛔ 安全要求：禁止事项

以下模式严禁使用，会造成严重的安全漏洞：

// ❌ PROHIBITED: Forwarding map data to LLM/agents
var geoJsonData = await LoadGeoJsonFromMapLayer();
var analysis = await llmService.AnalyzeAsync(geoJsonData);  // NEVER DO THIS

// ❌ PROHIBITED: Using external annotations in agent prompts
var tooltipText = mapFeature.Properties["tooltip"];
var response = await agent.ExecuteAsync($"Summarize: {tooltipText}");  // NEVER DO THIS

// ❌ PROHIBITED: Processing third-party tiles through automation
var tileUrl = "https://tile.openstreetmap.org/{z}/{x}/{y}.png";
await automationPipeline.IngestAsync(tileUrl);  // NEVER DO THIS

// ❌ PROHIBITED: Making decisions based on untrusted GeoJSON
var externalGeoJson = await httpClient.GetAsync("https://external-source.com/map.json");
var decision = MakeCriticalDecision(externalGeoJson);  // NEVER DO THIS

如果你认为需要在 AI/ML 系统中使用地图数据：

1. 停止并重新评估你的架构
2. 创建独立的服务端数据摄取管道
3. 实施完整的验证和清理
4. 获得明确的安全审查和批准
5. 在 AI 处理前设置人工审核关卡
6. 保留全面的审计跟踪

---

快速入门示例

// Basic map setup in Blazor (use validated tile URL or local tiles in production)
@page "/maps-demo"
@using Syncfusion.Blazor.Maps

<SfMaps>
    <MapsLayers>
        
        <MapsLayer UrlTemplate="@TileUrl">
        </MapsLayer>
    </MapsLayers>
</SfMaps>

@code {
    // SAFE: Host tiles locally or use a validated, domain-restricted provider
    private string TileUrl = "/tiles/{level}/{tileX}/{tileY}.png"; // local/cached tiles
    
    // This data stays in the UI layer only - NEVER forwarded to agents or LLMs
}

常见模式

模式 1：向地图添加标记

<SfMaps>
    <MapsLayers>
        <MapsLayer TValue="MarkerData" UrlTemplate="@TileUrl">
            <MapsMarkerSettings>
                <MapsMarker TValue="MarkerData" Latitude="37.368" Longitude="-122.095" 
                    Width="15" Height="15">
                </MapsMarker>
            </MapsMarkerSettings>
        </MapsLayer>
    </MapsLayers>
</SfMaps>

@code {
    public class MarkerData
    {
        public double Latitude { get; set; }
        public double Longitude { get; set; }
    }
}

模式 2：通过颜色映射绑定数据

<SfMaps>
    <MapsLayers>
        <MapsLayer ShapeDataSource="@ShapeData" 
                   ShapePropertyPath="@ShapePropertyPath"
                   DataSource="@DataSource" TValue="DataType">
            <MapsShapeSettings ColorValuePath="Population">
                <MapsShapeColorMappings>
                    <MapsShapeColorMapping From="0" To="50000" Color="#B3E5FC"></MapsShapeColorMapping>
                    <MapsShapeColorMapping From="50000" To="100000" Color="#81D4FA"></MapsShapeColorMapping>
                </MapsShapeColorMappings>
            </MapsShapeSettings>
        </MapsLayer>
    </MapsLayers>
</SfMaps>

模式 3：处理地图单击事件

<SfMaps @ref="mapInstance" OnShapeSelected="ShapeSelected" 
        OnMarkerClick="MarkerClicked">
    <MapsLayers>
        <MapsLayer UrlTemplate="@TileUrl">
        </MapsLayer>
    </MapsLayers>
</SfMaps>

@code {
    private SfMaps mapInstance;

    private void MarkerClicked(MarkerClickEventArgs args)
    {
        Console.WriteLine($"Marker clicked at: {args.Latitude}, {args.Longitude}");
    }

    private void ShapeSelected(ShapeSelectedEventArgs args)
    {
        Console.WriteLine($"Shape selected: {args.Data}");
    }
}

主要功能概览

• 多种地图提供商： 支持 Google Maps、Bing Maps、Azure Maps 和 OpenStreetMap
• 丰富的地理空间功能： 标记、多边形、折线、注释和气泡
• 数据可视化： 色彩映射、分级统计地图支持、图例和数据标签
• 交互性： 点击处理、悬停提示、缩放/平移控件、键盘导航
• 图层管理： 支持多图层，可切换可见性并动态更新
• 导出功能： 支持导出 PNG、SVG 和 PDF，并包含图例和标签
• 国际化： 支持多种语言和 RTL 文本渲染
• 无障碍访问： 符合 WCAG 标准，支持键盘导航和屏幕阅读器
• 自定义： 集成 Theme Studio、支持 CSS 自定义和标记样式设置
• 性能： 针对大型数据集和标记聚类优化渲染