唯杰地图 logo唯杰地图
VJMAP
EN

text

vjmapext/references/entity/text.md 5.5 KB122 行
原文

本文回答：TextEnt 单行文字 / MTextEnt 多行文字 —— 高度、对齐、旋转、样式。

一、TextEnt 单行文字

创建（位置参数，不是 options 对象）

// 构造签名：new TextEnt(insertionPoint?, textString?, height?)
const t = new vjmapext.TextEnt([100, 100], 'Hello vjmap', 20);
t.rotation = 0;                    // 度
t.color = 0xff0000;
mapcadLayer.addEntity(t);

属性（d.ts 真实成员）

属性 类型 说明
insertionPoint Point2D 插入点（注意：不叫 position）
textString string 文字内容（注意：不叫 text）
height number 高度（CAD 单位）
rotation number 旋转，度
widthFactor number 宽度因子，默认 1（⚠️ 1.0.1 渲染和 toJSON 都不使用，改了画面不变、存盘也丢）
font string 字体名（需预加载；不叫 fontName）
textAlignment TextAlignment 对齐枚举，见下
opacity number 不透明度
tag / prompt string? 属性定义标签/提示（ATTDEF 用）
invisible / constant / preset boolean? 属性定义标志位

对齐：textAlignment 用枚举 TextAlignmentEnum（1–9）

t.textAlignment = vjmapext.TextAlignmentEnum.MidCenter;  // 中心对齐到插入点
t.changed();                // 对齐改变字形排布（几何），styleChanged() 不生效
值 1 2 3 4 5 6 7 8 9
含义 Left Center Right MidLeft MidCenter MidRight TopLeft TopCenter TopRight

查询

t.boundingBox();              // 外接盒 BBox
t.height;                     // 高度

二、MTextEnt 多行文字

构造同样是位置参数；换行宽度属性叫 maxWidth（≤0 不换行），不是 width：

const mt = new vjmapext.MTextEnt([0, 0], '第一行\n第二行', 18);  // 存储层用真实 \n 换行
mt.maxWidth = 300;               // 换行宽度，0 = 不换行
mt.lineSpacingFactor = 1.6;      // 行距系数，默认 1.6
mapcadLayer.addEntity(mt);

⚠️ 换行与"富文本"的真实支持度

MTextEnt 渲染时只按真实换行符 \n 分行（再按 maxWidth 自动换行），不解析任何内联 MText 格式码。直接把 \\P、{\\C1;…}、{\\L…\\l}、{\\S…/…;}、\\U+XXXX 写进 textString，会按字面字符画出来（屏幕上真的显示 "\P"、"{\C1;…}"）。

\\P 只在交互输入路径有效：MTEXT 命令输入框、属性面板的文字编辑会把 \\P/\\n 转成 \n 再存入 textString。程序化赋值请直接用 '\n'。

逐字符变色/下划线/堆叠等排版能力当前未实现；要局部样式只能拆多个 TextEnt。

段落对齐：attachmentPoint 用枚举 MTextAttachmentEnum（1–9）

mt.attachmentPoint = vjmapext.MTextAttachmentEnum.MidCenter;  // =5

编号布局与 TextAlignmentEnum 相同（3×3 九宫格，从下往上数）：MText 是 1=BottomLeft … 3=BottomRight, 4=MidLeft … 6=MidRight, 7=TopLeft … 9=TopRight。区别只在第一行的含义和名字：TEXT 的 1–3（Left/Center/Right）对齐到基线，MTEXT 的 1–3（BottomLeft/…）对齐到文字块底边。建议只用枚举名。

三、字体加载

vjmapext 默认启用 opentype 子集渲染，字体需要预先加载：

await vjmapext.loadOpentypeFont('/fonts/simsun.ttf', '宋体');
await vjmapext.loadOpentypeFont('/fonts/arial.ttf', 'Arial');
// 或 mapcadLayer.loadFont(url, fontName?)

未加载的字体自动回退到默认字体。相关工具函数：getLoadedFontNames()、measureTextWidth(text, size, fontName)、truncateTextToWidth(...)、initDefaultFont()。详见 font-text。

四、动态更新

t.textString = '动态更新 ' + Date.now();
t.changed();                  // 内容变了用 changed
t.color = 0x00ff00;
t.styleChanged();             // 只改样式

五、查找文字

mapcadLayer.getEntities()
  .filter(e => e.type === 'TEXT' && e.textString.includes('关键字'))
  .forEach(e => { e.color = 0xffff00; e.styleChanged(); });

六、场景速查

场景 推荐
单行标签 / 编号 TextEnt
带换行的注释 MTextEnt
海量标签（图面文字） symbol/text-symbol
可交互的 HTML 文字 marker

七、常见坑

  1. 构造是位置参数：new TextEnt(pos, str, height)——传 options 对象不报错，但 insertionPoint 变成 Point2D(0,0)（toPoint2D 取 p[0]/p[1]=undefined 被构造默认值兜底）、textString 为空的实体。
  2. 属性名：textString/insertionPoint/font，不是 text/position/fontName。
  3. rotation 单位：度，不是弧度。
  4. 两个对齐枚举名字不同、布局相同：都是 1–3 下行、4–6 中行、7–9 上行；但 TextAlignmentEnum 1=Left（基线），MTextAttachmentEnum 1=BottomLeft（块底边）——用枚举名别用数字字面量。
  5. MText 只认 \n：textString 里写 '\\P' 不会换行（画成字面 "\P"）；交互输入框才做 \\P→\n 转换。程序化构造用 '第一行\n第二行'。
  6. 字体未加载：画面出现方块或默认字体；确认 loadOpentypeFont 完成再 add。
  7. height 过小：屏幕上看不见；height 是 CAD 单位，会随 zoom 变大变小。