唯杰地图 logo唯杰地图
VJMAP
EN

style-props

vjmapext/references/entity/style-props.md 5.8 KB156 行
原文

本文回答：所有实体公共样式属性 —— color / lineWidth / fillColor / fillOpacity / lineType / ltScale / layerId / visible / 显示级别。

一、样式属性表（继承自 EntityBase）

属性 类型 默认 说明
color number 0xFFFFFF 轮廓 / 文字颜色（0xRRGGBB），默认白色
layerId string '0' 所属图层（字段是 layerId 不是 layer）
lineType string 'CONTINUOUS' 线型名：DASHED / DASHDOT / DOT / CONTINUOUS 等
ltScale number 1 线型缩放因子
ltOffset number 0 线型偏移
lineWidth number 0 线宽（像素），默认 0=最细
visible boolean true 可见性
dynamic boolean false 动画实体标记
editable boolean true 是否允许交互编辑
selectableInReadonly boolean false 浏览模式下可否选中
minDisplayLevel / maxDisplayLevel number 0 / 24 显示 zoom 范围（不是 -1）
effectColor / effectWidth / effectOpacity / effectBlur number -1 / 6 / 0.4 / 4 发光特效（effectColor=-1 关闭）
customProperties object {} 自定义属性包装 {key:{type,value}}

fillColor/fillOpacity/borderOpacity/rotation 不在 EntityBase 上——它们是 CircleEnt / PolylineEnt / HatchEnt / TextEnt 等具体实体各自的字段（如 fillColor=-1 表示"跟随 color 填充"、TextEnt rotation 存度）。

二、颜色

颜色是 0xRRGGBB 十六进制整数，不是 CSS 字符串：

entity.color = 0xff4444;     // 红
entity.color = 0x44ff44;     // 绿
entity.color = 0x0088ff;     // 蓝

程序化从 CSS 字符串转整数：

function cssToHex(css) {
  const m = css.replace('#', '');
  return parseInt(m.length === 3
    ? m.split('').map(c => c + c).join('')
    : m, 16);
}
cssToHex('#ff4488');   // 16729736 == 0xff4488

三、填充

声明了 fillColor/fillOpacity/borderOpacity 的实体：CircleEnt / 闭合 PolylineEnt（云线即带 bulge 的闭合多段线）/ HatchEnt / EllipseEnt / SplineEnt；ArcEnt 三字段均无。

const circle = new CircleEnt([0, 0], 100);
circle.color = 0x4488ff;           // 边框
circle.fillColor = 0x4488ff;       // 填充
circle.fillOpacity = 0.4;
mapcadLayer.addEntity(circle);

组合：

circle.fillOpacity = 0;            // 空心圆
circle.borderOpacity = 0;          // 实心圆（仅填充）
circle.fillOpacity = 0.5;          // 填充 + 边框

四、线宽

单位是屏幕像素，不随 zoom 变化。要做随 zoom 变粗的效果，得手动监听 zoom 事件调 lineWidth。

entity.lineWidth = 2;
entity.styleChanged();

五、线型

内置线型：DASHED / DASHDOT / DOT / CENTER / HIDDEN 等（具体以 SDK 为准）。

entity.lineType = 'DASHED';
entity.ltScale = 20;         // 实虚节奏放大 20 倍
entity.changed();            // 线型要重新 tessellate，styleChanged() 不生效

ltScale 越大，虚线段越长。CAD 单位，通常 10–50 之间看得最自然。

自定义线型：见 map-style/layer-styles（底座）或 linetype/custom（mapext）。

六、图层

entity.layerId = '标注层';
entity.changed();            // layerId 不在 styleChanged 快路径

批量改：

mapcadLayer.getEntities()
  .filter(e => e.type === 'LINE')
  .forEach(e => { e.layerId = '线层'; e.changed(); });

按图层隐藏（不动 entity.visible）：

const hidden = new Set(['辅助', '标注']);
mapcadLayer.setHiddenLayerChecker(layerId => hidden.has(layerId));   // 传 null 取消

setHiddenLayerChecker 会同步给渲染管线、刷新跟随实体显隐的 FX 绑定并全量重绘——别直接调 renderPipeline.setHiddenLayerChecker（FX 不同步）。注意 createUI() 的图层面板也用它装自己的判定函数（面板每次变化会重装），自定义与内置面板二选一。

图层可见性、颜色叠加等见 layer/manage。

七、可见性 / 显示级别

visible

entity.visible = false;
entity.changed();            // visible 不在 styleChanged 快路径

minDisplayLevel / maxDisplayLevel

按 zoom 级别过滤（仅浏览模式）：

entity.minDisplayLevel = 3;
entity.maxDisplayLevel = 8;

超出范围 → 自动隐藏（但不影响选中）。

八、透明度组合

fillOpacity borderOpacity 效果
> 0 > 0 填充 + 描边
0 > 0 空心（仅描边）
> 0 0 实心（仅填充）
0 0 完全不可见

九、性能敏感属性

  • 改 color / lineWidth / effectColor / effectWidth / effectOpacity / effectBlur → styleChanged() 快路径，低代价（例外：lineWidth 改回 0 要 changed()——快路径只在 >0 时写 line_width、从不删旧值）
  • 改 fillColor / fillOpacity / borderOpacity / visible / layerId / lineType / ltScale → 必须 changed()（不在 updateFeatureStyleProps 回写清单）
  • 改任何几何 / rotation → changed()（重算 tessellation + 空间索引）

十、常见坑

  1. 用 CSS 字符串赋值 → 报错 / 颜色不对。永远用 0xRRGGBB。
  2. 忘记 styleChanged() → 改了不显示。
  3. 以为 fillColor=-1 是不填充 → -1 的语义是"跟随 color 填充"（d.ts 注释："fill follows the inherited color"）；不想要填充应把 fillOpacity 设为 0。
  4. 想要"随 zoom 变粗的线" → lineWidth 本身不响应 zoom，需要自己监听 map.on('zoom', ...)。
  5. 用了 CAD 单位的 lineWidth → 像素单位，数值大于 5 就会非常粗。