Trabajar con formas mediante la API Excel JavaScript

Excel define las formas como cualquier objeto que se encuentra en la capa de dibujo de Excel. Eso significa que cualquier cosa fuera de una celda es una forma. En este artículo se describe cómo usar formas geométricas, líneas e imágenes junto con las API Shape y ShapeCollection. Los gráficos se tratan en su propio artículo, Trabajar con gráficos mediante laAPI Excel JavaScript .

La siguiente imagen muestra formas que forman un termómetro. Imagen de un termómetro hecho como una Excel forma.

Crear formas

Las formas se crean y almacenan en la colección de formas de una hoja de cálculo ( Worksheet.shapes ). ShapeCollection tiene varios .add* métodos para este propósito. Todas las formas tienen nombres e IDs generados para ellos cuando se agregan a la colección. Estas son las name propiedades id y, respectivamente. name puede establecerlo el complemento para facilitar la recuperación con el ShapeCollection.getItem(name) método.

Los siguientes tipos de formas se agregan mediante el método asociado.

Forma Add (método) Firma
Forma geométrica addGeometricShape addGeometricShape(geometricShapeType: Excel.GeometricShapeType): Excel.Shape
Imagen (JPEG o PNG) addImage addImage(base64ImageString: string): Excel.Shape
Línea addLine addLine(startLeft: number, startTop: number, endLeft: number, endTop: number, connectorType?: Excel.ConnectorType): Excel.Shape
SVG addSvg addSvg(xml: string): Excel.Shape
Cuadro de texto addTextBox addTextBox(text?: string): Excel.Shape

Formas geométricas

Se crea una forma geométrica con ShapeCollection.addGeometricShape . Ese método toma una enumeración GeometricShapeType como argumento.

En el siguiente ejemplo de código se crea un rectángulo de 150 x 150 píxeles denominado "Cuadrado" que se coloca a 100 píxeles de los lados superior e izquierdo de la hoja de cálculo.

// This sample creates a rectangle positioned 100 pixels from the top and left sides
// of the worksheet and is 150x150 pixels.
Excel.run(function (context) {
    var shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    var rectangle = shapes.addGeometricShape(Excel.GeometricShapeType.rectangle);
    rectangle.left = 100;
    rectangle.top = 100;
    rectangle.height = 150;
    rectangle.width = 150;
    rectangle.name = "Square";
    return context.sync();
}).catch(errorHandlerFunction);

Imágenes

Las imágenes JPEG, PNG y SVG se pueden insertar en una hoja de cálculo como formas. El método toma una cadena codificada en ShapeCollection.addImage base64 como argumento. Se trata de una imagen JPEG o PNG en forma de cadena. ShapeCollection.addSvg también toma una cadena, aunque este argumento es XML que define el gráfico.

En el ejemplo de código siguiente se muestra un archivo de imagen cargado por un FileReader como una cadena. La cadena tiene los metadatos "base64", quitados antes de crear la forma.

// This sample creates an image as a Shape object in the worksheet.
var myFile = document.getElementById("selectedFile");
var reader = new FileReader();

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

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

Lines

Se crea una línea con ShapeCollection.addLine . Ese método necesita los márgenes izquierdo y superior de los puntos inicial y final de la línea. También se necesita una enumeración ConnectorType para especificar cómo se contorsiona la línea entre extremos. En el ejemplo de código siguiente se crea una línea recta en la hoja de cálculo.

// This sample creates a straight line from [200,50] to [300,150] on the worksheet
Excel.run(function (context) {
    var shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    var line = shapes.addLine(200, 50, 300, 150, Excel.ConnectorType.straight);
    line.name = "StraightLine";
    return context.sync();
}).catch(errorHandlerFunction);

