Excel.Shape class

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

扩展

属性

altTextDescription

指定对象的替代说明文本 Shape 。

altTextTitle

指定对象的备用标题文本 Shape 。

connectionSiteCount

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

context

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

displayName

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

fill

返回此形状的填充格式。

geometricShape

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

geometricShapeType

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

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.JPEGExcel.PictureFormat.PNG和 。Excel.PictureFormat.GIF

getAsImage(format)

将形状转换为图像,并将图像作为 Base64 编码的字符串返回。 DPI 为 96。 唯一支持的格式为 Excel.PictureFormat.BMP、 、 Excel.PictureFormat.JPEGExcel.PictureFormat.PNG和 。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, scaleType, scaleFrom)

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

scaleWidth(scaleFactor, scaleType, scaleFrom)

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

scaleWidth(scaleFactor, scaleType, scaleFrom)

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

set(properties, options)

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

set(properties)

基于现有加载的对象,同时在对象上设置多个属性。

setZOrder(position)

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

setZOrder(position)

将指定形状沿集合的 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;

属性值

displayName

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

readonly displayName: string;

属性值

string

注解

API 集:ExcelApi 1.15

fill

返回此形状的填充格式。

readonly fill: Excel.ShapeFill;

属性值

注解

API 集:ExcelApi 1.9

示例

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

await Excel.run(async (context) => {
    // Apply a solid fill color to the shape.
    const sheet = context.workbook.worksheets.getItem("Sample");
    const badge = sheet.shapes.getItem("Badge");
    const shapeFill: Excel.ShapeFill = badge.fill;
    shapeFill.setSolidColor("#FFE08A");

    await context.sync();
});

geometricShape

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

readonly geometricShape: Excel.GeometricShape;

属性值

注解

API 集:ExcelApi 1.9

geometricShapeType

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

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;

属性值

注解

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

示例

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

await Excel.run(async (context) => {
    const shapes = context.workbook.worksheets.getItem("Shapes").shapes;
    const textbox: Excel.Shape = shapes.addTextBox("A box with text");
    textbox.left = 100;
    textbox.top = 100;
    textbox.height = 20;
    textbox.width = 175;
    textbox.name = "Textbox";
    await context.sync();
});

id

指定形状标识符。

readonly id: string;

属性值

string

注解

API 集:ExcelApi 1.9

image

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

readonly 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;

属性值

注解

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;

属性值

注解

API 集:ExcelApi 1.9

示例

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

await Excel.run(async (context) => {
    // Load and log the shape's fill and outline properties.
    const sheet = context.workbook.worksheets.getItem("Sample");
    const badge = sheet.shapes.getItem("Badge");
    badge.fill.load(["foregroundColor", "transparency", "type"]);
    badge.lineFormat.load(["color", "dashStyle", "style", "transparency", "visible", "weight"]);

    await context.sync();

    console.log("Badge fill: " + JSON.stringify(badge.fill));
    console.log("Badge line format: " + JSON.stringify(badge.lineFormat));
});

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

示例

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

// This method groups the new chart title shape together with the existing chart.
await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getItem(sheetName);
  
  // Get the shapes to group.
  const titleShape = sheet.shapes.getItem("ChartTitle");
  const chartShape = sheet.shapes.getItem("SalesChart");
  
  // Create a group from the two shapes.
  const shapeGroup = sheet.shapes.addGroup([titleShape, chartShape]);
  shapeGroup.name = "GroupChart";
  
  await context.sync();
});

parentGroup

指定此形状的父组。

readonly parentGroup: 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;

属性值

注解

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

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

返回

注解

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.JPEGExcel.PictureFormat.PNG和 。Excel.PictureFormat.GIF

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

参数

format
Excel.PictureFormat

指定图像的格式。

返回

注解

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(format)

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

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

参数

format

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

指定图像的格式。

返回

注解

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

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

返回

load(propertyNames)

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

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

参数

propertyNames

string | string[]

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

返回

load(propertyNamesAndPaths)

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

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

参数

propertyNamesAndPaths

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

propertyNamesAndPaths.select 是指定要加载的属性的逗号分隔字符串,以及 propertyNamesAndPaths.expand 指定要加载的导航属性的逗号分隔字符串。

返回

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, scaleType, scaleFrom)

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

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

参数

scaleFactor

number

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

scaleType

"CurrentSize" | "OriginalSize"

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

scaleFrom

"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, scaleType, scaleFrom)

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

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

参数

scaleFactor

number

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

scaleType

"CurrentSize" | "OriginalSize"

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

scaleFrom

"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(position)

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

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

参数

position

"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;

返回

事件详细信息

onActivated

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

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

事件类型

注解

API 集:ExcelApi 1.9

onDeactivated

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

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

事件类型

注解

API 集:ExcelApi 1.9