# ESXYZLayer（OL简单xyz图层）

> 分类：**服务图层对象** | 引擎：- | 基类：否
> 继承链：`Destroyable -> ESSceneObject -> ESVisualObject -> ESXYZLayer`

ESXYZLayer 是用于在 OpenLayers 地图中加载和显示 XYZ 瓦片图层的对象。

## JSON 示例

```json
{
            "type": "ESXYZLayer",
            "url": "http://t0.tianditu.com/DataServer?T=vec_w&x={x}&y={y}&l={z}",
            "maxZoom": 18
        }
```

## 属性

| 属性 | 类型 | 默认值 | 说明 | 来源 |
| --- | --- | --- | --- | --- |
| `allowPicking` | boolean | false | 是否允许拾取 默认false | ESVisualObject |
| `attributions` | string[] \| undefined \| undefined | undefined | 图层属性信息来源，通常为一个字符串数组，每个字符串表示一条版权/归属信息。 | ESXYZLayer |
| `attributionsCollapsible` | boolean \| undefined | undefined | 版权信息是否可折叠，true 表示可折叠，false 或 undefined 表示不可折叠。 | ESXYZLayer |
| `cacheSize` | number \| undefined | undefined | 瓦片缓存大小（瓦片数量），用于控制内存中缓存的瓦片数量上限。 | ESXYZLayer |
| `collision` | boolean | true | 是否开启碰撞监测 默认true ,主要是UE使用 | ESVisualObject |
| `crossOrigin` | string \| undefined | undefined | 跨域请求时使用的 crossOrigin 属性值，如 'anonymous' 或 'use-credentials'。 | ESXYZLayer |
| `devTags` | string[] \| undefined | undefined | 对象类型名称相关的开发标签数组，使用 reactArrayWithUndefined 进行响应式处理，默认为 undefined。 | ESSceneObject |
| `execOnceFuncStr` | string \| undefined | undefined | 一次性执行函数的字符串表示，默认为 undefined。 | ESSceneObject |
| `extent` | JsonValue[] \| undefined \| undefined | undefined | 图层的显示范围，以 JSON 数组表示的边界框 [minX, minY, maxX, maxY]。 | ESXYZLayer |
| `extras` | JsonValue | undefined | 扩展属性 JSON，必须整体赋值，使用 reactJson 进行响应式处理，默认为 undefined。 | ESSceneObject |
| `flyInParam` | ESJFlyInParam \| undefined | undefined | 飞入参数 | ESVisualObject |
| `flyToParam` | ESJFlyToParam \| undefined | undefined | 飞向参数 | ESVisualObject |
| `gutter` | number \| undefined | undefined | 瓦片间的间隔像素数，用于处理瓦片拼接时的边缘缝隙。 | ESXYZLayer |
| `interpolate` | boolean \| undefined | undefined | 是否对瓦片进行插值，启用后可减少缩放时的锯齿现象。 | ESXYZLayer |
| `key` | string \| undefined | undefined | 用于标识该图层的键值，可在代码中通过此键快速查找图层。 | ESXYZLayer |
| `maxResolution` | number \| undefined | undefined | 最大分辨率，用于限制瓦片加载的最高分辨率。 | ESXYZLayer |
| `maxTilesDownload` | number \| undefined | undefined | 同时下载的最大瓦片数量，用于控制并发请求数。 | ESXYZLayer |
| `maxZoom` | number \| undefined | undefined | 最大缩放级别，超出此级别将不再加载更高级别的瓦片。 | ESXYZLayer |
| `minResolution` | number \| undefined | undefined | 最小分辨率，用于限制瓦片加载的最低分辨率。 | ESXYZLayer |
| `minZoom` | number \| undefined | undefined | 最小缩放级别，低于此级别将不再加载更低级别的瓦片。 | ESXYZLayer |
| `name` | string | "未命名场景对象" | 对象名称，默认为 '未命名场景对象'。 | ESSceneObject |
| `opaque` | boolean \| undefined | undefined | 瓦片背景是否不透明，true 表示不透明，false 表示支持透明瓦片。 | ESXYZLayer |
| `projection` | JsonValue \| undefined | undefined | 瓦片图层的投影坐标系，以 JSON 格式表示的投影定义（如 'EPSG:3857'）。 | ESXYZLayer |
| `ref` | string \| undefined | undefined | 对象引用，设置后可通过对象管理器 objm.$refs.xxx 快速获取到对象，默认为 undefined。 | ESSceneObject |
| `reprojectionErrorThreshold` | number \| undefined | undefined | 重投影误差阈值（像素），用于控制重投影时的精度与性能平衡。 | ESXYZLayer |
| `show` | boolean | true | 图层是否可见，true 为可见（默认值），false 为隐藏。 | ESXYZLayer |
| `tileGrid` | JsonValue \| undefined | undefined | 自定义瓦片网格，以 JSON 格式表示的 ol/tilegrid/TileGrid 配置。 | ESXYZLayer |
| `tileLoadFunction` | string \| undefined | undefined | 瓦片加载函数，类型为字符串形式的函数体或函数名，用于自定义瓦片加载逻辑。 | ESXYZLayer |
| `tilePixelRatio` | number \| undefined | undefined | 瓦片像素比，用于适配高 DPI（Retina）屏幕显示。 | ESXYZLayer |
| `tileSize` | [number, number] \| undefined | undefined | 瓦片尺寸，以 [宽度, 高度] 像素值表示，如 [256, 256]。 | ESXYZLayer |
| `tileUrlFunction` | string \| undefined | undefined | 瓦片 URL 函数，类型为字符串形式的函数体或函数名，用于根据瓦片坐标动态生成 URL。 | ESXYZLayer |
| `toDestroyFuncStr` | string \| undefined | undefined | 销毁函数的字符串表示，默认为 undefined。 | ESSceneObject |
| `transition` | number \| undefined | undefined | 瓦片加载过渡效果的持续时间（毫秒）。 | ESXYZLayer |
| `updateFuncStr` | string \| undefined | undefined | 更新函数的字符串表示，默认为 undefined。 | ESSceneObject |
| `url` | string \| undefined | undefined | 瓦片服务的 URL 模板，如 "http://tile.example.com/{z}/{x}/{y}.png"。 | ESXYZLayer |
| `urls` | string[] \| undefined \| undefined | undefined | 瓦片服务的多个 URL 模板数组，用于负载均衡（轮询使用）。 | ESXYZLayer |
| `visible` | boolean | true | 图层是否可见，true 为可见（默认值），false 为隐藏。此属性通常用于视图控制。 | ESXYZLayer |
| `wrapX` | boolean \| undefined | undefined | 是否在水平方向（X 轴）环绕地图，用于支持全球范围的无缝平铺。 | ESXYZLayer |
| `zDirection` | number \| undefined | undefined | 瓦片加载方向：0 表示从中心向四周，正数表示从低分辨率到高分辨率，负数反之。 | ESXYZLayer |
| `zIndex` | number | 1 | 图层的 z-index（层级顺序），值越大显示在越上方，默认为 1。 | ESXYZLayer |
| `zoomOffset` | number \| undefined | undefined | 缩放级别的偏移量，用于对齐自定义瓦片编号系统。 | ESXYZLayer |

