Web Components Usando células

OsWorksheetCell objetos em uma planilha Excel são o objeto que armazena seus valores reais de dados para a planilha. Este tópico aborda as muitas operações que você pode realizar nessas células, como acessá-las e suas regiões pelo nome, adicionar fórmulas e comentários às células, e mesclar e formatá-las.

Web Components 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-webcomponents-excel";
import { WorkbookFormat } from "igniteui-webcomponents-excel";
import { Worksheet } from "igniteui-webcomponents-excel";
import { WorksheetTable } from "igniteui-webcomponents-excel";
import { NamedReference } from "igniteui-webcomponents-excel";
import { WorksheetCellComment } from "igniteui-webcomponents-excel";
import { FormattedString } from "igniteui-webcomponents-excel";

Referencing Cells and Regions

Você pode acessar umWorksheetCell objeto ou umWorksheetRegion objeto chamando oworksheet objetogetCell ougetRegion métodos, respectivamente. Ambos os métodos aceitam um parâmetro de string que faz referência a uma célula. Obter uma referência para 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.

A Biblioteca Infragistics Web Components Excel suporta o referenciamento de células e regiões pelo nome através dosgetCell métodos egetRegion doworksheet objeto. Você se refere à célula ou região usando aNamedReference instância que se refere àquela célula ou região.

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

Um comentário permite exibir dicas ou notas para uma célula quando o mouse do usuário final paira sobre uma célula. Os comentários são exibidos como uma dica de ferramenta que contém texto. A Infragistics Web Components Biblioteca Excel permite adicionar comentários a uma célula definindo a propriedade deWorksheetCell umcomment objeto.

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

A Infragistics Web Components Excel Library permite adicionar fórmulas do Microsoft Excel a uma célula ou grupo de células em uma planilha de exercícios. Você pode fazer isso usando oWorksheetCell método doapplyFormula objeto ou instanciando umformula objeto e aplicando-o a uma célula. Independentemente da forma como você aplica uma fórmula a uma célula, você pode acessar oformula objeto usando aWorksheetCell propriedade doformula objeto. Se você precisa do valor, use a propriedade davalue célula.

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 diferentes formatações, incluindo cor de fundo, string 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 pelaWorksheetCell propriedade docellFormat objeto, você pode chamar ocellFormat método dosetFormatting objeto e passar umcellFormat objeto para copiar. Isso vai copiar todas as configurações de formato da primeira célula para a segunda célula. Você também pode fazer isso para 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

A Infragistics Web Components Biblioteca Excel permite personalizar a aparência e o comportamento de uma célula. Você pode personalizar uma célula definindo propriedades expostas pelacellFormat propriedade dosWorksheetCell objetos,WorksheetRow,WorksheetColumn, ouWorksheetMergedCellsRegion objetos.

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 possíveis de preenchimento usando propriedades e métodos estáticos naCellFill classe. São as seguintes:

NoColor- Uma propriedade que representa um preenchimento sem cor, permitindo que uma imagem de fundo da planilha, se houver, apareça.
CreateSolidFill- Retorna umaCellFillPattern instância que possui um estilo de padrão deSolid e uma cor de fundo definida como oucolorWorkbookColorInfo especificada no método.
CreatePatternFill- Retorna umaCellFillPattern instância que possui o estilo de padrão especificado e oscolor valores ouWorkbookColorInfo, especificados para as cores de fundo e padrão.
CreateLinearGradientFill- Retorna umaCellFillLinearGradient instância com os registros de ângulo e gradiente especificados.
CreateRectangularGradientFill- Retorna umaCellFillRectangularGradient instância com os indicados para esquerda, cima, direita e base do retângulo interno e os registros de gradiente. Se os valores do retângulo interno não forem especificados, o centro da célula é usado como 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 sobre cor de fundo e uma informação de cor de padrão que correspondem diretamente às seções de cor na aba Preenchimento do diálogo Formatar Células do Excel.
CellFillLinearGradient- Representa um preenchimento linear em gradiente. Ele possui um ângulo, que é graus no sentido horário do gradiente linear da esquerda para a direita, e uma coleção de paras de gradientes que descreve duas ou mais transições de cor ao longo do comprimento do gradiente.
CellFillRectangularGradient- Representa um preenchimento em gradiente retangular. Ele possui valores superior, esquerdo, direito e inferior, que descrevem, em coordenadas relativas, o retângulo interno de onde o gradiente começa e se estende até as bordas da célula. Também possui uma coleção de paradas de gradiente que descreve duas ou mais transições de cor ao longo do caminho do retângulo interno até as bordas da célula.

