Angular Using Cells

Os WorksheetCell objetos em uma planilha do Excel são o objeto que contém os valores de dados reais da planilha. Este tópico aborda as muitas operações que você pode executar nessas células, como acessá-las e suas regiões por nome, adicionar fórmulas e comentários às células e mesclá-las e formatá-las.

Angular Using Cells Example

References

O código a seguir mostra as importações necessárias para usar os trechos de código abaixo:

import { Workbook } from "igniteui-angular-excel";
import { WorkbookFormat } from "igniteui-angular-excel";
import { Worksheet } from "igniteui-angular-excel";
import { WorksheetTable } from "igniteui-angular-excel";
import { NamedReference } from "igniteui-angular-excel";
import { WorksheetCellComment } from "igniteui-angular-excel";
import { FormattedString } from "igniteui-angular-excel";

Referencing Cells and Regions

Você pode acessar um WorksheetCell objeto ou um WorksheetRegion objeto chamando os worksheet métodos or getRegion do getCell objeto, respectivamente. Ambos os métodos aceitam um parâmetro de cadeia de caracteres que faz referência a uma célula. Obter uma referência a uma célula é útil ao aplicar formatos ou trabalhar com fórmulas e conteúdo de células.

O código de exemplo a seguir demonstra como fazer referência a células e regiões:

var workbook = new Workbook();
var worksheet = workbook.worksheets().add("Sheet1");

//Accessing a single cell
var cell = worksheet.getCell("E2");
//Accessing a range of cells
var region = worksheet.getRegion("G1:G10");

Accessing Cells and Regions by Name

No Microsoft Excel, células individuais, bem como regiões de células, podem ter nomes atribuídos a elas. O nome de uma célula ou região pode ser usado para fazer referência a essa célula ou região em vez de seu endereço.

The Infragistics Angular Excel Library supports the referencing of cells and regions by name through the getCell and getRegion methods of the worksheet object. You refer to the cell or region using the NamedReference instance that refers to that cell or region.

Você pode usar o seguinte trecho de código como exemplo para nomear uma célula ou região:

var workbook = new Workbook();
var worksheet = workbook.worksheets().add("Sheet1");

var cell_reference = workbook.namedReferences().add("myCell", "=Sheet1:A1");
var region_reference = workbook.namedReferences().add("myRegion", "=Sheet1!A1:B2");

O código a seguir pode ser usado para obter a célula e a região referenciadas pelas referências nomeadas "myCell" e "myRegion" acima:

var cell = worksheet.getCell("myCell");
var region = worksheet.getRegion("myRegion");

Adding a Comment to a Cell

A comment allows you to display hints or notes for a cell when the end user’s mouse hovers over a cell. The comments display as a tooltip-like callout that contains text. The Infragistics Angular Excel Library allows you to add comments to a cell by setting a WorksheetCell object’s comment property.

O código de exemplo a seguir demonstra como adicionar um comentário a uma célula:

var workbook = new Workbook();
var worksheet = workbook.worksheets().add("Sheet1");

var cellComment = new WorksheetCellComment();
var commentText = new FormattedString("This cell has a comment.");
cellComment.text = commentText;

worksheet.rows(0).cells(0).comment = cellComment;

Adding a Formula to a Cell

The Infragistics Angular Excel Library allows you to add Microsoft Excel formulas to a cell or group of cells in a worksheet. You can do this using the WorksheetCell object’s applyFormula method or by instantiating a formula object and applying it to a cell. Regardless of the manner in which you apply a formula to a cell, you can access the formula object using the WorksheetCell object’s formula property. If you need the value, use the cell’s value property.

O código a seguir mostra como adicionar uma fórmula a uma célula.

 var workbook = new Workbook();
 var worksheet = workbook.worksheets().add("Sheet1");
 worksheet.rows(5).cells(0).applyFormula("=SUM(A1:A5)");

 //Using a Formula object to apply a formula
 var sumFormula = Formula.parse("=SUM(A1:A5)", CellReferenceMode.A1);
 sumFormula.applyTo(worksheet.rows(5).cells(0));

Copying a Cell’s Format