## 方法

| 方法 | 参数 | 返回 | 说明 | 来源 |
| --- | --- | --- | --- | --- |
| `addToViewer(viewer: ESViewer)` | viewer: ESViewer | - | 将对象添加到指定视口中。<br>**参数**：viewer - 要添加对象的视口。 | ESSceneObject |
| `calcFlyInParam()` | - | - | 触发计算飞入参数事件 | ESVisualObject |
| `calcFlyToParam()` | - | - | 触发计算飞向参数事件 | ESVisualObject |
| `createAttachedObject(createViewerPropSceneObject: (viewer: ESViewer) => Destroyable | undefined)` | createViewerPropSceneObject: (viewer: ESViewer) => Destroyable \| undefined | - | 创建与视口关联的对象，并返回一个销毁函数，用于手动销毁关联对象。<br>**参数**：createViewerPropSceneObject - 一个函数，用于创建与视口关联的对象。<br>**返回**：一个销毁函数，调用该函数可以销毁所有关联对象。 | ESSceneObject |
| `emptyFlyInParam()` | - | - | 清空飞入参数 | ESVisualObject |
| `emptyFlyToParam()` | - | - | 清空飞向参数 | ESVisualObject |
| `flush()` | - | - | 刷新对象，触发刷新事件。 | ESSceneObject |
| `flyIn(duration: number = 1)` | duration: number = 1 | - | 触发飞入事件<br>**参数**：duration - 飞入持续时间，默认为 1 | ESVisualObject |
| `flyTo(duration: number = 1)` | duration: number = 1 | - | 触发飞向事件<br>**参数**：duration - 飞向持续时间，默认为 1 | ESVisualObject |
| `getBoundSphere(viewer: ESViewer)` | viewer: ESViewer | - | 获取对象的边界球<br>**参数**：viewer - 视图器对象<br>**返回**：包含边界球信息的 Promise | ESVisualObject |
| `getESProperties()` | - | - | 获取该对象的 ES 属性列表，用于属性面板展示。 在继承父类属性的基础上，添加 url、zIndex、maxZoom、minZoom 等 XYZ 图层特有属性。<br>**返回**：包含 basic 等属性分类的属性对象。 | ESXYZLayer |
| `registerAttachedObject(createViewerPropSceneObject: (viewer: ESViewer) => Destroyable | undefined)` | createViewerPropSceneObject: (viewer: ESViewer) => Destroyable \| undefined | - | 注册与视口关联的对象，当对象被添加到视口或从视口移除时，会自动创建或销毁关联对象。<br>**参数**：createViewerPropSceneObject - 一个函数，用于创建与视口关联的对象。 | ESSceneObject |
| `registerAttachedObjectForContainer(createContainerPropSceneObject: (viewer: ESViewer, container: HTMLDivElement) => Destroyable | undefined)` | createContainerPropSceneObject: (viewer: ESViewer, container: HTMLDivElement) => Destroyable \| undefined | - | 注册与视口容器关联的对象，当对象被添加到视口或从视口移除时，会自动创建或销毁关联对象。<br>**参数**：createContainerPropSceneObject - 一个函数，用于创建与视口容器关联的对象。 | ESSceneObject |
| `reload()` | - | - | - | ESSceneObject |
| `removefromViewer(viewer: ESViewer)` | viewer: ESViewer | - | 将对象从指定视口中移除。<br>**参数**：viewer - 要移除对象的视口。 | ESSceneObject |
| `supportEditingModes()` | - | - | 获取当前对象支持的编辑模式<br>**返回**：支持的编辑模式数组 | ESVisualObject |
| `updateEditing()` | - | - | 更新编辑状态的方法，具体实现由子类完成 | ESVisualObject |

