PowerPoint.Shape class

Adjustments Возвращает объект , содержащий значения корректировки для всех корректировок в этой фигуре.

readonly adjustments: PowerPoint.Adjustments;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.10

Описание замещающего текста фигуры.

Замещающий текст предоставляет альтернативные текстовые представления информации, содержащейся в фигуре. Эта информация полезна для людей со зрением или когнитивными нарушениями, которые не могут видеть или понимать форму.

altTextDescription: string;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.10

Примеры

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

// Reads the accessibility properties of the first selected shape.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  await context.sync();

  if (shapeCount.value === 0) {
    console.warn("No shapes are selected. Select a shape on the slide and try again.");
    return;
  }

  const shape: PowerPoint.Shape = shapes.getItemAt(0);
  shape.load("id,name,altTextTitle,altTextDescription,isDecorative");
  await context.sync();

  console.log(`Shape ID: ${shape.id}`);
  console.log(`Name: "${shape.name}"`);
  console.log(`Alt text title: "${shape.altTextTitle}"`);
  console.log(`Alt text description: "${shape.altTextDescription}"`);
  console.log(`Is decorative: ${shape.isDecorative}`);
});

Замещающий заголовок текста фигуры.

Замещающий текст предоставляет альтернативные текстовые представления информации, содержащейся в фигуре. Эта информация полезна для людей со зрением или когнитивными нарушениями, которые не могут видеть или понимать форму. Заголовок может быть прочитан лицу с ограниченными возможностями и используется для определения того, хотят ли они услышать описание содержимого.

altTextTitle: string;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.10

Примеры

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

Контекст запроса, связанный с объектом . Это соединяет процесс надстройки с процессом ведущего приложения Office.

context: RequestContext;

Значение свойства

Возвращает идентификатор создания фигуры. Возвращает, null если фигура не имеет идентификатора создания.

readonly creationId: string | null;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.10

Возвращает коллекцию настраиваемых XML-частей в фигуре.

readonly customXmlParts: PowerPoint.CustomXmlPartCollection;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.7

Возвращает формат заливки фигуры.

readonly fill: PowerPoint.ShapeFill;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.4

Примеры

// 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/fill/type");
  await context.sync();
  shapes.items.map((shape) => {
    const shapeFillType = shape.fill.type as PowerPoint.ShapeFillType;
    console.log(`Shape ID ${shape.id} original fill type: ${shapeFillType}`);
    shape.fill.setSolidColor("red");
  });
  await context.sync();
});

Возвращает объект , связанный ShapeGroup с фигурой. Если тип фигуры не groupявляется , то этот метод возвращает ошибку GeneralException .

readonly group: PowerPoint.ShapeGroup;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.8

Примеры

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

Задает высоту фигуры (в точках). InvalidArgument Создает исключение, если задано отрицательное значение.

height: number;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.4

Примеры

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

Возвращает уникальный идентификатор фигуры.

readonly id: string;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.3

Указывает, является ли фигура декоративной или нет.

Декоративные объекты добавляют визуальный интерес, но не являются информативными (например, стилистические границы). People с помощью средств чтения с экрана услышит, что они декоративные, чтобы они знали, что они не пропускают какую-либо важную информацию.

isDecorative: boolean;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.10

Примеры

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

// Toggles the isDecorative property on the first selected shape.
// When isDecorative is true, screen readers announce the shape as
// decorative, indicating no alt text is needed.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  await context.sync();

  if (shapeCount.value === 0) {
    console.warn("No shapes are selected. Select a shape on the slide and try again.");
    return;
  }

  const shape: PowerPoint.Shape = shapes.getItemAt(0);
  shape.load("name,isDecorative");
  await context.sync();

  const wasDecorative = shape.isDecorative;
  shape.isDecorative = !wasDecorative;
  await context.sync();

  console.log(`Shape "${shape.name}" isDecorative changed: ${wasDecorative} → ${shape.isDecorative}`);
});

Расстояние (в точках) от левой части фигуры до левой стороны слайда.

left: number;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.4

Примеры

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

