Compartir a través de

Excel.ShapeCollection class

  • Referencia
Paquete:
excel

Representa una colección de todas las formas de la hoja de cálculo.

Extends
OfficeExtension.ClientObject

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

Propiedades

context

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

Obtiene los elementos secundarios cargados en esta colección.

Métodos

addGeometricShape(geometricShapeType)

Agrega una forma geométrica a la hoja de cálculo. Devuelve un Shape objeto que representa la nueva forma.
addGeometricShape(geometricShapeTypeString)

Agrega una forma geométrica a la hoja de cálculo. Devuelve un Shape objeto que representa la nueva forma.
addGroup(values)

Agrupa un subconjunto de formas en la hoja de cálculo de esta colección. Devuelve un Shape objeto que representa el nuevo grupo de formas.
addImage(base64ImageString)

Crea una imagen a partir de una cadena codificada en Base64 y la agrega a la hoja de cálculo. Devuelve el Shape objeto que representa la nueva imagen.
addLine(startLeft, startTop, endLeft, endTop, connectorType)

Agrega una línea a la hoja de cálculo. Devuelve un Shape objeto que representa la nueva línea.
addLine(startLeft, startTop, endLeft, endTop, connectorTypeString)

Agrega una línea a la hoja de cálculo. Devuelve un Shape objeto que representa la nueva línea.
addLocalImageReference(address)

Crea una referencia para la imagen local almacenada en la dirección de celda y la muestra como una forma flotante sobre las celdas.
addSvg(xml)

Crea un gráfico vectorial escalable (SVG) de una cadena XML y lo agrega a la hoja de cálculo. Devuelve un Shape objeto que representa la nueva imagen.
addTextBox(text)

Agrega un cuadro de texto a la hoja de cálculo con el texto proporcionado como contenido. Devuelve un Shape objeto que representa el nuevo cuadro de texto.
getCount()

Devuelve el número de formas de la hoja de cálculo.
getItem(key)

Obtiene una forma con su nombre o identificador.
getItemAt(index)

Obtiene una forma utilizando su posición en la colección.
getItemOrNullObject(key)

Obtiene una forma con su nombre o identificador. Si el objeto shape no existe, este método devuelve un objeto con su isNullObject propiedad establecida en true. Para obtener más información, vea *OrNullObject methods and properties( Métodos y propiedades de *OrNullObject).
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.
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 original Excel.ShapeCollection es un objeto de API, el toJSON método devuelve un objeto JavaScript sin formato (escrito como Excel.Interfaces.ShapeCollectionData) que contiene una matriz de "elementos" con copias superficiales de las propiedades cargadas de los elementos de la colección.

Detalles de las propiedades

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

items

Obtiene los elementos secundarios cargados en esta colección.

readonly items: Excel.Shape[];

Valor de propiedad

Excel.Shape[]

Detalles del método

addGeometricShape(geometricShapeType)

Agrega una forma geométrica a la hoja de cálculo. Devuelve un Shape objeto que representa la nueva forma.

addGeometricShape(geometricShapeType: Excel.GeometricShapeType): Excel.Shape;

Parámetros

geometricShapeType
Excel.GeometricShapeType

Representa el tipo de la forma geométrica. Vea Excel.GeometricShapeType para más información.

Devoluciones

Excel.Shape

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.hexagon);
    shape.left = 5;
    shape.top = 5;
    shape.height = 175;
    shape.width = 200;
    await context.sync();
});

addGeometricShape(geometricShapeTypeString)

Agrega una forma geométrica a la hoja de cálculo. Devuelve un Shape objeto que representa la nueva forma.

addGeometricShape(geometricShapeTypeString: "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"): Excel.Shape;

Parámetros

geometricShapeTypeString

"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"

Representa el tipo de la forma geométrica. Vea Excel.GeometricShapeType para más información.

Devoluciones

Excel.Shape

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

addGroup(values)

