Excel.Shape class

Paquete:

excel

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. Para obtener más información sobre el modelo de objetos de formas, lea Trabajar con formas mediante la API de JavaScript de Excel.

Extends

OfficeExtension.ClientObject

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

Propiedades

altTextDescription	Especifica el texto de descripción alternativo de un Shape objeto.
altTextTitle	Especifica el texto de título alternativo de un Shape objeto.
connectionSiteCount	Devuelve el número de sitios de conexión en esta forma.
context	Contexto de solicitud asociado al objeto . Esto conecta el proceso del complemento al proceso de la aplicación host de Office.
displayName	Obtiene el nombre para mostrar de la forma. Una forma recién creada tiene un nombre generado que está localizado y puede que no coincida con su name. En este escenario, puede usar esta API para obtener el nombre que se muestra en la interfaz de usuario.
fill	Devuelve el formato de relleno de esta forma.
geometricShape	Devuelve la forma geométrica asociada con la forma. Produce un error si el tipo de forma no es "GeometricShape".
geometricShapeType	Especifica el tipo de forma geométrica de esta forma geométrica. Vea Excel.GeometricShapeType para más información. Devuelve null si el tipo de forma no es "GeometricShape".
group	Devuelve el grupo de forma asociado con la forma. Produce un error si el tipo de forma no es "GroupShape".
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.
id	Especifica el identificador de forma.
image	Devuelve la imagen asociada con la forma. Produce un error si el tipo de forma no es "Image".
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.
level	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.
line	Devuelve la línea asociada con la forma. Produce un error si el tipo de forma no es "Line".
lineFormat	Devuelve el formato de línea de esta forma.
lockAspectRatio	Especifica si la relación de aspecto de esta forma está bloqueada.
name	Especifica el nombre de la forma.
parentGroup	Especifica el grupo primario de esta forma.
placement	Representa cómo está asociado el objeto a las celdas inferiores.
rotation	Especifica la rotación, en grados, de la forma.
textFrame	Devuelve el objeto de marco de texto de esta forma.
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.
type	Devuelve el tipo de esta forma. Vea Excel.ShapeType para más información.
visible	Especifica si la forma está visible.
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.
zOrderPosition	Devuelve la posición de la forma especificada en el orden z, siendo 0 la parte inferior de la pila del orden.

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.
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 Excel.PictureFormat.BMP,Excel.PictureFormat.PNG ,Excel.PictureFormat.JPEG y .Excel.PictureFormat.GIF
getAsImage(formatString)	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 Excel.PictureFormat.BMP,Excel.PictureFormat.PNG ,Excel.PictureFormat.JPEG y .Excel.PictureFormat.GIF
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.
load(options)	Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync() antes de leer las propiedades.
load(propertyNames)	Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync() antes de leer las propiedades.
load(propertyNamesAndPaths)	Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync() antes de leer las propiedades.
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, scaleTypeString, scaleFromString)	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.
scaleWidth(scaleFactor, scaleTypeString, scaleFromString)	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(properties, options)	Establece varias propiedades de un objeto al mismo tiempo. Puede pasar un objeto sin formato con las propiedades adecuadas u otro objeto de API del mismo tipo.
set(properties)	Establece varias propiedades en el objeto al mismo tiempo, en función de un objeto cargado existente.
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(positionString)	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.
toJSON()	Invalida el método JavaScript toJSON() para proporcionar una salida más útil cuando se pasa un objeto de API a JSON.stringify(). (JSON.stringifya su vez, llama al toJSON método del objeto que se le pasa). Mientras que el objeto Excel.Shape original es un objeto de API, el toJSON método devuelve un objeto JavaScript sin formato (escrito como Excel.Interfaces.ShapeData) que contiene copias superficiales de las propiedades secundarias cargadas del objeto original.

Eventos

onActivated	Se produce cuando se activa la forma.
onDeactivated	Se produce cuando se desactiva la forma.

Detalles de las propiedades

altTextDescription

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

altTextDescription: string;

Valor de propiedad

string

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

