Excel.Shape class

Paket:

excel

Stellt ein generisches Formobjekt im Arbeitsblatt dar. Eine Form kann eine geometrische Form, eine Linie, eine Gruppe von Formen usw. sein. Weitere Informationen zum Shape-Objektmodell finden Sie unter Arbeiten mit Shapes mithilfe der Excel-JavaScript-API.

Extends

OfficeExtension.ClientObject

Hinweise

[ API-Satz: ExcelApi 1.9 ]

Eigenschaften

altTextDescription	Gibt den alternativen Beschreibungstext für ein Shape -Objekt an.
altTextTitle	Gibt den alternativen Titeltext für ein Shape -Objekt an.
connectionSiteCount	Gibt die Anzahl der Verbindungsseiten für diese Form zurück.
context	Der Anforderungskontext, der dem -Objekt zugeordnet ist. Dadurch wird der Prozess des Add-Ins mit dem Prozess der Office-Hostanwendung verbunden.
fill	Gibt die Füllungsformatierung dieser Form zurück.
geometricShape	Gibt die der Form zugeordnete geometrische Form zurück. Es wird ein Fehler ausgelöst, wenn der Formtyp nicht "GeometricShape" ist.
geometricShapeType	Gibt den geometrischen Formtyp dieser geometrischen Form an. Weitere Informationen finden Sie unter Excel.GeometricShapeType . Gibt zurück null , wenn der Formtyp nicht "GeometricShape" ist.
group	Gibt die der Form zugeordnete Formgruppe zurück. Es wird ein Fehler ausgelöst, wenn der Formtyp nicht "GroupShape" ist.
height	Gibt die Höhe der Form in Punkt an. Löst eine Ausnahme aus InvalidArgument , wenn als Eingabe mit einem negativen Wert oder 0 (null) festgelegt wird.
id	Gibt den Shape-Bezeichner an.
image	Gibt das Bild zurück, das der Form zugeordnet ist. Es wird ein Fehler ausgelöst, wenn der Formtyp nicht "Image" ist.
left	Der Abstand in Punkten von der linken Seite der Form zur linken Seite des Arbeitsblatts. Löst eine InvalidArgument Ausnahme aus, wenn mit einem negativen Wert als Eingabe festgelegt wird.
level	Gibt die Ebene der angegebenen Form an. Beispielsweise bedeutet die Ebene 0, dass die Form nicht Teil von Gruppen ist, die Ebene 1 bedeutet, die Form ist Teil einer Gruppe der obersten Ebene, und die Ebene 2 bedeutet, dass die Form Teil einer Untergruppe der obersten Ebene ist.
line	Gibt die Linie zurück, die der Form zugeordnet ist. Es wird ein Fehler ausgelöst, wenn der Formtyp nicht "Line" ist.
lineFormat	Gibt die Linienformatierung dieser Form zurück.
lockAspectRatio	Gibt an, ob das Seitenverhältnis dieser Form gesperrt ist.
name	Gibt den Namen der Form an.
parentGroup	Gibt die übergeordnete Gruppe dieser Form an.
placement	Stellt dar, wie das Objekt an die Zellen darunter angefügt ist.
rotation	Gibt die Drehung der Form in Grad an.
textFrame	Gibt das textFrame-Objekt dieser Form zurück.
top	Der Abstand in Punkten zwischen der oberen Kante der Form und der oberen Kante der Arbeitsmappe. Löst eine InvalidArgument Ausnahme aus, wenn mit einem negativen Wert als Eingabe festgelegt wird.
type	Gibt den Typ dieser Form zurück. Weitere Informationen finden Sie unter Excel.ShapeType .
visible	Gibt an, ob die Form sichtbar ist.
width	Gibt die Breite der Form in Punkt an. Löst eine Ausnahme aus InvalidArgument , wenn als Eingabe mit einem negativen Wert oder 0 (null) festgelegt wird.
zOrderPosition	Gibt die Position der angegebenen Form in der Z-Reihenfolge an, wobei 0 den Boden des Reihenfolgestapels darstellt.

Methoden

