Работа с фигурами с помощью API JavaScript для PowerPoint

В этой статье описывается использование геометрических фигур, линий и текстовых полей в сочетании с API Shape и ShapeCollection .

Создание фигур

Фигуры создаются и хранятся в коллекции фигур слайда (slide.shapes). ShapeCollection имеет несколько .add* методов для этой цели. Все фигуры имеют имена и идентификаторы, созданные для них при добавлении в коллекцию. name Это свойства и id соответственно. name может быть задана надстройкой.

Геометрические фигуры

Геометрическая фигура создается с одной из перегрузок ShapeCollection.addGeometricShape. Первый параметр является перечислением GeometryShapeType или строковым эквивалентом одного из значений перечисления. Существует необязательный второй параметр типа 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 свойства Shape и left объектов и ShapeAddOptions указывают начальную точку линии относительно верхнего и левого краев слайда. Свойства height и width указывают конечную точку строки относительно начальной точки. Таким образом, конечная точка относительно верхнего и левого краев слайда имеет значение (top + height) на (left + width). Единица измерения для всех свойств — точек, а отрицательные значения допускаются.

В следующем примере кода создается прямая линия на слайде.

// 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 . Код может перемещать или изменять размер фигуры путем сброса этих свойств. (Эти свойства имеют немного другое значение, если фигура является линией. См. раздел Строки.)

Текст в фигурах

Геометрические фигуры могут содержать текст. Фигуры имеют textFrame свойство типа TextFrame. Объект 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 shapes = context.presentation.slides.getItemAt(0).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();
});