PowerPoint.ShapeCollection class

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

context: RequestContext;

Eigenschaftswert

Ruft die geladenen untergeordneten Elemente in dieser Sammlung ab.

readonly items: PowerPoint.Shape[];

Eigenschaftswert

Fügt der Folie eine geometrische Form hinzu. Gibt ein Shape Objekt zurück, das die neue Form darstellt.

addGeometricShape(geometricShapeType: PowerPoint.GeometricShapeType, options?: PowerPoint.ShapeAddOptions): PowerPoint.Shape;

Parameter

Gibt zurück

Das neu eingefügte Shape.

Hinweise

API-Satz: PowerPointApi 1.4

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/shapes.yaml

// This function gets the collection of shapes on the first slide,
// and adds a hexagon shape to the collection, while specifying its
// location and size. Then it names the shape.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeCollection = context.presentation.slides.getItemAt(0).shapes;
  const shapeOptions: PowerPoint.ShapeAddOptions = {
    left: 100,
    top: 100,
    height: 150,
    width: 150,
  };
  const hexagon: PowerPoint.Shape = shapes.addGeometricShape(PowerPoint.GeometricShapeType.hexagon, shapeOptions);
  hexagon.name = "Hexagon";

  await context.sync();
});

Fügt der Folie eine geometrische Form hinzu. Gibt ein Shape Objekt zurück, das die neue Form darstellt.

addGeometricShape(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", options?: PowerPoint.ShapeAddOptions): PowerPoint.Shape;

Parameter

Gibt zurück

Das neu eingefügte Shape.

Hinweise

API-Satz: PowerPointApi 1.4

Erstellen Sie eine Shape-Gruppe für mehrere Shapes.

addGroup(values: Array<string | Shape>): PowerPoint.Shape;

Parameter

Gibt zurück

Ein Shape Objekt, das die Formgruppe darstellt. Verwenden Sie die Shape.group Eigenschaft, um auf das ShapeGroup Objekt für die Gruppe zuzugreifen.

Hinweise

API-Satz: PowerPointApi 1.8

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/group-ungroup-shapes.yaml

await PowerPoint.run(async (context) => {
  // Groups the geometric shapes on the current slide.

  // Get the shapes on the current slide.
  context.presentation.load("slides");
  const slide: PowerPoint.Slide = context.presentation.getSelectedSlides().getItemAt(0);
  slide.load("shapes/items/type,shapes/items/id");
  await context.sync();

  const shapes: PowerPoint.ShapeCollection = slide.shapes;
  const shapesToGroup = shapes.items.filter((item) => item.type === PowerPoint.ShapeType.geometricShape);
  if (shapesToGroup.length === 0) {
    console.warn("No shapes on the current slide, so nothing to group.");
    return;
  }

  // Group the geometric shapes.
  console.log(`Number of shapes to group: ${shapesToGroup.length}`);
  const group = shapes.addGroup(shapesToGroup);
  group.load("id");
  await context.sync();

  console.log(`Grouped shapes. Group ID: ${group.id}`);
});

Fügt der Folie eine Linie hinzu. Gibt ein Shape Objekt zurück, das die neue Zeile darstellt.

addLine(connectorType?: PowerPoint.ConnectorType, options?: PowerPoint.ShapeAddOptions): PowerPoint.Shape;

Parameter

Gibt zurück

Das neu eingefügte Shape.

Hinweise

API-Satz: PowerPointApi 1.4

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/shapes.yaml

// This function gets the collection of shapes on the first slide,
// and adds a line to the collection, while specifying its
// start and end points. Then it names the shape.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeCollection = context.presentation.slides.getItemAt(0).shapes;

  // For a line, left and top are the coordinates of the start point,
  // while height and width are the coordinates of the end point.
  const line: PowerPoint.Shape = shapes.addLine(PowerPoint.ConnectorType.straight, {
    left: 400,
    top: 200,
    height: 20,
    width: 150,
  });
  line.name = "StraightLine";

  await context.sync();
});