copyTo(destinationSheet)	Kopiert ein Objekt und fügt es ein Shape . Die eingefügte Form wird an die gleiche Pixelposition wie dieses Shape kopiert.
delete()	Entfernt die Form aus dem Arbeitsblatt.
getAsImage(format)	Konvertiert die Form in ein Bild und gibt das Bild als Base64-codierte Zeichenfolge zurück. Der DPI-Wert ist 96. Die einzigen unterstützten Formate sind Excel.PictureFormat.BMP, Excel.PictureFormat.PNG, Excel.PictureFormat.JPEGund Excel.PictureFormat.GIF.
getAsImage(formatString)	Konvertiert die Form in ein Bild und gibt das Bild als Base64-codierte Zeichenfolge zurück. Der DPI-Wert ist 96. Die einzigen unterstützten Formate sind Excel.PictureFormat.BMP, Excel.PictureFormat.PNG, Excel.PictureFormat.JPEGund Excel.PictureFormat.GIF.
incrementLeft(increment)	Verschiebt die Form horizontal um die angegebene Punktanzahl.
incrementRotation(increment)	Dreht die Form um die angegebene Gradzahl um die Z-Achse. Verwenden Sie die rotation -Eigenschaft, um die absolute Drehung der Form festzulegen.
incrementTop(increment)	Verschiebt die Form vertikal um die angegebene Anzahl von Punkten.
load(options)	Stellt einen Befehl zum Laden der angegebenen Eigenschaften des Objekts in die Warteschlange ein. Vor dem Lesen der Eigenschaften müssen Sie "context.sync()" aufrufen.
load(propertyNames)	Stellt einen Befehl zum Laden der angegebenen Eigenschaften des Objekts in die Warteschlange ein. Vor dem Lesen der Eigenschaften müssen Sie "context.sync()" aufrufen.
load(propertyNamesAndPaths)	Stellt einen Befehl zum Laden der angegebenen Eigenschaften des Objekts in die Warteschlange ein. Vor dem Lesen der Eigenschaften müssen Sie "context.sync()" aufrufen.
scaleHeight(scaleFactor, scaleType, scaleFrom)	Skaliert die Höhe der Form anhand eines angegebenen Faktors. Für Bilder können Sie angeben, ob Sie die Form relativ zum Original oder zur aktuellen Größe skalieren möchten. Andere Formen als Bilder werden immer relativ zu ihrer aktuellen Höhe skaliert.
scaleHeight(scaleFactor, scaleTypeString, scaleFromString)	Skaliert die Höhe der Form anhand eines angegebenen Faktors. Für Bilder können Sie angeben, ob Sie die Form relativ zum Original oder zur aktuellen Größe skalieren möchten. Andere Formen als Bilder werden immer relativ zu ihrer aktuellen Höhe skaliert.
scaleWidth(scaleFactor, scaleType, scaleFrom)	Skaliert die Breite der Form anhand eines angegebenen Faktors. Für Bilder können Sie angeben, ob Sie die Form relativ zum Original oder zur aktuellen Größe skalieren möchten. Andere Formen als Bilder werden immer relativ zu ihrer aktuellen Breite skaliert.
scaleWidth(scaleFactor, scaleTypeString, scaleFromString)	Skaliert die Breite der Form anhand eines angegebenen Faktors. Für Bilder können Sie angeben, ob Sie die Form relativ zum Original oder zur aktuellen Größe skalieren möchten. Andere Formen als Bilder werden immer relativ zu ihrer aktuellen Breite skaliert.
set(properties, options)	Legt mehrere Eigenschaften eines Objekts gleichzeitig fest. Sie können entweder ein einfaches Objekt mit den entsprechenden Eigenschaften oder ein anderes API-Objekt desselben Typs übergeben.
set(properties)	Legt mehrere Eigenschaften für das -Objekt gleichzeitig fest, basierend auf einem vorhandenen geladenen Objekt.
setZOrder(position)	Verschiebt de angegebene Form in der Z-Reihenfolge der Sammlung nach oben oder unten, wodurch sie vor oder hinter anderen Formen zu liegen kommt.
setZOrder(positionString)	Verschiebt de angegebene Form in der Z-Reihenfolge der Sammlung nach oben oder unten, wodurch sie vor oder hinter anderen Formen zu liegen kommt.
toJSON()	Überschreibt die JavaScript-Methode toJSON() , um eine nützlichere Ausgabe bereitzustellen, wenn ein API-Objekt an JSON.stringify()übergeben wird. (JSON.stringifyruft wiederum die toJSON -Methode des Objekts auf, das an das Objekt übergeben wird.) Während das ursprüngliche Excel.Shape Objekt ein API-Objekt ist, gibt die toJSON Methode ein einfaches JavaScript-Objekt (typisiert als Excel.Interfaces.ShapeData) zurück, das flache Kopien aller geladenen untergeordneten Eigenschaften aus dem ursprünglichen Objekt enthält.

