文本实体

大约 5 分钟

文本实体

WebCAD 支持单行文本和多行文本两种文本实体。

TextEnt 单行文本

import { TextEnt, Point2D } from 'vjcad';

const text = new TextEnt(
  new Point2D(50, 50),    // 插入点
  '示例文字',              // 文本内容
  10,                      // 文字高度
  0,                       // 旋转角度
  'left',                  // 对齐方式
  'Arial',                 // 字体
  256                      // 颜色
);
text.setDefaults();

// 修改属性
text.text = '新文字';  // 或 text.textString = '新文字'
text.height = 15;
text.rotation = Math.PI / 6;  // 30度

TextEnt 属性

属性	类型	说明
`insertionPoint`	Point2D	插入点
`text`	string	文本内容（`textString` 的别名）
`textString`	string	文本内容
`height`	number	文字高度
`rotation`	number	旋转角度（弧度）
`textAlignment`	string	对齐方式
`styleName`	string	文字样式名称
`textStyle`	TextStyle	文字样式对象（只读，设置 styleName 后自动获取）

对齐方式

值	说明
`left`	左对齐
`center`	居中
`right`	右对齐
`aligned`	调整
`middle`	中间
`fit`	适合

MTextEnt 多行文本

import { MTextEnt, Point2D } from 'vjcad';

const mtext = new MTextEnt(
  new Point2D(50, 50),    // 插入点
  '多行文本内容',
  10,                      // 文字高度
  0,                       // 旋转角度
  1,                       // 对齐方式 (1=左上)
  1.0,                     // 行距因子
  'Arial',                 // 字体
  256                      // 颜色
);
mtext.maxWidth = 200;      // 最大宽度
mtext.setDefaults();

MTextEnt 属性

属性	类型	说明
`insertionPoint`	Point2D	插入点
`text`	string	文本内容（`textString` 的别名）
`textString`	string	文本内容
`contents`	string	富文本内容（含格式代码）
`height`	number	文字高度
`rotation`	number	旋转角度
`maxWidth`	number	最大宽度
`textAttachment`	number	对齐方式
`lineSpacingFactor`	number	行距因子
`styleName`	string	文字样式名称
`textStyle`	TextStyle	文字样式对象（只读，设置 styleName 后自动获取）

对齐方式

值	说明
1	左上
2	中上
3	右上
4	左中
5	正中
6	右中
7	左下
8	中下
9	右下

富文本格式

MText 支持富文本格式：

// 富文本格式
mtext.contents = '{\\fArial|b1;粗体文字}\\P普通文字';

常用格式代码：

代码	说明
`\\P`	换行
`\\f字体名;`	切换字体
`\\f字体名\|b1;`	粗体
`\\f字体名\|i1;`	斜体
`\\H高度;`	设置高度
`\\C颜色;`	设置颜色
`\\U+XXXX`	Unicode字符

文字样式

文字样式定义了文本的字体和默认属性。

TextStyle 属性

属性	类型	说明
`name`	string	样式名称
`fontFileName`	string	字体文件名（对应 MainView fonts 配置中的 name）
`bigFontFileName`	string	大字体文件名（用于 SHX 处理中文）
`fixedHeight`	number	固定高度（0 表示不固定）
`widthFactor`	number	宽度因子
`obliqueAngle`	number	倾斜角度（度）
`isVertical`	boolean	是否垂直
`isBackwards`	boolean	是否反向
`isUpsideDown`	boolean	是否倒置

使用文字样式

有两种方式使用字体和文字样式：

方式一：直接使用字体名（推荐，简单快捷）

MainView 会自动为配置的字体创建同名的 TextStyle，因此可以直接使用字体名作为 styleName，无需手动创建 TextStyle。

import { Engine, TextEnt, MTextEnt } from 'vjcad';

