ExcelScript.Shape interface

Referência

Pacote:: ExcelScript

Representa um objeto de forma genérica na planilha. Uma forma pode ser uma forma geométrica, uma linha, um grupo de formas, etc.

Comentários

Exemplos

/**
 * This script creates a hexagon shape on the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  const currentSheet = workbook.getActiveWorksheet();
  const hexagon: ExcelScript.Shape = 
    currentSheet.addGeometricShape(ExcelScript.GeometricShapeType.hexagon);
  
  // Set the hexagon size to 40x40 pixels.
  hexagon.setHeight(40);
  hexagon.setWidth(40);

  // Position the hexagon at [100,100] pixels.
  hexagon.setLeft(100);
  hexagon.setTop(100);
}

Métodos

copyTo(destinationSheet)	Copia e cola um `Shape` objeto. A forma colada é copiada para o mesmo local de pixel que essa forma.
delete()	Remove a forma da planilha.
getAltTextDescription()	Especifica o texto de descrição alternativa para um `Shape` objeto.
getAltTextTitle()	Especifica o texto de título alternativo para um `Shape` objeto.
getAsImage(format)	Converte a forma em uma imagem e retorna a imagem como uma cadeia de caracteres de base 64. O DPI é 96. Os únicos formatos com suporte são `ExcelScript.PictureFormat.BMP`,`ExcelScript.PictureFormat.PNG` , , `ExcelScript.PictureFormat.JPEG`e .`ExcelScript.PictureFormat.GIF`
getConnectionSiteCount()	Retorna o número de locais de conexão nessa forma.
getFill()	Retorna a formatação de preenchimento dessa forma.
getGeometricShape()	Retorna a forma geométrica associada à forma. Um erro será lançado, se o tipo de forma não for "GeometricShape".
getGeometricShapeType()	Especifica o tipo de forma geométrica dessa forma geométrica. Confira `ExcelScript.GeometricShapeType` detalhes. Retorna `null` se o tipo de forma não for "GeometricShape".
getGroup()	Retorna o grupo de forma associado à forma. Um erro será lançado, se o tipo de forma não for "GroupShape".
getHeight()	Especifica a altura, em pontos, da forma. Gera uma exceção `InvalidArgument` quando definida com um valor negativo ou zero como uma entrada.
getId()	Especifica o identificador de forma.
getImage()	Retorna a imagem associada à forma. Um erro será lançado, se o tipo de forma não for "Imagem".
getImageAsBase64(format)	Converte a forma em uma imagem e retorna a imagem como uma cadeia de caracteres de base 64. O DPI é 96. Os únicos formatos com suporte são `ExcelScript.PictureFormat.BMP`,`ExcelScript.PictureFormat.PNG` , , `ExcelScript.PictureFormat.JPEG`e .`ExcelScript.PictureFormat.GIF`
getLeft()	A distância, em pontos, da lateral esquerda da forma do lado esquerdo da planilha. Gera uma exceção `InvalidArgument` quando definida com um valor negativo como uma entrada.
getLevel()	Especifica o nível da forma especificada. Por exemplo, um nível de 0 significa que a forma não faz parte de nenhum grupo, um nível de 1 significa que a forma é parte de um grupo de nível superior e um nível 2 significa que a forma faz parte de um subgrupo do nível superior.
getLine()	Retorna a linha associada à forma. Um erro será lançado, se o tipo de forma não for "Linha".
getLineFormat()	Retorna a formatação de linha do objeto de forma.
getLockAspectRatio()	Especifica se a proporção dessa forma está bloqueada.
getName()	Especifica o nome da forma.
getParentGroup()	Especifica o grupo pai dessa forma.
getPlacement()	Representa como o objeto é anexado às células abaixo dela.
getRotation()	Especifica a rotação, em graus, da forma.
getTextFrame()	Retorna o objeto text frame de uma forma.
getTop()	A distância, em pontos, da borda superior da forma até a borda superior da planilha. Gera uma exceção `InvalidArgument` quando definida com um valor negativo como uma entrada.
getType()	Retorna o tipo dessa forma. Confira `ExcelScript.ShapeType` detalhes.
getVisible()	Especifica se a forma está visível.
getWidth()	Especifica a largura, em pontos, da forma. Gera uma exceção `InvalidArgument` quando definida com um valor negativo ou zero como uma entrada.
getZOrderPosition()	Retorna a posição da forma especificada na ordem z, com 0 representando a parte inferior da pilha do pedido.
incrementLeft(increment)	Move a forma horizontalmente pelo número especificado de pontos.
incrementRotation(increment)	O formato é girado em sentido horário ao redor do eixo z pelo número especificado de graus. Use a `rotation` propriedade para definir a rotação absoluta da forma.
incrementTop(increment)	Move a forma verticalmente pelo número especificado de pontos.
scaleHeight(scaleFactor, scaleType, scaleFrom)	Dimensiona a altura da forma por um fator especificado. Para imagens, é possível indicar se você deseja dimensionar a forma em relação ao tamanho original ou ao tamanho atual. As formas que não são figuras serão sempre dimensionadas em relação à sua altura atual.
scaleWidth(scaleFactor, scaleType, scaleFrom)	Dimensiona a largura da forma por um fator especificado. Para imagens, é possível indicar se você deseja dimensionar a forma em relação ao tamanho original ou ao tamanho atual. As formas que não são figuras serão sempre dimensionadas em relação à sua largura atual.
setAltTextDescription(altTextDescription)	Especifica o texto de descrição alternativa para um `Shape` objeto.
setAltTextTitle(altTextTitle)	Especifica o texto de título alternativo para um `Shape` objeto.
setGeometricShapeType(geometricShapeType)	Especifica o tipo de forma geométrica dessa forma geométrica. Confira `ExcelScript.GeometricShapeType` detalhes. Retorna `null` se o tipo de forma não for "GeometricShape".
setHeight(height)	Especifica a altura, em pontos, da forma. Gera uma exceção `InvalidArgument` quando definida com um valor negativo ou zero como uma entrada.
setLeft(left)	A distância, em pontos, da lateral esquerda da forma do lado esquerdo da planilha. Gera uma exceção `InvalidArgument` quando definida com um valor negativo como uma entrada.
setLockAspectRatio(lockAspectRatio)	Especifica se a proporção dessa forma está bloqueada.
setName(name)	Especifica o nome da forma.
setPlacement(placement)	Representa como o objeto é anexado às células abaixo dela.
setRotation(rotation)	Especifica a rotação, em graus, da forma.
setTop(top)	A distância, em pontos, da borda superior da forma até a borda superior da planilha. Gera uma exceção `InvalidArgument` quando definida com um valor negativo como uma entrada.
setVisible(visible)	Especifica se a forma está visível.
setWidth(width)	Especifica a largura, em pontos, da forma. Gera uma exceção `InvalidArgument` quando definida com um valor negativo ou zero como uma entrada.
setZOrder(position)	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.

Detalhes do método

copyTo(destinationSheet)

Copia e cola um Shape objeto. A forma colada é copiada para o mesmo local de pixel que essa forma.

copyTo(destinationSheet?: Worksheet | string): Shape;

Parâmetros

destinationSheet: ExcelScript.Worksheet | string

A folha à qual o objeto de forma será colado. O valor padrão é a planilha da forma copiada.

Retornos

ExcelScript.Shape

delete()

Remove a forma da planilha.

delete(): void;

Retornos

void

Exemplos

/**
 * This script deletes all the shapes on the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the collection of shapes on the currently selected worksheet.
  const shapes = workbook.getActiveWorksheet().getShapes();

  // Remove each shape.
  shapes.forEach(shape =>{
    shape.delete();
  });
}

getAltTextDescription()

Especifica o texto de descrição alternativa para um Shape objeto.

getAltTextDescription(): string;

Retornos

string

getAltTextTitle()

Especifica o texto de título alternativo para um Shape objeto.

getAltTextTitle(): string;

Retornos

string

getAsImage(format)

Aviso

Essa API foi preterida.

Use getImageAsBase64 instead.

Converte a forma em uma imagem e retorna a imagem como uma cadeia de caracteres de base 64. O DPI é 96. Os únicos formatos com suporte são ExcelScript.PictureFormat.BMP,ExcelScript.PictureFormat.PNG , , ExcelScript.PictureFormat.JPEGe .ExcelScript.PictureFormat.GIF

getAsImage(format: PictureFormat): string;

Parâmetros

format: ExcelScript.PictureFormat

Especifica o formato da imagem.

Retornos

string

Exemplos

/**
 * This script creates a star shape with the value from cell A1.
 * It then returns the image as a base64-encoded string. 
 * This string would be used as part of a Power Automate flow to add the image elsewhere.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the value of A1 from the worksheet named Sheet1.
  const sheet = workbook.getWorksheet("Sheet1");
  const value = sheet.getRange("A1").getValue();

  // Create a Shape object that looks like a 5-pointed star.
  const star = sheet.addGeometricShape(ExcelScript.GeometricShapeType.star5);

  // Set the text of star and make sure the shape fits the text.
  const textFrame = star.getTextFrame();
  textFrame.getTextRange().setText(value.toString());
  textFrame.setAutoSizeSetting(ExcelScript.ShapeAutoSize.autoSizeShapeToFitText);

  // Return the shape as a PNG image represented by a base64-encoded string.
  return star.getAsImage(ExcelScript.PictureFormat.png);
}

getConnectionSiteCount()

Retorna o número de locais de conexão nessa forma.

getConnectionSiteCount(): number;

Retornos

number

getFill()

Retorna a formatação de preenchimento dessa forma.

getFill(): ShapeFill;

Retornos

ExcelScript.ShapeFill

getGeometricShape()

Retorna a forma geométrica associada à forma. Um erro será lançado, se o tipo de forma não for "GeometricShape".

getGeometricShape(): GeometricShape;

Retornos

ExcelScript.GeometricShape

getGeometricShapeType()

Especifica o tipo de forma geométrica dessa forma geométrica. Confira ExcelScript.GeometricShapeType detalhes. Retorna null se o tipo de forma não for "GeometricShape".

getGeometricShapeType(): GeometricShapeType;

Retornos

ExcelScript.GeometricShapeType

getGroup()

Retorna o grupo de forma associado à forma. Um erro será lançado, se o tipo de forma não for "GroupShape".

getGroup(): ShapeGroup;

Retornos

ExcelScript.ShapeGroup

getHeight()

Especifica a altura, em pontos, da forma. Gera uma exceção InvalidArgument quando definida com um valor negativo ou zero como uma entrada.

getHeight(): number;

Retornos

number

getId()

Especifica o identificador de forma.

getId(): string;

Retornos

string

getImage()

Retorna a imagem associada à forma. Um erro será lançado, se o tipo de forma não for "Imagem".

getImage(): Image;

Retornos

ExcelScript.Image

Exemplos

/**
 * This script transfers an image from one worksheet to another.
 */