Ereignisse

onActivated	Tritt ein, wenn die Form aktiviert wird.
onDeactivated	Tritt ein, wenn die Form deaktiviert wird.

Details zur Eigenschaft

altTextDescription

Gibt den alternativen Beschreibungstext für ein Shape -Objekt an.

altTextDescription: string;

Eigenschaftswert

string

Hinweise

[ API-Satz: ExcelApi 1.9 ]

altTextTitle

Gibt den alternativen Titeltext für ein Shape -Objekt an.

altTextTitle: string;

Eigenschaftswert

string

Hinweise

[ API-Satz: ExcelApi 1.9 ]

connectionSiteCount

Gibt die Anzahl der Verbindungsseiten für diese Form zurück.

readonly connectionSiteCount: number;

Eigenschaftswert

number

Hinweise

[ API-Satz: ExcelApi 1.9 ]

context

Der Anforderungskontext, der dem -Objekt zugeordnet ist. Dadurch wird der Prozess des Add-Ins mit dem Prozess der Office-Hostanwendung verbunden.

context: RequestContext;

Eigenschaftswert

Excel.RequestContext

fill

Gibt die Füllungsformatierung dieser Form zurück.

readonly fill: Excel.ShapeFill;

Eigenschaftswert

Excel.ShapeFill

Hinweise

[ API-Satz: ExcelApi 1.9 ]

Beispiele

// 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

Gibt die der Form zugeordnete geometrische Form zurück. Es wird ein Fehler ausgelöst, wenn der Formtyp nicht "GeometricShape" ist.

readonly geometricShape: Excel.GeometricShape;

Eigenschaftswert

Excel.GeometricShape

Hinweise

[ API-Satz: ExcelApi 1.9 ]

geometricShapeType

Gibt den geometrischen Formtyp dieser geometrischen Form an. Weitere Informationen finden Sie unter Excel.GeometricShapeType . Gibt zurück null , wenn der Formtyp nicht "GeometricShape" ist.

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

Eigenschaftswert

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"

Hinweise

[ API-Satz: ExcelApi 1.9 ]

group

Gibt die der Form zugeordnete Formgruppe zurück. Es wird ein Fehler ausgelöst, wenn der Formtyp nicht "GroupShape" ist.

readonly group: Excel.ShapeGroup;

Eigenschaftswert

Excel.ShapeGroup

Hinweise

[ API-Satz: ExcelApi 1.9 ]

Beispiele

// 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

Gibt die Höhe der Form in Punkt an. Löst eine Ausnahme aus InvalidArgument , wenn als Eingabe mit einem negativen Wert oder 0 (null) festgelegt wird.

height: number;

Eigenschaftswert

number

Hinweise

[ API-Satz: ExcelApi 1.9 ]

id

Gibt den Shape-Bezeichner an.

readonly id: string;

Eigenschaftswert

string

Hinweise

[ API-Satz: ExcelApi 1.9 ]

image

Gibt das Bild zurück, das der Form zugeordnet ist. Es wird ein Fehler ausgelöst, wenn der Formtyp nicht "Image" ist.

readonly image: Excel.Image;

Eigenschaftswert

Excel.Image

Hinweise

[ API-Satz: ExcelApi 1.9 ]

left

Der Abstand in Punkten von der linken Seite der Form zur linken Seite des Arbeitsblatts. Löst eine InvalidArgument Ausnahme aus, wenn mit einem negativen Wert als Eingabe festgelegt wird.

left: number;

