三维元素手册
2026年8月13日大约 14 分钟
三维元素手册（41 种）
所有元素放在 scene-3d 的 pieces 里，按 { uid, type, options } 描述。本页是速查总览：按五个分类列出全部元素与高频关键选项（括号内为默认值）；每个元素的在线预览、全量属性表与可复制 JSON 在对应分类页里。
完整且永不过时的全量选项字典见 widget-schema.generated.json（由源码 defineOptions() 自动导出），编辑器属性面板与 AI 的 page_get_schemas 均以其为准。
分类页带在线预览
每个元素在分类页里都有一份在线预览，用的就是 data/三维/元素/ 里那个逐组件示例工程的场景（未裁剪），跑 vjmap 官方公开服务，联网即可出图。三维每个场景独占一个 GPU 上下文（引擎侧同页实例配额为 4），故预览按需加载——点「加载在线预览」才建场景，同页只保留一个活跃预览。
通用约定：
- 坐标为世界坐标（场景单位），
position多为[x, y, z]；角度用度（°）。 - 多数几何类元素支持
glow（辉光，需场景内有「后期效果」且启用 bloom）与cast-shadow/receive-shadow。 - 「测点驱动」三件套见测点数据驱动：
data-key+state-rules（状态色）+blink-values（告警闪烁），流动类另有flow-rules。
场景与环境
逐元素预览与全量属性见 场景与环境。
| 元素 | 名称 | 关键选项 |
|---|---|---|
scene3d-scene | 场景设置（单例） | engine(webgpu/webgl)；背景 bg-mode(color/transparent/panorama/sky) + sky-preset(night 星空/dusk 晚霞/dawn 晨曦/nebula 极光，零素材) + bg-image(jpg/png/hdr) + bg-blur；环境反射 env-mode(room 推荐/background/none) + env-intensity；网格 grid/grid-infinite/axes；雾 fog + fog-mode(linear 近远距离 / exp 指数大气感) + fog-color/fog-near/fog-far/fog-density；剖切分析 clip-enable + clip-axis/clip-position/clip-invert（运行层用 scene3dClip 动作控制）；服务 service-url/service-token（留空级联） |
scene3d-camera | 相机（单例） | 视角 position/target/fov + 「保存当前视角」按钮；入场飞入 entry-fly + entry-duration(2.5s)/entry-scale(2.2×)；巡航 cruise-mode(off/orbit 环绕/tour 书签巡航/path 路径漫游) + 各自参数；第一人称行走 walk-enable（播放态 W/S/A/D + Q/E 转向 + R/F 升降 + Shift 加速）；小地图 minimap + minimap-size/minimap-view/minimap-rotate(随航向旋转)；操控限制 min/max-distance、min/max-polar、allow-pan、dolly/truck-speed、smooth-time |
scene3d-view | 视角书签 | position/target；书签巡航与 scene3dFlyTo 动作 view-uid 的目标；编辑器有「保存当前视角 / 飞到此视角」按钮 |
scene3d-tilemap | 瓦片地图（底图） | tile-preset(osm/gaode-vec/gaode-img/tianditu-img/tianditu-vec(需 tile-token)/cad CAD 图纸瓦片(cad-mapid+cad-dark)/custom(tile-url+anno-url))；root-tile(z,x,y，0,0,0=世界地图，如北京 10,843,388) + base-scale(100)；CAD 叠加层 cad-overlay-mapid+cad-overlay-epsg；裁剪区域 clip-polygon(每行一顶点，web=经纬度/cad=图纸坐标，≥3 点) + clip-outer(反选挖洞)；样式滤镜 style-filter(dark 科技深蓝/none/gray/mono)；地形 terrain-url(terrain-rgb) + height-scale。底图不参与射线拾取 |
scene3d-effects | 后期效果（建议单份） | 辉光 bloom + bloom-intensity(2)/bloom-threshold(0.1)——各元素勾 glow 才参与；交互描边 outline-hover(悬停)/outline-click(点击保持) + outline-color/outline-strength；hover-tip(悬停名称气泡，免配交互) + hover-tip-sub(气泡附带模型内部部件名，如「设备 · 泵体」) |
基础建模
逐元素预览与全量属性见 基础建模。
| 元素 | 名称 | 关键选项 |
|---|---|---|
scene3d-light | 灯光 | light-kind(ambient/directional/point/spot/hemisphere)、light-color/light-intensity、position/light-target、聚光 spot-angle/spot-penumbra；阴影 cast-shadow + shadow-quality(512/1024/2048)；镜头光晕 lensflare(朝灯看时光核+星芒+鬼影，程序化零素材，WebGPU 自动切 TSL 版) + flare-size/flare-color |
scene3d-shape | 形状 | shape(box/sphere/cylinder/cone/capsule/plane/torus) + shape-size；材质 mat-kind：standard(PBR 全套)/hologram 全息/transmission 玻璃/flow-gradient 流光渐变/shadertoy(贴 mainImage 代码)/reflector 镜面(仅 plane)；变换 position/rotation/scale + billboard(公告牌面向相机)；pickable(地面/背景板建议关)；动效：路径动画组、自转 spin 组、呼吸脉动 pulse 组；测点三件套 |
scene3d-extrude | 拉伸体 | ext-outline(多行 x,z 底面轮廓) + ext-height；材质 standard/flow-gradient；科技轮廓线 edges + edge-color；自转/脉动组；测点三件套。单楼精修首选 |
scene3d-buildings | 批量楼块 | bld-data(每行一楼 x,z;x,z;…|高度[|底色[|顶色]])；默认底/顶渐变色、发光边框线 show-border + border-color/border-top-color、base-height。单实体一次绘制承载上百楼，城市尺度铺量 |
scene3d-instances | 批量实例 | 同一几何/模型按数据批量铺场景（树阵/路灯/车位/机柜）：inst-source(box/sphere/cylinder/cone/model + model-url) + inst-size；排布 inst-layout(manual 手动多行 x,y,z[,缩放[,朝向°[,#颜色]]] / grid 网格 / ring 圆环 / line 直线 / scatter 随机散布) + 各自参数 + layout-origin，「转为手动数据」按钮把参数化排布落回文本逐行微调；外观 inst-color/inst-metalness/inst-roughness + glow；hover-highlight + hover-color 悬停指到哪亮哪（大批量巡检定位）；data-key 测点 JSON 整批重排（数量/位置/颜色全刷新）。InstancedMesh 单实体一次绘制承载万级实例 |
scene3d-model | 模型 | model-url(glb/gltf/fbx/obj/3ds，≤200MB 直传)、model-scale/model-anchor + 「自适应大小」按钮（模型过大/过小看不见时按最大边≈10 世界单位归一缩放并自动取景）、骨骼动画 anim-autoplay+anim-index；路径动画（含 path-anim-clip 行进动画名）、自转/脉动组；子对象样式 sub-rules（按模型内部命名部件配效果：match 下拉直接选部件（候选列完整模型、可 ✕ 清空）或手输名称/路径，支持 * 通配、` |
scene3d-tiles3d | 倾斜摄影（3D Tiles） | tiles-url(Cesium 3D Tiles 的 tileset.json 直链)、tiles-scale(米制大场景可 0.1)、error-target(屏幕误差像素)。LOD 按视距自动加载卸载；插件按需异步加载 |
scene3d-cadwall | CAD 转 3D | cad-mapid(vjmap 服务上的 CAD 图) + cad-version/cad-layer/cad-condition/cad-limit/fit-size；转换规则 cad-rules：每条 = 一个条件查询转一类实体，condition(如 name=='AcDbPolyline'、layerindex==2、isclosed==1) + kind(wall 墙体/solid 拉伸体块/flat 填充地面/line 贴地线稿) + height/base/color/opacity/emissive/edges；未配规则退化为整图拉默认墙体 |
标注与信息
逐元素预览与全量属性见 标注与信息。
| 元素 | 名称 | 关键选项 |
|---|---|---|
scene3d-label | 值标签（CSS2D） | label-text + data-key(测点值) + unit/decimals；anchor/occlusion；font-size/text-color/bg-color；测点状态色/闪烁；点击派发 piece-click |
scene3d-text | 三维文字 | text(多行，中文免字体)、text-size(世界高)、text-billboard(朝相机/固定可 rotation)；text-color/text-bg/text-stroke/glow；测点三件套 |
scene3d-marker | 标记点（CSS2D） | marker-style(beacon 呼吸光圈/ring 旋转光环/pin 图钉) + marker-text/marker-icon；marker-color/marker-size；测点三件套；点击派发 piece-click |
scene3d-fxmarker | 动效标记（CSS2D） | 引擎成品多层光圈动效，科技感 POI 首选：fx-style(breathing 呼吸光圈/diffused 扩散光点/fluorescence 荧光点/halo-ring 发光光环/rotating-aperture 旋转光圈/rotating-textborder 旋转文字边框) + marker-text；fx-colors(多色逗号分隔，留空用引擎默认配色) + marker-size；anchor/occlusion；测点 state-rules(命中覆盖整组配色) + blink-values；点击派发 piece-click。与「标记点」互补：标记点是轻量 CSS 动画，这里是引擎带的成品动效 |
scene3d-beam | 光柱标记 | beam-height/beam-width + position(贴地落点)；beam-color/beam-opacity、底部涟漪 ripple + ripple-radius/ripple-period、顶部菱形 beam-top；测点换色/闪烁。POI 与告警地标标配，双交叉渐变面片零素材 |
scene3d-board | 数据看板牌（CSS2D） | board-title(留空=元素名) + board-rows(每行 标签|测点键|单位|小数位，多行=多指标实时刷新) + row-state-rules(行值命中变色)；board-width/board-accent/value-color；点击派发 piece-click |
scene3d-chart2d | 图表贴片 | 柱状/饼图画在纹理上的真三维面板（可遮挡/可辉光/进截图，与 CSS2D 看板牌互补）：chart-kind(bar/pie/donut) + chart-title + chart-data(多行 标签,值[,#颜色])；panel-width/panel-height + billboard/rotation + bg-color/text-color + glow；chart-anim 生长动画；data-key 测点 JSON 整批刷新（刷新带生长动画）。零素材离线可用，斜放设备旁或贴墙当"车间图表屏" |
scene3d-html | HTML 面板（CSS3D） | html(任意 HTML/内联样式，工程作者书写) + panel-width(世界宽)/panel-px-width(排版像素宽)；panel-billboard/rotation(斜放立牌)/occlude(可被场景遮挡)。与看板牌的区别：真正贴在三维空间，近大远小可遮挡 |
scene3d-sprites | 图标点位（批量精灵） | icon-url(留空=内置发光圆点 icon-color) + sprite-size + size-attenuation/allow-overlap；points(每行 x,y,z[,标签文字]，有标签则图标上方出批量文字精灵 text-size/text-color)；data-key 测点 JSON [[x,y,z,标签?],…] 整批刷新。参与深度遮挡与拾取，单实体承载上百点位 |
scene3d-ruler | 测量标注 | ruler-start/ruler-end 两端点；ruler-color/ruler-decimals/ruler-unit/ruler-scale。持久工程标注；编辑器视口工具条另有交互式「测量」工具 |
组态与流动
逐元素预览与全量属性见 组态与流动。
| 元素 | 名称 | 关键选项 |
|---|---|---|
scene3d-pipe | 管道 | pipe-path(多行 x,y,z，自动圆滑) + pipe-radius；管体 PBR 色；流动 flow + flow-color/flow-speed/flow-density/flow-reverse；测点 state-rules(管体色) + flow-rules(值=on/off/reverse[:速度]) |
scene3d-pipenet | 管网（分支拓扑） | net-paths(多行 x,y,z，空行或 --- 分段，端点重合自动生成节点球)；断面 net-shape(circle/arch 拱形管廊/rect 风管桥架) + 尺寸；测点三件套。给水/电力/燃气分支网络 |
scene3d-persons | 人员点位 | 定位系统驱动的移动人员：data-key 测点 JSON [[id,x,y,z,姓名?],…] 按 id 差分（新增出现/缺失移除/移动在 move-duration 内补间平滑）；person-mode(sprite 图标精灵(零素材定位针，person-color/icon-url) / model 人物模型(model-url 默认 three 官方士兵⚠️公网直链 + walk-clip/idle-clip 行走待机动画自动切换))；follow-net 关联管网元素=人员坐标按 CAD 图纸坐标换算到场景；姓名标签 name-size/name-color/name-prefix；select-wave 点击选中扩散光波；trail-limit 历史轨迹上限（配 scene3dPersonTrail 动作回放）；demo-walk 内置沿管网随机行走演示（产出与真实数据同格式，接真实数据源关掉即可） |
scene3d-carflow | 车流 | 收费站/闸口过车模拟：model-piece 关联主模型，车道/抬杆按模型内命名子对象匹配（lane-match 如 CD* + lane-reverse 反向车道 + pole-match 如 GZ*，按名称排序配对）；抬杆 pole-axis/pole-angle/pole-duration；车型 car-urls(每行 url,车型名，默认 vjmap 六车模⚠️外网直链) + car-scale；行程 drive-duration/dwell 杆前停留/spawn-gap 发车间隔 + approach-dist/stop-dist/exit-dist；车顶信息卡 show-card(card-plate-prefix 车牌前缀/card-abnormal-rate 异常概率) + 车道号牌 lane-tags；flow-play-only(默认仅播放态运行)；点击车辆 payload 带 carPlate/carDriver/carType/carState/laneName |
scene3d-flyline | 飞线 | fly-from/fly-to/fly-height(拱高)/fly-width；line-color/pulse-color/pulse-count；flow-speed/flow-reverse；测点 flow-rules |
scene3d-line | 线条（批量细线） | line-paths(每行 x,y,z，--- 分段一实体多条)；line-color + 动画 line-animate(none/grow 生长循环/march 跑马亮段) + animate-speed/march-length；细线配辉光=霓虹。测点换色/闪烁 |
scene3d-trail | 导引线（箭头流动宽线） | trail-path(贴地建议 y≈0.18，有地面时再抬高)；trail-color(发光箭头同染)/trail-width(屏幕像素等宽)/trail-icon-length+trail-icon-space(箭头长度/间距,长度建议≥线宽)/trail-animate+trail-speed；trail-show-line+trail-line-opacity 半透明同色底带；测点 state-rules+flow-rules。疏散路线/巡检动线 |
scene3d-wall | 光墙围栏 | wall-path(多行 x,z 或 x,y,z) + wall-height/wall-close；wall-color/wall-opacity/wall-flow 流光扫动 + flow-speed/flow-repeat；测点换色/闪烁。周界告警标配 |
scene3d-radar | 雷达扫描 | radar-radius + position(贴地稍抬)；radar-color/radar-speed/radar-sector/radar-opacity；测点换色/闪烁 |
scene3d-zone | 区域面 | zone-points(每行 x,z 或 x,y,z，≥3 点闭合)；zone-color/zone-opacity；测点换色/闪烁。责任分区/危险区/管控区，告警整区红闪 |
scene3d-heatmap | 热力图 | heat-mode(2d 贴地/3d 曲面) + heat-size/heat-height；heat-points(多行 x,z,值) + heat-min/max + heat-opacity/heat-radius；data-key 测点 JSON 整批实时替换。离线 playground 无远程插件时回退本地贴地色斑 |
scene3d-tank | 液位罐 | tank-shape(cylinder/box) + tank-size + position(罐底中心)；开口玻璃罐体 + 半透明液柱与波浪液面；shell-color/shell-opacity、liquid-color 及低/高液位色；数据 data-key(或静态 tank-value) + tank-min/max 量程 + tank-low/tank-high 阈值 + blink-high(高液位脉冲)；show-value 罐顶百分比。液位平滑升降 |
scene3d-points | 数据点云 | points-shape(sphere/box/diamond) + points-size(+points-size-by-value)；量程配色 points-min/max + 低/中/高三色；points-data(多行 x,y,z,值) + data-key JSON 整批刷新。InstancedMesh 单次绘制上千点位 |
scene3d-video | 视频面板 | video-url(mp4/webm，留空="无信号"占位) + video-size/video-billboard；发光边框 video-frame + frame-color。监控墙/设备屏 |
scene3d-ledtext | LED 字幕屏 | led-text + led-direction(horizon 跑马灯/vertical 滚屏) + led-speed/led-size；led-color/led-bg/led-font-size；data-key 测点值直接上屏 + 状态色/闪烁。告示/标语/告警滚动 |
特效
逐元素预览与全量属性见 特效。
| 元素 | 名称 | 关键选项 |
|---|---|---|
scene3d-particle | 粒子特效 | fx-kind：fire 火焰/smoke 烟雾/rain 下雨/snow 下雪/firework 烟花(循环绽放，位置=爆心)/text 文字聚字(fx-text + fx-text-height/fx-text-cycle，粒子周期汇聚成字)/custom(粘贴引擎 particle.toJSON())；fx-intensity/fx-size/fx-range/fx-color |
scene3d-spriteanim | 序列帧动画 | 精灵图逐帧播放成动画贴片：sheet-url(横向等分 PNG/WebP 条带 + frames 帧数；SVG data-URI 会先栅格成 PNG) 或 atlas-url(TexturePacker JSON 图集 + frame-name 动画名，可多动画切换)；fps/autoplay/loop/flip-x；as-sprite(公告牌朝相机/固定平面) + sprite-scale + glow；测点 anim-rules(每行 值1|值2=帧动画名，如状态切 idle/run/alarm 三套动作)。⚠️ 贴图素材需自备 URL |
scene3d-lottie | Lottie 动画 | AE 导出的矢量动画贴进三维：lottie-url(Lottie JSON，外链需允许跨域) + quality/speed/loop；panel-width/panel-height + billboard/rotation + glow。自更新纹理贴平面（真三维面，可遮挡/进截图），动态 logo/图标动效/引导动画；扩展 loader 从引擎插件服务按需下载（需服务可达） |
| （通用动效） | 自转 / 脉动 / 路径动画 | 形状/模型/拉伸体通用：自转 spin + spin-axis/spin-speed；呼吸脉动 pulse + pulse-scale/pulse-speed（心跳缩放）；路径动画 path-points + path-duration/path-loop/path-autoplay（+ 第三人称跟拍 path-camera-follow），运行层用 scene3dPathControl 控制 |
辉光的正确打开方式
场景里放一个「后期效果」（scene3d-effects，建议单份）并开启 bloom，然后给要发光的元素勾 glow——选择性泛光只作用于勾选元素的亮部。自发光/加色材质配低亮度阈值（0.07~0.1）效果最佳。