Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
O Excel define as formas como qualquer objeto que se encontra na camada de desenho do Excel. Isso significa que qualquer coisa fora de uma célula é uma forma. Este artigo descreve como utilizar formas geométricas, linhas e imagens em conjunto com as APIs Shape e ShapeCollection . Os gráficos são abordados no seu próprio artigo, Trabalhar com gráficos com a API JavaScript do Excel.
A imagem seguinte mostra formas que formam um termómetro.
Criar formas
As formas são criadas através e armazenadas numa coleção de formas de uma folha de cálculo (Worksheet.shapes).
ShapeCollection tem vários .add* métodos para esta finalidade. Todas as formas têm nomes e IDs gerados para as mesmas quando são adicionadas à coleção. Estas são as name propriedades e id , respetivamente.
name pode ser definido pelo seu suplemento para uma obtenção fácil com o ShapeCollection.getItem(name) método .
Os seguintes tipos de formas são adicionados com o método associado.
| Forma | Add Method | Assinatura |
|---|---|---|
| Forma Geométrica | addGeometricShape | addGeometricShape(geometricShapeType: Excel.GeometricShapeType): Excel.Shape |
| Imagem (JPEG ou PNG) | addImage | addImage(base64ImageString: string): Excel.Shape |
| Line | addLine | addLine(startLeft: number, startTop: number, endLeft: number, endTop: number, connectorType?: Excel.ConnectorType): Excel.Shape |
| SVG | addSvg | addSvg(xml: string): Excel.Shape |
| Caixa de Texto | addTextBox | addTextBox(text?: string): Excel.Shape |
Formas geométricas
É criada uma forma geométrica com ShapeCollection.addGeometricShape. Este método utiliza uma enumeração GeometricShapeType como um argumento.
O seguinte exemplo de código cria um retângulo de 150x150 píxeis com o nome "Quadrado" que está posicionado a 100 píxeis dos lados superior e esquerdo da folha de cálculo.
// 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
As imagens JPEG, PNG e SVG podem ser inseridas numa folha de cálculo como formas. O ShapeCollection.addImage método utiliza uma cadeia codificada em Base64 como argumento. Trata-se de uma imagem JPEG ou PNG na forma de cadeia.
ShapeCollection.addSvg também recebe uma cadeia, embora este argumento seja XML que define o gráfico.
O seguinte exemplo de código mostra um ficheiro de imagem a ser carregado por um FileReader como uma cadeia. A cadeia tem os metadados "base64", removidos antes de a 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
É criada uma linha com ShapeCollection.addLine. Este método precisa das margens esquerda e superior dos pontos de início e de fim da linha. Também é necessária uma enumeração ConnectorType para especificar a forma como a linha se contorce entre pontos finais. O seguinte exemplo de código cria uma linha reta na folha de cálculo.
// 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 ligadas a outros objetos de Forma. Os connectBeginShape métodos e connectEndShape anexam o início e o fim de uma linha a formas nos pontos de ligação especificados. As localizações destes pontos variam consoante a forma, mas podem Shape.connectionSiteCount ser utilizadas para garantir que o suplemento não se liga a um ponto fora dos limites. Uma linha é desligada de quaisquer formas anexadas com os disconnectBeginShape métodos e disconnectEndShape .
O seguinte exemplo de código liga a linha "MyLine" a duas formas denominadas "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 encontram-se em cima da folha de cálculo. A respetiva colocação é definida pela left propriedade e top . Funcionam como margens das respetivas margens da folha de cálculo, sendo [0, 0] o canto superior esquerdo. Estes podem ser definidos diretamente ou ajustados a partir da sua posição atual com os incrementLeft métodos e incrementTop . A quantidade que uma forma é rodada da posição predefinida também é estabelecida desta forma, sendo a rotation propriedade a quantidade absoluta e o incrementRotation método que ajusta a rotação existente.
A profundidade de uma forma relativamente a outras formas é definida pela zorderPosition propriedade . Isto é definido com o setZOrder método , que utiliza shapeZOrder.
setZOrder ajusta a ordenação da forma atual relativamente às outras formas.
O seu suplemento tem algumas opções para alterar a altura e a largura das formas. Definir a height propriedade ou width altera a dimensão especificada sem alterar a outra dimensão.
scaleWidth E scaleHeight ajuste as respetivas dimensões da forma em relação ao tamanho atual ou original (com base no valor do ShapeScaleType fornecido). Um parâmetro shapeScaleFrom opcional especifica a partir do local onde a forma é dimensionada (canto superior esquerdo, centro ou canto inferior direito). Se a lockAspectRatio propriedade for true, os métodos de dimensionamento mantêm a proporção atual da forma ao ajustar também a outra dimensão.
Observação
As alterações diretas às height propriedades e width só afetam essa propriedade, independentemente lockAspectRatio do valor da propriedade.
O seguinte exemplo de código mostra uma forma a ser dimensionada para 1,25 vezes o tamanho original e rodada 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();
});
Obter a forma ativa
Obtenha a forma ativa com um dos seguintes métodos.
O seguinte exemplo de código mostra como obter a forma ativa num livro e aumentar a altura em 10%.
await Excel.run(async (context) => {
const shape = context.workbook.getActiveShapeOrNullObject();
if (shape !== null) {
shape.load("height");
await context.sync();
shape.height = shape.height + shape.height * 0.1;
await context.sync();
}
});
Texto em formas
As Formas Geométricas podem conter texto. As formas têm uma textFrame propriedade do tipo TextFrame. O TextFrame objeto gere as opções de apresentação de texto (como margens e excesso de texto).
TextFrame.textRange é um objeto TextRange com o conteúdo do texto e as definições do tipo de letra.
O seguinte exemplo de código cria uma forma geométrica denominada "Onda" com o texto "Texto da Forma". Também ajusta as cores da forma e do 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 texto preto. Tal é igual ao que é criado pelo botão Caixa de Texto do Excel no separador Inserir . addTextBox utiliza um argumento de cadeia para definir o texto de TextRange.
O seguinte exemplo de código 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
As formas podem ser agrupadas em conjunto. Isto permite que um utilizador os trate como uma única entidade para posicionar, dimensionar e outras tarefas relacionadas. Um ShapeGroup é um tipo de Shape, pelo que o suplemento trata o grupo como uma única forma.
O seguinte exemplo de código mostra três formas a serem agrupadas em conjunto. O exemplo de código subsequente mostra que o grupo de formas está a ser movido para a direita com 50 píxeis.
// 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();
});
Importante
As formas individuais dentro do grupo são referenciadas através da ShapeGroup.shapes propriedade GroupShapeCollection, que é do tipo GroupShapeCollection. Já não estão acessíveis através da coleção de formas da folha de cálculo depois de serem agrupadas. Por exemplo, se a sua folha de cálculo tivesse três formas e estivessem todas agrupadas, o método da shapes.getCount folha de cálculo devolveria uma contagem de 1.
Exportar formas como imagens
Qualquer Shape objeto pode ser convertido numa imagem.
Shape.getAsImage devolve uma cadeia codificada em Base64. O formato da imagem é especificado como uma enumeração PictureFormat transmitida 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.
});
Eliminar formas
As formas são removidas da folha de cálculo com o Shape método do delete objeto. Não são necessários outros metadados.
O seguinte exemplo de código elimina todas as formas de 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
Colaborar conosco no GitHub
A fonte deste conteúdo pode ser encontrada no GitHub, onde você também pode criar e revisar problemas e solicitações de pull. Para obter mais informações, confira o nosso guia para colaboradores.