Eigenschaftswert

number

Hinweise

[ API-Satz: ExcelApi 1.9 ]

level

Gibt die Ebene der angegebenen Form an. Beispielsweise bedeutet die Ebene 0, dass die Form nicht Teil von Gruppen ist, die Ebene 1 bedeutet, die Form ist Teil einer Gruppe der obersten Ebene, und die Ebene 2 bedeutet, dass die Form Teil einer Untergruppe der obersten Ebene ist.

readonly level: number;

Eigenschaftswert

number

Hinweise

[ API-Satz: ExcelApi 1.9 ]

line

Gibt die Linie zurück, die der Form zugeordnet ist. Es wird ein Fehler ausgelöst, wenn der Formtyp nicht "Line" ist.

readonly line: Excel.Line;

Eigenschaftswert

Excel.Line

Hinweise

[ API-Satz: ExcelApi 1.9 ]

Beispiele

// 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

Gibt die Linienformatierung dieser Form zurück.

readonly lineFormat: Excel.ShapeLineFormat;

Eigenschaftswert

Excel.ShapeLineFormat

Hinweise

[ API-Satz: ExcelApi 1.9 ]

lockAspectRatio

Gibt an, ob das Seitenverhältnis dieser Form gesperrt ist.

lockAspectRatio: boolean;

Eigenschaftswert

boolean

Hinweise

[ API-Satz: ExcelApi 1.9 ]

Beispiele

// 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

Gibt den Namen der Form an.

name: string;

Eigenschaftswert

string

Hinweise

[ API-Satz: ExcelApi 1.9 ]

parentGroup

Gibt die übergeordnete Gruppe dieser Form an.

readonly parentGroup: Excel.Shape;

Eigenschaftswert

Excel.Shape

Hinweise

[ API-Satz: ExcelApi 1.9 ]

placement

Stellt dar, wie das Objekt an die Zellen darunter angefügt ist.

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

Eigenschaftswert

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

Hinweise

[ API-Satz: ExcelApi 1.10 ]

rotation

Gibt die Drehung der Form in Grad an.

rotation: number;

Eigenschaftswert

number

Hinweise

[ API-Satz: ExcelApi 1.9 ]

Beispiele

// 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

Gibt das textFrame-Objekt dieser Form zurück.

readonly textFrame: Excel.TextFrame;

Eigenschaftswert

Excel.TextFrame

Hinweise

[ API-Satz: ExcelApi 1.9 ]

top

Der Abstand in Punkten zwischen der oberen Kante der Form und der oberen Kante der Arbeitsmappe. Löst eine InvalidArgument Ausnahme aus, wenn mit einem negativen Wert als Eingabe festgelegt wird.

top: number;

Eigenschaftswert

number

Hinweise

[ API-Satz: ExcelApi 1.9 ]

type

Gibt den Typ dieser Form zurück. Weitere Informationen finden Sie unter Excel.ShapeType .

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

Eigenschaftswert

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

Hinweise

[ API-Satz: ExcelApi 1.9 ]

visible

Gibt an, ob die Form sichtbar ist.

visible: boolean;

Eigenschaftswert

boolean

Hinweise

[ API-Satz: ExcelApi 1.9 ]

width

Gibt die Breite der Form in Punkt an. Löst eine Ausnahme aus InvalidArgument , wenn als Eingabe mit einem negativen Wert oder 0 (null) festgelegt wird.

width: number;

Eigenschaftswert

number

Hinweise

[ API-Satz: ExcelApi 1.9 ]

zOrderPosition

Gibt die Position der angegebenen Form in der Z-Reihenfolge an, wobei 0 den Boden des Reihenfolgestapels darstellt.

readonly zOrderPosition: number;

Eigenschaftswert

number

Hinweise

[ API-Satz: ExcelApi 1.9 ]

Details zur Methode

copyTo(destinationSheet)

Kopiert ein Objekt und fügt es ein Shape . Die eingefügte Form wird an die gleiche Pixelposition wie dieses Shape kopiert.

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

Parameter

destinationSheet

Excel.Worksheet | string

Das Blatt, in das das Shape-Objekt eingefügt wird. Der Standardwert ist das Arbeitsblatt der kopierten Form.