altTextTitle

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

altTextTitle: string;

Valor de propiedad

string

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

connectionSiteCount

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

readonly connectionSiteCount: number;

Valor de propiedad

number

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

context

Contexto de solicitud asociado al objeto . Esto conecta el proceso del complemento al proceso de la aplicación host de Office.

context: RequestContext;

Valor de propiedad

Excel.RequestContext

displayName

Obtiene el nombre para mostrar de la forma. Una forma recién creada tiene un nombre generado que está localizado y puede que no coincida con su name. En este escenario, puede usar esta API para obtener el nombre que se muestra en la interfaz de usuario.

readonly displayName: string;

Valor de propiedad

string

Comentarios

[ Conjunto de API: ExcelApi 1.15 ]

fill

Devuelve el formato de relleno de esta forma.

readonly fill: Excel.ShapeFill;

Valor de propiedad

Excel.ShapeFill

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-create-and-delete.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.addGeometricShape(Excel.GeometricShapeType.smileyFace);
    shape.left = 300;
    shape.top = 100;
    shape.height = 100;
    shape.width = 100;
    shape.fill.foregroundColor = "yellow"
    await context.sync();
});

geometricShape

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

readonly geometricShape: Excel.GeometricShape;

Valor de propiedad

Excel.GeometricShape

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

geometricShapeType

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

geometricShapeType: Excel.GeometricShapeType | "LineInverse" | "Triangle" | "RightTriangle" | "Rectangle" | "Diamond" | "Parallelogram" | "Trapezoid" | "NonIsoscelesTrapezoid" | "Pentagon" | "Hexagon" | "Heptagon" | "Octagon" | "Decagon" | "Dodecagon" | "Star4" | "Star5" | "Star6" | "Star7" | "Star8" | "Star10" | "Star12" | "Star16" | "Star24" | "Star32" | "RoundRectangle" | "Round1Rectangle" | "Round2SameRectangle" | "Round2DiagonalRectangle" | "SnipRoundRectangle" | "Snip1Rectangle" | "Snip2SameRectangle" | "Snip2DiagonalRectangle" | "Plaque" | "Ellipse" | "Teardrop" | "HomePlate" | "Chevron" | "PieWedge" | "Pie" | "BlockArc" | "Donut" | "NoSmoking" | "RightArrow" | "LeftArrow" | "UpArrow" | "DownArrow" | "StripedRightArrow" | "NotchedRightArrow" | "BentUpArrow" | "LeftRightArrow" | "UpDownArrow" | "LeftUpArrow" | "LeftRightUpArrow" | "QuadArrow" | "LeftArrowCallout" | "RightArrowCallout" | "UpArrowCallout" | "DownArrowCallout" | "LeftRightArrowCallout" | "UpDownArrowCallout" | "QuadArrowCallout" | "BentArrow" | "UturnArrow" | "CircularArrow" | "LeftCircularArrow" | "LeftRightCircularArrow" | "CurvedRightArrow" | "CurvedLeftArrow" | "CurvedUpArrow" | "CurvedDownArrow" | "SwooshArrow" | "Cube" | "Can" | "LightningBolt" | "Heart" | "Sun" | "Moon" | "SmileyFace" | "IrregularSeal1" | "IrregularSeal2" | "FoldedCorner" | "Bevel" | "Frame" | "HalfFrame" | "Corner" | "DiagonalStripe" | "Chord" | "Arc" | "LeftBracket" | "RightBracket" | "LeftBrace" | "RightBrace" | "BracketPair" | "BracePair" | "Callout1" | "Callout2" | "Callout3" | "AccentCallout1" | "AccentCallout2" | "AccentCallout3" | "BorderCallout1" | "BorderCallout2" | "BorderCallout3" | "AccentBorderCallout1" | "AccentBorderCallout2" | "AccentBorderCallout3" | "WedgeRectCallout" | "WedgeRRectCallout" | "WedgeEllipseCallout" | "CloudCallout" | "Cloud" | "Ribbon" | "Ribbon2" | "EllipseRibbon" | "EllipseRibbon2" | "LeftRightRibbon" | "VerticalScroll" | "HorizontalScroll" | "Wave" | "DoubleWave" | "Plus" | "FlowChartProcess" | "FlowChartDecision" | "FlowChartInputOutput" | "FlowChartPredefinedProcess" | "FlowChartInternalStorage" | "FlowChartDocument" | "FlowChartMultidocument" | "FlowChartTerminator" | "FlowChartPreparation" | "FlowChartManualInput" | "FlowChartManualOperation" | "FlowChartConnector" | "FlowChartPunchedCard" | "FlowChartPunchedTape" | "FlowChartSummingJunction" | "FlowChartOr" | "FlowChartCollate" | "FlowChartSort" | "FlowChartExtract" | "FlowChartMerge" | "FlowChartOfflineStorage" | "FlowChartOnlineStorage" | "FlowChartMagneticTape" | "FlowChartMagneticDisk" | "FlowChartMagneticDrum" | "FlowChartDisplay" | "FlowChartDelay" | "FlowChartAlternateProcess" | "FlowChartOffpageConnector" | "ActionButtonBlank" | "ActionButtonHome" | "ActionButtonHelp" | "ActionButtonInformation" | "ActionButtonForwardNext" | "ActionButtonBackPrevious" | "ActionButtonEnd" | "ActionButtonBeginning" | "ActionButtonReturn" | "ActionButtonDocument" | "ActionButtonSound" | "ActionButtonMovie" | "Gear6" | "Gear9" | "Funnel" | "MathPlus" | "MathMinus" | "MathMultiply" | "MathDivide" | "MathEqual" | "MathNotEqual" | "CornerTabs" | "SquareTabs" | "PlaqueTabs" | "ChartX" | "ChartStar" | "ChartPlus";

