Trabalhar com formas usando a API JavaScript do Excel

O Excel define formas como qualquer objeto que esteja na camada de desenho do Excel. Isso significa que qualquer coisa fora de uma célula é uma forma. Este artigo descreve como usar formas geométricas, linhas e imagens em conjunto com as APIs Shape e ShapeCollection . Os gráficos são abordados em seu próprio artigo, Trabalhe com gráficos usando a API JavaScript do Excel.

A imagem a seguir mostra formas que formam um termômetro.

Criar formas

As formas são criadas por meio e armazenadas na coleção de formas de uma planilha (Worksheet.shapes). ShapeCollection tem vários .add* métodos para essa finalidade. Todas as formas têm nomes e IDs gerados para elas quando são adicionadas à coleção. Estas são as name propriedades e id , respectivamente. name pode ser definido pelo seu suplemento para fácil recuperação com o ShapeCollection.getItem(name) método.

Os tipos de formas a seguir são adicionados usando o método associado.

Formas geométricas

Uma forma geométrica é criada com ShapeCollection.addGeometricShape. Esse método usa um enumeração GeometricShapeType como argumento.

O exemplo de código a seguir cria um retângulo de 150x150 pixels chamado "Square" posicionado a 100 pixels dos lados superior e esquerdo da planilha.

// This sample creates a rectangle positioned 100 pixels from the top and left sides
// of the worksheet and is 150x150 pixels.
await Excel.run(async (context) => {
    let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;

    let rectangle = shapes.addGeometricShape(Excel.GeometricShapeType.rectangle);
    rectangle.left = 100;
    rectangle.top = 100;
    rectangle.height = 150;
    rectangle.width = 150;
    rectangle.name = "Square";

    await context.sync();
});

Imagens

Imagens JPEG, PNG e SVG podem ser inseridas em uma planilha como formas. O ShapeCollection.addImage método usa uma cadeia de caracteres codificada com base64 como argumento. Esta é uma imagem JPEG ou PNG em forma de cadeia de caracteres. ShapeCollection.addSvg também usa uma cadeia de caracteres, embora esse argumento seja XML que define o gráfico.

O exemplo de código a seguir mostra um arquivo de imagem sendo carregado por um FileReader como uma cadeia de caracteres. A cadeia de caracteres tem os metadados "base64", removidos antes da forma ser criada.

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

reader.onload = (event) => {
    Excel.run(function (context) {
        let startIndex = reader.result.toString().indexOf("base64,");
        let myBase64 = reader.result.toString().substr(startIndex + 7);
        let sheet = context.workbook.worksheets.getItem("MyWorksheet");
        let 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]);

Linhas

Uma linha é criada com ShapeCollection.addLine. Esse método precisa das margens esquerda e superior dos pontos de início e de extremidade da linha. Ele também usa um enumeração ConnectorType para especificar como a linha se contorta entre pontos de extremidade. O exemplo de código a seguir cria uma linha reta na planilha.

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

As linhas podem ser conectadas a outros objetos Shape. Os connectBeginShape métodos e connectEndShape anexam o início e o término de uma linha a formas nos pontos de conexão especificados. Os locais desses pontos variam de acordo com a forma, mas podem Shape.connectionSiteCount ser usados para garantir que o suplemento não se conecte a um ponto fora dos limites. Uma linha é desconectada de todas as formas anexadas usando os disconnectBeginShape métodos e disconnectEndShape .

O exemplo de código a seguir conecta a linha "MyLine" a duas formas chamadas "LeftShape" e "RightShape".

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

Mover e redimensionar formas

As formas ficam na parte superior da planilha. Seu posicionamento é definido pela left propriedade e top . Elas atuam como margens das respectivas bordas da planilha, com [0, 0] sendo o canto superior esquerdo. Elas podem ser definidas diretamente ou ajustadas de sua posição atual com os incrementLeft métodos e incrementTop . O quanto uma forma é girada da posição padrão também é estabelecida dessa maneira, com a rotation propriedade sendo a quantidade absoluta e o incrementRotation método ajustando a rotação existente.

A profundidade de uma forma em relação a outras formas é definida pela zorderPosition propriedade. Isso é definido usando o setZOrder método, que usa um ShapeZOrder. setZOrder ajusta a ordenação da forma atual em relação às outras formas.

Seu suplemento tem algumas opções para alterar a altura e a largura das formas. A configuração da height propriedade ou width altera a dimensão especificada sem alterar a outra dimensão. O scaleHeight e scaleWidth ajustar as respectivas dimensões da forma em relação ao tamanho atual ou original (com base no valor do ShapeScaleType fornecido). Um parâmetro opcional ShapeScaleFrom especifica de onde a forma é dimensionada (canto superior esquerdo, canto médio ou canto inferior direito). Se a lockAspectRatio propriedade for true, os métodos de escala manterão a proporção atual da forma ajustando também a outra dimensão.

O exemplo de código a seguir mostra uma forma sendo dimensionada para 1,25 vezes seu tamanho original e girada 30 graus.

// In this sample, the shape "Octagon" is rotated 30 degrees clockwise
// and scaled 25% larger, with the upper-left corner remaining in place.
await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("MyWorksheet");

    let shape = sheet.shapes.getItem("Octagon");
    shape.incrementRotation(30);
    shape.lockAspectRatio = true;
    shape.scaleWidth(
        1.25,
        Excel.ShapeScaleType.currentSize,
        Excel.ShapeScaleFrom.scaleFromTopLeft);

    await context.sync();
});

