xdata

本文回答：扩展数据通过 entity.setExtData(appName, dataObj) 写、entity.extData 读、entity.hasExtData() 判断、entity.clearExtData() 清；底层格式 entity.xdataRaw = { '1001': appName, '1000': JSON字符串 }。导出 DWG 后重新加载数据仍保留，是给业务实体绑业务字段的标准做法。每个实体只存一组 appName + 一个 JSON：setExtData 是整体覆盖（换 appName 会把旧 appName 的数据一起冲掉），多个业务模块请共用一个 appName、在 JSON 里分字段；extData 每次读都是 JSON.parse 出来的新对象，改它不影响实体，必须再 setExtData 写回。

一、写

const sensor = new LineEnt([0, 0], [100, 0]);
sensor.setDefaults();
sensor.setExtData('SENSOR_DATA', {
  name:       '温度传感器',
  value:      25.5,
  unit:       '℃',
  isActive:   true,
  lastUpdate: '2026-01-29'
});
Engine.addEntities(sensor);

MCP 参考：vjcad/example/property/07xdata.js。

二、读

sensor.hasExtData();              // true
sensor.extDataAppName;            // 'SENSOR_DATA'
const data = sensor.extData;      // 已自动 JSON.parse
console.log(data.value);          // 25.5

MCP 参考：vjcad/example/property/07xdata.js。

三、改 / 清

// 修改：基于现有数据（extData 是解析出的副本，改完必须写回）
const cur = pipe.extData;
cur.flow = 180.5;
cur.lastCheck = '2026-01-28';
pipe.setExtData('PIPE_ATTR', cur);

// 整段替换
sensor.setExtData('SENSOR_DATA', { value: 30.2, alarm: true });

// 清除
sensor.clearExtData();
sensor.hasExtData();              // false

MCP 参考：vjcad/example/property/07xdata.js。

四、原始格式（高级）

const raw = sensor.xdataRaw;
// {
//   '1001': 'SENSOR_DATA',     // AppName
//   '1000': '{"name":"温度传感器", ...}'   // JSON 字符串
// }

MCP 参考：vjcad/example/property/07xdata.js。

AutoCAD 标准 XData 用 group code 1000~1071。vjcad 把 1001=AppName / 1000=JSON 这一对最常用的字段封装成了 setExtData / extData。

五、批量查询带 XData 的实体

const allEnts = Engine.getEntities();
const withXdata = allEnts.filter(e => e.hasExtData?.());

const byAppName = {};
withXdata.forEach(e => {
  const name = e.extDataAppName;
  (byAppName[name] = byAppName[name] || []).push(e);
});

MCP 参考：vjcad/example/property/07xdata.js。

六、属性面板（手动查看）

UI 选中实体后，右侧属性面板会显示"扩展数据"行；点击右边按钮可打开详细编辑对话框。详见 vjcad/example/property/07xdata.js 的"提示"部分。

反例

• 把整个 DOM Element / 函数 / 循环引用塞进 setExtData 的 data：会 JSON.stringify 失败 / 数据不完整。
• 用同一个 appName 但写入完全不同的 schema：读取时容易破坏现有逻辑。建议给每个 appName 一个稳定的字段集。
• 试图用 entity.xdata = {...} 直接赋值：EntityBase 没有 xdata 属性（存储字段是私有 _xdata），这样只会挂一个无关的普通字段，不显示、不保存、不导出。用 setExtData(name, data)，或底层 entity.xdataRaw = { '1001': appName, '1000': jsonStr }。
• cur = e.extData; cur.x = 1; 后忘了 setExtData 写回：extData 每次返回新解析的对象，修改丢失。
• 同一实体先 setExtData('A', …) 再 setExtData('B', …)：A 的数据被整体覆盖，不是追加第二个 appName。

参考（官方文档 MCP）

• 文档：vjcad/doc/property/index.md
• 示例：vjcad/example/property/07xdata.js