As células podem ter formatação diferente, incluindo cor de fundo, cadeia de caracteres de formato e estilo de fonte. Se você precisar que uma célula tenha o mesmo formato de uma célula formatada anteriormente, em vez de definir individualmente cada opção exposta pela WorksheetCell propriedade do cellFormat objeto, você poderá chamar o cellFormat método do setFormatting objeto e passar a ele um cellFormat objeto para copiar. Isso copiará todas as configurações de formato da primeira célula para a segunda célula. Você também pode fazer isso para uma linha, região de célula mesclada ou coluna.

O código a seguir mostra como copiar o formato da 2ª coluna para a 4ª coluna:

var workbook = new Workbook();
var worksheet = workbook.worksheets().add("Sheet1");

//Format 2nd column
worksheet.columns(1).cellFormat.fill = CellFill.createSolidFill("Blue");
worksheet.columns(1).cellFormat.font.bold = true;

//Copy format of 2nd column to 4th column
worksheet.columns(3).cellFormat.setFormatting(worksheet.columns(1).cellFormat);

Formatting a Cell

The Infragistics Angular Excel Library allows you to customize the look and behavior of a cell. You can customize a cell by setting properties exposed by the cellFormat property of the WorksheetCell, WorksheetRow, WorksheetColumn, or WorksheetMergedCellsRegion objects.

Você pode personalizar todos os aspectos da aparência de uma célula. Você pode definir a fonte, o plano de fundo e as bordas de uma célula, bem como o alinhamento e a rotação do texto. Você pode até aplicar um formato diferente caractere por caractere para o texto de uma célula.

Você também pode formatar valores de célula atribuindo uma cadeia de caracteres de formato. Uma cadeia de caracteres de formato aceitável segue os padrões de formato e códigos de formatação tradicionais.

O código a seguir mostra como formatar uma célula para exibir números como moeda:

var workbook = new Workbook(format);
var workbook = workbook.worksheets().add("Sheet1");

worksheet.columns(2).cellFormat.formatString = "\"$\"#,##0.00";

Excel 2007 Color Model

A paleta de cores é análoga à caixa de diálogo de cores na interface do usuário do Microsoft Excel 2007. Você pode abrir essa caixa de diálogo de cores navegando até Opções do Excel => Salvar => Cores.

Você pode criar todos os tipos de preenchimento possíveis usando propriedades e métodos estáticos na CellFill classe. Eles são os seguintes:

NoColor- Uma propriedade que representa um preenchimento sem cor, que permite que uma imagem de plano de fundo da planilha, se houver, apareça.
CreateSolidFill- Retorna uma CellFillPattern instância que tem um estilo de padrão e uma cor de Solid fundo definida como ou color WorkbookColorInfo especificada no método.
CreatePatternFill- Retorna uma CellFillPattern instância que tem o estilo de padrão especificado e os color valores or WorkbookColorInfo, especificados para as cores de fundo e padrão.
CreateLinearGradientFill- Retorna uma CellFillLinearGradient instância com o ângulo e as paradas de gradiente especificados.
CreateRectangularGradientFill- Retorna uma CellFillRectangularGradient instância com a esquerda, a parte superior, a direita e a parte inferior especificadas do retângulo interno e das paradas de gradiente. Se os valores do retângulo interno não forem especificados, o centro da célula será usado como o retângulo interno.

Os tipos derivados, representando os vários preenchimentos que podem ser criados, são os seguintes:

CellFillPattern- Um padrão que representa um preenchimento de célula sem cor, uma cor sólida ou um preenchimento de padrão para uma célula. Ele tem informações de cor de fundo e informações de cor padrão que correspondem diretamente às seções de cores na guia Preenchimento da caixa de diálogo Formatar células do Excel.
CellFillLinearGradient- Representa um preenchimento de gradiente linear. Ele tem um ângulo, que é graus no sentido horário do gradiente linear da esquerda para a direita, e uma coleção de paradas de gradientes que descreve duas ou mais transições de cores ao longo do comprimento do gradiente.
CellFillRectangularGradient- Representa um preenchimento de gradiente retangular. Ele tem valores superior, esquerdo, direito e inferior, que descrevem, em coordenadas relativas, o retângulo interno a partir do qual o gradiente começa e sai para as bordas da célula. Ele também tem uma coleção de paradas de gradiente que descreve duas ou mais transições de cores ao longo do caminho do retângulo interno para as bordas da célula.

