Power Point. Shape class

示例

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

// Changes the selected shapes fill color to red.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();
  shapes.items.map((shape) => {
    shape.fill.setSolidColor("red");
  });
  await context.sync();
});

group

返回 ShapeGroup 与形状关联的。如果形状类型不是 group，则此方法返回 GeneralException 错误。

readonly group: PowerPoint.ShapeGroup;

属性值

PowerPoint.ShapeGroup

注解

示例

// 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) => {
  // Ungroups the first shape group 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 shapeGroups = shapes.items.filter((item) => item.type === PowerPoint.ShapeType.group);
  if (shapeGroups.length === 0) {
    console.warn("No shape groups on the current slide, so nothing to ungroup.");
    return;
  }

  // Ungroup the first grouped shapes.
  const firstGroupId = shapeGroups[0].id;
  const shapeGroupToUngroup = shapes.getItem(firstGroupId);
  shapeGroupToUngroup.group.ungroup();
  await context.sync();

  console.log(`Ungrouped shapes with group ID: ${firstGroupId}`);
});

height

指定形状的高度（以磅为单位）。 InvalidArgument使用负值设置时引发异常。

height: number;

属性值

number

注解

示例

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

// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();
  let maxHeight = 0;
  shapes.items.map((shape) => {
    shape.load("width,height");
  });
  await context.sync();
  shapes.items.map((shape) => {
    shape.left = currentLeft;
    shape.top = currentTop;
    currentLeft += shape.width;
    if (shape.height > maxHeight) maxHeight = shape.height;
  });
  await context.sync();
  currentLeft = 0;
  if (currentTop > slideHeight - 200) currentTop = 0;
});

id

获取形状的唯一 ID。

readonly id: string;

属性值

string

注解

[ API 集：PowerPointApi 1.3 ]

left

从形状左侧到幻灯片左侧的距离（以磅为单位）。

left: number;

属性值

number

注解

示例

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

// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();
  let maxHeight = 0;
  shapes.items.map((shape) => {
    shape.load("width,height");
  });
  await context.sync();
  shapes.items.map((shape) => {
    shape.left = currentLeft;
    shape.top = currentTop;
    currentLeft += shape.width;
    if (shape.height > maxHeight) maxHeight = shape.height;
  });
  await context.sync();
  currentLeft = 0;
  if (currentTop > slideHeight - 200) currentTop = 0;
});

level

返回指定形状的级别。

级别为 0 表示形状不是组的一部分。
级别为 1 表示形状是顶级组的一部分。
大于 1 的级别指示形状是嵌套组。

readonly level: number;

属性值

number

注解

lineFormat

返回此形状的线条格式。

readonly lineFormat: PowerPoint.ShapeLineFormat;

属性值

PowerPoint.ShapeLineFormat

注解

name

指定此形状的名称。

name: string;

属性值

string

注解

parentGroup

返回此形状的父组。如果形状不是组的一部分，则此方法返回 GeneralException 错误。

readonly parentGroup: PowerPoint.Shape;

属性值

PowerPoint.Shape

注解

placeholderFormat

返回专门应用于此占位符的属性。如果形状类型不是 placeholder，则此方法返回 GeneralException 错误。

readonly placeholderFormat: PowerPoint.PlaceholderFormat;

属性值

PowerPoint.PlaceholderFormat

注解

textFrame

返回此 Shape的 PowerPoint.TextFrame 对象。 InvalidArgument如果形状不支持，TextFrame则引发异常。

readonly textFrame: PowerPoint.TextFrame;

属性值

PowerPoint.TextFrame

注解

top

从形状的上边缘到幻灯片上边缘的距离（以磅为单位）。

top: number;

属性值

number

注解

示例

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

// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();
  let maxHeight = 0;
  shapes.items.map((shape) => {
    shape.load("width,height");
  });
  await context.sync();
  shapes.items.map((shape) => {
    shape.left = currentLeft;
    shape.top = currentTop;
    currentLeft += shape.width;
    if (shape.height > maxHeight) maxHeight = shape.height;
  });
  await context.sync();
  currentLeft = 0;
  if (currentTop > slideHeight - 200) currentTop = 0;
});

type

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

readonly type: PowerPoint.ShapeType | "Unsupported" | "Image" | "GeometricShape" | "Group" | "Line" | "Table" | "Callout" | "Chart" | "ContentApp" | "Diagram" | "Freeform" | "Graphic" | "Ink" | "Media" | "Model3D" | "Ole" | "Placeholder" | "SmartArt" | "TextBox";

属性值

注解

示例

// 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();
});

width

指定形状的宽度（以磅为单位）。 InvalidArgument使用负值设置时引发异常。

width: number;

属性值

number

注解

示例

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

// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();
  let maxHeight = 0;
  shapes.items.map((shape) => {
    shape.load("width,height");
  });
  await context.sync();
  shapes.items.map((shape) => {
    shape.left = currentLeft;
    shape.top = currentTop;
    currentLeft += shape.width;
    if (shape.height > maxHeight) maxHeight = shape.height;
  });
  await context.sync();
  currentLeft = 0;
  if (currentTop > slideHeight - 200) currentTop = 0;
});

zOrderPosition

返回形状的 z 顺序位置，0 表示顺序堆栈的底部。幻灯片上的每个形状都有唯一的 z 顺序，但每张幻灯片也有唯一的 z 顺序堆栈，因此，单独幻灯片上的两个形状可能具有相同的 z 顺序编号。

readonly zOrderPosition: number;

属性值

number

注解

示例

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

async function changeZOrder(operation: PowerPoint.ShapeZOrder) {
  // Changes the z-order position of the selected shapes.
  return PowerPoint.run(async (context) => {
    const selectedShapes = context.presentation.getSelectedShapes();
    selectedShapes.load();
    await context.sync();

    if (selectedShapes.items.length === 0) {
      console.log("No shapes are selected.");
    } else {
      let direction = 1; // Start with bottom-most (lowest number).

      // Start with top-most when sending to back or bringing forward.

      switch (operation) {
        case PowerPoint.ShapeZOrder.bringForward:

        case PowerPoint.ShapeZOrder.sendToBack:
          direction = -1; // Reverse direction.

          break;
      }

      // Change the z-order position for each of the selected shapes,

      // starting with the bottom-most when bringing to front or sending backward,

      // or top-most when sending to back or bringing forward,

      // so the selected shapes retain their relative z-order positions after they're changed.

      selectedShapes.items
        .sort((a, b) => (a.zOrderPosition - b.zOrderPosition) * direction)
        .forEach((shape) => {
          try {
            const originalZOrderPosition = shape.zOrderPosition;
            shape.setZOrder(operation);

            console.log(`Changed z-order of shape ${shape.id}.`);
          } catch (err) {
            console.log(`Unable to change z-order of shape ${shape.id}. ${err.message}`);
          }
        });

      await context.sync();
    }
  });
}

方法详细信息

delete()

从形状集合中删除形状。如果形状不存在，则不执行任何作用。

delete(): void;

void

注解

[ API 集：PowerPointApi 1.3 ]

示例

// 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 then iterates through them, deleting each one.
await PowerPoint.run(async (context) => {
  const slide: PowerPoint.Slide = context.presentation.slides.getItemAt(0);
  const shapes: PowerPoint.ShapeCollection = slide.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();
});

getParentSlide()

返回包含此 Shape的父 PowerPoint.Slide 对象。如果此形状不属于， Slide则引发异常。

getParentSlide(): PowerPoint.Slide;

PowerPoint.Slide

注解

getParentSlideLayout()

返回包含此 Shape的父 PowerPoint.SlideLayout 对象。如果此形状不属于， SlideLayout则引发异常。