// 单行文字 - 直接使用字体名
const text = new TextEnt();
text.insertionPoint = [0, 100];
text.text = "使用楷体字体";
text.height = 10;
text.styleName = "simkai";  // 直接使用字体名，无需手动创建 TextStyle
text.setDefaults();

// 多行文字 - 使用 SHX 字体
const mtext = new MTextEnt();
mtext.insertionPoint = [0, 50];
mtext.text = "SHX Font Text";
mtext.height = 8;
mtext.styleName = "_default";  // 直接使用字体名
mtext.setDefaults();

Engine.addEntities([text, mtext]);

自动创建的 TextStyle

MainView 在字体加载完成后，会自动为每个配置的字体创建同名的 TextStyle。例如：

配置 { name: "simkai", ... } 的字体，会自动创建名为 "simkai" 的 TextStyle
配置 { name: "_default", ... } 的字体，会自动创建名为 "_default" 的 TextStyle

方式二：手动创建自定义 TextStyle（适合高级设置）

当需要自定义样式属性（如宽度因子 widthFactor、倾斜角度 obliqueAngle）时，手动创建 TextStyle。

import { Engine, TextStyle, TextEnt, MTextEnt } from 'vjcad';

// 创建自定义文字样式
const kaitiStyle = new TextStyle();
kaitiStyle.name = "楷体样式";           // 自定义样式名称
kaitiStyle.fontFileName = "simkai";     // 对应 MainView fonts 配置中的 name
kaitiStyle.widthFactor = 1.5;           // 宽度因子 1.5
kaitiStyle.obliqueAngle = 15;           // 倾斜 15 度

// 添加到文档
Engine.currentDoc.textStyles.add(kaitiStyle);

// 单行文字使用自定义样式
const text = new TextEnt();
text.insertionPoint = [0, 100];
text.text = "使用楷体样式";
text.height = 10;
text.styleName = "楷体样式";  // 使用自定义样式名称
text.setDefaults();

// 多行文字使用自定义样式
const mtext = new MTextEnt();
mtext.insertionPoint = [0, 50];
mtext.text = "多行文字\n使用楷体样式";
mtext.height = 8;
mtext.styleName = "楷体样式";  // 使用自定义样式名称
mtext.setDefaults();

Engine.addEntities([text, mtext]);

字体配置

字体需要在 MainView 初始化时配置加载：

import { MainView, initCadContainer } from 'vjcad';

const cadView = new MainView({
  appname: "唯杰CAD",
  version: "v1.0.0",
  serviceUrl: env.serviceUrl,
  accessToken: env.accessToken,
  fonts: [
    // TrueType 字体（woff/ttf/otf）
    { 
      path: "./fonts/simkai.woff",
      name: "simkai",              // 字体名称（同时也是自动创建的 TextStyle 名称）
      kind: "woff"
    },
    // SHX 字体（AutoCAD 形字体）
    { 
      path: "./fonts/_default.shx",
      name: "_default",            // 字体名称（同时也是自动创建的 TextStyle 名称）
      kind: "shx"
    }
  ]
});

initCadContainer("map", cadView);
await cadView.onLoad();

// 字体加载后，可以直接使用字体名作为 styleName
const text = new TextEnt();
text.styleName = "simkai";     // 使用 TrueType 字体
text.styleName = "_default";   // 使用 SHX 字体

字体类型说明

TrueType 字体（woff/ttf/otf）：适合中文显示，字形美观
SHX 字体：AutoCAD 兼容，渲染效率高，适合工程图纸

注意

字体配置中的 name 属性非常重要：

它是字体的唯一标识符
MainView 会自动为每个字体创建同名的 TextStyle
在文本实体中可以直接将 name 作为 styleName 使用

获取已有样式

const doc = Engine.currentDoc;
const textStyles = doc.textStyles;

// 获取文字样式
const style = textStyles.itemByName('Standard');

// 应用文字样式到文字实体
text.styleName = 'Standard';

下一步

块和插入 - Block、Insert
自定义实体 - 创建自定义实体
图层管理 - 图层操作