PowerPoint.Shape class

Devolve um Adjustments objeto que contém valores de ajuste para todos os ajustes nesta forma.

readonly adjustments: PowerPoint.Adjustments;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.10 ]

A descrição do texto alternativo da Forma.

O texto alternativo fornece representações alternativas baseadas em texto das informações contidas na Forma. Estas informações são úteis para pessoas com deficiências visuais ou cognitivas que podem não conseguir ver ou compreender a forma.

altTextDescription: string;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.10 ]

O título do texto alternativo da Forma.

O texto alternativo fornece representações alternativas baseadas em texto das informações contidas na Forma. Estas informações são úteis para pessoas com deficiências visuais ou cognitivas que podem não conseguir ver ou compreender a forma. Um título pode ser lido para uma pessoa portadora de deficiência e é utilizado para determinar se pretende ouvir a descrição do conteúdo.

altTextTitle: string;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.10 ]

O contexto do pedido associado ao objeto . Esta ação liga o processo do suplemento ao processo da aplicação anfitriã do Office.

context: RequestContext;

Valor da propriedade

Obtém o ID de criação da forma. Devolve null se a forma não tiver um ID de criação.

readonly creationId: string | null;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.10 ]

Devolve uma coleção de peças XML personalizadas na forma.

readonly customXmlParts: PowerPoint.CustomXmlPartCollection;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.7 ]

Retorna a formatação de preenchimento dessa forma.

readonly fill: PowerPoint.ShapeFill;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.4 ]

Exemplos

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

Devolve o ShapeGroup associado à forma. Se o tipo de forma não groupfor , este método devolve o GeneralException erro.

readonly group: PowerPoint.ShapeGroup;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.8 ]

Exemplos

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

Especifica a altura, em pontos, da forma. Lança uma exceção InvalidArgument quando definida com um valor negativo.

height: number;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.4 ]

Exemplos

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

Obtém o ID exclusivo da forma.

readonly id: string;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.3 ]

Representa se a forma é decorativa ou não.

Os objetos decorativos acrescentam interesse visual, mas não são informativos (por exemplo, limites estilísticos). Pessoas que utilizam leitores de ecrã irão ouvir que são decorativos para saberem que não faltam informações importantes.

isDecorative: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.10 ]

A distância, em pontos, do lado esquerdo da forma para o lado esquerdo do diapositivo.

left: number;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.4 ]

Exemplos

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

Devolve o nível da forma especificada.

• Um nível de 0 significa que a forma não faz parte de um grupo.

• Um nível de 1 significa que a forma faz parte de um grupo de nível superior.

• Um nível superior a 1 indica que a forma é um grupo aninhado.

readonly level: number;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.8 ]

Retorna a formatação de linha do objeto de forma.

readonly lineFormat: PowerPoint.ShapeLineFormat;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.4 ]

Especifica o nome desta forma.

name: string;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.4 ]

Devolve o grupo principal desta forma. Se a forma não fizer parte de um grupo, este método devolve o GeneralException erro.

readonly parentGroup: PowerPoint.Shape;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.8 ]

Devolve as propriedades que se aplicam especificamente a este marcador de posição. Se o tipo de forma não placeholderfor , este método devolve o GeneralException erro.

readonly placeholderFormat: PowerPoint.PlaceholderFormat;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.8 ]

Exemplos

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

Especifica a rotação, em graus, da forma à volta do eixo z. Um valor positivo indica rotação no sentido dos ponteiros do relógio e um valor negativo indica rotação para a esquerda.

rotation: number;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.10 ]

Devolve uma coleção de etiquetas na forma.

readonly tags: PowerPoint.TagCollection;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.3 ]

Devolve o objeto PowerPoint.TextFrame deste Shape. Gera uma exceção InvalidArgument se a forma não suportar um TextFrame.

readonly textFrame: PowerPoint.TextFrame;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.4 ]

A distância, em pontos, desde a margem superior da forma até à margem superior do diapositivo.

top: number;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.4 ]

Exemplos

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

Retorna o tipo dessa forma. Consulte PowerPoint.ShapeType para obter detalhes.

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

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.4 ]

Exemplos

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

Especifica se a forma está visível.

visible: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.10 ]

Especifica a largura, em pontos, da forma. Lança uma exceção InvalidArgument quando definida com um valor negativo.

width: number;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.4 ]

Exemplos

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

Devolve a posição z-order da forma, com 0 a representar a parte inferior da pilha de encomendas. Cada forma num diapositivo tem uma ordem z exclusiva, mas cada diapositivo também tem uma pilha de ordenação z exclusiva, pelo que duas formas em diapositivos separados podem ter o mesmo número de ordenação z.