Agrupa un subconjunto de formas en la hoja de cálculo de esta colección. Devuelve un Shape objeto que representa el nuevo grupo de formas.

addGroup(values: Array<string | Shape>): Excel.Shape;

Parámetros

values

Array<string | Excel.Shape>

Matriz de identificadores de forma u objetos de forma.

Devoluciones

Excel.Shape

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 square = sheet.shapes.getItem("Square");
    const pentagon = sheet.shapes.getItem("Pentagon");
    const octagon = sheet.shapes.getItem("Octagon");

    const shapeGroup = sheet.shapes.addGroup([square, pentagon, octagon]);
    shapeGroup.name = "Group";
    console.log("Shapes grouped");

    await context.sync();
});

addImage(base64ImageString)

Crea una imagen a partir de una cadena codificada en Base64 y la agrega a la hoja de cálculo. Devuelve el Shape objeto que representa la nueva imagen.

addImage(base64ImageString: string): Excel.Shape;

Parámetros

base64ImageString

string

Cadena codificada en Base64 que representa una imagen en formato JPEG o PNG.

Devoluciones

Excel.Shape

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

const myFile = <HTMLInputElement>document.getElementById("selectedFile");
const reader = new FileReader();

reader.onload = (event) => {
    Excel.run((context) => {
        const startIndex = reader.result.toString().indexOf("base64,");
        const myBase64 = reader.result.toString().substr(startIndex + 7);
        const sheet = context.workbook.worksheets.getItem("Shapes");
        const image = sheet.shapes.addImage(myBase64);
        image.name = "Image";
        return context.sync();
    });
};

// Read in the image file as a data URL.
reader.readAsDataURL(myFile.files[0]);

addLine(startLeft, startTop, endLeft, endTop, connectorType)

Agrega una línea a la hoja de cálculo. Devuelve un Shape objeto que representa la nueva línea.

addLine(startLeft: number, startTop: number, endLeft: number, endTop: number, connectorType?: Excel.ConnectorType): Excel.Shape;

Parámetros

startLeft

number

Distancia, en puntos, desde el principio de la línea hasta el lado izquierdo de la hoja de cálculo.

startTop

number

Distancia, en puntos, desde el principio de la línea hasta la parte superior de la hoja de cálculo.

endLeft

number

Distancia, en puntos, desde el final de la línea a la izquierda de la hoja de cálculo.

endTop

number

Distancia, en puntos, desde el final de la línea hasta la parte superior de la hoja de cálculo.

connectorType
Excel.ConnectorType

Representa el tipo de conector. Vea Excel.ConnectorType para más información.

Devoluciones

Excel.Shape

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.addLine(200, 50, 300, 150, Excel.ConnectorType.straight);
    line.name = "StraightLine";
    await context.sync();
});

addLine(startLeft, startTop, endLeft, endTop, connectorTypeString)

Agrega una línea a la hoja de cálculo. Devuelve un Shape objeto que representa la nueva línea.

addLine(startLeft: number, startTop: number, endLeft: number, endTop: number, connectorTypeString?: "Straight" | "Elbow" | "Curve"): Excel.Shape;

Parámetros

startLeft

number

Distancia, en puntos, desde el principio de la línea hasta el lado izquierdo de la hoja de cálculo.

startTop

number

Distancia, en puntos, desde el principio de la línea hasta la parte superior de la hoja de cálculo.

endLeft

number

Distancia, en puntos, desde el final de la línea a la izquierda de la hoja de cálculo.

endTop

number

Distancia, en puntos, desde el final de la línea hasta la parte superior de la hoja de cálculo.

connectorTypeString

"Straight" | "Elbow" | "Curve"

Representa el tipo de conector. Vea Excel.ConnectorType para más información.

Devoluciones

Excel.Shape

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

addLocalImageReference(address)

Nota

Esta API se ofrece a los desarrolladores como versión preliminar y puede cambiar en función de los comentarios que recibamos. No utilice esta API en un entorno de producción.