O snippet de código a seguir demonstra como criar um preenchimento sólido em um WorksheetCell:

var workbook = new Workbook();
var worksheet = workbook.worksheets().add("Sheet1");

var cellFill = CellFill.createSolidFill("Blue");
worksheet.rows(0).cells(0).cellFormat.fill = cellFill;

Você pode especificar uma cor (a cor do plano de fundo das células do Excel, borda, etc.) usando gradientes lineares e retangulares nas células. Quando as pastas de trabalho com esses gradientes são salvas em .xls formato de arquivo e abertas no Microsoft Excel 2007/2010, os gradientes ficam visíveis, mas quando esses arquivos são abertos no Microsoft Excel 2003, a célula é preenchida com a cor sólida da primeira parada de gradiente.

Estas são as maneiras pelas quais uma cor pode ser definida, da seguinte maneira:

A cor automática (que é a cor do sistema WindowText)
Qualquer cor RGB definida pelo usuário
A theme color

Se uma cor RGB ou de tema for usada, uma tonalidade opcional poderá ser aplicada para clarear ou escurecer a cor. Essa tonalidade não pode ser definida diretamente na interface do usuário do Microsoft Excel 2007, mas várias cores na paleta de cores exibidas para o usuário são, na verdade, cores de tema com tonalidades aplicadas.

Cada pasta de trabalho tem 12 cores de tema associadas. Eles são os seguintes:

Light 1
Light 2
Dark 1
Dark 2
Accent1
Accent2
Accent3
Accent4
Accent5
Accent6
Hiperlink
Followed Hyperlink
Há valores padrão quando uma pasta de trabalho é criada, que podem ser personalizados por meio do Excel.

As cores são definidas pela WorkbookColorInfo classe, que é uma classe imutável selada. A classe tem uma propriedade estática Automatic, que retorna a cor automática, e há vários construtores que permitem criar uma WorkbookColorInfo instância com um valor de cor ou tema e uma tonalidade opcional.

O getResolvedColor método em WorkbookColorInfo permite determinar qual cor será realmente vista pelo usuário quando ele abrir o arquivo no Excel.

Se o WorkbookColorInfo representar uma cor de tema, você deverá passar uma instância de pasta de trabalho para o método para que ele possa obter o valor RGB da cor do tema da pasta de trabalho.

Ao salvar nos formatos de arquivo mais recentes, como .xlsx, as informações de cores mais recentes são salvas diretamente no arquivo. Ao salvar em um formato de arquivo mais antigo, como .xls, o índice para a cor mais próxima na paleta será salvo. Além disso, os formatos mais antigos têm registros de recursos futuros que podem ser salvos para indicar as informações de cores mais recentes.

Quando os formatos mais antigos são abertos no Microsoft Excel 2003 e versões anteriores, esses registros de recursos futuros são ignorados, mas quando os formatos de arquivo mais antigos são abertos no Excel 2007 e posterior, seus registros são lidos e as informações de cor deles substituem a cor indexada que foi carregada anteriormente a partir dos registros de formato normal.

Excel Format Support

Você pode definir uma série de formatos diferentes em um WorksheetCell usando o cellFormat objeto retornado pela cellFormat propriedade dessa célula. Esse cellFormat objeto permite que você estilize muitos aspectos diferentes da célula, como bordas, fonte, preenchimento, alinhamentos e se a célula deve ou não ser reduzida para caber ou ser bloqueada.

Você também pode acessar os estilos internos do Microsoft Excel 2007 usando a styles workbook coleção do objeto. A lista completa de estilos no Excel pode ser encontrada na galeria Estilos de Célula da guia Página Inicial do Microsoft Excel 2007.

Há um tipo especial de estilo na coleção da pasta styles de trabalho conhecido como estilo "normal", que pode ser acessado usando a propriedade dessa normalStyle coleção ou indexando na coleção com o nome "Normal".