function main(workbook: ExcelScript.Workbook)
{
  // Get the worksheet with the image on it.
  let firstWorksheet = workbook.getWorksheet("FirstSheet");

  // Get the first image from the worksheet.
  // If a script added the image, you could add a name to make it easier to find.
  let image: ExcelScript.Image;
  firstWorksheet.getShapes().forEach((shape, index) => {
    if (shape.getType() === ExcelScript.ShapeType.image) {
      image = shape.getImage();
      return;
    }
  });

  // Copy the image to another worksheet.
  image.getShape().copyTo("SecondSheet");
}

getImageAsBase64(format)

getImageAsBase64(format: PictureFormat): string;

Parâmetros

format: ExcelScript.PictureFormat

Especifica o formato da imagem.

Retornos

string

getLeft()

A distância, em pontos, da lateral esquerda da forma do lado esquerdo da planilha. Gera uma exceção InvalidArgument quando definida com um valor negativo como uma entrada.

getLeft(): number;

Retornos

number

getLevel()

Especifica o nível da forma especificada. Por exemplo, um nível de 0 significa que a forma não faz parte de nenhum grupo, um nível de 1 significa que a forma é parte de um grupo de nível superior e um nível 2 significa que a forma faz parte de um subgrupo do nível superior.

getLevel(): number;