Возвращает уровень указанной фигуры.

• Уровень 0 означает, что фигура не является частью группы.

• Уровень 1 означает, что фигура является частью группы верхнего уровня.

• Уровень больше 1 указывает, что фигура является вложенной группой.

readonly level: number;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.8

Возвращает формат линии для фигуры.

readonly lineFormat: PowerPoint.ShapeLineFormat;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.4

Указывает имя этой фигуры.

name: string;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.4

Возвращает родительскую группу этой фигуры. Если фигура не входит в группу, этот метод возвращает ошибку GeneralException .

readonly parentGroup: PowerPoint.Shape;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.8

Возвращает свойства, которые применяются специально к этому заполнителю. Если тип фигуры не placeholderявляется , то этот метод возвращает ошибку GeneralException .

readonly placeholderFormat: PowerPoint.PlaceholderFormat;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.8

Примеры

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

// Gets the placeholder shapes in the slide.
await PowerPoint.run(async (context) => {
  // Get properties for every shape in the collection.
  const shapes: PowerPoint.ShapeCollection = context.presentation.slides.getItemAt(0).shapes;
  shapes.load("type,name");
  await context.sync();

  const placeholderShapes = [];
  console.log(`Number of shapes found: ${shapes.items.length}`);
  shapes.items.forEach((shape) => {
    if (shape.type === PowerPoint.ShapeType.placeholder) {
      // Load placeholderFormat property.
      // PowerPoint throws an exception if you try to load this property on a shape that isn't a placeholder type.
      shape.load("placeholderFormat");
      placeholderShapes.push(shape);
    }
  });
  await context.sync();

  console.log(`Number of placeholder shapes found: ${placeholderShapes.length}`);
  for (let i = 0; i < placeholderShapes.length; i++) {
    let currentPlaceholder: PowerPoint.PlaceholderFormat = placeholderShapes[i].placeholderFormat;
    let placeholderType = currentPlaceholder.type as PowerPoint.PlaceholderType;
    let placeholderContainedType = currentPlaceholder.containedType as PowerPoint.ShapeType;
    console.log(`Shape "${placeholderShapes[i].name}" placeholder properties:`);
    console.log(`\ttype: ${placeholderType}`);
    console.log(`\tcontainedType: ${placeholderContainedType}`);
  }
});

Задает поворот фигуры вокруг оси Z в градусах. Положительное значение указывает на поворот по часовой стрелке, а отрицательное значение — на вращение против часовой стрелки.

rotation: number;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.10

Возвращает коллекцию тегов в фигуре.

readonly tags: PowerPoint.TagCollection;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.3

Возвращает объект PowerPoint.TextFrame этого объекта Shape. Создает исключение, InvalidArgument если фигура не поддерживает TextFrame.

readonly textFrame: PowerPoint.TextFrame;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.4

Расстояние (в точках) от верхнего края фигуры до верхнего края слайда.

top: number;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.4

Примеры

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

Возвращает тип фигуры. Дополнительные сведения см. в статье 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";

Значение свойства

Комментарии

Набор API: PowerPointApi 1.4

Примеры

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

Указывает, видна ли фигура.

visible: boolean;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.10

Задает ширину фигуры (в точках). InvalidArgument Создает исключение, если задано отрицательное значение.

width: number;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.4

Примеры

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

Возвращает позицию z-порядка фигуры, при этом значение 0 представляет нижнюю часть стека заказов. Каждая фигура на слайде имеет уникальный Z-порядок, но каждый слайд также имеет уникальный стек z-порядка, поэтому две фигуры на разных слайдах могут иметь одинаковый номер z-порядка.

readonly zOrderPosition: number;

Значение свойства

Комментарии

Набор API: PowerPointApi 1.8

Примеры

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

Возвращает объект PowerPoint.Graphic , если эта фигура является ShapeType.graphic. Если эта фигура не Graphicявляется , возвращается объект со свойством isNullObject , для свойства имеет значение true . Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.

getGraphicOrNullObject(): PowerPoint.Graphic;

Возвращаемое значение

