通过

Excel.Shape class

  • 参考
包:
excel

表示工作表中的泛型形状对象。 形状可以是几何形状、线条、一组形状等。若要了解有关形状对象模型的详细信息，请阅读 使用 Excel JavaScript API 处理形状。

扩展
OfficeExtension.ClientObject

注解

[ API 集：ExcelApi 1.9 ]

属性

altTextDescription

指定对象的可选说明文本 Shape 。
altTextTitle

指定对象的可选标题文本 Shape 。
connectionSiteCount

返回此形状上的连接站点数。
context

与 对象关联的请求上下文。 这会将加载项的进程连接到 Office 主机应用程序的进程。
displayName

获取形状的显示名称。 新创建的形状具有已本地化且可能与其 name不匹配的生成名称。 在此方案中，可以使用此 API 获取 UI 中显示的名称。
fill

返回此形状的填充格式。
geometricShape

返回与形状关联的几何形状。 如果形状类型不是“GeometricShape”，则会引发错误。
geometricShapeType

指定此几何形状的几何形状类型。 有关详细信息，请参阅 Excel.GeometricShapeType。 null如果形状类型不是“GeometricShape”，则返回 。
group

返回与形状关联的形状组。 如果形状类型不是“GroupShape”，则会引发错误。
height

指定形状的高度（以磅为单位）。 InvalidArgument使用负值或零作为输入进行设置时引发异常。
id

指定形状标识符。
image

返回与形状关联的图像。 如果形状类型不是“Image”，则会引发错误。
left

从形状左侧到工作表左侧的距离（以磅为单位）。 InvalidArgument将负值设置为输入时引发异常。
level

指定指定形状的级别。 例如，级别 0 表示形状不是任何组的一部分，级别 1 表示形状是顶级组的一部分，级别 2 表示形状是顶级子组的一部分。
line

返回与形状关联的线条。 如果形状类型不是“Line”，则会引发错误。
lineFormat

返回此形状的线条格式。
lockAspectRatio

指定是否锁定此形状的纵横比。
name

指定形状的名称。
parentGroup

指定此形状的父组。
placement

表示对象如何附加到其下方的单元格。
rotation

指定形状的旋转（以度为单位）。
textFrame

返回此形状的文本框对象。
top

从形状上边缘到工作表上边缘之间的距离（以磅为单位）。 InvalidArgument将负值设置为输入时引发异常。
type

返回此形状的类型。 有关详细信息，请参阅 Excel.ShapeType。
visible

指定形状是否可见。
width

指定形状的宽度（以磅为单位）。 InvalidArgument使用负值或零作为输入进行设置时引发异常。
zOrderPosition

返回指定形状在 z 顺序中的位置，0 表示顺序堆栈的底部。

方法

copyTo(destinationSheet)

复制并粘贴 Shape 对象。 粘贴的形状将复制到此形状所在的同一像素位置。
delete()

从工作表删除形状。
getAsImage(format)

将形状转换为图像，并将图像作为 Base64 编码的字符串返回。 DPI 为 96。 唯一支持的格式是 Excel.PictureFormat.BMP、Excel.PictureFormat.PNG、Excel.PictureFormat.JPEG 和 。Excel.PictureFormat.GIF
getAsImage(formatString)

将形状转换为图像，并将图像作为 Base64 编码的字符串返回。 DPI 为 96。 唯一支持的格式是 Excel.PictureFormat.BMP、Excel.PictureFormat.PNG、Excel.PictureFormat.JPEG 和 。Excel.PictureFormat.GIF
incrementLeft(increment)

以指定磅数水平移动形状。
incrementRotation(increment)

将形状围绕 z 轴旋转特定度数。 rotation使用 属性设置形状的绝对旋转。
incrementTop(increment)

以指定磅数垂直移动形状。
load(options)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。
load(propertyNames)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。
load(propertyNamesAndPaths)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。
scaleHeight(scaleFactor, scaleType, scaleFrom)

按指定因子缩放形状的高度。 对于图像，你可以说明是相对于原始尺寸还是当前尺寸缩放形状。 对于除图片以外的其他形状来说，缩放总是相对于其当前高度而言。
scaleHeight(scaleFactor, scaleTypeString, scaleFromString)