Crea una referencia para la imagen local almacenada en la dirección de celda y la muestra como una forma flotante sobre las celdas.

addLocalImageReference(address: string): Excel.Shape;

Parámetros

address

string

Dirección de la celda que contiene la imagen local.

Devoluciones

Excel.Shape

Objeto Shape asociado a la forma flotante.

Comentarios

[ Conjunto de API: ExcelApi BETA (SOLO VERSIÓN PRELIMINAR) ]

addSvg(xml)

Nota

Esta API se ofrece a los desarrolladores como versión preliminar y puede cambiar en función de los comentarios que recibamos. No utilice esta API en un entorno de producción.

Crea un gráfico vectorial escalable (SVG) de una cadena XML y lo agrega a la hoja de cálculo. Devuelve un Shape objeto que representa la nueva imagen.

addSvg(xml: string): Excel.Shape;

Parámetros

xml

string

Cadena XML que representa el SVG.

Devoluciones

Excel.Shape

Comentarios

[ Conjunto de API: ExcelApi BETA (SOLO VERSIÓN PRELIMINAR) ]

addTextBox(text)

Agrega un cuadro de texto a la hoja de cálculo con el texto proporcionado como contenido. Devuelve un Shape objeto que representa el nuevo cuadro de texto.

addTextBox(text?: string): Excel.Shape;

Parámetros

text

string

Representa el texto que se mostrará en el cuadro de texto creado.

Devoluciones

Excel.Shape

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-textboxes.yaml

await Excel.run(async (context) => {
    const shapes = context.workbook.worksheets.getItem("Shapes").shapes;
    const textbox = shapes.addTextBox("A box with text");
    textbox.left = 100;
    textbox.top = 100;
    textbox.height = 20;
    textbox.width = 175;
    textbox.name = "Textbox";
    await context.sync();
});

getCount()

Devuelve el número de formas de la hoja de cálculo.

getCount(): OfficeExtension.ClientResult<number>;

Devoluciones

OfficeExtension.ClientResult<number>

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

getItem(key)

Obtiene una forma con su nombre o identificador.

getItem(key: string): Excel.Shape;

Parámetros

key

string

Nombre o identificador de la forma que se va a recuperar.

Devoluciones

Excel.Shape

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

getItemAt(index)

Obtiene una forma utilizando su posición en la colección.

getItemAt(index: number): Excel.Shape;

Parámetros

index

number

Índice de base cero de la forma que se va a recuperar.

Devoluciones

Excel.Shape

Comentarios

[ Conjunto de API: ExcelApi 1.9 ]

getItemOrNullObject(key)

Obtiene una forma con su nombre o identificador. Si el objeto shape no existe, este método devuelve un objeto con su isNullObject propiedad establecida en true. Para obtener más información, vea *OrNullObject methods and properties( Métodos y propiedades de *OrNullObject).

getItemOrNullObject(key: string): Excel.Shape;

Parámetros

key

string

Nombre o identificador de la forma que se va a recuperar.

Devoluciones

Excel.Shape

Comentarios

[ Conjunto de API: ExcelApi 1.14 ]

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.ShapeCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions): Excel.ShapeCollection;

Parámetros

options

Excel.Interfaces.ShapeCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions

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

Devoluciones

Excel.ShapeCollection

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.ShapeCollection;

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

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?: OfficeExtension.LoadOption): Excel.ShapeCollection;

Parámetros

propertyNamesAndPaths
OfficeExtension.LoadOption

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

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 original Excel.ShapeCollection es un objeto de API, el toJSON método devuelve un objeto JavaScript sin formato (escrito como Excel.Interfaces.ShapeCollectionData) que contiene una matriz de "elementos" con copias superficiales de las propiedades cargadas de los elementos de la colección.

toJSON(): Excel.Interfaces.ShapeCollectionData;

Devoluciones

Excel.Interfaces.ShapeCollectionData