使用 PowerPoint JavaScript API 处理形状

项目
03/17/2023

本文介绍如何将几何形状、线条和文本框与 Shape 和 ShapeCollection API 结合使用。

创建形状

形状通过创建并存储在幻灯片的形状集合中， slide.shapes () 。 ShapeCollection.add*有多种方法可用于此目的。所有形状在添加到集合时都有为其生成的名称和 ID。这些分别是 name 和 id 属性。 name 可由加载项设置。

几何形状

使用的重载 ShapeCollection.addGeometricShape之一创建几何形状。第一个参数是 GeometricShapeType 枚举或等效于枚举值之一的字符串。 ShapeAddOptions 类型的第二个可选参数可以指定形状的初始大小及其相对于幻灯片顶部和左侧的位置（以磅为单位）。或者，可以在创建形状后设置这些属性。

下面的代码示例创建一个名为 “Square” 的矩形，该矩形位于幻灯片的顶部和左侧 100 磅处。方法返回对象 Shape 。

// This sample creates a rectangle positioned 100 points from the top and left sides
// of the slide and is 150x150 points. The shape is put on the first slide.
await PowerPoint.run(async (context) => {
    const shapes = context.presentation.slides.getItemAt(0).shapes;
    const rectangle = shapes.addGeometricShape(PowerPoint.GeometricShapeType.rectangle);
    rectangle.left = 100;
    rectangle.top = 100;
    rectangle.height = 150;
    rectangle.width = 150;
    rectangle.name = "Square";
    await context.sync();
});

Lines

使用的重载 ShapeCollection.addLine之一创建行。第一个参数是 ConnectorType 枚举或等效于枚举值之一的字符串，用于指定端点之间的换行方式。 ShapeAddOptions 类型的第二个可选参数可以指定线条的起点和终点。或者，可以在创建形状后设置这些属性。方法返回对象 Shape 。

注意

当形状是线条时，top和对象的和 leftShapeAddOptions 属性Shape指定相对于幻灯片的上边缘和左边缘的线条的起点。和属性指定相对于起点的直线的端点。widthheight 因此， () topwidth + heightleft + (相对于幻灯片上边缘和左边缘的终点) 。所有属性的度量单位为磅，允许使用负值。

下面的代码示例在幻灯片上创建一条直线。

// This sample creates a straight line on the first slide.
await PowerPoint.run(async (context) => {
    const shapes = context.presentation.slides.getItemAt(0).shapes;
    const line = shapes.addLine(PowerPoint.ConnectorType.straight, {left: 200, top: 50, height: 300, width: 150});
    line.name = "StraightLine";
    await context.sync();
});

文本框

使用 addTextBox 方法创建文本框。第一个参数是最初应出现在框中的文本。 ShapeAddOptions 类型的第二个可选参数可以指定文本框的初始大小及其相对于幻灯片顶部和左侧的位置。或者，可以在创建形状后设置这些属性。

下面的代码示例演示如何在第一张幻灯片上创建文本框。

// This sample creates a text box with the text "Hello!" and sizes it appropriately.
await PowerPoint.run(async (context) => {
    const shapes = context.presentation.slides.getItemAt(0).shapes;
    const textbox = shapes.addTextBox("Hello!");
    textbox.left = 100;
    textbox.top = 100;
    textbox.height = 300;
    textbox.width = 450;
    textbox.name = "Textbox";
    await context.sync();
});

移动形状和调整形状大小

形状位于幻灯片顶部。其位置由 left 和 top 属性定义。它们充当幻灯片各自边缘的边距，以磅为单位，左上角 left: 0 为和 top: 0 。形状大小由 height 和 width 属性指定。代码可以通过重置这些属性来移动形状或调整形状大小。 (当形状为线条时，这些属性的含义略有不同。请参阅 Lines.)

形状中的文本

几何形状可以包含文本。形状具有 textFrameTextFrame 类型的属性。对象 TextFrame 管理文本显示选项 (，例如边距和文本溢出) 。 TextFrame.textRange 是具有文本内容和字体设置的 TextRange 对象。

下面的代码示例使用文本“形状文本”创建名为“大括号”的几何形状。它还会调整形状和文本颜色，并将文本的垂直对齐方式设置为中心。

// This sample creates a light blue rectangle with braces ("{}") on the left and right ends
// and adds the purple text "Shape text" to the center.
await PowerPoint.run(async (context) => {
    const shapes = context.presentation.slides.getItemAt(0).shapes;
    const braces = shapes.addGeometricShape(PowerPoint.GeometricShapeType.bracePair);
    braces.left = 100;
    braces.top = 400;
    braces.height = 50;
    braces.width = 150;
    braces.name = "Braces";
    braces.fill.setSolidColor("lightblue");
    braces.textFrame.textRange.text = "Shape text";
    braces.textFrame.textRange.font.color = "purple";
    braces.textFrame.verticalAlignment = PowerPoint.TextVerticalAlignment.middleCentered;
    await context.sync();
});

删除形状

使用 Shape 对象的 delete 方法从幻灯片中删除形状。

以下代码示例演示如何删除形状。

await PowerPoint.run(async (context) => {
    // Delete all shapes from the first slide.
    const sheet = context.presentation.slides.getItemAt(0);
    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(function (shape) {
        shape.delete();
    });
    await context.sync();
});