Комментарии

Набор API: Бета-версия PowerPointApi (только предварительная версия)

Отрисовывает изображение фигуры.

getImageAsBase64(options?: PowerPoint.ShapeGetImageOptions): OfficeExtension.ClientResult<string>;

Параметры

Возвращаемое значение

Строка изображения фигуры в кодировке Base64 в указанном формате.

Комментарии

Набор API: PowerPointApi 1.10

Примеры

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

// Gets an image of the first selected shape using default options
// (PNG format at the shape's original size).
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  await context.sync();

  if (shapeCount.value === 0) {
    console.warn("No shapes are selected. Please select a shape and try again.");
    return;
  }

  const shape: PowerPoint.Shape = shapes.getItemAt(0);
  // Call getImageAsBase64 with no options - returns PNG at the shape's true size.
  const imageResult: OfficeExtension.ClientResult<string> = shape.getImageAsBase64();
  await context.sync();

  displayImage(imageResult.value, "Default (original size, PNG)");
});

Возвращает родительский объект PowerPoint.Slide , содержащий этот Shapeобъект . Создает исключение, если эта фигура не принадлежит .Slide

getParentSlide(): PowerPoint.Slide;

Возвращаемое значение

Комментарии

Набор API: PowerPointApi 1.5

Примеры

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

// Gets navigational (complex) properties of the selected text range.
await PowerPoint.run(async (context) => {
  const textRange: PowerPoint.TextRange = context.presentation.getSelectedTextRange();
  textRange.load("font,paragraphFormat/bulletFormat,paragraphFormat/horizontalAlignment");

  const parentTextFrame: PowerPoint.TextFrame = textRange.getParentTextFrame();
  const parentShape: PowerPoint.Shape = parentTextFrame.getParentShape();
  const parentSlide: PowerPoint.Slide = parentShape.getParentSlide();
  parentShape.load("id");
  parentSlide.load("id");
  await context.sync();

  console.log(`Selected text range found in parent shape with ID ${parentShape.id} on parentSlide with ID ${parentSlide.id}`);

  console.log("Font properties of selected text range:");
  console.log(`\tallCaps: ${textRange.font.allCaps}`);
  console.log(`\tbold: ${textRange.font.bold}`);
  console.log(`\tcolor: ${textRange.font.color}`);
  console.log(`\tdoubleStrikethrough: ${textRange.font.doubleStrikethrough}`);
  console.log(`\titalic: ${textRange.font.italic}`);
  console.log(`\tname: ${textRange.font.name}`);
  console.log(`\tsize: ${textRange.font.size}`);
  console.log(`\tsmallCaps: ${textRange.font.smallCaps}`);
  console.log(`\tstrikethrough: ${textRange.font.strikethrough}`);
  console.log(`\tsubscript: ${textRange.font.subscript}`);
  console.log(`\tsuperscript: ${textRange.font.superscript}`);
  console.log(`\tunderline: ${textRange.font.underline}`);

  console.log("Paragraph format properties of selected text range:");
  console.log(`\tbulletFormat.visible: ${textRange.paragraphFormat.bulletFormat.visible}`);
  console.log(`\thorizontalAlignment: ${textRange.paragraphFormat.horizontalAlignment}`);
});

Возвращает родительский объект PowerPoint.SlideLayout , содержащий этот Shapeобъект . Создает исключение, если эта фигура не принадлежит .SlideLayout

getParentSlideLayout(): PowerPoint.SlideLayout;

Возвращаемое значение

Комментарии

Набор API: PowerPointApi 1.5

Возвращает родительский объект PowerPoint.SlideLayout , содержащий этот Shapeобъект . Если эта фигура не принадлежит SlideLayout, возвращается объект со свойством isNullObject , которому присвоено значение true . Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.

getParentSlideLayoutOrNullObject(): PowerPoint.SlideLayout;

Возвращаемое значение

Комментарии

Набор API: PowerPointApi 1.5

Возвращает родительский объект PowerPoint.SlideMaster , содержащий этот Shapeобъект . Создает исключение, если эта фигура не принадлежит .SlideMaster