按指定因子缩放形状的高度。 对于图像，你可以说明是相对于原始尺寸还是当前尺寸缩放形状。 对于除图片以外的其他形状来说，缩放总是相对于其当前高度而言。
scaleWidth(scaleFactor, scaleType, scaleFrom)

按指定因子缩放形状的宽度。 对于图像，你可以说明是相对于原始尺寸还是当前尺寸缩放形状。 对于除图片以外的其他形状来说，缩放总是相对于其当前宽度而言。
scaleWidth(scaleFactor, scaleTypeString, scaleFromString)

按指定因子缩放形状的宽度。 对于图像，你可以说明是相对于原始尺寸还是当前尺寸缩放形状。 对于除图片以外的其他形状来说，缩放总是相对于其当前宽度而言。
set(properties, options)

同时设置对象的多个属性。 可以传递具有相应属性的纯对象，也可以传递同一类型的另一个 API 对象。
set(properties)

基于现有的已加载对象，同时对对象设置多个属性。
setZOrder(position)

将指定形状沿集合的 z 顺序向上或向下移动，将其移动到其他形状的前面或后面。
setZOrder(positionString)

将指定形状沿集合的 z 顺序向上或向下移动，将其移动到其他形状的前面或后面。
toJSON()

重写 JavaScript toJSON() 方法，以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 JSON.stringify (，反过来又调用toJSON传递给它的 对象的 方法。) 而原始Excel.Shape对象是 API 对象，toJSON该方法返回一个纯 JavaScript 对象， (类型为 Excel.Interfaces.ShapeData) ，其中包含原始对象中任何已加载子属性的浅表副本。

事件

onActivated

当激活形状时发生此事件。
onDeactivated

当停用形状时发生此事件。

属性详细信息

altTextDescription

指定对象的可选说明文本 Shape 。

altTextDescription: string;

属性值

string

注解

[ API 集：ExcelApi 1.9 ]

altTextTitle

指定对象的可选标题文本 Shape 。

altTextTitle: string;

属性值

string

注解

[ API 集：ExcelApi 1.9 ]

connectionSiteCount

返回此形状上的连接站点数。

readonly connectionSiteCount: number;

属性值

number

注解

[ API 集：ExcelApi 1.9 ]

context

与 对象关联的请求上下文。 这会将加载项的进程连接到 Office 主机应用程序的进程。

context: RequestContext;

属性值

Excel.RequestContext

displayName

获取形状的显示名称。 新创建的形状具有已本地化且可能与其 name不匹配的生成名称。 在此方案中，可以使用此 API 获取 UI 中显示的名称。

readonly displayName: string;

属性值

string

注解

[ API 集：ExcelApi 1.15 ]

fill

返回此形状的填充格式。

readonly fill: Excel.ShapeFill;

属性值

Excel.ShapeFill

注解

[ API 集：ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-create-and-delete.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.addGeometricShape(Excel.GeometricShapeType.smileyFace);
    shape.left = 300;
    shape.top = 100;
    shape.height = 100;
    shape.width = 100;
    shape.fill.foregroundColor = "yellow"
    await context.sync();
});

geometricShape

返回与形状关联的几何形状。 如果形状类型不是“GeometricShape”，则会引发错误。

readonly geometricShape: Excel.GeometricShape;

属性值

Excel.GeometricShape

注解

[ API 集：ExcelApi 1.9 ]

geometricShapeType

指定此几何形状的几何形状类型。 有关详细信息，请参阅 Excel.GeometricShapeType。 null如果形状类型不是“GeometricShape”，则返回 。

