> **本文回答**：扩展数据通过 `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` 写回。

## 一、写

```js
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`。

## 二、读

```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`。

## 三、改 / 清

```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`。

## 四、原始格式（高级）

```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 的实体

```js
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`