3D 元素表示您項目中的三維物體，包括導入的 3D 模型、基本幾何原型、從 2D 形狀擠出來的形狀、3D 文本和布林運算的結果。
3D 元素共享來自 基本元素 和 視圖元素 的共同字段，同時還引入了額外的 3D 專用屬性。
| 屬性 | 類型 | 必要 | 範例 | 值範圍 | 描述 |
|---|---|---|---|---|---|
| type | string | true | - | 3D | 元素的類型。對於 3D 元素，這始終是 "3D"。 |
| sourceId | string | false | - | - | 3D 模型或幾何資源的內部標識符。 |
| ext | string | false | - | glb | gltf | geometry | text3d | 3D 元素的文件擴展名或幾何類型。 |
| externalUrl | string | false | - | - | 加載外部 glTF/glb 模型的可選 URL。引擎將獲取並緩存模型。 |
| nodeCategory | string | false | - | basic | polyhedron | extrusion | pathSweep | boolean | 3D 節點的類別，指示它是如何創建的。 |
| geometryType | string | false | - | - | 基本幾何的類型。請參見下面的 "幾何類型" 部分。 |
| originalWidth | number | false | - | - | 3D 模型在世界單位中的原始寬度。 |
| originalHeight | number | false | - | - | 3D 模型在世界單位中的原始高度。 |
| originalDepth | number | false | - | - | 3D 模型在世界單位中的原始深度。 |
| currentAnimationIndex | number | false | - | - | 當前播放的 glTF 動畫的索引（如果模型包含動畫）。 |
除了標準的 2D 變換屬性（x, y, 旋轉, scaleX, scaleY）外，3D 元素還支持額外的變換屬性以進行三維定位和旋轉：
| 屬性 | 類型 | 必要 | 範例 | 值範圍 | 描述 |
|---|---|---|---|---|---|
| z | number | false | - | - | 元素在 3D 空間中的深度位置。單位與像素對齊，z=0 對應於畫布平面。 |
| rotationX | number | false | - | - | 圍繞 X 軸的旋轉，以度為單位。 |
| rotationY | number | false | - | - | 圍繞 Y 軸的旋轉，以度為單位。 |
| scaleZ | number | false | - | > 0 | 沿 Z 軸的縮放因子。值大於 1 放大，介於 0 和 1 之間的值縮小。 |
geometryType 字段指定基本 3D 幾何的類型。可用類型按類別組織：
基本形狀 (nodeCategory: "basic"):
cube - 六面體sphere - 球形幾何cylinder - 圓柱幾何cone - 圓錐幾何torus - 圈狀幾何capsule - 膠囊形幾何disc - 扁平圓盤多面體 (nodeCategory: "polyhedron"):
pyramid - 四面體金字塔octahedron - 八面體icosahedron - 二十面體dodecahedron - 十二面體hexPrism - 六面體棱柱triangle - 三角形棱柱擠出形狀 (nodeCategory: "extrusion"):
plus - 加號/十字形star - 星形roundedRect - 圓角矩形路徑掃描 (nodeCategory: "pathSweep"):
helix - 螺旋torusKnot - 圈結幾何tricylinder - 三圓柱交集3D 元素可以通過擠出 2D 形狀來創建。當您在編輯器中將 2D 形狀元素轉換為 3D 時，它會生成一個新的 type: "3D" 元素，並包含以下額外字段：
| 屬性 | 類型 | 必要 | 範例 | 值範圍 | 描述 |
|---|---|---|---|---|---|
| extrusionSource | object | false | - | - | 用於創建 3D 擠出的原始 2D 形狀數據。包含完整的 ShapeNodeData。 |
| shapeSizeX | number | false | - | - | 擠出形狀的寬度，以像素為單位。 |
| shapeSizeY | number | false | - | - | 擠出形狀的高度，以像素為單位。 |
| shapeExtrusion | number | false | - | - | 沿 Z 軸的擠出深度，以像素為單位。 |
| shapeCorner | string | false | - | round | chamfer | straight | 擠出形狀的角落類型。 |
| shapeRoundnessSmooth | number | false | - | 0 - 1 | 圓角的平滑度（0-1）。 |
| shapeRoundnessArc | number | false | - | - | 圓角的弧半徑。 |
| shapeBevel | number | false | - | - | 邊緣的斜切深度。 |
| shapeBevelSides | number | false | - | - | 斜切邊緣的段數。 |
3D 元素還可以表示具有深度和斜切的三維文本：
| 屬性 | 類型 | 必要 | 範例 | 值範圍 | 描述 |
|---|---|---|---|---|---|
| textContent | string | false | - | - | 要在 3D 中渲染的文本內容。 |
| textStyle3D | object | false | - | - | 文本樣式屬性（字體、大小、粗細等）。重用一些 2D 文本樣式字段。 |
| textDepth | number | false | - | - | 3D 文本的擠出深度。 |
| textBevelSize | number | false | - | - | 文本邊緣的斜切大小。 |
| textBevelSegments | number | false | - | - | 文本斜切的段數。 |
| textCurveSegments | number | false | - | - | 文本曲線的段數。 |
3D 元素支持先進的材料屬性和紋理映射：
| 屬性 | 類型 | 必要 | 範例 | 值範圍 | 描述 |
|---|---|---|---|---|---|
| geometryColor | string | false | #FFFFFF | - | 3D 幾何的基本顏色，以十六進制格式表示。 |
| materialType | string | false | - | - | 材料的 MaterialX 預設路徑。示例："StandardSurface/standard_surface_gold.mtlx"。 |
| textures | object | false | - | - | 材料的紋理映射（顏色、法線、粗糙度、金屬度、環境遮蔽、發光）。 |
textures 對象可以包含以下紋理映射屬性：
colorMap - 基本顏色/漫反射紋理normalMap - 表面細節的法線圖roughnessMap - 粗糙度紋理metalnessMap - 金屬度紋理aoMap - 環境遮蔽圖emissiveMap - 發光紋理每個紋理映射可以包括強度參數以控制其效果。
具有 ext: "glb" 或 ext: "gltf" 的 3D 元素表示導入的 3D 模型：
externalUrl 指定遠程 glTF/glb 文件的 URLsourceId 獲取並緩存模型currentAnimationIndex 選擇要播放的動畫1
2{
3 "id": "3d-cube-001",
4 "type": "3D",
5 "start": 0,
6 "duration": 5,
7 "trackIndex": 0,
8 "x": 540,
9 "y": 540,
10 "z": 0,
11 "width": 200,
12 "height": 200,
13 "anchorX": 100,
14 "anchorY": 100,
15 "rotation": 0,
16 "rotationX": 30,
17 "rotationY": 45,
18 "scaleX": 1,
19 "scaleY": 1,
20 "scaleZ": 1,
21 "alpha": 1,
22 "ext": "geometry",
23 "geometryType": "cube",
24 "nodeCategory": "basic",
25 "geometryColor": "#4A90E2"
26}
271
2{
3 "id": "3d-extrusion-001",
4 "type": "3D",
5 "start": 0,
6 "duration": 5,
7 "trackIndex": 0,
8 "x": 540,
9 "y": 540,
10 "z": 0,
11 "width": 300,
12 "height": 300,
13 "anchorX": 150,
14 "anchorY": 150,
15 "rotation": 0,
16 "rotationX": 0,
17 "rotationY": 0,
18 "scaleX": 1,
19 "scaleY": 1,
20 "scaleZ": 1,
21 "alpha": 1,
22 "ext": "geometry",
23 "nodeCategory": "extrusion",
24 "shapeSizeX": 300,
25 "shapeSizeY": 300,
26 "shapeExtrusion": 100,
27 "geometryColor": "#FF6B6B",
28 "extrusionSource": {
29 "shapeType": "SHAPE_STAR",
30 "starPoints": 5,
31 "starInnerRadius": 0.4
32 }
33}
341
2{
3 "id": "3d-model-001",
4 "type": "3D",
5 "start": 0,
6 "duration": 10,
7 "trackIndex": 0,
8 "x": 540,
9 "y": 540,
10 "z": -200,
11 "width": 400,
12 "height": 400,
13 "anchorX": 200,
14 "anchorY": 200,
15 "rotation": 0,
16 "rotationX": 0,
17 "rotationY": 0,
18 "scaleX": 1,
19 "scaleY": 1,
20 "scaleZ": 1,
21 "alpha": 1,
22 "ext": "glb",
23 "externalUrl": "https://example.com/models/animated_character.glb",
24 "sourceId": "cached-model-123",
25 "currentAnimationIndex": 0,
26 "originalWidth": 2,
27 "originalHeight": 2,
28 "originalDepth": 2
29}
30