## 事件

| 事件 | 说明 | 来源 |
| --- | --- | --- |
| `activeViewerChanged` | - | ESSceneObject |
| `calcFlyInParamEvent` | 获取计算飞入参数事件 | ESVisualObject |
| `calcFlyToParamEvent` | 获取计算飞向参数事件 | ESVisualObject |
| `createdEvent` | 获取对象创建事件。 | ESSceneObject |
| `editingChanged` | 获取编辑状态改变事件 | ESVisualObject |
| `flushEvent` | 获取刷新对象事件。 | ESSceneObject |
| `flyInEvent` | 获取飞入事件 | ESVisualObject |
| `flyOverEvent` | 获取飞行结束事件 | ESVisualObject |
| `flyToDistanceChanged` | 获取飞向距离改变事件 | ESVisualObject |
| `flyToEvent` | 获取飞向事件 | ESVisualObject |
| `flyToFlyDurationChanged` | 获取飞向持续时间改变事件 | ESVisualObject |
| `flyToHDeltaChanged` | 获取飞向水平偏移量改变事件 | ESVisualObject |
| `flyToHeadingChanged` | 获取飞向航向改变事件 | ESVisualObject |
| `flyToPDeltaChanged` | 获取飞向垂直偏移量改变事件 | ESVisualObject |
| `flyToPitchChanged` | 获取飞向俯仰角改变事件 | ESVisualObject |
| `pickedEvent` | 获取拾取事件 | ESVisualObject |
| `readyEvent` | - | ESSceneObject |
| `reloadEvent` | - | ESSceneObject |
| `toDestroyFuncChanged` | 获取销毁函数改变事件。 | ESSceneObject |
| `updateFuncChanged` | 获取更新函数改变事件。 | ESSceneObject |

---
> 本文由 `generate-docs.mjs` 从源码自动生成，请勿手改。修改对象属性/方法后重跑脚本刷新。