geometricShapeType: Excel.GeometricShapeType | "LineInverse" | "Triangle" | "RightTriangle" | "Rectangle" | "Diamond" | "Parallelogram" | "Trapezoid" | "NonIsoscelesTrapezoid" | "Pentagon" | "Hexagon" | "Heptagon" | "Octagon" | "Decagon" | "Dodecagon" | "Star4" | "Star5" | "Star6" | "Star7" | "Star8" | "Star10" | "Star12" | "Star16" | "Star24" | "Star32" | "RoundRectangle" | "Round1Rectangle" | "Round2SameRectangle" | "Round2DiagonalRectangle" | "SnipRoundRectangle" | "Snip1Rectangle" | "Snip2SameRectangle" | "Snip2DiagonalRectangle" | "Plaque" | "Ellipse" | "Teardrop" | "HomePlate" | "Chevron" | "PieWedge" | "Pie" | "BlockArc" | "Donut" | "NoSmoking" | "RightArrow" | "LeftArrow" | "UpArrow" | "DownArrow" | "StripedRightArrow" | "NotchedRightArrow" | "BentUpArrow" | "LeftRightArrow" | "UpDownArrow" | "LeftUpArrow" | "LeftRightUpArrow" | "QuadArrow" | "LeftArrowCallout" | "RightArrowCallout" | "UpArrowCallout" | "DownArrowCallout" | "LeftRightArrowCallout" | "UpDownArrowCallout" | "QuadArrowCallout" | "BentArrow" | "UturnArrow" | "CircularArrow" | "LeftCircularArrow" | "LeftRightCircularArrow" | "CurvedRightArrow" | "CurvedLeftArrow" | "CurvedUpArrow" | "CurvedDownArrow" | "SwooshArrow" | "Cube" | "Can" | "LightningBolt" | "Heart" | "Sun" | "Moon" | "SmileyFace" | "IrregularSeal1" | "IrregularSeal2" | "FoldedCorner" | "Bevel" | "Frame" | "HalfFrame" | "Corner" | "DiagonalStripe" | "Chord" | "Arc" | "LeftBracket" | "RightBracket" | "LeftBrace" | "RightBrace" | "BracketPair" | "BracePair" | "Callout1" | "Callout2" | "Callout3" | "AccentCallout1" | "AccentCallout2" | "AccentCallout3" | "BorderCallout1" | "BorderCallout2" | "BorderCallout3" | "AccentBorderCallout1" | "AccentBorderCallout2" | "AccentBorderCallout3" | "WedgeRectCallout" | "WedgeRRectCallout" | "WedgeEllipseCallout" | "CloudCallout" | "Cloud" | "Ribbon" | "Ribbon2" | "EllipseRibbon" | "EllipseRibbon2" | "LeftRightRibbon" | "VerticalScroll" | "HorizontalScroll" | "Wave" | "DoubleWave" | "Plus" | "FlowChartProcess" | "FlowChartDecision" | "FlowChartInputOutput" | "FlowChartPredefinedProcess" | "FlowChartInternalStorage" | "FlowChartDocument" | "FlowChartMultidocument" | "FlowChartTerminator" | "FlowChartPreparation" | "FlowChartManualInput" | "FlowChartManualOperation" | "FlowChartConnector" | "FlowChartPunchedCard" | "FlowChartPunchedTape" | "FlowChartSummingJunction" | "FlowChartOr" | "FlowChartCollate" | "FlowChartSort" | "FlowChartExtract" | "FlowChartMerge" | "FlowChartOfflineStorage" | "FlowChartOnlineStorage" | "FlowChartMagneticTape" | "FlowChartMagneticDisk" | "FlowChartMagneticDrum" | "FlowChartDisplay" | "FlowChartDelay" | "FlowChartAlternateProcess" | "FlowChartOffpageConnector" | "ActionButtonBlank" | "ActionButtonHome" | "ActionButtonHelp" | "ActionButtonInformation" | "ActionButtonForwardNext" | "ActionButtonBackPrevious" | "ActionButtonEnd" | "ActionButtonBeginning" | "ActionButtonReturn" | "ActionButtonDocument" | "ActionButtonSound" | "ActionButtonMovie" | "Gear6" | "Gear9" | "Funnel" | "MathPlus" | "MathMinus" | "MathMultiply" | "MathDivide" | "MathEqual" | "MathNotEqual" | "CornerTabs" | "SquareTabs" | "PlaqueTabs" | "ChartX" | "ChartStar" | "ChartPlus";

属性值