Las líneas se pueden conectar a otros objetos Shape. Los connectBeginShape connectEndShape métodos and adjuntan el principio y el final de una línea a las formas en los puntos de conexión especificados. Las ubicaciones de estos puntos varían según la forma, pero se pueden usar para garantizar que el complemento no se conecte a un punto que está fuera de Shape.connectionSiteCount límites. Una línea se desconecta de cualquier forma adjunta mediante los disconnectBeginShape disconnectEndShape métodos and.

En el ejemplo de código siguiente se conecta la línea "MyLine" a dos formas denominadas "LeftShape" y "RightShape".

// This sample connects a line between two shapes at connection points '0' and '3'.
Excel.run(function (context) {
    var shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    var line = shapes.getItem("MyLine").line;
    line.connectBeginShape(shapes.getItem("LeftShape"), 0);
    line.connectEndShape(shapes.getItem("RightShape"), 3);
    return context.sync();
}).catch(errorHandlerFunction);

Mover y cambiar el tamaño de las formas

Las formas se sientan encima de la hoja de cálculo. La propiedad and define su left top ubicación. Actúan como márgenes de los bordes respectivos de la hoja de cálculo, siendo [0, 0] la esquina superior izquierda. Estos pueden establecerse directamente o ajustarse desde su posición actual con los incrementLeft incrementTop métodos and. La cantidad de forma girada desde la posición predeterminada también se establece de esta manera, siendo la propiedad la cantidad absoluta y el método ajustando la rotation incrementRotation rotación existente.

La propiedad define la profundidad de una forma con respecto a otras zorderPosition formas. Esto se establece mediante el setZOrder método, que toma un ShapeZOrder. setZOrder ajusta el orden de la forma actual con respecto a las otras formas.

El complemento tiene un par de opciones para cambiar el alto y el ancho de las formas. Si se establece height la propiedad width or, se cambia la dimensión especificada sin cambiar la otra dimensión. El y ajustar las dimensiones respectivas de la forma en relación con el tamaño actual o original (en función del valor de scaleHeight scaleWidth ShapeScaleType proporcionado). Un parámetro ShapeScaleFrom opcional especifica desde dónde se escala la forma (esquina superior izquierda, media o esquina inferior derecha). Si la lockAspectRatio propiedad es true, los métodos de escala mantienen la relación de aspecto actual de la forma ajustando también la otra dimensión.

Nota

Los cambios directos en height las propiedades y solo afectan a esa width propiedad, independientemente del valor de la lockAspectRatio propiedad.

En el ejemplo de código siguiente se muestra una forma que se escala a 1,25 veces su tamaño original y gira 30 grados.

// In this sample, the shape "Octagon" is rotated 30 degrees clockwise
// and scaled 25% larger, with the upper-left corner remaining in place.
Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("MyWorksheet");
    var shape = sheet.shapes.getItem("Octagon");
    shape.incrementRotation(30);
    shape.lockAspectRatio = true;
    shape.scaleWidth(
        1.25,
        Excel.ShapeScaleType.currentSize,
        Excel.ShapeScaleFrom.scaleFromTopLeft);
    return context.sync();
}).catch(errorHandlerFunction);

Texto en formas

Las formas geométricas pueden contener texto. Las formas tienen una textFrame propiedad de tipo TextFrame. El TextFrame objeto administra las opciones de presentación de texto (como márgenes y desbordamiento de texto). TextFrame.textRange es un objeto TextRange con el contenido de texto y la configuración de fuente.

En el ejemplo de código siguiente se crea una forma geométrica denominada "Wave" con el texto "Shape Text". También ajusta la forma y los colores del texto, así como establece la alineación horizontal del texto en el centro.

// This sample creates a light-blue wave shape and adds the purple text "Shape text" to the center.
Excel.run(function (context) {
    var shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    var wave = shapes.addGeometricShape(Excel.GeometricShapeType.wave);
    wave.left = 100;
    wave.top = 400;
    wave.height = 50;
    wave.width = 150;
    wave.name = "Wave";
    wave.fill.setSolidColor("lightblue");
    wave.textFrame.textRange.text = "Shape text";
    wave.textFrame.textRange.font.color = "purple";
    wave.textFrame.horizontalAlignment = Excel.ShapeTextHorizontalAlignment.center;
    return context.sync();
}).catch(errorHandlerFunction);