Retornos

number

getLine()

Retorna a linha associada à forma. Um erro será lançado, se o tipo de forma não for "Linha".

getLine(): Line;

Retornos

ExcelScript.Line

Exemplos

/**
 * This script adds a line that goes from cell B2 to cell F4 on the current worksheet.
 */ 
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  const sheet = workbook.getActiveWorksheet();

  // Get the ranges for the two cells.
  const b2Range = sheet.getRange("B2");
  const f4Range = sheet.getRange("F4");

  // Add a straight line that connects the top-left corners of both cells.
  const newShape = sheet.addLine(
    b2Range.getLeft(),
    b2Range.getTop(),
    f4Range.getLeft(),
    f4Range.getTop(),
    ExcelScript.ConnectorType.straight);

  // Add an open arrowhead to the end of the line, such that it points at F4.
  const line = newShape.getLine();
  line.setEndArrowheadStyle(ExcelScript.ArrowheadStyle.open);
}

getLineFormat()

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

getLineFormat(): ShapeLineFormat;

Retornos

ExcelScript.ShapeLineFormat

getLockAspectRatio()

Especifica se a proporção dessa forma está bloqueada.

getLockAspectRatio(): boolean;

Retornos

boolean

getName()

Especifica o nome da forma.

getName(): string;

Retornos

string

getParentGroup()

Especifica o grupo pai dessa forma.

getParentGroup(): Shape;

Retornos

ExcelScript.Shape

getPlacement()

Representa como o objeto é anexado às células abaixo dela.