Excel.GeometricShapeType | "LineInverse" | "Triangle" | "RightTriangle" | "Rectangle" | "Diamond" | "Parallelogram" | "Trapezoid" | "NonIsoscelesTrapezoid" | "Pentagon" | "Hexagon" | "Heptagon" | "Octagon" | "Decagon" | "Dodecagon" | "Star4" | "Star5" | "Star6" | "Star7" | "Star8" | "Star10" | "Star12" | "Star16" | "Star24" | "Star32" | "RoundRectangle" | "Round1Rectangle" | "Round2SameRectangle" | "Round2DiagonalRectangle" | "SnipRoundRectangle" | "Snip1Rectangle" | "Snip2SameRectangle" | "Snip2DiagonalRectangle" | "Plaque" | "Ellipse" | "Teardrop" | "HomePlate" | "Chevron" | "PieWedge" | "Pie" | "BlockArc" | "Donut" | "NoSmoking" | "RightArrow" | "LeftArrow" | "UpArrow" | "DownArrow" | "StripedRightArrow" | "NotchedRightArrow" | "BentUpArrow" | "LeftRightArrow" | "UpDownArrow" | "LeftUpArrow" | "LeftRightUpArrow" | "QuadArrow" | "LeftArrowCallout" | "RightArrowCallout" | "UpArrowCallout" | "DownArrowCallout" | "LeftRightArrowCallout" | "UpDownArrowCallout" | "QuadArrowCallout" | "BentArrow" | "UturnArrow" | "CircularArrow" | "LeftCircularArrow" | "LeftRightCircularArrow" | "CurvedRightArrow" | "CurvedLeftArrow" | "CurvedUpArrow" | "CurvedDownArrow" | "SwooshArrow" | "Cube" | "Can" | "LightningBolt" | "Heart" | "Sun" | "Moon" | "SmileyFace" | "IrregularSeal1" | "IrregularSeal2" | "FoldedCorner" | "Bevel" | "Frame" | "HalfFrame" | "Corner" | "DiagonalStripe" | "Chord" | "Arc" | "LeftBracket" | "RightBracket" | "LeftBrace" | "RightBrace" | "BracketPair" | "BracePair" | "Callout1" | "Callout2" | "Callout3" | "AccentCallout1" | "AccentCallout2" | "AccentCallout3" | "BorderCallout1" | "BorderCallout2" | "BorderCallout3" | "AccentBorderCallout1" | "AccentBorderCallout2" | "AccentBorderCallout3" | "WedgeRectCallout" | "WedgeRRectCallout" | "WedgeEllipseCallout" | "CloudCallout" | "Cloud" | "Ribbon" | "Ribbon2" | "EllipseRibbon" | "EllipseRibbon2" | "LeftRightRibbon" | "VerticalScroll" | "HorizontalScroll" | "Wave" | "DoubleWave" | "Plus" | "FlowChartProcess" | "FlowChartDecision" | "FlowChartInputOutput" | "FlowChartPredefinedProcess" | "FlowChartInternalStorage" | "FlowChartDocument" | "FlowChartMultidocument" | "FlowChartTerminator" | "FlowChartPreparation" | "FlowChartManualInput" | "FlowChartManualOperation" | "FlowChartConnector" | "FlowChartPunchedCard" | "FlowChartPunchedTape" | "FlowChartSummingJunction" | "FlowChartOr" | "FlowChartCollate" | "FlowChartSort" | "FlowChartExtract" | "FlowChartMerge" | "FlowChartOfflineStorage" | "FlowChartOnlineStorage" | "FlowChartMagneticTape" | "FlowChartMagneticDisk" | "FlowChartMagneticDrum" | "FlowChartDisplay" | "FlowChartDelay" | "FlowChartAlternateProcess" | "FlowChartOffpageConnector" | "ActionButtonBlank" | "ActionButtonHome" | "ActionButtonHelp" | "ActionButtonInformation" | "ActionButtonForwardNext" | "ActionButtonBackPrevious" | "ActionButtonEnd" | "ActionButtonBeginning" | "ActionButtonReturn" | "ActionButtonDocument" | "ActionButtonSound" | "ActionButtonMovie" | "Gear6" | "Gear9" | "Funnel" | "MathPlus" | "MathMinus" | "MathMultiply" | "MathDivide" | "MathEqual" | "MathNotEqual" | "CornerTabs" | "SquareTabs" | "PlaqueTabs" | "ChartX" | "ChartStar" | "ChartPlus"

