# 对象公共属性本文档描述多个对象类型共享的 extInfo.property 字段。具体对象文档只说明对象专有字段；遇到公共字段时应以本文为准。
# 属性位置对象样式通常位于：
text ElementNode.extInfo.property例如：
json {
"type": "text",
"point": [80, 60, 320, 120],
"extInfo": {
"property": {
"realType": "TextBox",
"anchor": [80, 60, 320, 120],
"rotation": 15,
"fillStyle": { "type": "color", "color": { "realColor": -1, "color": -1 } }
}
},
"children": []
}# realTypets type RealType =
| "Auto"
| "TextBox"
| "Picture"
| "table"
| "TableCell"
| "Group"
| "Background"值 适用对象 说明 Autotext自动形状文本或占位符文本。 TextBoxtext显式文本框。 Pictureimage图片对象。音频/视频封面也可以使用该类型。 tabletable表格对象。 TableCelltableColumn表格单元格。 Groupcontainer分组对象。 Background背景 背景。
type 决定节点协议，realType 决定该节点在 PPTX 语义中的真实形态。实现方不应只依赖 realType 判断对象类型，因为文本、形状、占位符都可能使用相近的真实类型。
# anchorts type Box = [x: number, y: number, width: number, height: number]anchor 描述对象的几何区域。它与节点级 point 都是 [x, y, width, height]，但用途不同：
字段 作用 point对象在当前坐标系中的外框，主要用于布局和快速定位。 property.anchor对象真实几何锚点，生成 PPTX 或精确渲染时应使用该字段。
顶层对象的 point 和 anchor 通常一致。分组内部对象的 anchor 可以是相对坐标或归一化坐标，需要结合父分组的 interiorAnchor 转换。
# 设置位置和尺寸json {
"point": [100, 80, 240, 120],
"extInfo": {
"property": {
"anchor": [100, 80, 240, 120]
}
}
}x、y 决定对象左上角。width、height 决定对象尺寸。宽高应大于 0。宽高为 0 时对象不可见或无法被正确选择。 负坐标可以表示对象部分位于页面外，但第三方渲染器应明确是否支持。 # rotationts type Rotation = numberrotation 表示对象绕自身中心旋转的角度，单位为度。正值通常表示顺时针旋转。
json {
"rotation": 45
}设置效果：
值 效果 0 或缺失不旋转。 45顺时针旋转 45 度。 90旋转为竖向。 -30逆时针旋转 30 度。
建议将角度规范化到 -360..360 或 0..360，避免不同渲染器对大角度值处理不一致。
# shapeTypeshapeType 描述对象外框形状。当前常用值为 rect。当对象需要以圆角矩形、椭圆或其他形状裁剪时，可扩展为对应形状名称。
json {
"shapeType": "rect"
}shapeType 应与 geometry.name 保持一致。若两者冲突，建议以 geometry.name 作为精确几何，以 shapeType 作为快速分类。
# geometryts type Geometry = {
name: string
data: unknown | null
avLst: unknown | null
textBounds: unknown | null
}字段 说明 name几何类型，例如 rect、tableColumn。 data自定义路径或几何数据。没有自定义几何时为 null。 avLst形状调节点列表。没有调节点时为 null。 textBounds文本边界信息。没有额外文本边界时为 null。
geometry 决定对象实际轮廓。对于图片对象，几何会影响图片裁剪范围；对于文本对象，几何会影响背景填充、边框和文本排版区域。
# placeholderts type Placeholder = {
type: string
idx?: number
size?: string
visible: boolean
}字段 说明 type占位符语义，例如 TITLE、BODY、CENTERED_TITLE、SUBTITLE、CONTENT、PICTURE、DATETIME、FOOTER、SLIDE_NUMBER。 idx占位符索引。同一版式内多个相同类型占位符用它区分。 size占位符尺寸级别，例如 half、quarter。 visible占位符是否可见。
设置方式：
json {
"placeholder": {
"type": "TITLE",
"visible": false
}
}使用限制：
placeholder 主要用于母版、版式和页面中的占位文本或占位内容对象。idx 应在同一版式范围内稳定，便于页面对象与占位符匹配。visible: false 表示占位符默认不作为实物内容展示；编辑器仍可使用它提供插入位置和默认样式。# fillStylets type FillStyle =
| { type: "noFill" }
| { type: "color"; color: ColorValue }
| { type: "gradient"; gradient: GradientFill }
| { type: "texture"; texture: TextureFill }fillStyle 控制对象内部填充。文本框、形状、表格单元格、背景和图片都可以使用填充。图片对象通常使用 texture 填充。
# 无填充json {
"fillStyle": { "type": "noFill" }
}效果：对象内部透明，只显示文本、边框或子内容。适用于无背景文本框。
限制：
noFill 不应同时带 color、gradient 或 texture。若对象没有边框也没有文本，noFill 会让对象不可见，但对象仍可能可被选中。 # 纯色填充json {
"fillStyle": {
"type": "color",
"color": {
"scheme": "accent1",
"realColor": -12028725,
"color": -12028725
}
}
}字段 说明 scheme可选。引用主题色槽位。 realColor实际渲染颜色。 color原始颜色或主题基础颜色。 alpha可选。透明度，范围建议 0..100000，值越大越不透明。 lumMod可选。亮度乘数。 lumOff可选。亮度偏移。 shade可选。变暗比例。 tint可选。变亮比例。
设置效果：
只设置 realColor / color：使用纯色。 设置 scheme：颜色可随主题变化。 设置 alpha：颜色半透明，能看到底层内容。 设置 lumMod / lumOff：在主题色基础上变亮或变暗。 realColor 和 color 都使用核心协议中的 32 位有符号 ARGB 十进制颜色。常用转换示例：
#FFFFFF 写为 -1。#000000 写为 -16777216。#4874CB 写为 -12028725。rgba(0,0,0,0.17) 可写为 realColor: 721420288，并同时写入 alpha: 17000 保留透明度语义。具体换算公式、十六进制和 rgba() 的处理规则见 ../core.md 的“颜色”章节。
# 渐变填充json {
"fillStyle": {
"type": "gradient",
"gradient": {
"angle": 90,
"colors": [
{ "realColor": -1, "color": -1 },
{ "realColor": -12028725, "color": -12028725 }
],
"fractions": [0, 1],
"gradientType": "linear",
"insets": null,
"flip": null,
"tileRect": null,
"rotWithShape": null
}
}
}字段 说明 angle渐变角度。常用于线性渐变方向。 colors渐变色标数组。 fractions色标位置数组，长度应与 colors 一致。通常使用 0..1。 gradientType渐变类型，例如 linear。 insets渐变区域内缩。没有内缩时为 null。 flip翻转模式。没有翻转时为 null。 tileRect平铺区域。没有平铺时为 null。 rotWithShape是否随形状旋转。
限制：
colors.length 与 fractions.length 应一致。fractions 应按从小到大排列。只有当目标渲染器支持渐变时才应使用复杂渐变；否则建议降级为首个色标或平均色。 # 纹理填充ts type TextureFill = {
imageData: string
contentType: string
alpha: number
flipMode: string
stretch?: [left: number, top: number, right: number, bottom: number]
insets?: [left: number, top: number, right: number, bottom: number]
offset?: [x: number, y: number]
scale?: [x: number, y: number]
alignment?: string
alphaModFix?: number
rotWithShape?: boolean
}字段 说明 imageData图片资源。可以是 URL，也可以是 data:image/...;base64,...。 contentTypeMIME 类型，例如 image/png、image/jpeg。 alpha图片透明度，100000 表示完全不透明。 flipMode翻转模式。常用 NONE。 stretch拉伸填充参数。通常 [0,0,0,0] 表示完整图片拉伸到对象区域。 insets裁剪内缩参数。常用于图片裁剪。 offset平铺或缩放时的偏移。 scale平铺或缩放时的比例。 alignment对齐方式，例如 CENTER。 alphaModFix透明度修正值。 rotWithShape是否随对象旋转。
# 拉伸图片填充json {
"type": "texture",
"texture": {
"imageData": "data:image/png;base64,...",
"contentType": "image/png",
"alpha": 100000,
"flipMode": "NONE",
"stretch": [0, 0, 0, 0]
}
}效果：图片被拉伸填满对象区域。对象宽高比与图片宽高比不一致时，图片会被压缩或拉伸变形。
# 裁剪图片填充json {
"type": "texture",
"texture": {
"imageData": "data:image/png;base64,...",
"contentType": "image/png",
"alpha": 100000,
"flipMode": "NONE",
"insets": [71667, 0, 0, 48134]
}
}效果：先按 insets 裁剪图片，再填充到对象区域。裁剪值通常使用 PPTX 百分比单位，正值表示从对应边向内裁剪。
# 平铺或缩放图片填充json {
"type": "texture",
"texture": {
"imageData": "https://example.com/image.jpg",
"contentType": "image/jpeg",
"alpha": 100000,
"flipMode": "NONE",
"offset": [0, 0],
"scale": [0.1, 0.1],
"alignment": "CENTER",
"rotWithShape": true
}
}效果：图片按 scale 缩放后填充对象，可结合 offset 和 alignment 控制位置。适用于纹理、图案或保持图片原始比例的场景。
限制：
stretch 和 scale / offset 不建议同时使用。若同时出现，应明确一个优先级。imageData 为远程 URL 时，渲染端需要具备下载和缓存能力。alpha、alphaModFix 都会影响透明度，合成时应避免重复应用。# strokeStylets type StrokeStyle = {
paint?: FillStyle
lineWidth?: number
lineCap?: string
lineJoin?: string
lineDash?: string
lineCompound?: string
}字段 说明 paint线条填充。使用 { "type": "noFill" } 表示无边框。 lineWidth线宽。值越大边框越粗。 lineCap线端样式，例如 FLAT。 lineJoin转角连接样式，例如 ROUND。 lineDash虚线样式，例如 SOLID。 lineCompound复合线样式，例如 SINGLE、DOUBLE。
示例：
json {
"strokeStyle": {
"paint": {
"type": "color",
"color": { "realColor": -16777216, "color": -16777216 }
},
"lineWidth": 2,
"lineDash": "SOLID",
"lineCompound": "SINGLE"
}
}# shadowshadow 表示对象阴影。文本框、图片、形状、表格单元格等可视对象都可以支持阴影。
ts type Shadow = {
algn?: string
blur?: number
angle?: number
distance?: number
rotWithShape?: boolean
scaleX?: number
scaleY?: number
fillStyle: FillStyle
}字段 说明 algn阴影相对对象的对齐位置。例如 t 表示顶部方向的对齐基准。 blur模糊半径。值越大，阴影边缘越柔和。 angle阴影方向角度。 distance阴影相对对象的偏移距离。 rotWithShape对象旋转时阴影是否一起旋转。 scaleX阴影横向缩放比例。大于 1 时阴影比对象更宽。 scaleY阴影纵向缩放比例。大于 1 时阴影比对象更高。 fillStyle阴影颜色和透明度。通常使用半透明颜色填充。
示例：
json {
"shadow": {
"algn": "t",
"blur": 47,
"angle": 90,
"distance": 4,
"rotWithShape": false,
"scaleX": 1.08,
"scaleY": 1.08,
"fillStyle": {
"type": "color",
"color": {
"realColor": 721420288,
"color": -16777216,
"alpha": 17000
}
}
}
}设置效果：
增大 blur：阴影更柔和，扩散范围更大。 增大 distance：阴影离对象更远，方向由 angle 决定。 设置较低 alpha：阴影更淡。 设置 scaleX / scaleY 大于 1：阴影面积略大于对象，类似外阴影。 限制：
fillStyle 应使用颜色填充。渐变或图片阴影可能无法被所有渲染器支持。blur 和 distance 不建议使用负数。如果对象本身透明或无填充，阴影仍应按对象几何轮廓计算。 # effectLstts type EffectList = Record<string, unknown>effectLst 用于保留额外效果列表。当前可为空对象。第三方实现如果不能识别其中的效果，应保留原值并透传。
# hyperlinkts type Hyperlink = {
type: string
label?: string
address: string
action?: string
}字段 说明 type链接类型，例如 URL。 label链接显示名称。可以为空字符串。 address链接地址或动作地址。 action动作指令。媒体播放可使用 ppaction://media。
示例：
json {
"hyperlink": {
"type": "URL",
"label": "",
"address": "ppaction://media",
"action": "ppaction://media"
}
}媒体对象通常使用 ppaction://media 触发播放行为。普通网页跳转可把 address 设置为 URL。