O normalStyle contém as propriedades padrão para todas as células na pasta de trabalho, a menos que especificado de outra forma em uma linha, coluna ou célula. Alterar as propriedades no normalStyle alterará todas as propriedades de formato de célula padrão na pasta de trabalho. Isso é útil, por exemplo, se você quiser alterar a fonte padrão da pasta de trabalho.

Você pode limpar a styles coleção ou redefini-la para seu estado predefinido usando os clear métodos e reset, respectivamente. Ambos removerão todos os estilos definidos pelo usuário, mas clear limparão totalmente a styles coleção.

Com esse recurso, uma style propriedade foi adicionada ao cellFormat objeto. Esta é uma referência a uma WorkbookStyle instância, representando o estilo pai do formato. Para formatos de um estilo, essa propriedade sempre será nula, pois os estilos não podem ter um estilo pai. Para formatos de linha, coluna e célula, a style propriedade sempre retorna o normalStyle por padrão.

Se a style propriedade for definida como nula, ela será revertida para o normalStyle. Se ele for definido como outro estilo na coleção de estilos, esse estilo agora manterá os padrões para todas as propriedades não definidas no formato da célula.

Quando a style propriedade é definida em um formato de célula, as opções de formato incluídas no style são removidas do formato de célula. Todas as outras propriedades são deixadas intactas. Por exemplo, se um estilo de célula incluindo formatação de borda foi criado e esse estilo foi definido como da célula style, a opção de formato de borda no formato de célula seria removida e o formato de célula incluiria apenas formatação de preenchimento.

Quando um sinalizador de opção de formato é removido de um formato, todas as propriedades associadas são redefinidas para seus valores não definidos, de modo que as propriedades de borda do formato de célula são implicitamente redefinidas para valores padrão/não definidos.

Você pode determinar o que realmente seria visto nas células usando o getResolvedCellFormat método em classes que representam uma linha, coluna, célula e célula mesclada.

Esse método retorna uma cellFormat instância que se refere ao associado cellFormat no qual ele se baseia. Portanto, as cellFormat alterações subsequentes na propriedade serão refletidas na instância retornada de uma getResolvedCellFormat chamada.

Merging Cells

Além de definir o valor ou o formato das células, você também pode mesclar células para fazer com que duas ou mais células apareçam como uma. Se você mesclar células, elas deverão estar em uma região retangular.

Quando você mescla células, cada célula na região terá o mesmo valor e formato de célula. As células mescladas também serão associadas ao mesmo WorksheetMergedCellsRegion objeto, acessível a partir de sua associatedMergedCellsRegion propriedade. O objeto resultante WorksheetMergedCellsRegion também terá o mesmo valor e formato de célula que as células.

Definir o valor (ou formato da célula) da região ou de qualquer célula da região alterará o valor de todas as células e da região. Se você desfazer a mesclagem de células, todas as células mescladas anteriormente manterão o formato de célula compartilhada que tinham antes de serem desmescladas. No entanto, somente a célula superior esquerda da região manterá o valor compartilhado.

Para criar uma região de célula mesclada, você deve adicionar um intervalo de células à worksheet coleção do mergedCellsRegions objeto. Essa coleção expõe um Add método que usa quatro parâmetros inteiros. Os quatro parâmetros determinam o índice da linha e coluna inicial (célula superior esquerda) e o índice da linha e coluna final (célula inferior direita).

var workbook = new Workbook();
var worksheet = workbook.worksheets().add("Sheet1");

// Make some column headers
worksheet.rows(1).cells(1).value = "Morning";
worksheet.rows(1).cells(2).value = "Afternoon";
worksheet.rows(1).cells(3).value = "Evening";

// Create a merged region from column 1 to column 3
var mergedRegion1 =  ws.mergedCellsRegions().add(0, 1, 0, 3);

// Set the value of the merged region
mergedRegion1.value = "Day 1";

// Set the cell alignment of the middle cell in the merged region.
// Since a cell and its merged region shared a cell format, this will ultimately set the format of the merged region
worksheet.rows(0).cells(2).cellFormat.alignment = HorizontalCellAlignment.Center;

Retrieving the Cell Text as Displayed in Excel