注解

[ API 集：ExcelApi 1.9 ]

group

返回与形状关联的形状组。 如果形状类型不是“GroupShape”，则会引发错误。

readonly group: Excel.ShapeGroup;

属性值

Excel.ShapeGroup

注解

[ API 集：ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-groups.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");

    const shapeGroup = sheet.shapes.getItem("Group").group;
    shapeGroup.ungroup();
    console.log("Shapes ungrouped");

    await context.sync();
});

height

指定形状的高度（以磅为单位）。 InvalidArgument使用负值或零作为输入进行设置时引发异常。

height: number;

属性值

number

注解

[ API 集：ExcelApi 1.9 ]

id

指定形状标识符。

readonly id: string;

属性值

string

注解

[ API 集：ExcelApi 1.9 ]

image

返回与形状关联的图像。 如果形状类型不是“Image”，则会引发错误。

readonly image: Excel.Image;

属性值

Excel.Image

注解

[ API 集：ExcelApi 1.9 ]

left

从形状左侧到工作表左侧的距离（以磅为单位）。 InvalidArgument将负值设置为输入时引发异常。

left: number;

属性值

number

注解

[ API 集：ExcelApi 1.9 ]

level

指定指定形状的级别。 例如，级别 0 表示形状不是任何组的一部分，级别 1 表示形状是顶级组的一部分，级别 2 表示形状是顶级子组的一部分。

readonly level: number;

属性值

number

注解

[ API 集：ExcelApi 1.9 ]

line

返回与形状关联的线条。 如果形状类型不是“Line”，则会引发错误。

readonly line: Excel.Line;

属性值

Excel.Line

注解

[ API 集：ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-lines.yaml

await Excel.run(async (context) => {
    const shapes = context.workbook.worksheets.getItem("Shapes").shapes;
    const line = shapes.getItem("StraightLine").line;
    line.beginArrowheadLength = Excel.ArrowheadLength.long;
    line.beginArrowheadWidth = Excel.ArrowheadWidth.wide;
    line.beginArrowheadStyle = Excel.ArrowheadStyle.oval;

    line.endArrowheadLength = Excel.ArrowheadLength.long;
    line.endArrowheadWidth = Excel.ArrowheadWidth.wide;
    line.endArrowheadStyle = Excel.ArrowheadStyle.triangle;

    await context.sync();
});

lineFormat

返回此形状的线条格式。

readonly lineFormat: Excel.ShapeLineFormat;

属性值

Excel.ShapeLineFormat

注解

[ API 集：ExcelApi 1.9 ]

lockAspectRatio

指定是否锁定此形状的纵横比。

lockAspectRatio: boolean;

属性值

boolean

注解

[ API 集：ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Octagon")
    shape.lockAspectRatio = true;
    shape.scaleHeight(1.25, Excel.ShapeScaleType.currentSize);
    await context.sync();
});

name

指定形状的名称。

name: string;

属性值

string

注解

[ API 集：ExcelApi 1.9 ]

parentGroup

指定此形状的父组。

readonly parentGroup: Excel.Shape;

属性值

Excel.Shape

注解

[ API 集：ExcelApi 1.9 ]

placement

表示对象如何附加到其下方的单元格。

placement: Excel.Placement | "TwoCell" | "OneCell" | "Absolute";

属性值

Excel.Placement | "TwoCell" | "OneCell" | "Absolute"

注解

[ API 集：ExcelApi 1.10 ]

rotation

指定形状的旋转（以度为单位）。

rotation: number;

属性值

number

注解

[ API 集：ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-create-and-delete.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.addGeometricShape(Excel.GeometricShapeType.triangle);
    shape.left = 100;
    shape.top = 300;
    shape.height = 150;
    shape.width = 200;
    shape.rotation = 45;
    shape.fill.clear();
    await context.sync();
});

textFrame

返回此形状的文本框对象。

readonly textFrame: Excel.TextFrame;

属性值

Excel.TextFrame

注解

