# 多边形实体

 `PolygonsEntity` 是由 实体`Entity` 和 `PolygonsModule` 模块组合而成的新的实体。

 [PolygonsEntity](https://vjmap.com/map3d/api/classes/PolygonsEntity.html) =  [Entity](https://vjmap.com/map3d/api/classes/Entity.html) + [PolygonsModule](https://vjmap.com/map3d/api/classes/PolygonsModule.html) 

 ## 常用方法

 `PolygonsEntity` 是由 实体`Entity` 派生而来。具体 [Entity](https://vjmap.com/map3d/api/classes/Entity.html) 的所有属性和方法。同时也具有[PolygonsModule](https://vjmap.com/map3d/api/classes/PolygonsModule.html)  的相关方法。

|方法|描述|
|:---|:---|
|[getPolygons](https://vjmap.com/map3d/api/classes/PolygonsEntity.html#getPolygons)|获取多边形对象（**返回单个合并 `Mesh`，不是数组**——所有数据项三角化进同一几何体，勿取 `.length`）|
|[getVertexSymbol](https://vjmap.com/map3d/api/classes/PolygonsEntity.html#getVertexSymbol)|获取顶点对象|
|[isShowVertex](https://vjmap.com/map3d/api/classes/PolygonsEntity.html#isShowVertex)|是否显示顶点|
|[getVertexData](https://vjmap.com/map3d/api/classes/PolygonsEntity.html#getVertexData)|获取顶点数据|
|[setShowVertex](https://vjmap.com/map3d/api/classes/PolygonsEntity.html#setShowVertex)|设置是否显示顶点|
|[getBorderPolyline](https://vjmap.com/map3d/api/classes/PolygonsEntity.html#getBorderPolyline)|获取多边形边框对象|
|[updateStyle](https://vjmap.com/map3d/api/classes/PolygonsEntity.html#updateStyle)|**设置**样式，必传 `MeshBasicMaterialParameters`。⚠️ 内部逐键 `material[k] = v; material[k].needsUpdate = true`：值为**原始类型**（`opacity: 0.5`、`transparent: true`、数字/字符串 `color`）时严格模式下抛 `TypeError`（该键已写入、后续键被跳过）；只传对象值（如 `color: new THREE.Color(...)`），或直接改 `getPolygons().material` 再设 `needsUpdate = true`|
|[updateHightStyle](https://vjmap.com/map3d/api/classes/PolygonsEntity.html#updateHightStyle)|**设置**高亮样式，必传材质参数（官方拼写 `Hight`）。同样有原始值抛错问题；且它把参数记进了 `style`（覆盖普通样式记录）而非 `highlightStyle`|
|[setData](https://vjmap.com/map3d/api/classes/PolygonsEntity.html#setData)|修改数据|
|[getData](https://vjmap.com/map3d/api/classes/PolygonsEntity.html#getData)|获取数据|
|[getItemDataByFaceIndex](https://vjmap.com/map3d/api/classes/PolygonsEntity.html#getItemDataByFaceIndex)|通过faceIndex获取数据|
|[refreshHighlight](https://vjmap.com/map3d/api/classes/PolygonsEntity.html#refreshHighlight)|刷新高亮数据|   
|[setItemHighlight](https://vjmap.com/map3d/api/classes/PolygonsEntity.html#setItemHighlight)|设置某项高亮与否。⚠️ `setItemHighlight(id, false)` 只删记录、**不重绘**，需随后调 `refreshHighlight()`（或用 `clearHighlight()`）|  
|[isItemHighlight](https://vjmap.com/map3d/api/classes/PolygonsEntity.html#isItemHighlight)|获取某项高亮与否|  
|[clearHighlight](https://vjmap.com/map3d/api/classes/PolygonsEntity.html#clearHighlight)|清除所有高亮|  

## 使用示例

### 创建PolygonsEntity
```js
let svc = new vjmap3d.Service(env.serviceUrl, env.accessToken);
let app = new vjmap3d.App(svc, {
    container: "map", // 容器id
    scene: {
        gridHelper: { visible: true } // 是否显示坐标网格
    },
    camera: {  // 相机设置
        viewHelper: { enable: true, position: "leftBottom" } // 是否显示视角指示器
    }
})
let data = [];
data.push({
    coordinates: [[7, 0, 3],[-4, 0, -2],[-5, 0, 3]],
    color: "#00ff00"
})
data.push({
    // 当为多个多边形时，第一个多边形后面的多边形将掏空挖洞处理
    coordinates: [[[7, 0, -8],[-1, 2, -1],[-8, 1, -9],[17, 0, -18]],  [ [-2, 0, -9],[2, 0, -10],[2, 0, -7],[-1, 0, -6]]],
    color: "#00f"
})
let polygons = new vjmap3d.PolygonsEntity({ //PolygonsEntity
    data: data
})
polygons.addTo(app)
```

### 增加事件
```js
polygons.pointerEvents = true; // 允许事件交互
polygons.on("mouseover", e => {
    if (e?.intersection?.faceIndex !== undefined) {
        let itemData = polygons.getItemDataByFaceIndex(e?.intersection?.faceIndex);
        if (itemData && itemData.id) polygons.setItemHighlight(itemData.id, true)
    }
})
polygons.on("mouseout", e => {
    polygons.clearHighlight()
})
```

### 修改、新增、删除
调用 [setData](https://vjmap.com/map3d/api/classes/PolygonsEntity.html#setData) 来对数据进行增删改
```js
// 如新增一条
data.push({
    coordinates: [[7, 0, 3],[-4, 0, -2],[-5, 0, 3]],
    color: "#f00"
})
polygons.setData(data)
```

### 渐变色
如果`color`属性为数组时，并且颜色值不一样时，将绘制成渐变色

> ⚠️ **运行时实现有缺陷**：数组颜色并不按顶点序号一一对应——内部按三角面的角点收集颜色，却用"顶点序号×3"去取，颜色会错位；简单多边形（如下例三角形）除第一个顶点外大多取不到颜色而变成**白色**。需要可靠的逐顶点渐变时，请自建带 `color` 顶点属性的 `THREE.Mesh`（`vertexColors: true`）；`PolygonsEntity` 建议只用单色。

```js
// 如新增渐变色
 data.push({
    coordinates: [[10, 0, 0], [20, 0, 0], [15, 5, 5]],
    color: ["#f00", "#0ff", "#f0f"]
})
polygons.setData(data)
```

<mapFrame>
<pre>
 let svc = new vjmap3d.Service(env.serviceUrl, env.accessToken);
let app = new vjmap3d.App(svc, {
    container: "map", // 容器id
    scene: {
        gridHelper: { visible: true } // 是否显示坐标网格
    },
    stat: {
        show: true,
        left: "0"
    },
    camera: {  // 相机设置
        viewHelper: { enable: true, position: "leftBottom" } // 是否显示视角指示器
    }
})
let data = [];
data.push({
    coordinates: [[7, 0, 3],[-4, 0, -2],[-5, 0, 3]],
    color: "#f00"
})
data.push({
    // 当为多个多边形时，第一个多边形后面的多边形将掏空挖洞处理
    coordinates: [[[7, 0, -8],[-1, 2, -1],[-8, 1, -9],[17, 0, -18]],  [ [-2, 0, -9],[2, 0, -10],[2, 0, -7],[-1, 0, -6]]],
    // 当颜色为数组时用顶点渐变色（⚠️ 运行时颜色会错位，见上文"渐变色"说明）
    color: ["#0f0","#ff0","#0ff","#f00","#00f","#f0f","#777","#7ff"]
})
//
let polygons = new vjmap3d.PolygonsEntity({ //PolygonsEntity
    data: data,
    highlightStyle: {
        color: "#777" // 高亮时颜色
    }
})
polygons.addTo(app)
//
polygons.pointerEvents = true; // 允许事件交互
polygons.on("mouseover", e => {
    if (e?.intersection?.faceIndex !== undefined) {
        let itemData = polygons.getItemDataByFaceIndex(e?.intersection?.faceIndex);
        if (itemData && itemData.id) polygons.setItemHighlight(itemData.id, true)
    }
})
polygons.on("mouseout", e => {
    polygons.clearHighlight()
})
//
const ui = await app.getConfigPane({ title: "设置", style: { width: "250px", overflow: "hidden"}});
let cfg = [
    {
        type: 'checkbox',
        label: '显示顶点',
        getValue: () => polygons.isShowVertex(),
        setValue: v => {
            polygons.setShowVertex(v)
        }
    },
    {
        type: 'button',
        label: '增加一个多边形',
        value: ()=> {
            data.push({
                coordinates: [vjmap3d.randPoint3D(),vjmap3d.randPoint3D(),vjmap3d.randPoint3D()],
                color: vjmap3d.randColor()
            })
            polygons.setData(data)
        }
    },
    {
        type: 'button',
        label: '修改第一个多边形颜色',
        value: ()=> {
            if (data.length > 0) {
                data[0].color = vjmap3d.randColor()
            }
            polygons.setData(data)
        }
    },
    {
        type: 'button',
        label: '删除第一个多边形',
        value: ()=> {
            if (data.length == 0) {
                return
            }
            data.splice(0, 1)
            polygons.setData(data)
        }
    }
]
cfg.forEach(c => ui.appendChild(c));
</pre>
</mapFrame>