Fügt der Folie eine Linie hinzu. Gibt ein Shape Objekt zurück, das die neue Zeile darstellt.

addLine(connectorType?: "Straight" | "Elbow" | "Curve", options?: PowerPoint.ShapeAddOptions): PowerPoint.Shape;

Parameter

Gibt zurück

Das neu eingefügte Shape.

Hinweise

API-Satz: PowerPointApi 1.4

Fügt der Folie ein Bild hinzu. Gibt ein Shape Objekt zurück, das das neue Bild darstellt.

addPicture(base64EncodedImage: string, options?: PowerPoint.PictureAddOptions): PowerPoint.Shape;

Parameter

Gibt zurück

Das neu eingefügte Shape.

Hinweise

API-Satz: PowerPointApi BETA (NUR VORSCHAU)

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/preview-apis/add-picture.yaml

// Insert a picture on the current slide.
await PowerPoint.run(async (context) => {
  const slide: PowerPoint.Slide = context.presentation.getSelectedSlides().getItemAt(0);

  // Use PictureAddOptions to control the position and dimensions (in points).
  const options: PowerPoint.PictureAddOptions = {
    left: 100,
    top: 100,
    width: 250,
    height: 180,
  };

  const picture: PowerPoint.Shape = slide.shapes.addPicture(getSampleImageBase64(), options);
  picture.name = "SamplePicture";

  // Set accessibility properties on the inserted picture.
  picture.altTextTitle = "Sample image";
  picture.altTextDescription = "A cartoon dog image used as a sample picture in this add-in.";

  await context.sync();
});

Fügt der Folie eine Tabelle hinzu. Gibt ein Shape Objekt zurück, das die neue Tabelle darstellt. Verwenden Sie die Shape.table Eigenschaft, um das Table Objekt für die Form abzurufen.

addTable(rowCount: number, columnCount: number, options?: PowerPoint.TableAddOptions): PowerPoint.Shape;

Parameter

Gibt zurück

Das neu eingefügte Shape.

Hinweise

API-Satz: PowerPointApi 1.8

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/add-modify-tables.yaml

// Adds a basic table.
await PowerPoint.run(async (context) => {
  const shapes = context.presentation.getSelectedSlides().getItemAt(0).shapes;

  // Add a simple table, specifying the row and column count.
  shapes.addTable(3, 4);
  await context.sync();
});

Fügt der Folie ein Textfeld hinzu, das den bereitgestellten Text als Inhalt enthält. Gibt ein Shape Objekt zurück, das das neue Textfeld darstellt.

addTextBox(text: string, options?: PowerPoint.ShapeAddOptions): PowerPoint.Shape;

Parameter

Gibt zurück

Das neu eingefügte Shape.

Hinweise

API-Satz: PowerPointApi 1.4

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/shapes.yaml

// This function gets the collection of shapes on the first slide,
// and adds a text box to the collection, while specifying its text,
// location, and size. Then it names the text box.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeCollection = context.presentation.slides.getItemAt(0).shapes;
  const textbox: PowerPoint.Shape = shapes.addTextBox("Hello!", {
    left: 100,
    top: 300,
    height: 300,
    width: 450,
  });
  textbox.name = "Textbox";

  return context.sync();
});

Ruft die Anzahl der Shapes in der Sammlung ab.

getCount(): OfficeExtension.ClientResult<number>;

Gibt zurück

Die Anzahl der Shapes in der Sammlung.

Hinweise

API-Satz: PowerPointApi 1.3

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/add-modify-tables.yaml

// Gets the table from a shape.
await PowerPoint.run(async (context) => {
  const shapes = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();

  if (shapeCount.value > 0) {
    const shape = shapes.getItemAt(0);
    shape.load("type");
    await context.sync();

    // The shape type can indicate whether the shape is a table.
    const isTable = shape.type === PowerPoint.ShapeType.table;

    if (isTable) {
      // Get the Table object for the Shape which is a table.
      const table = shape.getTable();
      table.load();
      await context.sync();

      // Get the Table row and column count.
      console.log("Table RowCount: " + table.rowCount + " and columnCount: " + table.columnCount);
    } else console.log("Selected shape isn't table.");
  } else console.log("No shape selected.");
});

