ExcelScript.Shape interface

Referência

Pacote:: ExcelScript

Representa um objeto de forma genérico na folha de cálculo. 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 a mesma localização de píxeis que esta forma.
delete()	Remove a forma da planilha.
getAltTextDescription()	Especifica o texto de descrição alternativo de 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 suportados 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 desta forma geométrica. Veja `ExcelScript.GeometricShapeType` para obter detalhes. Devolve `null` se o tipo de forma não for "Forma Geométrica".
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 entrada.
getId()	Especifica o identificador da 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 suportados 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. Lança uma exceção `InvalidArgument` quando definida com um valor negativo como 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 desta forma está bloqueada.
getName()	Especifica o nome da forma.
getParentGroup()	Especifica o grupo principal desta 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. Lança uma exceção `InvalidArgument` quando definida com um valor negativo como entrada.
getType()	Retorna o tipo dessa forma. Veja `ExcelScript.ShapeType` para obter 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 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. Utilize 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 alternativo de 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 desta forma geométrica. Veja `ExcelScript.GeometricShapeType` para obter detalhes. Devolve `null` se o tipo de forma não for "Forma Geométrica".
setHeight(height)	Especifica a altura, em pontos, da forma. Gera uma exceção `InvalidArgument` quando definida com um valor negativo ou zero como entrada.
setLeft(left)	A distância, em pontos, da lateral esquerda da forma do lado esquerdo da planilha. Lança uma exceção `InvalidArgument` quando definida com um valor negativo como entrada.
setLockAspectRatio(lockAspectRatio)	Especifica se a proporção desta 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. Lança uma exceção `InvalidArgument` quando definida com um valor negativo como 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 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 a mesma localização de píxeis que esta forma.

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

Parâmetros

destinationSheet: ExcelScript.Worksheet | string

A folha à qual o objeto da forma será colado. O valor predefinido é a folha de cálculo 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 alternativo de 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 suportados 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 desta forma geométrica. Veja ExcelScript.GeometricShapeType para obter detalhes. Devolve null se o tipo de forma não for "Forma Geométrica".

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 entrada.

getHeight(): number;

Retornos

number

getId()

Especifica o identificador da 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. Lança uma exceção InvalidArgument quando definida com um valor negativo como 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 desta forma está bloqueada.

getLockAspectRatio(): boolean;

Retornos

boolean

getName()

Especifica o nome da forma.

getName(): string;

Retornos

string

getParentGroup()

Especifica o grupo principal desta 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. Lança uma exceção InvalidArgument quando definida com um valor negativo como entrada.

getTop(): number;

Retornos

number

getType()

Retorna o tipo dessa forma. Veja ExcelScript.ShapeType para obter 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 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 move-a para a esquerda. Se a folha for orientada da direita para a esquerda, isto é invertido: os valores positivos irão mover a forma para a esquerda e os valores negativos irão movê-la 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. Utilize a rotation propriedade para definir a rotação absoluta da forma.

incrementRotation(increment: number): void;

Parâmetros

increment: number

Quantos graus a forma será rodada. Um valor positivo roda a forma no sentido dos ponteiros do relógio e um valor negativo roda-a para a esquerda.

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 move-a 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 relativamente ao respetivo tamanho original ou atual. A opção de dimensionamento do 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 for omitido, representa que o canto superior esquerdo da forma mantém a 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 relativamente ao respetivo tamanho original ou atual. A opção de dimensionamento do 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 for omitido, representa que o canto superior esquerdo da forma mantém a sua posição.

Retornos

void

setAltTextDescription(altTextDescription)

Especifica o texto de descrição alternativo de 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 desta forma geométrica. Veja ExcelScript.GeometricShapeType para obter detalhes. Devolve null se o tipo de forma não for "Forma Geométrica".

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 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. Lança uma exceção InvalidArgument quando definida com um valor negativo como entrada.

setLeft(left: number): void;

Parâmetros

left: number

Retornos

void

setLockAspectRatio(lockAspectRatio)

Especifica se a proporção desta 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. Lança uma exceção InvalidArgument quando definida com um valor negativo como 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 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 ordenação z relativamente às outras formas. Veja ExcelScript.ShapeZOrder para obter detalhes.

Retornos

void

Compartilhar via

ExcelScript.Shape interface

Comentários

Exemplos

Métodos

Detalhes do método

copyTo(destinationSheet)

Parâmetros

Retornos

delete()

Retornos

Exemplos

getAltTextDescription()

Retornos

getAltTextTitle()

Retornos

getAsImage(format)

Parâmetros

Retornos

Exemplos

getConnectionSiteCount()

Retornos

getFill()

Retornos

getGeometricShape()

Retornos

getGeometricShapeType()

Retornos

getGroup()

Retornos

getHeight()

Retornos

getId()

Retornos

getImage()

Retornos

Exemplos

getImageAsBase64(format)

Parâmetros

Retornos

getLeft()

Retornos

getLevel()

Retornos

getLine()

Retornos

Exemplos

getLineFormat()

Retornos

getLockAspectRatio()

Retornos

getName()

Retornos

getParentGroup()

Retornos

getPlacement()

Retornos

getRotation()

Retornos

getTextFrame()

Retornos

Exemplos

getTop()

Retornos

getType()

Retornos

getVisible()

Retornos

getWidth()

Retornos

getZOrderPosition()

Retornos

incrementLeft(increment)

Parâmetros

Retornos

incrementRotation(increment)

Parâmetros

Retornos

incrementTop(increment)

Parâmetros