Gibt zurück

Excel.Shape

Hinweise

[ API-Satz: ExcelApi 1.10 ]

delete()

Entfernt die Form aus dem Arbeitsblatt.

delete(): void;

Gibt zurück

void

Hinweise

[ API-Satz: ExcelApi 1.9 ]

Beispiele

// 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)

Konvertiert die Form in ein Bild und gibt das Bild als Base64-codierte Zeichenfolge zurück. Der DPI-Wert ist 96. Die einzigen unterstützten Formate sind Excel.PictureFormat.BMP, Excel.PictureFormat.PNG, Excel.PictureFormat.JPEGund Excel.PictureFormat.GIF.

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

Parameter

format

Excel.PictureFormat

Gibt das Format des Bilds an.

Gibt zurück

OfficeExtension.ClientResult<string>

Hinweise

[ API-Satz: ExcelApi 1.9 ]

Beispiele

// 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)

Konvertiert die Form in ein Bild und gibt das Bild als Base64-codierte Zeichenfolge zurück. Der DPI-Wert ist 96. Die einzigen unterstützten Formate sind Excel.PictureFormat.BMP, Excel.PictureFormat.PNG, Excel.PictureFormat.JPEGund Excel.PictureFormat.GIF.

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

Parameter

formatString

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

Gibt das Format des Bilds an.

Gibt zurück

OfficeExtension.ClientResult<string>

Hinweise

[ API-Satz: ExcelApi 1.9 ]

incrementLeft(increment)

Verschiebt die Form horizontal um die angegebene Punktanzahl.

incrementLeft(increment: number): void;

Parameter

increment

number

Das Inkrement in Punkt wird die Form horizontal verschoben. Ein positiver Wert verschiebt die Form nach rechts und ein negativer Wert nach links. Wenn das Blatt von rechts nach links ausgerichtet ist, wird dies umgekehrt: Positive Werte verschieben die Form nach links und negative Werte nach rechts.

Gibt zurück

void

Hinweise

[ API-Satz: ExcelApi 1.9 ]

Beispiele

// 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)

Dreht die Form um die angegebene Gradzahl um die Z-Achse. Verwenden Sie die rotation -Eigenschaft, um die absolute Drehung der Form festzulegen.

incrementRotation(increment: number): void;

Parameter

increment

number

Wie viele Grad die Form gedreht wird. Ein positiver Wert dreht die Form im Uhrzeigersinn, und ein negativer Wert dreht sie gegen den Uhrzeigersinn.

Gibt zurück

void

Hinweise

[ API-Satz: ExcelApi 1.9 ]

Beispiele

// 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)

Verschiebt die Form vertikal um die angegebene Anzahl von Punkten.

incrementTop(increment: number): void;

Parameter

increment

number

Das Inkrement in Punkt wird die Form vertikal verschoben. Ein positiver Wert verschiebt die Form nach unten, und ein negativer Wert verschiebt sie nach oben.

Gibt zurück

void

Hinweise

[ API-Satz: ExcelApi 1.9 ]

Beispiele

// 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)

Stellt einen Befehl zum Laden der angegebenen Eigenschaften des Objekts in die Warteschlange ein. Vor dem Lesen der Eigenschaften müssen Sie "context.sync()" aufrufen.

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

Parameter

options

Excel.Interfaces.ShapeLoadOptions

Stellt Optionen dafür bereit, welche Eigenschaften des -Objekts geladen werden sollen.

Gibt zurück

Excel.Shape

load(propertyNames)

Stellt einen Befehl zum Laden der angegebenen Eigenschaften des Objekts in die Warteschlange ein. Vor dem Lesen der Eigenschaften müssen Sie "context.sync()" aufrufen.

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

Parameter

propertyNames

string | string[]

Eine durch Trennzeichen getrennte Zeichenfolge oder ein Array von Zeichenfolgen, die die zu ladenden Eigenschaften angeben.

Gibt zurück

Excel.Shape

load(propertyNamesAndPaths)

Stellt einen Befehl zum Laden der angegebenen Eigenschaften des Objekts in die Warteschlange ein. Vor dem Lesen der Eigenschaften müssen Sie "context.sync()" aufrufen.

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