Valor de propiedad

Excel.GeometricShapeType | "LineInverse" | "Triangle" | "RightTriangle" | "Rectangle" | "Diamond" | "Parallelogram" | "Trapezoid" | "NonIsoscelesTrapezoid" | "Pentagon" | "Hexagon" | "Heptagon" | "Octagon" | "Decagon" | "Dodecagon" | "Star4" | "Star5" | "Star6" | "Star7" | "Star8" | "Star10" | "Star12" | "Star16" | "Star24" | "Star32" | "RoundRectangle" | "Round1Rectangle" | "Round2SameRectangle" | "Round2DiagonalRectangle" | "SnipRoundRectangle" | "Snip1Rectangle" | "Snip2SameRectangle" | "Snip2DiagonalRectangle" | "Plaque" | "Ellipse" | "Teardrop" | "HomePlate" | "Chevron" | "PieWedge" | "Pie" | "BlockArc" | "Donut" | "NoSmoking" | "RightArrow" | "LeftArrow" | "UpArrow" | "DownArrow" | "StripedRightArrow" | "NotchedRightArrow" | "BentUpArrow" | "LeftRightArrow" | "UpDownArrow" | "LeftUpArrow" | "LeftRightUpArrow" | "QuadArrow" | "LeftArrowCallout" | "RightArrowCallout" | "UpArrowCallout" | "DownArrowCallout" | "LeftRightArrowCallout" | "UpDownArrowCallout" | "QuadArrowCallout" | "BentArrow" | "UturnArrow" | "CircularArrow" | "LeftCircularArrow" | "LeftRightCircularArrow" | "CurvedRightArrow" | "CurvedLeftArrow" | "CurvedUpArrow" | "CurvedDownArrow" | "SwooshArrow" | "Cube" | "Can" | "LightningBolt" | "Heart" | "Sun" | "Moon" | "SmileyFace" | "IrregularSeal1" | "IrregularSeal2" | "FoldedCorner" | "Bevel" | "Frame" | "HalfFrame" | "Corner" | "DiagonalStripe" | "Chord" | "Arc" | "LeftBracket" | "RightBracket" | "LeftBrace" | "RightBrace" | "BracketPair" | "BracePair" | "Callout1" | "Callout2" | "Callout3" | "AccentCallout1" | "AccentCallout2" | "AccentCallout3" | "BorderCallout1" | "BorderCallout2" | "BorderCallout3" | "AccentBorderCallout1" | "AccentBorderCallout2" | "AccentBorderCallout3" | "WedgeRectCallout" | "WedgeRRectCallout" | "WedgeEllipseCallout" | "CloudCallout" | "Cloud" | "Ribbon" | "Ribbon2" | "EllipseRibbon" | "EllipseRibbon2" | "LeftRightRibbon" | "VerticalScroll" | "HorizontalScroll" | "Wave" | "DoubleWave" | "Plus" | "FlowChartProcess" | "FlowChartDecision" | "FlowChartInputOutput" | "FlowChartPredefinedProcess" | "FlowChartInternalStorage" | "FlowChartDocument" | "FlowChartMultidocument" | "FlowChartTerminator" | "FlowChartPreparation" | "FlowChartManualInput" | "FlowChartManualOperation" | "FlowChartConnector" | "FlowChartPunchedCard" | "FlowChartPunchedTape" | "FlowChartSummingJunction" | "FlowChartOr" | "FlowChartCollate" | "FlowChartSort" | "FlowChartExtract" | "FlowChartMerge" | "FlowChartOfflineStorage" | "FlowChartOnlineStorage" | "FlowChartMagneticTape" | "FlowChartMagneticDisk" | "FlowChartMagneticDrum" | "FlowChartDisplay" | "FlowChartDelay" | "FlowChartAlternateProcess" | "FlowChartOffpageConnector" | "ActionButtonBlank" | "ActionButtonHome" | "ActionButtonHelp" | "ActionButtonInformation" | "ActionButtonForwardNext" | "ActionButtonBackPrevious" | "ActionButtonEnd" | "ActionButtonBeginning" | "ActionButtonReturn" | "ActionButtonDocument" | "ActionButtonSound" | "ActionButtonMovie" | "Gear6" | "Gear9" | "Funnel" | "MathPlus" | "MathMinus" | "MathMultiply" | "MathDivide" | "MathEqual" | "MathNotEqual" | "CornerTabs" | "SquareTabs" | "PlaqueTabs" | "ChartX" | "ChartStar" | "ChartPlus"

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

