ExcelScript.Shape interface
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
copy |
Copia y pega un |
delete() | Quita la forma de la hoja de cálculo. |
get |
Especifica el texto de descripción alternativo de un |
get |
Especifica el texto de título alternativo de un |
get |
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 |
get |
Devuelve el número de sitios de conexión en esta forma. |
get |
Devuelve el formato de relleno de esta forma. |
get |
Devuelve la forma geométrica asociada con la forma. Produce un error si el tipo de forma no es "GeometricShape". |
get |
Especifica el tipo de forma geométrica de esta forma geométrica. Vea |
get |
Devuelve el grupo de forma asociado con la forma. Produce un error si el tipo de forma no es "GroupShape". |
get |
Especifica el alto, en puntos, de la forma. Produce una |
get |
Especifica el identificador de forma. |
get |
Devuelve la imagen asociada con la forma. Produce un error si el tipo de forma no es "Image". |
get |
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 |
get |
La distancia, en puntos, desde el lado izquierdo de la forma hasta el lado izquierdo de la hoja de cálculo. Produce una |
get |
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. |
get |
Devuelve la línea asociada con la forma. Produce un error si el tipo de forma no es "Line". |
get |
Devuelve el formato de línea de esta forma. |
get |
Especifica si la relación de aspecto de esta forma está bloqueada. |
get |
Especifica el nombre de la forma. |
get |
Especifica el grupo primario de esta forma. |
get |
Representa cómo está asociado el objeto a las celdas inferiores. |
get |
Especifica la rotación, en grados, de la forma. |
get |
Devuelve el objeto de marco de texto de esta forma. |
get |
La distancia, en puntos, desde el borde superior de la forma al borde superior de la hoja de cálculo. Produce una |
get |
Devuelve el tipo de esta forma. Vea |
get |
Especifica si la forma está visible. |
get |
Especifica el ancho, en puntos, de la forma. Produce una |
get |
Devuelve la posición de la forma especificada en el orden z, siendo 0 la parte inferior de la pila del orden. |
increment |
Mueve la forma horizontalmente el número de puntos especificado. |
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 |
increment |
Mueve la forma verticalmente el número de puntos. |
scale |
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. |
scale |
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. |
set |
Especifica el texto de descripción alternativo de un |
set |
Especifica el texto de título alternativo de un |
set |
Especifica el tipo de forma geométrica de esta forma geométrica. Vea |
set |
Especifica el alto, en puntos, de la forma. Produce una |
set |
La distancia, en puntos, desde el lado izquierdo de la forma hasta el lado izquierdo de la hoja de cálculo. Produce una |
set |
Especifica si la relación de aspecto de esta forma está bloqueada. |
set |
Especifica el nombre de la forma. |
set |
Representa cómo está asociado el objeto a las celdas inferiores. |
set |
Especifica la rotación, en grados, de la forma. |
set |
La distancia, en puntos, desde el borde superior de la forma al borde superior de la hoja de cálculo. Produce una |
set |
Especifica si la forma está visible. |
set |
Especifica el ancho, en puntos, de la forma. Produce una |
set |
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
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
getGeometricShape()
Devuelve la forma geométrica asociada con la forma. Produce un error si el tipo de forma no es "GeometricShape".
getGeometricShape(): GeometricShape;
Devoluciones
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
getGroup()
Devuelve el grupo de forma asociado con la forma. Produce un error si el tipo de forma no es "GroupShape".
getGroup(): ShapeGroup;
Devoluciones
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
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)
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
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
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
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()
getPlacement()
Representa cómo está asociado el objeto a las celdas inferiores.
getPlacement(): Placement;
Devoluciones
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
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
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)
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.
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