O texto exibido em uma célula depende de vários fatores além do valor real da célula, como a cadeia de caracteres de formato e a largura da coluna em que a célula está contida.

A cadeia de caracteres de formato determina como o valor da célula é convertido em texto e qual caractere literal deve ser exibido com o valor formatado. Você pode encontrar informações mais detalhadas sobre códigos de formato aqui.

A quantidade de espaço horizontal disponível em uma célula desempenha um papel importante na forma como o valor é exibido para o usuário.

O texto exibido pode ser diferente dependendo da largura variável da coluna.

Ao exibir números e usar a string de formato contendo "Geral" ou"@", existem vários formatos que são tentados para encontrar uma formatação que se ajuste à largura da célula. Uma lista de formatos de exemplo é mostrada abaixo:

Valor Normal- O número é exibido como seria se houvesse uma quantidade ilimitada de espaço.
Remover dígitos decimais- Os dígitos decimais serão removidos um de cada vez até que seja encontrado um formato adequado. Por exemplo, um valor de 12345.6789 será reduzido para os seguintes formatos até que um se encaixe: 12345.679, 12345.68, 12345.7 e 12346. Isso será interrompido quando o primeiro dígito significativo for o único restante, portanto, por exemplo, valores como 0,0001234567890 só podem ser reduzidos para 0,0001.
Científico, 5 dígitos decimais- O número é exibido na forma de 0,00000E+00, como 1,23457E+09 ou 1,23457E-04
Científico, 4 dígitos decimais- O número é exibido na forma de 0,0000E+00, como 1,2346E+09 ou 1,23456E-04
Científico, 3 dígitos decimais- O número é exibido na forma de 0.000E+00, como 1.235E+09 ou 1.235E-0
Científico, 2 dígitos decimais- O número é exibido na forma de 0,00E + 00, como 1,23E + 09 ou 1,23E-04
Científico, 1 dígitos decimais- O número é exibido na forma de 0.0E + 00, como 1.2E + 09 ou 1.2E-04
Científico, 0 dígitos decimais- O número é exibido na forma de 0E+00, como 1E+09 ou 1E-04
Valor arredondado- Se o primeiro dígito significativo estiver na parte decimal do número, o valor será arredondado para o valor inteiro mais próximo. Por exemplo, para um valor 0,0001234567890, ele será arredondado para 0 e o texto exibido na célula será 0.
Marcas de hash- Se nenhuma versão condensada do número puder ser exibida, os hashes (#) serão repetidos na largura da célula.
Cadeia de caracteres vazia- Se nenhuma marca de hash couber na célula, uma cadeia de caracteres vazia será retornada como texto da célula exibida.

Se a cadeia de caracteres de formato para o valor numérico não contiver Geral ou @, haverá apenas os seguintes estágios de redimensionamento: Valor normal, Marcas de hash, Cadeia de caracteres vazia

Se um texto for usado na célula, o texto exibido na célula sempre terá o valor total, independentemente de estar cortado ou não na célula.

O único momento em que esse não é o caso é quando os caracteres de preenchimento são usados na string de formato. Em seguida, o valor será exibido como todas as marcas de hash quando não houver espaço suficiente para o texto.

Você pode definir a propriedade da showFormulasInCells planilha para que as fórmulas displayOptions sejam exibidas nas células em vez de seus resultados, e as strings de formato e as larguras das células sejam ignoradas. Os valores de texto são exibidos como se sua cadeia de caracteres de formato fosse @ , os valores numéricos não integrais são exibidos como se sua cadeia de caracteres de formato fosse 0,0 e os valores numéricos integrais são exibidos como se sua cadeia de caracteres de formato fosse 0 .

Além disso, se o valor não couber, ele não será exibido como todos os hashes. O texto de exibição ainda retornará seu texto completo como o texto da célula, mesmo que não seja totalmente visto.

O snippet de código a seguir demonstra o uso do getText método para obter o texto como ele seria exibido no Excel:

var workbook = new Workbook();
var worksheet = this.workbook.worksheets().add("Sheet1");

var cellText = worksheet.rows(0).cells(0).getText();

Angular Using Cells