getPlacement(): Placement;

Retornos

ExcelScript.Placement

getRotation()

Especifica a rotação, em graus, da forma.

getRotation(): number;

Retornos

number

getTextFrame()

Retorna o objeto text frame de uma forma.

getTextFrame(): TextFrame;

Retornos

ExcelScript.TextFrame

Exemplos

/**
 * This script creates a star shape with the value from cell A1.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the value of A1 from the worksheet named Sheet1.
  const sheet = workbook.getWorksheet("Sheet1");
  const value = sheet.getRange("A1").getValue();

  // Create a Shape object that looks like a 5-pointed star.
  const star = sheet.addGeometricShape(ExcelScript.GeometricShapeType.star5);

  // Set the text of star and make sure the shape fits the text.
  const textFrame = star.getTextFrame();
  textFrame.getTextRange().setText(value.toString());
  textFrame.setAutoSizeSetting(ExcelScript.ShapeAutoSize.autoSizeShapeToFitText);
}

getTop()

A distância, em pontos, da borda superior da forma até a borda superior da planilha. Gera uma exceção InvalidArgument quando definida com um valor negativo como uma entrada.

getTop(): number;

Retornos

number

getType()

Retorna o tipo dessa forma. Confira ExcelScript.ShapeType detalhes.

getType(): ShapeType;

Retornos

ExcelScript.ShapeType

getVisible()

Especifica se a forma está visível.

getVisible(): boolean;

Retornos

boolean

getWidth()

Especifica a largura, em pontos, da forma. Gera uma exceção InvalidArgument quando definida com um valor negativo ou zero como uma entrada.

getWidth(): number;

Retornos

number

getZOrderPosition()

Retorna a posição da forma especificada na ordem z, com 0 representando a parte inferior da pilha do pedido.

getZOrderPosition(): number;

Retornos

number

incrementLeft(increment)

Move a forma horizontalmente pelo número especificado de pontos.

incrementLeft(increment: number): void;

Parâmetros

increment: number

O incremento, em pontos, a forma será movida horizontalmente. Um valor positivo move a forma para a direita e um valor negativo a move para a esquerda. Se a planilha estiver orientada da direita para a esquerda, isso será revertido: valores positivos moverão a forma para a esquerda e os valores negativos a moverão para a direita.

Retornos

void

incrementRotation(increment)

O formato é girado em sentido horário ao redor do eixo z pelo número especificado de graus. Use a rotation propriedade para definir a rotação absoluta da forma.

incrementRotation(increment: number): void;

Parâmetros

increment: number

Quantos graus a forma será girada. Um valor positivo gira a forma no sentido horário e um valor negativo gira-a no sentido anti-horário.

Retornos

void

incrementTop(increment)

Move a forma verticalmente pelo número especificado de pontos.

incrementTop(increment: number): void;

Parâmetros

increment: number

O incremento, em pontos, a forma será movida verticalmente. Um valor positivo move a forma para baixo e um valor negativo a move para cima.

Retornos

void

scaleHeight(scaleFactor, scaleType, scaleFrom)

Dimensiona a altura da forma por um fator especificado. Para imagens, é possível indicar se você deseja dimensionar a forma em relação ao tamanho original ou ao tamanho atual. As formas que não são figuras serão sempre dimensionadas em relação à sua altura atual.

scaleHeight(
            scaleFactor: number,
            scaleType: ShapeScaleType,
            scaleFrom?: ShapeScaleFrom
        ): void;

Parâmetros

scaleFactor: number

Especifica a proporção entre a altura da forma após você redimensioná-la e a altura atual ou original.

scaleType: ExcelScript.ShapeScaleType

Especifica se a forma é dimensionada em relação ao tamanho original ou atual. A opção de dimensionamento de tamanho original só funciona para imagens.

scaleFrom: ExcelScript.ShapeScaleFrom

Opcional. Especifica qual parte da forma mantém sua posição quando a forma é dimensionada. Se omitido, ele representa o canto superior esquerdo da forma mantém sua posição.

Retornos

void

scaleWidth(scaleFactor, scaleType, scaleFrom)

Dimensiona a largura da forma por um fator especificado. Para imagens, é possível indicar se você deseja dimensionar a forma em relação ao tamanho original ou ao tamanho atual. As formas que não são figuras serão sempre dimensionadas em relação à sua largura atual.

scaleWidth(
            scaleFactor: number,
            scaleType: ShapeScaleType,
            scaleFrom?: ShapeScaleFrom
        ): void;

Parâmetros

scaleFactor: number

Especifica a proporção entre a largura da forma após você redimensioná-la e a largura atual ou original.

scaleType: ExcelScript.ShapeScaleType

Especifica se a forma é dimensionada em relação ao tamanho original ou atual. A opção de dimensionamento de tamanho original só funciona para imagens.

scaleFrom: ExcelScript.ShapeScaleFrom

Opcional. Especifica qual parte da forma mantém sua posição quando a forma é dimensionada. Se omitido, ele representa o canto superior esquerdo da forma mantém sua posição.

Retornos

void

setAltTextDescription(altTextDescription)

Especifica o texto de descrição alternativa para um Shape objeto.

setAltTextDescription(altTextDescription: string): void;

Parâmetros

altTextDescription: string

Retornos

void

setAltTextTitle(altTextTitle)

Especifica o texto de título alternativo para um Shape objeto.

setAltTextTitle(altTextTitle: string): void;

Parâmetros

altTextTitle: string

Retornos

void

setGeometricShapeType(geometricShapeType)

Especifica o tipo de forma geométrica dessa forma geométrica. Confira ExcelScript.GeometricShapeType detalhes. Retorna null se o tipo de forma não for "GeometricShape".

setGeometricShapeType(geometricShapeType: GeometricShapeType): void;

Parâmetros

geometricShapeType: ExcelScript.GeometricShapeType

Retornos

void

setHeight(height)

Especifica a altura, em pontos, da forma. Gera uma exceção InvalidArgument quando definida com um valor negativo ou zero como uma entrada.

setHeight(height: number): void;

Parâmetros

height: number

Retornos

void

setLeft(left)

A distância, em pontos, da lateral esquerda da forma do lado esquerdo da planilha. Gera uma exceção InvalidArgument quando definida com um valor negativo como uma entrada.

setLeft(left: number): void;

Parâmetros

left: number

Retornos

void

setLockAspectRatio(lockAspectRatio)

Especifica se a proporção dessa forma está bloqueada.

setLockAspectRatio(lockAspectRatio: boolean): void;

Parâmetros

lockAspectRatio: boolean

Retornos

void

setName(name)

Especifica o nome da forma.

setName(name: string): void;

Parâmetros

name: string

Retornos

void

Exemplos

/**
 * This script creates a triangle shape on the current worksheet and names it "TRI".
 */