getParentSlideMaster(): PowerPoint.SlideMaster;

Возвращаемое значение

Комментарии

Набор API: PowerPointApi 1.5

Возвращает родительский объект PowerPoint.SlideMaster , содержащий этот Shapeобъект . Если эта фигура не принадлежит SlideMaster, возвращается объект со свойством isNullObject , которому присвоено значение true . Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.

getParentSlideMasterOrNullObject(): PowerPoint.SlideMaster;

Возвращаемое значение

Комментарии

Набор API: PowerPointApi 1.5

Возвращает родительский объект PowerPoint.Slide , содержащий этот Shapeобъект . Если эта фигура не принадлежит Slide, возвращается объект со свойством isNullObject , которому присвоено значение true . Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.

getParentSlideOrNullObject(): PowerPoint.Slide;

Возвращаемое значение

Комментарии

Набор API: PowerPointApi 1.5

Возвращает объект , Table если эта фигура является таблицей.

getTable(): PowerPoint.Table;

Возвращаемое значение

Комментарии

Набор API: PowerPointApi 1.8

Примеры

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

Возвращает объект PowerPoint.TextFrame этого объекта Shape. Если фигура не поддерживает TextFrameобъект , то возвращается объект со свойством isNullObject , для свойства имеет значение true . Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.

getTextFrameOrNullObject(): PowerPoint.TextFrame;

Возвращаемое значение

Комментарии

Набор API: PowerPointApi 1.10

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().

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

Параметры

Возвращаемое значение

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().

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

Параметры

Возвращаемое значение

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().

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

Параметры

Возвращаемое значение

Задает гиперссылку для этого Shape объекта с указанными параметрами. При этом будут удалены все существующие гиперссылки на этом объекте Shape.

setHyperlink(options?: PowerPoint.HyperlinkAddOptions): PowerPoint.Hyperlink;

Параметры

Возвращаемое значение

Только что созданный объект PowerPoint.Hyperlink .

Комментарии

Набор API: PowerPointApi 1.10

Примеры

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

// Updates the hyperlink on the first selected shape on the current slide.
await PowerPoint.run(async (context) => {
  const shape: PowerPoint.Shape = context.presentation.getSelectedShapes().getItemAt(0).load("type");
  const hyperlinkAddOptions: PowerPoint.HyperlinkAddOptions = {
    address: "https://www.microsoft.com",
    screenTip: "Updated screen tip of link on shape",
  };
  const hyperlink: PowerPoint.Hyperlink = shape.setHyperlink(hyperlinkAddOptions).load("address,screenTip");
  try {
    await context.sync();
  } catch {
    console.warn("Confirm that you have at least one slide and you've selected a shape on the active slide.");
    return;
  }

  console.log(
    `Updated link on the selected ${shape.type} shape to "${hyperlink.address}" (screen tip: "${hyperlink.screenTip}").`,
  );
});

Перемещает указанную фигуру вверх или вниз по оси Z в коллекции, что переносит ее вперед или назад относительно других фигур.

setZOrder(position: PowerPoint.ShapeZOrder): void;

Параметры

Возвращаемое значение

Комментарии

Набор API: PowerPointApi 1.8

Примеры

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

Перемещает указанную фигуру вверх или вниз по оси Z в коллекции, что переносит ее вперед или назад относительно других фигур.

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

Параметры

Возвращаемое значение

Комментарии

Набор API: PowerPointApi 1.8

Переопределяет метод JavaScript toJSON() , чтобы обеспечить более полезные выходные данные при передаче объекта API в JSON.stringify(). (JSON.stringifyв свою очередь вызывает toJSON метод переданного ему объекта.) В то время как исходный PowerPoint.Shape объект является объектом API, toJSON метод возвращает обычный объект JavaScript (типизированный как PowerPoint.Interfaces.ShapeData), который содержит неглубокие копии всех загруженных дочерних свойств из исходного объекта.

toJSON(): PowerPoint.Interfaces.ShapeData;

Возвращаемое значение