[ API 集：ExcelApi 1.9 ]

top

从形状上边缘到工作表上边缘之间的距离（以磅为单位）。 InvalidArgument将负值设置为输入时引发异常。

top: number;

属性值

number

注解

[ API 集：ExcelApi 1.9 ]

type

返回此形状的类型。 有关详细信息，请参阅 Excel.ShapeType。

readonly type: Excel.ShapeType | "Unsupported" | "Image" | "GeometricShape" | "Group" | "Line";

属性值

Excel.ShapeType | "Unsupported" | "Image" | "GeometricShape" | "Group" | "Line"

注解

[ API 集：ExcelApi 1.9 ]

visible

指定形状是否可见。

visible: boolean;

属性值

boolean

注解

[ API 集：ExcelApi 1.9 ]

width

指定形状的宽度（以磅为单位）。 InvalidArgument使用负值或零作为输入进行设置时引发异常。

width: number;

属性值

number

注解

[ API 集：ExcelApi 1.9 ]

zOrderPosition

返回指定形状在 z 顺序中的位置，0 表示顺序堆栈的底部。

readonly zOrderPosition: number;

属性值

number

注解

[ API 集：ExcelApi 1.9 ]

方法详细信息

copyTo(destinationSheet)

复制并粘贴 Shape 对象。 粘贴的形状将复制到此形状所在的同一像素位置。

copyTo(destinationSheet?: Worksheet | string): Excel.Shape;

参数

destinationSheet

Excel.Worksheet | string

形状对象将粘贴到的工作表。 默认值为复制形状的工作表。

返回

Excel.Shape

注解

[ API 集：ExcelApi 1.10 ]

delete()

从工作表删除形状。

delete(): void;

返回

void

注解

[ API 集：ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-create-and-delete.yaml

await Excel.run(async (context) => {
    context.workbook.worksheets.getItemOrNullObject("Shapes").delete();
    const sheet = context.workbook.worksheets.add("Shapes");

    const shapes = sheet.shapes;

    // load all the shapes in the collection without loading their properties
    shapes.load("items/$none");
    await context.sync();

    shapes.items.forEach((shape) => shape.delete());
    await context.sync();
});

getAsImage(format)

将形状转换为图像，并将图像作为 Base64 编码的字符串返回。 DPI 为 96。 唯一支持的格式是 Excel.PictureFormat.BMP、Excel.PictureFormat.PNG、Excel.PictureFormat.JPEG 和 。Excel.PictureFormat.GIF

getAsImage(format: Excel.PictureFormat): OfficeExtension.ClientResult<string>;

参数

format
Excel.PictureFormat

指定图像的格式。

返回

OfficeExtension.ClientResult<string>

注解

[ API 集：ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-images.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Image");
    const result = shape.getAsImage(Excel.PictureFormat.png);
    await context.sync();

    const imageString = result.value;
    // Your add-in would save this string as a .png file.
    console.log("The image's Base64-encoded string: " + imageString);
});

getAsImage(formatString)

将形状转换为图像，并将图像作为 Base64 编码的字符串返回。 DPI 为 96。 唯一支持的格式是 Excel.PictureFormat.BMP、Excel.PictureFormat.PNG、Excel.PictureFormat.JPEG 和 。Excel.PictureFormat.GIF

getAsImage(formatString: "UNKNOWN" | "BMP" | "JPEG" | "GIF" | "PNG" | "SVG"): OfficeExtension.ClientResult<string>;

参数

formatString

"UNKNOWN" | "BMP" | "JPEG" | "GIF" | "PNG" | "SVG"

指定图像的格式。

返回

OfficeExtension.ClientResult<string>

注解

[ API 集：ExcelApi 1.9 ]

incrementLeft(increment)

以指定磅数水平移动形状。

incrementLeft(increment: number): void;

参数

increment

number

该增量（以磅为单位）将水平移动形状。 正值将形状向右移动，负值将形状向左移动。 如果工作表是从右向左方向的，则相反：正值会将形状向左移动，负值会将形状向右移动。

返回

void

注解

[ API 集：ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Square")
    shape.incrementLeft(-25);
    await context.sync();
});

incrementRotation(increment)