group

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

readonly group: Excel.ShapeGroup;

Valor de propiedad

Excel.ShapeGroup

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-groups.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");

    const shapeGroup = sheet.shapes.getItem("Group").group;
    shapeGroup.ungroup();
    console.log("Shapes ungrouped");

    await context.sync();
});

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.

height: number;

Valor de propiedad

number

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

id

Especifica el identificador de forma.

readonly id: string;

Valor de propiedad

string

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

image

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

readonly image: Excel.Image;

Valor de propiedad

Excel.Image

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

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.

left: number;

Valor de propiedad

number

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

level

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.

readonly level: number;

Valor de propiedad

number

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

line

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

readonly line: Excel.Line;

Valor de propiedad

Excel.Line

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-lines.yaml

await Excel.run(async (context) => {
    const shapes = context.workbook.worksheets.getItem("Shapes").shapes;
    const line = shapes.getItem("StraightLine").line;
    line.beginArrowheadLength = Excel.ArrowheadLength.long;
    line.beginArrowheadWidth = Excel.ArrowheadWidth.wide;
    line.beginArrowheadStyle = Excel.ArrowheadStyle.oval;

    line.endArrowheadLength = Excel.ArrowheadLength.long;
    line.endArrowheadWidth = Excel.ArrowheadWidth.wide;
    line.endArrowheadStyle = Excel.ArrowheadStyle.triangle;

    await context.sync();
});

lineFormat

Devuelve el formato de línea de esta forma.

readonly lineFormat: Excel.ShapeLineFormat;

Valor de propiedad

Excel.ShapeLineFormat

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

lockAspectRatio

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

lockAspectRatio: boolean;

Valor de propiedad