Texto em formas

Formas geométricas podem conter texto. As formas têm uma textFrame propriedade do tipo TextFrame. O TextFrame objeto gerencia as opções de exibição de texto (como margens e estouro de texto). TextFrame.textRange é um objeto TextRange com o conteúdo de texto e as configurações de fonte.

O exemplo de código a seguir cria uma forma geométrica chamada "Wave" com o texto "Texto de Forma". Ele também ajusta a forma e as cores de texto, bem como define o alinhamento horizontal do texto para o centro.

// This sample creates a light-blue wave shape and adds the purple text "Shape text" to the center.
await Excel.run(async (context) => {
    let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    let 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;

    await context.sync();
});

O addTextBox método de ShapeCollection cria um GeometricShape tipo Rectangle com um fundo branco e um texto em preto. Isso é o mesmo que é criado pelo botão Caixa de Texto do Excel na guia Inserir . addTextBox usa um argumento de cadeia de caracteres para definir o texto do TextRange.

O exemplo de código a seguir mostra a criação de uma caixa de texto com o texto "Olá!".

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

Grupos de formas

Formas podem ser agrupadas. Isso permite que um usuário os trate como uma única entidade para posicionamento, dimensionamento e outras tarefas relacionadas. Um ShapeGroup é um tipo de Shape, portanto, seu suplemento trata o grupo como uma única forma.

O exemplo de código a seguir mostra três formas sendo agrupadas. O exemplo de código subsequente mostra esse grupo de formas sendo movido para os 50 pixels à direita.

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

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

    await context.sync();
});

// This sample moves the previously created shape group to the right by 50 pixels.
await Excel.run(async (context) => {
    let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    let shapeGroup = shapes.getItem("Group");
    shapeGroup.incrementLeft(50);
    await context.sync();
});

Exportar formas como imagens

Qualquer Shape objeto pode ser convertido em uma imagem. Shape.getAsImage retorna a cadeia de caracteres codificada com base64. O formato da imagem é especificado como um enumeração PictureFormat passado para getAsImage.

await Excel.run(async (context) => {
    let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    let shape = shapes.getItem("Image");
    let stringResult = shape.getAsImage(Excel.PictureFormat.png);

    await context.sync();

    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.
});

Excluir formas

As formas são removidas da planilha com o Shape método do delete objeto. Nenhum outro metadado é necessário.

O exemplo de código a seguir exclui todas as formas do MyWorksheet.

// This deletes all the shapes from "MyWorksheet".
await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("MyWorksheet");
    let shapes = sheet.shapes;

    // We'll load all the shapes in the collection without loading their properties.
    shapes.load("items/$none");
    await context.sync();

    shapes.items.forEach(function (shape) {
        shape.delete();
    });
    
    await context.sync();
});

Confira também

• Conceitos fundamentais de programação com a API JavaScript do Excel
• Trabalhar com gráficos usando a API JavaScript do Excel