mapdata-query

本文回答：mapcadLayer.queryMapEntities / queryMapEntitiesByLayer —— 一条 SQL 从后端拉回批量 DWG 实体。

一、为什么要用它

直接用 svc.conditionQueryFeature 有三个坑：

1. 类型名是数字 ID：后端表里 name='13' 代表 AcDbText，不是字符串。
2. 分批请求贵：一次 HTTP + SQL 空间查询有几十 ms 开销；N 次查询 = N × 开销。
3. 结果需要再处理：坐标系、缺省字段处理。

queryMapEntities 封装了这三点：

const fc = await mapcadLayer.queryMapEntities({
  entTypes: ['AcDbText', 'AcDbMText'],     // 自动翻译成 name='13' or name='12'
  condition: "text like '%标题%'"          // 再 AND 拼 where
});

返回标准 GeoJSON.FeatureCollection。

二、queryMapEntities 选项

三、常用 entTypes 翻译表

翻译过程 SDK 会调 svc.getConstData().entTypeIdMap 并按 service 缓存。

四、按图层查询

const fc = await mapcadLayer.queryMapEntitiesByLayer(
  '道路',                                   // 图层名（不是索引）
  ['AcDbLine', 'AcDbPolyline', 'AcDb2dPolyline'],
  { limit: 20000 }
);
// 内部 where: layerindex=N and (name='1' or name='2' or name='3')

entType 传 undefined → 只按图层过滤。

⚠️ 图层名 vs 索引坑（实采 2026-09-20）：layerName 是在 svc.getMapLayers() 里按 l.name 匹配的图层名；查询结果里 properties.layerindex 是数字索引（如 12），把这个索引串当 layerName 传回去会查不到图层并静默返回空 FC（不报错）。实体属性里的图层名要用 getMapLayers()[layerindex].name 反查。

五、combineWhere 拼多条件

const where = vjmapext.combineWhere(
  "text like '%A%'",
  "text like '%B%'",
  ""                         // 空串自动忽略
);
// → (text like '%A%') or (text like '%B%')

六、buildEntTypeCondition 手动拿类型片段

自己拼 SQL：

const typeFrag = await vjmapext.buildEntTypeCondition(map, ['AcDbText','AcDbMText']);
// → "name='13' or name='12'"

const fc = await mapcadLayer.queryMapEntities({
  condition: `(${typeFrag}) and color=-65536`
});

七、分页

单次 limit 最大建议 50000；大数据分页：

async function fetchAll(opts, limit = 10000) {
  const all = [];
  for (let begin = 0; ; begin += limit) {      // 游标按 limit 步进，不能按 features.length
    const fc = await mapcadLayer.queryMapEntities({ ...opts, limit, beginpos: begin });
    all.push(...fc.features);
    if (fc.eof || begin + limit >= (fc.recordCount ?? 0)) break;   // 以 eof / recordCount 判结束
  }
  return all;
}

⚠️ 无法提取几何（既无 geom 也无 location）的记录会在组装 FeatureCollection 时被丢弃，所以 features.length 可能小于本页实际行数——用它判断"最后一页"会提前退出，用它推进 beginpos 会重复取数。

八、返回结构

{
  type: 'FeatureCollection',
  features: Feature[],
  recordCount?: number,      // 总数
  beginpos?: number,
  eof?: boolean
}

每个 Feature：

{
  type: 'Feature',
  id: string | number,              // objectid
  properties: {
    name: string,                   // 'AcDbText' 等可读名
    objectid: string,
    layerindex: number,
    color: number,                  // int32，可能负数
    location?: string,              // "x,y" 或 "x,y;x,y"
    points?: string,
    text?: string, contents?: string,
    height?: number, rotate?: number,
    ...
  },
  geometry: Geometry
}

九、典型场景

1 找出所有 "总平面图" 文字

const fc = await mapcadLayer.queryMapEntities({
  entTypes: ['AcDbText', 'AcDbMText'],
  condition: vjmapext.combineWhere(
    "text like '%总平面图%'",
    "contents like '%总平面图%'"
  )
});

2 取视口内某图层所有线

const bounds = map.getGeoBounds();
const fc = await mapcadLayer.queryMapEntitiesByLayer('wall', ['AcDbLine','AcDbPolyline'], {
  bounds: [bounds.min.x, bounds.min.y, bounds.max.x, bounds.max.y],
  isContains: false
});

3 仅要属性不要几何（速度提升）

const fc = await mapcadLayer.queryMapEntities({
  entTypes: ['AcDbText'],
  fields: 'objectid,text,location,color,layerindex',
  includegeom: false
});

十、常见坑

1. entTypes 直接传 'AcDbText'：queryMapEntities 的 entTypes 必须传数组 ['AcDbText']——单字符串会被逐字符当类型名查表，全部不命中，静默返回空 FeatureCollection。只有 queryMapEntitiesByLayer 的 entType 形参容忍单字符串（内部自动归一为数组）。
2. bounds 单位：是 CAD 坐标，不是经纬度；要 map.fromLngLat 转。
3. limit 过大 + includegeom：返回数据 MB 级，网络和 parse 都慢。
4. name='AcDbText' 永远命中 0 条：后端 name 是数字 ID，不是可读名。
5. 多个 queryMapEntities 并发：OK，但服务端有 rate limit；超 30 req/s 可能被限流。
6. fields 必须含 geojson 才出 Feature：行转 Feature 时 SDK 只认 geom/points/location/center/insertionPoint/origin 等几何字段，而 geom 本身是 _processQueryResult 从后端 geojson 字段合成的——fields:"objectid" 这类纯属性清单会让 recordCount=554 但 features 为 0（行全被丢，不报错）。fields 里写 geojson 而非 geom。

相关

• 后续接管 → features-to-entities
• 隐藏原图 → mapdata-hider
• SQL 表达式细节 → backend/query-sql