ExcelScript.Shape interface

Referencia

Paquete:: ExcelScript

Representa un objeto de forma genérico en la hoja de cálculo. Una forma podría ser una forma geométrica, una línea, un grupo de formas, etc.

Comentarios

Ejemplos

/**
 * 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 y pega un `Shape` objeto. La forma pegada se copia en la misma ubicación de píxel que esta forma.
delete()	Quita la forma de la hoja de cálculo.
getAltTextDescription()	Especifica el texto de descripción alternativo de un `Shape` objeto.
getAltTextTitle()	Especifica el texto de título alternativo de un `Shape` objeto.
getAsImage(format)	Convierte la forma a una imagen y devuelve la imagen como una cadena con codificación base 64. El valor de PPP es 96. Los únicos formatos admitidos son `ExcelScript.PictureFormat.BMP`,`ExcelScript.PictureFormat.PNG` ,`ExcelScript.PictureFormat.JPEG` y .`ExcelScript.PictureFormat.GIF`
getConnectionSiteCount()	Devuelve el número de sitios de conexión en esta forma.
getFill()	Devuelve el formato de relleno de esta forma.
getGeometricShape()	Devuelve la forma geométrica asociada con la forma. Produce un error si el tipo de forma no es "GeometricShape".
getGeometricShapeType()	Especifica el tipo de forma geométrica de esta forma geométrica. Vea `ExcelScript.GeometricShapeType` para más información. Devuelve `null` si el tipo de forma no es "GeometricShape".
getGroup()	Devuelve el grupo de forma asociado con la forma. Produce un error si el tipo de forma no es "GroupShape".
getHeight()	Especifica el alto, en puntos, de la forma. Produce una `InvalidArgument` excepción cuando se establece con un valor negativo o cero como entrada.
getId()	Especifica el identificador de forma.
getImage()	Devuelve la imagen asociada con la forma. Produce un error si el tipo de forma no es "Image".
getImageAsBase64(format)	Convierte la forma a una imagen y devuelve la imagen como una cadena con codificación base 64. El valor de PPP es 96. Los únicos formatos admitidos son `ExcelScript.PictureFormat.BMP`,`ExcelScript.PictureFormat.PNG` ,`ExcelScript.PictureFormat.JPEG` y .`ExcelScript.PictureFormat.GIF`
getLeft()	La distancia, en puntos, desde el lado izquierdo de la forma hasta el lado izquierdo de la hoja de cálculo. Produce una `InvalidArgument` excepción cuando se establece con un valor negativo como entrada.
getLevel()	Especifica el nivel de la forma especificada. Por ejemplo, un nivel de 0 significa que la forma no es parte de ningún grupo, un nivel de 1 significa que la forma es parte de un grupo del nivel superior y un nivel 2 significa que la forma es parte de un grupo secundario del nivel superior.
getLine()	Devuelve la línea asociada con la forma. Produce un error si el tipo de forma no es "Line".
getLineFormat()	Devuelve el formato de línea de esta forma.
getLockAspectRatio()	Especifica si la relación de aspecto de esta forma está bloqueada.
getName()	Especifica el nombre de la forma.
getParentGroup()	Especifica el grupo primario de esta forma.
getPlacement()	Representa cómo está asociado el objeto a las celdas inferiores.
getRotation()	Especifica la rotación, en grados, de la forma.
getTextFrame()	Devuelve el objeto de marco de texto de esta forma.
getTop()	La distancia, en puntos, desde el borde superior de la forma al borde superior de la hoja de cálculo. Produce una `InvalidArgument` excepción cuando se establece con un valor negativo como entrada.
getType()	Devuelve el tipo de esta forma. Vea `ExcelScript.ShapeType` para más información.
getVisible()	Especifica si la forma está visible.
getWidth()	Especifica el ancho, en puntos, de la forma. Produce una `InvalidArgument` excepción cuando se establece con un valor negativo o cero como entrada.
getZOrderPosition()	Devuelve la posición de la forma especificada en el orden z, siendo 0 la parte inferior de la pila del orden.
incrementLeft(increment)	Mueve la forma horizontalmente el número de puntos especificado.
incrementRotation(increment)	Gira la forma en el sentido de las agujas del reloj alrededor del eje Z según el número de grados. Use la `rotation` propiedad para establecer la rotación absoluta de la forma.
incrementTop(increment)	Mueve la forma verticalmente el número de puntos.
scaleHeight(scaleFactor, scaleType, scaleFrom)	Cambia el alto de la forma en un factor especificado. Para imágenes, puede indicar si desea aplicar una escala a la forma respecto al tamaño original o al actual. El tamaño de las formas distintas de imágenes siempre se ajusta en relación con su alto actual.
scaleWidth(scaleFactor, scaleType, scaleFrom)	Cambia el ancho de la forma en un factor especificado. Para imágenes, puede indicar si desea aplicar una escala a la forma respecto al tamaño original o al actual. El tamaño de las formas distintas de imágenes siempre se ajusta con relación a su ancho actual.
setAltTextDescription(altTextDescription)	Especifica el texto de descripción alternativo de un `Shape` objeto.
setAltTextTitle(altTextTitle)	Especifica el texto de título alternativo de un `Shape` objeto.
setGeometricShapeType(geometricShapeType)	Especifica el tipo de forma geométrica de esta forma geométrica. Vea `ExcelScript.GeometricShapeType` para más información. Devuelve `null` si el tipo de forma no es "GeometricShape".
setHeight(height)	Especifica el alto, en puntos, de la forma. Produce una `InvalidArgument` excepción cuando se establece con un valor negativo o cero como entrada.
setLeft(left)	La distancia, en puntos, desde el lado izquierdo de la forma hasta el lado izquierdo de la hoja de cálculo. Produce una `InvalidArgument` excepción cuando se establece con un valor negativo como entrada.
setLockAspectRatio(lockAspectRatio)	Especifica si la relación de aspecto de esta forma está bloqueada.
setName(name)	Especifica el nombre de la forma.
setPlacement(placement)	Representa cómo está asociado el objeto a las celdas inferiores.
setRotation(rotation)	Especifica la rotación, en grados, de la forma.
setTop(top)	La distancia, en puntos, desde el borde superior de la forma al borde superior de la hoja de cálculo. Produce una `InvalidArgument` excepción cuando se establece con un valor negativo como entrada.
setVisible(visible)	Especifica si la forma está visible.
setWidth(width)	Especifica el ancho, en puntos, de la forma. Produce una `InvalidArgument` excepción cuando se establece con un valor negativo o cero como entrada.
setZOrder(position)	Mueve la forma especificada hacia arriba o hacia abajo en el orden z de la colección, que se desplaza delante o detrás de otras formas.

Detalles del método

copyTo(destinationSheet)

Copia y pega un Shape objeto. La forma pegada se copia en la misma ubicación de píxel que esta forma.

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

Parámetros

destinationSheet: ExcelScript.Worksheet | string

Hoja en la que se pegará el objeto de forma. El valor predeterminado es la hoja de cálculo de la forma copiada.

Devoluciones

ExcelScript.Shape

delete()

Quita la forma de la hoja de cálculo.

delete(): void;

Devoluciones

void

Ejemplos

/**
 * 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 el texto de descripción alternativo de un Shape objeto.

getAltTextDescription(): string;

Devoluciones

string

getAltTextTitle()

Especifica el texto de título alternativo de un Shape objeto.

getAltTextTitle(): string;

Devoluciones

string

getAsImage(format)

Advertencia

Esta API ya está en desuso.

Use getImageAsBase64 instead.

Convierte la forma a una imagen y devuelve la imagen como una cadena con codificación base 64. El valor de PPP es 96. Los únicos formatos admitidos son ExcelScript.PictureFormat.BMP,ExcelScript.PictureFormat.PNG ,ExcelScript.PictureFormat.JPEG y .ExcelScript.PictureFormat.GIF

getAsImage(format: PictureFormat): string;

Parámetros

format: ExcelScript.PictureFormat

Especifica el formato de la imagen.

Devoluciones

string

Ejemplos

/**
 * 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()

Devuelve el número de sitios de conexión en esta forma.

getConnectionSiteCount(): number;

Devoluciones

number

getFill()

Devuelve el formato de relleno de esta forma.

getFill(): ShapeFill;

Devoluciones

ExcelScript.ShapeFill

getGeometricShape()

Devuelve la forma geométrica asociada con la forma. Produce un error si el tipo de forma no es "GeometricShape".

getGeometricShape(): GeometricShape;

Devoluciones

ExcelScript.GeometricShape

getGeometricShapeType()

Especifica el tipo de forma geométrica de esta forma geométrica. Vea ExcelScript.GeometricShapeType para más información. Devuelve null si el tipo de forma no es "GeometricShape".

getGeometricShapeType(): GeometricShapeType;

Devoluciones

ExcelScript.GeometricShapeType

getGroup()

Devuelve el grupo de forma asociado con la forma. Produce un error si el tipo de forma no es "GroupShape".

getGroup(): ShapeGroup;

Devoluciones

ExcelScript.ShapeGroup

getHeight()

Especifica el alto, en puntos, de la forma. Produce una InvalidArgument excepción cuando se establece con un valor negativo o cero como entrada.

getHeight(): number;

Devoluciones

number

getId()

Especifica el identificador de forma.

getId(): string;

Devoluciones

string

getImage()

Devuelve la imagen asociada con la forma. Produce un error si el tipo de forma no es "Image".

getImage(): Image;

Devoluciones

ExcelScript.Image

Ejemplos

/**
 * 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 el formato de la imagen.

Devoluciones

string

getLeft()

La distancia, en puntos, desde el lado izquierdo de la forma hasta el lado izquierdo de la hoja de cálculo. Produce una InvalidArgument excepción cuando se establece con un valor negativo como entrada.

getLeft(): number;

Devoluciones

number

getLevel()

Especifica el nivel de la forma especificada. Por ejemplo, un nivel de 0 significa que la forma no es parte de ningún grupo, un nivel de 1 significa que la forma es parte de un grupo del nivel superior y un nivel 2 significa que la forma es parte de un grupo secundario del nivel superior.

getLevel(): number;

Devoluciones

number

getLine()

Devuelve la línea asociada con la forma. Produce un error si el tipo de forma no es "Line".

getLine(): Line;

Devoluciones

ExcelScript.Line

Ejemplos

/**
 * 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()

Devuelve el formato de línea de esta forma.

getLineFormat(): ShapeLineFormat;

Devoluciones

ExcelScript.ShapeLineFormat

getLockAspectRatio()

Especifica si la relación de aspecto de esta forma está bloqueada.

getLockAspectRatio(): boolean;

Devoluciones

boolean

getName()

Especifica el nombre de la forma.

getName(): string;

Devoluciones

string

getParentGroup()

Especifica el grupo primario de esta forma.

getParentGroup(): Shape;

Devoluciones

ExcelScript.Shape

getPlacement()

Representa cómo está asociado el objeto a las celdas inferiores.

getPlacement(): Placement;

Devoluciones

ExcelScript.Placement

getRotation()

Especifica la rotación, en grados, de la forma.

getRotation(): number;

Devoluciones

number

getTextFrame()

Devuelve el objeto de marco de texto de esta forma.

getTextFrame(): TextFrame;

Devoluciones

ExcelScript.TextFrame

Ejemplos

/**
 * 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()

La distancia, en puntos, desde el borde superior de la forma al borde superior de la hoja de cálculo. Produce una InvalidArgument excepción cuando se establece con un valor negativo como entrada.

getTop(): number;

Devoluciones

number

getType()

Devuelve el tipo de esta forma. Vea ExcelScript.ShapeType para más información.

getType(): ShapeType;

Devoluciones

ExcelScript.ShapeType

getVisible()

Especifica si la forma está visible.

getVisible(): boolean;

Devoluciones

boolean

getWidth()

Especifica el ancho, en puntos, de la forma. Produce una InvalidArgument excepción cuando se establece con un valor negativo o cero como entrada.

getWidth(): number;

Devoluciones

number

getZOrderPosition()

Devuelve la posición de la forma especificada en el orden z, siendo 0 la parte inferior de la pila del orden.

getZOrderPosition(): number;

Devoluciones

number

incrementLeft(increment)

Mueve la forma horizontalmente el número de puntos especificado.

incrementLeft(increment: number): void;

Parámetros

increment: number

El incremento, en puntos, la forma se moverá horizontalmente. Un valor positivo mueve la forma a la derecha y un valor negativo la mueve a la izquierda. Si la hoja está orientada de derecha a izquierda, esto se invierte: los valores positivos moverán la forma a la izquierda y los valores negativos la moverán a la derecha.

Devoluciones

void

incrementRotation(increment)

Gira la forma en el sentido de las agujas del reloj alrededor del eje Z según el número de grados. Use la rotation propiedad para establecer la rotación absoluta de la forma.

incrementRotation(increment: number): void;

Parámetros

increment: number

Cuántos grados girará la forma. Un valor positivo gira la forma en el sentido de las agujas del reloj y un valor negativo la gira en sentido contrario a las agujas del reloj.

Devoluciones

void

incrementTop(increment)

Mueve la forma verticalmente el número de puntos.

incrementTop(increment: number): void;

Parámetros

increment: number

El incremento, en puntos, la forma se moverá verticalmente. Un valor positivo mueve la forma hacia abajo y un valor negativo la mueve hacia arriba.

Devoluciones

void

scaleHeight(scaleFactor, scaleType, scaleFrom)

Cambia el alto de la forma en un factor especificado. Para imágenes, puede indicar si desea aplicar una escala a la forma respecto al tamaño original o al actual. El tamaño de las formas distintas de imágenes siempre se ajusta en relación con su alto actual.

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

Parámetros

scaleFactor: number

Especifica la relación entre el alto de la forma después de cambiar su tamaño y el alto original o actual.

scaleType: ExcelScript.ShapeScaleType

Especifica si la forma se escala con respecto a su tamaño original o actual. La opción de escalado de tamaño original solo funciona para imágenes.

scaleFrom: ExcelScript.ShapeScaleFrom

Opcional. Especifica qué parte de la forma mantiene su posición cuando se ajusta el tamaño de la forma. Si se omite, representa la esquina superior izquierda de la forma conserva su posición.

Devoluciones

void

scaleWidth(scaleFactor, scaleType, scaleFrom)

Cambia el ancho de la forma en un factor especificado. Para imágenes, puede indicar si desea aplicar una escala a la forma respecto al tamaño original o al actual. El tamaño de las formas distintas de imágenes siempre se ajusta con relación a su ancho actual.

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

Parámetros

scaleFactor: number

Especifica la relación entre el ancho de la forma después de cambiar su tamaño y el ancho original o actual.

scaleType: ExcelScript.ShapeScaleType

Especifica si la forma se escala con respecto a su tamaño original o actual. La opción de escalado de tamaño original solo funciona para imágenes.

scaleFrom: ExcelScript.ShapeScaleFrom

Opcional. Especifica qué parte de la forma mantiene su posición cuando se ajusta el tamaño de la forma. Si se omite, representa la esquina superior izquierda de la forma conserva su posición.

Devoluciones

void

setAltTextDescription(altTextDescription)

Especifica el texto de descripción alternativo de un Shape objeto.

setAltTextDescription(altTextDescription: string): void;

Parámetros

altTextDescription: string

Devoluciones

void

setAltTextTitle(altTextTitle)

Especifica el texto de título alternativo de un Shape objeto.

setAltTextTitle(altTextTitle: string): void;

Parámetros

altTextTitle: string

Devoluciones

void

setGeometricShapeType(geometricShapeType)

Especifica el tipo de forma geométrica de esta forma geométrica. Vea ExcelScript.GeometricShapeType para más información. Devuelve null si el tipo de forma no es "GeometricShape".

setGeometricShapeType(geometricShapeType: GeometricShapeType): void;

Parámetros

geometricShapeType: ExcelScript.GeometricShapeType

Devoluciones

void

setHeight(height)

Especifica el alto, en puntos, de la forma. Produce una InvalidArgument excepción cuando se establece con un valor negativo o cero como entrada.

setHeight(height: number): void;

Parámetros

height: number

Devoluciones

void

setLeft(left)

setLeft(left: number): void;

Parámetros

left: number

Devoluciones

void

setLockAspectRatio(lockAspectRatio)

Especifica si la relación de aspecto de esta forma está bloqueada.

setLockAspectRatio(lockAspectRatio: boolean): void;

Parámetros

lockAspectRatio: boolean

Devoluciones

void

setName(name)

Especifica el nombre de la forma.

setName(name: string): void;

Parámetros

name: string

Devoluciones

void

Ejemplos

/**
 * 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 cómo está asociado el objeto a las celdas inferiores.

setPlacement(placement: Placement): void;

Parámetros

placement: ExcelScript.Placement

Devoluciones

void

Ejemplos

/**
 * 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 la rotación, en grados, de la forma.

setRotation(rotation: number): void;

Parámetros

rotation: number

Devoluciones

void

setTop(top)

La distancia, en puntos, desde el borde superior de la forma al borde superior de la hoja de cálculo. Produce una InvalidArgument excepción cuando se establece con un valor negativo como entrada.

setTop(top: number): void;

Parámetros

top: number

Devoluciones

void

setVisible(visible)

Especifica si la forma está visible.

setVisible(visible: boolean): void;

Parámetros

visible: boolean

Devoluciones

void

setWidth(width)

Especifica el ancho, en puntos, de la forma. Produce una InvalidArgument excepción cuando se establece con un valor negativo o cero como entrada.

setWidth(width: number): void;

Parámetros

width: number

Devoluciones

void

setZOrder(position)

Mueve la forma especificada hacia arriba o hacia abajo en el orden z de la colección, que se desplaza delante o detrás de otras formas.

setZOrder(position: ShapeZOrder): void;

Parámetros

position: ExcelScript.ShapeZOrder

Dónde mover la forma en la pila de orden Z en relación con las otras formas. Vea ExcelScript.ShapeZOrder para más información.

Devoluciones

void