Parameter

propertyNamesAndPaths

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

propertyNamesAndPaths.select ist eine durch Trennzeichen getrennte Zeichenfolge, die die zu ladenden Eigenschaften angibt, und propertyNamesAndPaths.expand eine durch Trennzeichen getrennte Zeichenfolge, die die zu ladenden Navigationseigenschaften angibt.

Gibt zurück

Excel.Shape

scaleHeight(scaleFactor, scaleType, scaleFrom)

Skaliert die Höhe der Form anhand eines angegebenen Faktors. Für Bilder können Sie angeben, ob Sie die Form relativ zum Original oder zur aktuellen Größe skalieren möchten. Andere Formen als Bilder werden immer relativ zu ihrer aktuellen Höhe skaliert.

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

Parameter

scaleFactor

number

Gibt das Verhältnis zwischen der Höhe der Form nach der Änderung ihrer Größe und der aktuellen oder ursprünglichen Höhe an.

scaleType

Excel.ShapeScaleType

Gibt an, ob die Form relativ zur ursprünglichen oder aktuellen Größe skaliert wird. Die Ursprüngliche Größenskalierungsoption funktioniert nur für Bilder.

scaleFrom

Excel.ShapeScaleFrom

Optional. Gibt an, welcher Teil der Form beim Skalieren die Position beibehält. Wenn sie nicht angegeben wird, stellt sie dar, dass die obere linke Ecke der Form ihre Position behält.

Gibt zurück

void

Hinweise

[ API-Satz: ExcelApi 1.9 ]

Beispiele

// 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)

Skaliert die Höhe der Form anhand eines angegebenen Faktors. Für Bilder können Sie angeben, ob Sie die Form relativ zum Original oder zur aktuellen Größe skalieren möchten. Andere Formen als Bilder werden immer relativ zu ihrer aktuellen Höhe skaliert.

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

Parameter

scaleFactor

number

Gibt das Verhältnis zwischen der Höhe der Form nach der Änderung ihrer Größe und der aktuellen oder ursprünglichen Höhe an.

scaleTypeString

"CurrentSize" | "OriginalSize"

Gibt an, ob die Form relativ zur ursprünglichen oder aktuellen Größe skaliert wird. Die Ursprüngliche Größenskalierungsoption funktioniert nur für Bilder.

scaleFromString

"ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

Optional. Gibt an, welcher Teil der Form beim Skalieren die Position beibehält. Wenn sie nicht angegeben wird, stellt sie dar, dass die obere linke Ecke der Form ihre Position behält.

Gibt zurück

void

Hinweise

[ API-Satz: ExcelApi 1.9 ]

scaleWidth(scaleFactor, scaleType, scaleFrom)

Skaliert die Breite der Form anhand eines angegebenen Faktors. Für Bilder können Sie angeben, ob Sie die Form relativ zum Original oder zur aktuellen Größe skalieren möchten. Andere Formen als Bilder werden immer relativ zu ihrer aktuellen Breite skaliert.

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

Parameter

scaleFactor

number

Gibt das Verhältnis zwischen der Breite der Form nach der Änderung ihrer Größe und der aktuellen oder ursprünglichen Breite an.

scaleType

Excel.ShapeScaleType

Gibt an, ob die Form relativ zur ursprünglichen oder aktuellen Größe skaliert wird. Die Ursprüngliche Größenskalierungsoption funktioniert nur für Bilder.

scaleFrom

Excel.ShapeScaleFrom

Optional. Gibt an, welcher Teil der Form beim Skalieren die Position beibehält. Wenn sie nicht angegeben wird, stellt sie dar, dass die obere linke Ecke der Form ihre Position behält.

Gibt zurück

void

Hinweise

[ API-Satz: ExcelApi 1.9 ]

scaleWidth(scaleFactor, scaleTypeString, scaleFromString)

Skaliert die Breite der Form anhand eines angegebenen Faktors. Für Bilder können Sie angeben, ob Sie die Form relativ zum Original oder zur aktuellen Größe skalieren möchten. Andere Formen als Bilder werden immer relativ zu ihrer aktuellen Breite skaliert.

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