O seguinte trecho de código demonstra como criar um preenchimento sólido em umWorksheetCell:

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 pelaWorkbookColorInfo classe, que é uma classe selada e imutável. A classe possui uma propriedade estáticaAutomatic, que retorna a cor automática, e existem vários construtores que permitem criar umaWorkbookColorInfo instância com um valor de cor ou tema e um tinte opcional.

OgetResolvedColor método emWorkbookColorInfo On permite que você determine qual cor será realmente vista pelo usuário ao abrir o arquivo no Excel.

Se oWorkbookColorInfo representa uma cor de tema, você deve passar uma instância de Workbook para o método para que ele possa obter o valor RGB da cor do tema a partir do workbook.

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 umWorksheetCell usando ocellFormat objeto retornado pelacellFormat propriedade dessa célula. EssecellFormat objeto permite que você estilize muitos aspectos diferentes da célula, como bordas, fonte, preenchimento, alinhamentos e se a célula deve encolher para se encaixar ou ser travada.

Você também pode acessar os estilos integrados do Microsoft Excel 2007 usando astyles coleção doworkbook objeto. A lista completa de estilos no Excel pode ser encontrada na galeria de Estilos de Célula da aba Início do Microsoft Excel 2007.

Existe um tipo especial de estilo na coleção dostyles livro de exercícios conhecido como estilo "normal", que pode ser acessado usando anormalStyle propriedade dessa coleção ou indexando dentro da coleção com o nome "Normal".

ContémnormalStyle as propriedades padrão de todas as células do workbook, a menos que especificado de outra forma em uma linha, coluna ou célula. Mudar as propriedades nonormalStyle vai alterar todas as propriedades padrão do formato de célula no livro de exercícios. Isso é útil, por exemplo, se você quiser mudar a fonte padrão do seu livro de exercícios.

Você pode limpar astyles coleção ou resetá-la para seu estado pré-definido usando osclear métodos andreset, respectivamente. Ambos removem todos os estilos definidos pelo usuário, masclear limpam completamente astyles coleção.

Com esse recurso, umastyle propriedade foi adicionada aocellFormat objeto. Isso é uma referência a umaWorkbookStyle instância, representando o estilo pai do formato. Para formatos de um estilo, essa propriedade será sempre nula, pois estilos não podem ter um estilo pai. Para formatos de linha, coluna e célula, astyle propriedade sempre retorna onormalStyle por padrão.

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

Quando astyle propriedade é definida em um formato de célula, as opções de formato incluídas em sãostyle removidas do formato da célula. Todas as outras propriedades permanecem intactas. Por exemplo, se um estilo de célula incluindo formatação de borda fosse criado e esse estilo fosse definido como dastyle célula, a opção de formatar borda no formato da célula seria removida e o formato da 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 ogetResolvedCellFormat método das classes que representam linha, coluna, célula e célula mescada.

Esse método retorna umacellFormat instância que se refere à associaçãocellFormat na qual se baseia. Portanto, mudanças subsequentes nacellFormat propriedade serão refletidas na instância retornada de umagetResolvedCellFormat 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 da região terá o mesmo valor e formato de célula. As células fundidas também estarão associadas ao mesmoWorksheetMergedCellsRegion objeto, acessível a partir de suaassociatedMergedCellsRegion propriedade. O objeto resultanteWorksheetMergedCellsRegion 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élulas mescladas, você deve adicionar um intervalo de células àworksheet coleção domergedCellsRegions objeto. Essa coleção expõe umAdd método que recebe quatro parâmetros inteiros. Os quatro parâmetros determinam o índice da linha e coluna iniciais (célula mais à esquerda) e o índice da linha e coluna finais (célula mais à 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 dadisplayOptionsshowFormulasInCells planilha para que as fórmulas sejam exibidas em células em vez dos resultados, e as strings de formatação e larguras das células sejam ignoradas. Os valores do texto são exibidos como se sua string de formato fosse @, valores numéricos não inteiros exibem como se sua string de formato fosse 0.0 e valores numéricos inteiros exibem como se sua string 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 seguinte trecho de código demonstra o uso dogetText 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();