将形状围绕 z 轴旋转特定度数。 rotation使用 属性设置形状的绝对旋转。

incrementRotation(increment: number): void;

参数

increment

number

形状将旋转多少度。 正值顺时针旋转形状，负值逆时针旋转形状。

返回

void

注解

[ API 集：ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-images.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Image");
    shape.incrementRotation(180);
    await context.sync();
});

incrementTop(increment)

以指定磅数垂直移动形状。

incrementTop(increment: number): void;

参数

increment

number

增量（以磅为单位）将垂直移动形状。 正值将形状向下移动，负值将形状向上移动。

返回

void

注解

[ API 集：ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Pentagon")
    shape.incrementTop(25);
    await context.sync();
});

load(options)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。

load(options?: Excel.Interfaces.ShapeLoadOptions): Excel.Shape;

参数

options
Excel.Interfaces.ShapeLoadOptions

提供要加载对象的属性的选项。

返回

Excel.Shape

load(propertyNames)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。

load(propertyNames?: string | string[]): Excel.Shape;

参数

propertyNames

string | string[]

逗号分隔的字符串或指定要加载的属性的字符串数组。

返回

Excel.Shape

load(propertyNamesAndPaths)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.Shape;

参数

propertyNamesAndPaths

{ select?: string; expand?: string; }

propertyNamesAndPaths.select 是一个逗号分隔的字符串，指定要加载的属性，是 propertyNamesAndPaths.expand 一个逗号分隔的字符串，指定要加载的导航属性。

返回

Excel.Shape

scaleHeight(scaleFactor, scaleType, scaleFrom)

按指定因子缩放形状的高度。 对于图像，你可以说明是相对于原始尺寸还是当前尺寸缩放形状。 对于除图片以外的其他形状来说，缩放总是相对于其当前高度而言。

scaleHeight(scaleFactor: number, scaleType: Excel.ShapeScaleType, scaleFrom?: Excel.ShapeScaleFrom): void;

参数

scaleFactor

number

指定形状调整后的高度与当前或原始高度的比例。

scaleType
Excel.ShapeScaleType

指定是相对于其原始大小还是当前大小缩放形状。 原始大小缩放选项仅适用于图像。

scaleFrom
Excel.ShapeScaleFrom

可选。 指定在缩放形状时，该形状的哪一部分将保持在原有的位置。 如果省略，则表示形状的左上角保留其位置。

返回

void

注解

[ API 集：ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Octagon")
    shape.lockAspectRatio = true;
    shape.scaleHeight(1.25, Excel.ShapeScaleType.currentSize);
    await context.sync();
});

scaleHeight(scaleFactor, scaleTypeString, scaleFromString)

按指定因子缩放形状的高度。 对于图像，你可以说明是相对于原始尺寸还是当前尺寸缩放形状。 对于除图片以外的其他形状来说，缩放总是相对于其当前高度而言。

scaleHeight(scaleFactor: number, scaleTypeString: "CurrentSize" | "OriginalSize", scaleFromString?: "ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"): void;

参数

scaleFactor

number

指定形状调整后的高度与当前或原始高度的比例。

scaleTypeString

"CurrentSize" | "OriginalSize"

指定是相对于其原始大小还是当前大小缩放形状。 原始大小缩放选项仅适用于图像。

scaleFromString

"ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

可选。 指定在缩放形状时，该形状的哪一部分将保持在原有的位置。 如果省略，则表示形状的左上角保留其位置。

返回

void

注解

[ API 集：ExcelApi 1.9 ]

scaleWidth(scaleFactor, scaleType, scaleFrom)

按指定因子缩放形状的宽度。 对于图像，你可以说明是相对于原始尺寸还是当前尺寸缩放形状。 对于除图片以外的其他形状来说，缩放总是相对于其当前宽度而言。

scaleWidth(scaleFactor: number, scaleType: Excel.ShapeScaleType, scaleFrom?: Excel.ShapeScaleFrom): void;

参数

scaleFactor

number

指定形状调整后的宽度与当前或原始宽度的比例。

scaleType
Excel.ShapeScaleType

指定是相对于其原始大小还是当前大小缩放形状。 原始大小缩放选项仅适用于图像。