boolean

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Octagon")
    shape.lockAspectRatio = true;
    shape.scaleHeight(1.25, Excel.ShapeScaleType.currentSize);
    await context.sync();
});

name

Especifica el nombre de la forma.

name: string;

Valor de propiedad

string

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

parentGroup

Especifica el grupo primario de esta forma.

readonly parentGroup: Excel.Shape;

Valor de propiedad

Excel.Shape

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

placement

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

placement: Excel.Placement | "TwoCell" | "OneCell" | "Absolute";

Valor de propiedad

Excel.Placement | "TwoCell" | "OneCell" | "Absolute"

Comentarios

[ Conjunto de API: ExcelApi 1.10 ]

rotation

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

rotation: number;

Valor de propiedad

number

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-create-and-delete.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.addGeometricShape(Excel.GeometricShapeType.triangle);
    shape.left = 100;
    shape.top = 300;
    shape.height = 150;
    shape.width = 200;
    shape.rotation = 45;
    shape.fill.clear();
    await context.sync();
});

textFrame

Devuelve el objeto de marco de texto de esta forma.

readonly textFrame: Excel.TextFrame;

Valor de propiedad

Excel.TextFrame

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

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.

top: number;

Valor de propiedad

number

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

type

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

readonly type: Excel.ShapeType | "Unsupported" | "Image" | "GeometricShape" | "Group" | "Line";

Valor de propiedad

Excel.ShapeType | "Unsupported" | "Image" | "GeometricShape" | "Group" | "Line"

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

visible

Especifica si la forma está visible.

visible: boolean;

Valor de propiedad

boolean

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

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.

width: number;

Valor de propiedad

number

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

zOrderPosition

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

readonly zOrderPosition: number;

Valor de propiedad

number

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

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): Excel.Shape;

Parámetros

destinationSheet

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

Excel.Shape

Comentarios

[ Conjunto de API: ExcelApi 1.10 ]

delete()

Quita la forma de la hoja de cálculo.

delete(): void;

Devoluciones

void

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-create-and-delete.yaml

await Excel.run(async (context) => {
    context.workbook.worksheets.getItemOrNullObject("Shapes").delete();
    const sheet = context.workbook.worksheets.add("Shapes");

    const shapes = sheet.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();
});

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 Excel.PictureFormat.BMP,Excel.PictureFormat.PNG ,Excel.PictureFormat.JPEG y .Excel.PictureFormat.GIF

getAsImage(format: Excel.PictureFormat): OfficeExtension.ClientResult<string>;

Parámetros

format

Excel.PictureFormat

Especifica el formato de la imagen.

Devoluciones

OfficeExtension.ClientResult<string>

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-images.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Image");
    const result = shape.getAsImage(Excel.PictureFormat.png);
    await context.sync();

    const imageString = result.value;
    // Your add-in would save this string as a .png file.
    console.log("The image's Base64-encoded string: " + imageString);
});

getAsImage(formatString)

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 Excel.PictureFormat.BMP,Excel.PictureFormat.PNG ,Excel.PictureFormat.JPEG y .Excel.PictureFormat.GIF

getAsImage(formatString: "UNKNOWN" | "BMP" | "JPEG" | "GIF" | "PNG" | "SVG"): OfficeExtension.ClientResult<string>;

Parámetros

formatString

"UNKNOWN" | "BMP" | "JPEG" | "GIF" | "PNG" | "SVG"

Especifica el formato de la imagen.

Devoluciones

OfficeExtension.ClientResult<string>

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

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

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Square")
    shape.incrementLeft(-25);
    await context.sync();
});

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

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-images.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Image");
    shape.incrementRotation(180);
    await context.sync();
});

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

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Pentagon")
    shape.incrementTop(25);
    await context.sync();
});

load(options)

Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync() antes de leer las propiedades.

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

Parámetros

options

Excel.Interfaces.ShapeLoadOptions

Proporciona opciones para las propiedades del objeto que se van a cargar.

Devoluciones

Excel.Shape

load(propertyNames)

Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync() antes de leer las propiedades.

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