El addTextBox método de crea un tipo con un fondo blanco y un texto ShapeCollection GeometricShape Rectangle negro. Esto es lo mismo que lo que crea el botón cuadro de texto de Excel de la pestaña Insertar. addTextBox toma un argumento de cadena para establecer el texto de TextRange .

En el ejemplo de código siguiente se muestra la creación de un cuadro de texto con el texto "¡Hola!".

// This sample creates a text box with the text "Hello!" and sizes it appropriately.
Excel.run(function (context) {
    var shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    var textbox = shapes.addTextBox("Hello!");
    textbox.left = 100;
    textbox.top = 100;
    textbox.height = 20;
    textbox.width = 45;
    textbox.name = "Textbox";
    return context.sync();
}).catch(errorHandlerFunction);

Grupos de formas

Las formas se pueden agrupar. Esto permite que un usuario las trate como una sola entidad para el posicionamiento, el tamaño y otras tareas relacionadas. Un ShapeGroup es un tipo de , por lo que el complemento trata Shape el grupo como una sola forma.

En el ejemplo de código siguiente se muestran tres formas agrupadas. En el ejemplo de código siguiente se muestra el grupo de formas que se mueve a los 50 píxeles correctos.

// This sample takes three previously-created shapes ("Square", "Pentagon", and "Octagon")
// and groups them into a single ShapeGroup.
Excel.run(function (context) {
    var shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    var square = shapes.getItem("Square");
    var pentagon = shapes.getItem("Pentagon");
    var octagon = shapes.getItem("Octagon");

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

    return context.sync();
}).catch(errorHandlerFunction);

// This sample moves the previously created shape group to the right by 50 pixels.
Excel.run(function (context) {
    var shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    var shapeGroup = sheet.shapes.getItem("Group");
    shapeGroup.incrementLeft(50);
    return context.sync();
}).catch(errorHandlerFunction);

Importante

Se hace referencia a formas individuales dentro del grupo a través de la ShapeGroup.shapes propiedad, que es de tipo GroupShapeCollection. Ya no son accesibles a través de la colección de formas de la hoja de cálculo después de agruparse. Por ejemplo, si la hoja de cálculo tuviera tres formas y todas estuvieran agrupadas, el método de la hoja de cálculo devolvería un shapes.getCount recuento de 1.

Exportar formas como imágenes

Cualquier Shape objeto se puede convertir en una imagen. Shape.getAsImage devuelve una cadena codificada en base64. El formato de la imagen se especifica como una enumeración PictureFormat pasada a getAsImage .

Excel.run(function (context) {
    var shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    var shape = sheet.shapes.getItem("Image");
    var stringResult = shape.getAsImage(Excel.PictureFormat.png);

    return context.sync().then(function () {
        console.log(stringResult.value);
        // Instead of logging, your add-in may use the base64-encoded string to save the image as a file or insert it in HTML.
    });
}).catch(errorHandlerFunction);

Eliminar formas

Las formas se quitan de la hoja de cálculo Shape con el método del delete objeto. No se necesitan otros metadatos.

En el ejemplo de código siguiente se eliminan todas las formas de MyWorksheet.

// This deletes all the shapes from "MyWorksheet".
Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("MyWorksheet");
    var shapes = sheet.shapes;

    // We'll load all the shapes in the collection without loading their properties.
    shapes.load("items/$none");
    return context.sync().then(function () {
        shapes.items.forEach(function (shape) {
            shape.delete()
        });
        return context.sync();
    }).catch(errorHandlerFunction);
}).catch(errorHandlerFunction);

Vea también