scaleFrom
Excel.ShapeScaleFrom

可选。 指定在缩放形状时，该形状的哪一部分将保持在原有的位置。 如果省略，则表示形状的左上角保留其位置。

返回

void

注解

[ API 集：ExcelApi 1.9 ]

scaleWidth(scaleFactor, scaleTypeString, scaleFromString)

按指定因子缩放形状的宽度。 对于图像，你可以说明是相对于原始尺寸还是当前尺寸缩放形状。 对于除图片以外的其他形状来说，缩放总是相对于其当前宽度而言。

scaleWidth(scaleFactor: number, scaleTypeString: "CurrentSize" | "OriginalSize", scaleFromString?: "ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"): void;

参数

scaleFactor

number

指定形状调整后的宽度与当前或原始宽度的比例。

scaleTypeString

"CurrentSize" | "OriginalSize"

指定是相对于其原始大小还是当前大小缩放形状。 原始大小缩放选项仅适用于图像。

scaleFromString

"ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

可选。 指定在缩放形状时，该形状的哪一部分将保持在原有的位置。 如果省略，则表示形状的左上角保留其位置。

返回

void

注解

[ API 集：ExcelApi 1.9 ]

set(properties, options)

同时设置对象的多个属性。 可以传递具有相应属性的纯对象，也可以传递同一类型的另一个 API 对象。

set(properties: Interfaces.ShapeUpdateData, options?: OfficeExtension.UpdateOptions): void;

参数

properties
Excel.Interfaces.ShapeUpdateData

一个 JavaScript 对象，其属性按同构方式构造为调用方法的对象的属性。

options
OfficeExtension.UpdateOptions

提供一个选项，用于在 properties 对象尝试设置任何只读属性时禁止显示错误。

返回

void

set(properties)

基于现有的已加载对象，同时对对象设置多个属性。

set(properties: Excel.Shape): void;

参数

properties
Excel.Shape

返回

void

setZOrder(position)

将指定形状沿集合的 z 顺序向上或向下移动，将其移动到其他形状的前面或后面。

setZOrder(position: Excel.ShapeZOrder): void;

参数

position
Excel.ShapeZOrder

相对于其他形状移动 z 顺序堆栈中的形状的位置。 有关详细信息，请参阅 Excel.ShapeZOrder。

返回

void

注解

[ API 集：ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Octagon")
    shape.setZOrder(Excel.ShapeZOrder.sendBackward);
    await context.sync();
});

setZOrder(positionString)

将指定形状沿集合的 z 顺序向上或向下移动，将其移动到其他形状的前面或后面。

setZOrder(positionString: "BringToFront" | "BringForward" | "SendToBack" | "SendBackward"): void;

参数

positionString

"BringToFront" | "BringForward" | "SendToBack" | "SendBackward"

相对于其他形状移动 z 顺序堆栈中的形状的位置。 有关详细信息，请参阅 Excel.ShapeZOrder。

返回

void

注解

[ API 集：ExcelApi 1.9 ]

toJSON()

重写 JavaScript toJSON() 方法，以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 JSON.stringify (，反过来又调用toJSON传递给它的 对象的 方法。) 而原始Excel.Shape对象是 API 对象，toJSON该方法返回一个纯 JavaScript 对象， (类型为 Excel.Interfaces.ShapeData) ，其中包含原始对象中任何已加载子属性的浅表副本。

toJSON(): Excel.Interfaces.ShapeData;

返回

Excel.Interfaces.ShapeData

事件详细信息

onActivated

当激活形状时发生此事件。

readonly onActivated: OfficeExtension.EventHandlers<Excel.ShapeActivatedEventArgs>;

事件类型

OfficeExtension.EventHandlers<Excel.ShapeActivatedEventArgs>

注解

[ API 集：ExcelApi 1.9 ]

onDeactivated

当停用形状时发生此事件。

readonly onDeactivated: OfficeExtension.EventHandlers<Excel.ShapeDeactivatedEventArgs>;

事件类型

OfficeExtension.EventHandlers<Excel.ShapeDeactivatedEventArgs>

注解

[ API 集：ExcelApi 1.9 ]