Parámetros

propertyNames

string | string[]

Una cadena delimitada por comas o una matriz de cadenas que especifican las propiedades que se van a cargar.

Devoluciones

Excel.Shape

load(propertyNamesAndPaths)

Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync() antes de leer las propiedades.

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

Parámetros

propertyNamesAndPaths

{ select?: string; expand?: string; }

propertyNamesAndPaths.select es una cadena delimitada por comas que especifica las propiedades que se van a cargar y propertyNamesAndPaths.expand es una cadena delimitada por comas que especifica las propiedades de navegación que se van a cargar.

Devoluciones

Excel.Shape

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: Excel.ShapeScaleType, scaleFrom?: Excel.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

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

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

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Octagon")
    shape.lockAspectRatio = true;
    shape.scaleHeight(1.25, Excel.ShapeScaleType.currentSize);
    await context.sync();
});

scaleHeight(scaleFactor, scaleTypeString, scaleFromString)

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, scaleTypeString: "CurrentSize" | "OriginalSize", scaleFromString?: "ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"): 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.

scaleTypeString

"CurrentSize" | "OriginalSize"

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.

scaleFromString

"ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

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

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

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: Excel.ShapeScaleType, scaleFrom?: Excel.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

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

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

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

scaleWidth(scaleFactor, scaleTypeString, scaleFromString)

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, scaleTypeString: "CurrentSize" | "OriginalSize", scaleFromString?: "ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"): 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.

scaleTypeString

"CurrentSize" | "OriginalSize"

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.

scaleFromString

"ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

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

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

set(properties, options)

Establece varias propiedades de un objeto al mismo tiempo. Puede pasar un objeto sin formato con las propiedades adecuadas u otro objeto de API del mismo tipo.

set(properties: Interfaces.ShapeUpdateData, options?: OfficeExtension.UpdateOptions): void;

Parámetros

properties

Excel.Interfaces.ShapeUpdateData

Objeto JavaScript con propiedades estructuradas isomórficamente con las propiedades del objeto al que se llama al método.

options

OfficeExtension.UpdateOptions

Proporciona una opción para suprimir errores si el objeto properties intenta establecer propiedades de solo lectura.

Devoluciones

void

set(properties)

Establece varias propiedades en el objeto al mismo tiempo, en función de un objeto cargado existente.

set(properties: Excel.Shape): void;

Parámetros

properties

Excel.Shape

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

Parámetros

position

Excel.ShapeZOrder

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

Devoluciones

void

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Octagon")
    shape.setZOrder(Excel.ShapeZOrder.sendBackward);
    await context.sync();
});

setZOrder(positionString)

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(positionString: "BringToFront" | "BringForward" | "SendToBack" | "SendBackward"): void;

Parámetros

positionString

"BringToFront" | "BringForward" | "SendToBack" | "SendBackward"

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

Devoluciones

void

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

toJSON()

Invalida el método JavaScript toJSON() para proporcionar una salida más útil cuando se pasa un objeto de API a JSON.stringify(). (JSON.stringifya su vez, llama al toJSON método del objeto que se le pasa). Mientras que el objeto Excel.Shape original es un objeto de API, el toJSON método devuelve un objeto JavaScript sin formato (escrito como Excel.Interfaces.ShapeData) que contiene copias superficiales de las propiedades secundarias cargadas del objeto original.

toJSON(): Excel.Interfaces.ShapeData;

Devoluciones

Excel.Interfaces.ShapeData

Detalles del evento

onActivated

Se produce cuando se activa la forma.

readonly onActivated: OfficeExtension.EventHandlers<Excel.ShapeActivatedEventArgs>;

Tipo de evento

OfficeExtension.EventHandlers<Excel.ShapeActivatedEventArgs>

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

onDeactivated

Se produce cuando se desactiva la forma.

readonly onDeactivated: OfficeExtension.EventHandlers<Excel.ShapeDeactivatedEventArgs>;

Tipo de evento

OfficeExtension.EventHandlers<Excel.ShapeDeactivatedEventArgs>

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]