Parameter

scaleFactor

number

Gibt das Verhältnis zwischen der Breite der Form nach der Änderung ihrer Größe und der aktuellen oder ursprünglichen Breite an.

scaleTypeString

"CurrentSize" | "OriginalSize"

Gibt an, ob die Form relativ zur ursprünglichen oder aktuellen Größe skaliert wird. Die Ursprüngliche Größenskalierungsoption funktioniert nur für Bilder.

scaleFromString

"ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

Optional. Gibt an, welcher Teil der Form beim Skalieren die Position beibehält. Wenn sie nicht angegeben wird, stellt sie dar, dass die obere linke Ecke der Form ihre Position behält.

Gibt zurück

void

Hinweise

[ API-Satz: ExcelApi 1.9 ]

set(properties, options)

Legt mehrere Eigenschaften eines Objekts gleichzeitig fest. Sie können entweder ein einfaches Objekt mit den entsprechenden Eigenschaften oder ein anderes API-Objekt desselben Typs übergeben.

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

Parameter

properties

Excel.Interfaces.ShapeUpdateData

Ein JavaScript-Objekt mit Eigenschaften, die isomorph zu den Eigenschaften des Objekts strukturiert sind, für das die Methode aufgerufen wird.

options

OfficeExtension.UpdateOptions

Stellt eine Option zum Unterdrücken von Fehlern bereit, wenn das Eigenschaftenobjekt versucht, schreibgeschützte Eigenschaften festzulegen.

Gibt zurück

void

set(properties)

Legt mehrere Eigenschaften für das -Objekt gleichzeitig fest, basierend auf einem vorhandenen geladenen Objekt.

set(properties: Excel.Shape): void;

Parameter

properties

Excel.Shape

Gibt zurück

void

setZOrder(position)

Verschiebt de angegebene Form in der Z-Reihenfolge der Sammlung nach oben oder unten, wodurch sie vor oder hinter anderen Formen zu liegen kommt.

setZOrder(position: Excel.ShapeZOrder): void;

Parameter

position

Excel.ShapeZOrder

Wo die Form im Z-Reihenfolgenstapel relativ zu den anderen Shapes verschoben werden soll. Weitere Informationen finden Sie unter Excel.ShapeZOrder .

Gibt zurück

void

Hinweise

[ API-Satz: ExcelApi 1.9 ]

Beispiele

// 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)

Verschiebt de angegebene Form in der Z-Reihenfolge der Sammlung nach oben oder unten, wodurch sie vor oder hinter anderen Formen zu liegen kommt.

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

Parameter

positionString

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

Wo die Form im Z-Reihenfolgenstapel relativ zu den anderen Shapes verschoben werden soll. Weitere Informationen finden Sie unter Excel.ShapeZOrder .

Gibt zurück

void

Hinweise

[ API-Satz: ExcelApi 1.9 ]

toJSON()

Überschreibt die JavaScript-Methode toJSON() , um eine nützlichere Ausgabe bereitzustellen, wenn ein API-Objekt an JSON.stringify()übergeben wird. (JSON.stringifyruft wiederum die toJSON -Methode des Objekts auf, das an das Objekt übergeben wird.) Während das ursprüngliche Excel.Shape Objekt ein API-Objekt ist, gibt die toJSON Methode ein einfaches JavaScript-Objekt (typisiert als Excel.Interfaces.ShapeData) zurück, das flache Kopien aller geladenen untergeordneten Eigenschaften aus dem ursprünglichen Objekt enthält.

toJSON(): Excel.Interfaces.ShapeData;

Gibt zurück

Excel.Interfaces.ShapeData

Details zum Ereignis

onActivated

Tritt ein, wenn die Form aktiviert wird.

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

Ereignistyp

OfficeExtension.EventHandlers<Excel.ShapeActivatedEventArgs>

Hinweise

[ API-Satz: ExcelApi 1.9 ]

onDeactivated

Tritt ein, wenn die Form deaktiviert wird.

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

Ereignistyp

OfficeExtension.EventHandlers<Excel.ShapeDeactivatedEventArgs>

Hinweise

[ API-Satz: ExcelApi 1.9 ]