function main(workbook: ExcelScript.Workbook) {
  const currentSheet = workbook.getActiveWorksheet();
  const triangle: ExcelScript.Shape = 
    currentSheet.addGeometricShape(ExcelScript.GeometricShapeType.triangle);
  
  triangle.setName("TRI");
}

setPlacement(placement)

Representa como o objeto é anexado às células abaixo dela.

setPlacement(placement: Placement): void;

Parâmetros

placement: ExcelScript.Placement

Retornos

void

Exemplos

/**
 * This script creates a diamond shape at cell C3.
 * The shape moves and resizes as the grid underneath it changes.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get cell C3 in the current worksheet.
  const sheet = workbook.getActiveWorksheet();
  const cell = sheet.getRange("C3");

  // Create a diamond that slightly overlaps the cell C3.
  const diamond = sheet.addGeometricShape(ExcelScript.GeometricShapeType.diamond);
  // Set each dimension so that the shape extends 5 pixels beyond the cell borders.
  diamond.setLeft(cell.getLeft() - 5);
  diamond.setTop(cell.getTop() - 5);
  diamond.setHeight(cell.getHeight() + 10);
  diamond.setWidth(cell.getWidth() + 10);

  // Set the placement of the shape so that it resizes and moves with the grid.
  diamond.setPlacement(ExcelScript.Placement.twoCell);
}

setRotation(rotation)

Especifica a rotação, em graus, da forma.

setRotation(rotation: number): void;

Parâmetros

rotation: number

Retornos

void

setTop(top)

A distância, em pontos, da borda superior da forma até a borda superior da planilha. Gera uma exceção InvalidArgument quando definida com um valor negativo como uma entrada.

setTop(top: number): void;

Parâmetros

top: number

Retornos

void

setVisible(visible)

Especifica se a forma está visível.

setVisible(visible: boolean): void;

Parâmetros

visible: boolean

Retornos

void

setWidth(width)

Especifica a largura, em pontos, da forma. Gera uma exceção InvalidArgument quando definida com um valor negativo ou zero como uma entrada.

setWidth(width: number): void;

Parâmetros

width: number

Retornos

void

setZOrder(position)

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: ShapeZOrder): void;

Parâmetros

position: ExcelScript.ShapeZOrder

Para onde mover a forma na pilha de ordem z em relação às outras formas. Confira ExcelScript.ShapeZOrder detalhes.

Retornos

void