> **本文回答**：批量处理主题总览 —— GeoJSON 批量、实体批量、mapdata 联动、样式快路径。

# 批量主题 (vjmapext + vjmap)

处理大量数据的几种路径：

| 路径 | 适用 | 延迟 | 入口 |
|---|---|---|---|
| GeoJSON `source.setData` 批量 | 纯展示（线 / 点 / 面） | 瞬时 | [geojson-bulk](../../../vjmap/references/batch/geojson-bulk.md) |
| 多实体 `addEntity` 循环 + 合并 dirty | CAD 实体，需交互 / 标注 | 帧内 | [entity-bulk-add](entity-bulk-add.md) |
| `queryMapEntities` + `featuresToEntities` | 从 DWG 原图拉实体并接管 | 一次 SQL | [mapdata-query](mapdata-query.md) |
| `MapEntityHider` 样式隐藏 | 避免底图双重显示 | 栅格重拉瓦片 / 矢量瞬时 | [mapdata-hider](mapdata-hider.md) |
| 仅样式批量变更 | 上万实体只是改颜色 / 透明度 | 单帧 | [bulk-style-update](bulk-style-update.md) |

## 子项索引

| 文件 | 主题 |
|---|---|
| [geojson-bulk](../../../vjmap/references/batch/geojson-bulk.md) | `source.setData(FeatureCollection)` 批量绘制 |
| [entity-bulk-add](entity-bulk-add.md) | 批量 `addEntity` + dirty 合并 |
| [mapdata-query](mapdata-query.md) | `queryMapEntities` / `queryMapEntitiesByLayer` 一次 SQL 拉大量 |
| [features-to-entities](features-to-entities.md) | `featuresToEntities(fc)` 转实体 + 属性映射 |
| [mapdata-hider](mapdata-hider.md) | `createMapDataHider` 栅格 / 矢量双模式 |
| [bulk-style-update](bulk-style-update.md) | 仅样式批量（styleChanged 快路径） |

## 关键决策树

```
想批量画几十万个简单图形（散点 / 简单线）？
    → 用 GeoJSON 图层（primitive/geojson-source）
    → 见 geojson-bulk

想从 DWG 原图拉出符合条件的实体并接管？
    → queryMapEntities + featuresToEntities
    → + MapEntityHider 隐藏原图
    → 见 mapdata-query / features-to-entities / mapdata-hider

想一次性修改上万个已有实体的颜色？
    → styleChanged 快路径
    → 见 bulk-style-update

想手写创建大量 CAD 实体？
    → 批量 addEntity（渲染自动按帧合并）+ 可选 undoManager 事务
    → 见 entity-bulk-add
```

## 最小代码（DWG 实体接管 1 分钟能跑）

```js
// 1. 查出所有"总平面图"文字
const fc = await mapcadLayer.queryMapEntities({
  entTypes: ['AcDbText', 'AcDbMText'],
  condition: "text like '%总平面图%' or contents like '%总平面图%'"
});

// 2. 隐藏原图
const hider = mapcadLayer.createMapDataHider();
await hider.hide(fc.features);

// 3. 转 SDK 实体
const ents = mapcadLayer.featuresToEntities(fc);
ents.forEach(e => {
  e.color = 0xff0000;
  mapcadLayer.addEntity(e);
});
```

## 主题级 Top 3 陷阱

1. **循环里对每个新实体都手动标脏** → `addEntity` 已自动标脏且重绘按帧合并，画蛇添足。
2. **只传 `objectid` 给 `hider.hide()`** → 矢量底图用 feature.id 过滤，传字符串无效；**传 Feature 对象** 才能兼容两种底图。
3. **`featuresToEntities` 忘传 blocks** → `AcDbBlockReference` 找不到定义会回退到几何展开，失去块语义；要么先 `mapcadLayer.blocks.add(blockDef)`，要么显式传 `opts.blocks`。

## 相关主题

- 实体生命周期 → [entity/lifecycle](../entity/lifecycle.md)
- GeoJSON 源管理 → [primitive/geojson-source](../../../vjmap/references/primitive/geojson-source.md)
- 性能细节 → [perf/batch-rendering](../perf/batch-rendering.md)
- 后台查询 API → [backend/query-features](../../../vjmap/references/backend/query-features.md)