getParentSlideLayout(): PowerPoint.SlideLayout;

PowerPoint.SlideLayout

注解

getParentSlideLayoutOrNullObject()

返回包含此 Shape的父 PowerPoint.SlideLayout 对象。如果此形状不属于 SlideLayout， isNullObject 则返回属性设置为 true 的对象。有关详细信息，请参阅 *OrNullObject 方法和属性。

getParentSlideLayoutOrNullObject(): PowerPoint.SlideLayout;

PowerPoint.SlideLayout

注解

getParentSlideMaster()

返回包含此 Shape的父 PowerPoint.SlideMaster 对象。如果此形状不属于， SlideMaster则引发异常。

getParentSlideMaster(): PowerPoint.SlideMaster;

PowerPoint.SlideMaster

注解

getParentSlideMasterOrNullObject()

返回包含此 Shape的父 PowerPoint.SlideMaster 对象。如果此形状不属于 SlideMaster， isNullObject 则返回属性设置为 true 的对象。有关详细信息，请参阅 *OrNullObject 方法和属性。

getParentSlideMasterOrNullObject(): PowerPoint.SlideMaster;

PowerPoint.SlideMaster

注解

getParentSlideOrNullObject()

返回包含此 Shape的父 PowerPoint.Slide 对象。如果此形状不属于 Slide， isNullObject 则返回属性设置为 true 的对象。有关详细信息，请参阅 *OrNullObject 方法和属性。

getParentSlideOrNullObject(): PowerPoint.Slide;

PowerPoint.Slide

注解

getTable()

如果此形状是表， Table 则返回对象。

getTable(): PowerPoint.Table;

PowerPoint.Table

注解

示例

// 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.");
});

load(options)

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

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

参数

options: PowerPoint.Interfaces.ShapeLoadOptions

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

PowerPoint.Shape

load(propertyNames)

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

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

参数

propertyNames: string | string[]

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

PowerPoint.Shape

load(propertyNamesAndPaths)

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

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

参数

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

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

PowerPoint.Shape

setZOrder(position)

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

setZOrder(position: PowerPoint.ShapeZOrder): void;

参数

position: PowerPoint.ShapeZOrder

指定如何在 z 顺序堆栈中移动形状。使用 ShapeZOrder 枚举。

void

注解

示例

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

async function changeZOrder(operation: PowerPoint.ShapeZOrder) {
  // Changes the z-order position of the selected shapes.
  return PowerPoint.run(async (context) => {
    const selectedShapes = context.presentation.getSelectedShapes();
    selectedShapes.load();
    await context.sync();

    if (selectedShapes.items.length === 0) {
      console.log("No shapes are selected.");
    } else {
      let direction = 1; // Start with bottom-most (lowest number).

      // Start with top-most when sending to back or bringing forward.

      switch (operation) {
        case PowerPoint.ShapeZOrder.bringForward:

        case PowerPoint.ShapeZOrder.sendToBack:
          direction = -1; // Reverse direction.

          break;
      }

      // Change the z-order position for each of the selected shapes,

      // starting with the bottom-most when bringing to front or sending backward,

      // or top-most when sending to back or bringing forward,

      // so the selected shapes retain their relative z-order positions after they're changed.

      selectedShapes.items
        .sort((a, b) => (a.zOrderPosition - b.zOrderPosition) * direction)
        .forEach((shape) => {
          try {
            const originalZOrderPosition = shape.zOrderPosition;
            shape.setZOrder(operation);

            console.log(`Changed z-order of shape ${shape.id}.`);
          } catch (err) {
            console.log(`Unable to change z-order of shape ${shape.id}. ${err.message}`);
          }
        });

      await context.sync();
    }
  });
}

setZOrder(positionString)

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

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

参数

positionString: "BringForward" | "BringToFront" | "SendBackward" | "SendToBack"

指定如何在 z 顺序堆栈中移动形状。使用 ShapeZOrder 枚举。

void

注解