readonly zOrderPosition: number;

Valor da propriedade

Comentários

[ Conjunto de API: PowerPointApi 1.8 ]

Exemplos

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

Elimina a forma da coleção de formas. Não faz nada se a forma não existir.

delete(): void;

Retornos

Comentários

[ Conjunto de API: PowerPointApi 1.3 ]

Exemplos

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

Compõe uma imagem da forma.

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

Parâmetros

Retornos

Uma cadeia codificada com Base64 da imagem da forma no formato especificado.

Comentários

[ Conjunto de API: PowerPointApi 1.10 ]

Devolve o objeto principal PowerPoint.Slide que contém este Shape. Gera uma exceção se esta forma não pertencer a um Slide.

getParentSlide(): PowerPoint.Slide;

Retornos

Comentários

[ Conjunto de API: PowerPointApi 1.5 ]

Devolve o objeto principal PowerPoint.SlideLayout que contém este Shape. Gera uma exceção se esta forma não pertencer a um SlideLayout.

getParentSlideLayout(): PowerPoint.SlideLayout;

Retornos

Comentários

[ Conjunto de API: PowerPointApi 1.5 ]

Devolve o objeto principal PowerPoint.SlideLayout que contém este Shape. Se esta forma não pertencer a um , é devolvido um SlideLayoutobjeto com uma isNullObject propriedade definida como true . Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

getParentSlideLayoutOrNullObject(): PowerPoint.SlideLayout;

Retornos

Comentários

[ Conjunto de API: PowerPointApi 1.5 ]

Devolve o objeto principal PowerPoint.SlideMaster que contém este Shape. Gera uma exceção se esta forma não pertencer a um SlideMaster.

getParentSlideMaster(): PowerPoint.SlideMaster;

Retornos

Comentários

[ Conjunto de API: PowerPointApi 1.5 ]

Devolve o objeto principal PowerPoint.SlideMaster que contém este Shape. Se esta forma não pertencer a um , é devolvido um SlideMasterobjeto com uma isNullObject propriedade definida como true . Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

getParentSlideMasterOrNullObject(): PowerPoint.SlideMaster;

Retornos

Comentários

[ Conjunto de API: PowerPointApi 1.5 ]

Devolve o objeto principal PowerPoint.Slide que contém este Shape. Se esta forma não pertencer a um , é devolvido um Slideobjeto com uma isNullObject propriedade definida como true . Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

getParentSlideOrNullObject(): PowerPoint.Slide;

Retornos

Comentários

[ Conjunto de API: PowerPointApi 1.5 ]

Devolve o Table objeto se esta forma for uma tabela.

getTable(): PowerPoint.Table;

Retornos

Comentários

[ Conjunto de API: PowerPointApi 1.8 ]

Exemplos

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

Devolve o objeto PowerPoint.TextFrame deste Shape. Se a forma não suportar um , é devolvido um TextFrameobjeto com uma isNullObject propriedade definida como true . Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

getTextFrameOrNullObject(): PowerPoint.TextFrame;

Retornos

Comentários

[ Conjunto de API: PowerPointApi 1.10 ]

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

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

Parâmetros

Retornos

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

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

Parâmetros

Retornos

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

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

Parâmetros

Retornos

Define uma hiperligação com Shape as opções especificadas. Esta ação eliminará qualquer hiperligação existente neste Shape.

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

Parâmetros

Retornos

O objeto PowerPoint.Hyperlink recentemente criado.

Comentários

[ Conjunto de API: PowerPointApi 1.10 ]

Move a forma especificada para cima ou para baixo na ordem z da coleção, que a desloca para frente ou para trás de outras formas.

setZOrder(position: PowerPoint.ShapeZOrder): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: PowerPointApi 1.8 ]

Exemplos

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

Move a forma especificada para cima ou para baixo na ordem z da coleção, que a desloca para frente ou para trás de outras formas.

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

Parâmetros

Retornos

Comentários

[ Conjunto de API: PowerPointApi 1.8 ]

Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é transmitido para JSON.stringify(). (JSON.stringifypor sua vez, chama o toJSON método do objeto que lhe é transmitido.) Enquanto o objeto original PowerPoint.Shape é um objeto de API, o toJSON método devolve um objeto JavaScript simples (escrito como PowerPoint.Interfaces.ShapeData) que contém cópias rasas de quaisquer propriedades subordinadas carregadas do objeto original.

toJSON(): PowerPoint.Interfaces.ShapeData;

Retornos