Ruft ein Shape anhand seiner eindeutigen ID ab. Wenn die Form nicht vorhanden ist, wird ein Fehler ausgelöst.

getItem(key: string): PowerPoint.Shape;

Parameter

Gibt zurück

Das Shape mit der eindeutigen ID. Wenn eine solche Form nicht vorhanden ist, wird ein Fehler ausgelöst.

Hinweise

API-Satz: PowerPointApi 1.3

Ruft eine Form mithilfe ihres nullbasierten Indexes in der Auflistung ab. Ein Fehler wird ausgelöst, wenn der Index außerhalb des zulässigen Bereichs liegt.

getItemAt(index: number): PowerPoint.Shape;

Parameter

Gibt zurück

Das Shape am angegebenen Index. Ein Fehler wird ausgelöst, wenn der Index außerhalb des zulässigen Bereichs liegt.

Hinweise

API-Satz: PowerPointApi 1.3

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/tags/tags.yaml

await PowerPoint.run(async function (context) {
  const slide: PowerPoint.Slide = context.presentation.slides.getItemAt(0);
  const shape: PowerPoint.Shape = slide.shapes.getItemAt(0);
  shape.tags.add("MOUNTAIN", "Denali");

  await context.sync();

  const myShapeTag: PowerPoint.Tag = shape.tags.getItem("MOUNTAIN");
  myShapeTag.load("key, value");

  await context.sync();

  console.log("Added key " + JSON.stringify(myShapeTag.key) + " with value " + JSON.stringify(myShapeTag.value));
});

Ruft ein Shape anhand seiner eindeutigen ID ab. Wenn eine solche Form nicht vorhanden ist, wird ein Objekt mit der isNullObject auf true festgelegten Eigenschaft zurückgegeben. Weitere Informationen finden Sie unter *OrNullObject-Methoden und -Eigenschaften.

getItemOrNullObject(id: string): PowerPoint.Shape;

Parameter

Gibt zurück

Das Shape mit der eindeutigen ID. Wenn eine solche Form nicht vorhanden ist, wird ein Objekt mit der isNullObject auf true festgelegten Eigenschaft zurückgegeben.

Hinweise

API-Satz: PowerPointApi 1.3

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?: PowerPoint.Interfaces.ShapeCollectionLoadOptions & PowerPoint.Interfaces.CollectionLoadOptions): PowerPoint.ShapeCollection;

Parameter

Gibt zurück

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[]): PowerPoint.ShapeCollection;

Parameter

Gibt zurück

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-shapes-by-type.yaml

// Changes the transparency of every geometric shape in the slide.
await PowerPoint.run(async (context) => {
  // Get the type of shape for every shape in the collection.
  const shapes: PowerPoint.ShapeCollection = context.presentation.slides.getItemAt(0).shapes;
  shapes.load("type");
  await context.sync();

  // Change the shape transparency to be halfway transparent.
  shapes.items.forEach((shape) => {
    if (shape.type === PowerPoint.ShapeType.geometricShape) {
      shape.fill.transparency = 0.5;
    }
  });
  await context.sync();
});

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?: OfficeExtension.LoadOption): PowerPoint.ShapeCollection;

Parameter

Gibt zurück

Ü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 sie übergeben wird.) Während das ursprüngliche PowerPoint.ShapeCollection Objekt ein API-Objekt ist, gibt die toJSON Methode ein einfaches JavaScript-Objekt (typisiert als PowerPoint.Interfaces.ShapeCollectionData) zurück, das ein "items"-Array mit flachen Kopien aller geladenen Eigenschaften aus den Elementen der Sammlung enthält.

toJSON(): PowerPoint.Interfaces.ShapeCollectionData;

Gibt zurück