地理围栏

地理围栏从 GeoJSON 地址加载 Polygon / MultiPolygon，以边界线和浅色填充显示，支持岛屿及内环。它是展示图层，不限制相机移动，也不执行点位进出判断或告警。

配置地址与开关

const map = await createMap({
  container: 'map',
  assetBaseUrl: '/cesium/',
  source: { type: 'naturalEarth' },
  geofence: {
    id: 'city-fence', // 省略时为 geofence
    url: '/data/shenzhen.geojson',
    enabled: true,
  },
});

map.setLayerVisible('city-fence', false); // 关闭
map.setLayerVisible('city-fence', true); // 开启，无需重复下载
await map.flyToLayer('city-fence'); // 查看整个围栏
map.removeLayer('city-fence');

也可在创建地图后动态配置：

await map.addGeofenceLayer({
  id: 'city-fence',
  url: '/data/shenzhen.geojson',
  enabled: true,
  fillColor: 'rgba(65, 145, 255, 0.035)',
  outlineColor: '#368be8',
  outlineWidth: 2,
});

enabled 默认 true；false 会下载并解析数据，但不显示。创建时配置围栏会等待围栏加载，数据或网络失败使 createMap 拒绝并清理地图；动态添加失败拒绝 Promise，发出 GEOFENCE_LOAD 事件并释放图层 ID。加载中调用 removeLayer 或销毁地图，会中止 fetch 并阻止迟到数据挂载。图层 ID 与普通图层、3D Tiles 共用命名空间。点击围栏通过 click 事件报告图层及生成的要素 ID。围栏不使用普通图层的 addFeature / updateFeature；替换地址时删除后重新添加。

遮盖围栏外区域

map.updateGeofenceStyle('city-fence', {
  maskEnabled: true,
  maskColor: '#101828',
  maskOpacity: 0.6,
});

// 单独关闭掩模，保留围栏边线与填充。
map.updateGeofenceStyle('city-fence', { maskEnabled: false });

这些字段也可以直接传给 addGeofenceLayer 或初始化的 geofence。 maskEnabled 默认 false；maskColor 默认 rgba(16, 24, 40, 0.6)，支持 CSS 颜色； maskOpacity 为 0–1，设置后覆盖颜色自身的 alpha，0 完全透明、1 完全不透明。掩模取所有围栏面的并集：重叠区域不会误遮盖，岛屿保持可见，内环属于围栏外区域；如果另一个围栏面覆盖内环，则该部分保持可见。边界按经纬度连接，支持跨日期变更线的局部围栏。

掩模覆盖围栏外的地面和底图，不裁剪 3D 模型、点位或 DOM 标记，也不限制相机。调整颜色、透明度或开关不重新下载数据；隐藏围栏时掩模一起隐藏，删除围栏或销毁地图时一起清理。 SDK 在支持 requestIdleCallback 的浏览器中，利用空闲时间预计算并缓存掩模边界；不支持时在首次启用时计算。遮罩按当前视野生成本地透明底图瓦片，随缩放细化，无额外网络请求，避免全球贴地多边形在远景和倾斜视角下产生接缝、白块，也不再等待大范围立体几何构建。关闭掩模时不会提前创建遮罩图层；后续开关及不透明度调整复用已有图层。更换颜色仅重新生成遮罩瓦片，继续复用边界缓存，不重复更新未变化的围栏样式；切换底图后遮罩仍位于底图上方。缓存仅属于当前地图中的当前围栏，删除、重新加载围栏或销毁地图会清理缓存及待执行的预计算任务。示例的「地理围栏 → 配置设置」提供「遮盖围栏外区域」、颜色和不透明度控件，可提前配置，开启围栏后生效。

数据与部署

支持非空 FeatureCollection 或单个 Feature，仅接受 Polygon / MultiPolygon。环必须闭合，至少四个位置；坐标为经度、纬度和可选椭球高度。边界线贴地显示，不将 GeoJSON 高度当作围墙高度。不支持投影坐标或 CRS 覆盖，不会隐式转换坐标。GeoJSON 中的 HTML、样式和远程 CRS 链接不会执行。跨域地址需要数据服务允许 CORS，HTTPS 页面使用 HTTPS 数据地址。

示例已录入用户提供的 public/data/shenzhen.geojson，包含深圳全市及 10 个区，共 11 个要素、4061 个位置。完整保留原文件；数据未声明坐标基准和测绘精度，SDK 按输入经纬度展示，不将其视为经过核验的行政区划或业务判定依据。该文件随示例静态站部署，不包含在 SDK npm 包内。

左侧「地理围栏」默认关闭。开启后加载当前地址；关闭仅隐藏，同地址再次开启不重新下载。修改地址后点击「应用地址」；关闭状态下仅保存当前输入，下次开启时加载。重新创建地图会沿用当前地址及开关。示例自定义默认地址使用 VITE_GEOFENCE_URL，无配置时地址随应用 BASE_URL 自动适配子路径部署。

地理围栏 ​

配置地址与开关 ​

遮盖围栏外区域 ​

数据与部署 ​

地理围栏

配置地址与开关

遮盖围栏外区域

数据与部署