Definir e obter o intervalo selecionado usando a API JavaScript do Excel
Este artigo fornece exemplos de código que definem e obtêm o intervalo selecionado com a API JavaScript do Excel. Para obter a lista completa de propriedades e métodos compatíveis com o Range objeto, consulte Classe Excel.Range.
Observação
A API JavaScript do Excel não tem um objeto ou classe "Célula". Em vez disso, a API JavaScript do Excel define todas as células do Excel como objetos Range. Uma célula individual na interface do usuário do Excel se traduz em um objeto Range com uma célula na API JavaScript do Excel. Um único objeto Range também pode conter várias células contíguas. Confira Trabalhar com células usando a API JavaScript do Excel para saber mais.
Definir o intervalo selecionado
O exemplo de código a seguir seleciona o intervalo B2:E6 na planilha ativa.
await Excel.run(async (context) => {
let sheet = context.workbook.worksheets.getActiveWorksheet();
let range = sheet.getRange("B2:E6");
range.select();
await context.sync();
});
Intervalo selecionado B2:E6
Obter o intervalo selecionado
O exemplo de código a seguir obtém o intervalo selecionado, carrega sua address propriedade e grava uma mensagem no console.
await Excel.run(async (context) => {
let range = context.workbook.getSelectedRange();
range.load("address");
await context.sync();
console.log(`The address of the selected range is "${range.address}"`);
});
Selecione a borda de um intervalo usado
Os métodos Range.getRangeEdge e Range.getExtendedRange permitem que o suplemento replique o comportamento dos atalhos de seleção de teclado, selecionando a borda do intervalo usado com base no intervalo selecionado no momento. Para saber mais sobre intervalos usados, consulte Intervalo de uso.
Na captura de tela a seguir, o intervalo usado é a tabela com valores em cada célula, C5:F12. As células vazias fora dessa tabela estão fora do intervalo usado.
Selecione a célula na borda do intervalo usado atual
O exemplo de código a seguir mostra como usar o Range.getRangeEdge método para selecionar a célula na borda mais distante do intervalo usado atual, na direção para cima. Essa ação corresponde ao resultado do uso do atalho de teclado da tecla de seta Ctrl+Up enquanto um intervalo é selecionado.
await Excel.run(async (context) => {
// Get the selected range.
let range = context.workbook.getSelectedRange();
// Specify the direction with the `KeyboardDirection` enum.
let direction = Excel.KeyboardDirection.up;
// Get the active cell in the workbook.
let activeCell = context.workbook.getActiveCell();
// Get the top-most cell of the current used range.
// This method acts like the Ctrl+Up arrow key keyboard shortcut while a range is selected.
let rangeEdge = range.getRangeEdge(
direction,
activeCell
);
rangeEdge.select();
await context.sync();
});
Antes de selecionar a célula na borda do intervalo usado
A captura de tela a seguir mostra um intervalo usado e um intervalo selecionado dentro do intervalo usado. O intervalo usado é uma tabela com dados em C5:F12. Dentro desta tabela, o intervalo D8:E9 está selecionado. Essa seleção é o estado anterior , antes de executar o Range.getRangeEdge método.
Depois de selecionar a célula na borda do intervalo usado
A captura de tela a seguir mostra a mesma tabela da captura de tela anterior, com dados no intervalo C5:F12. Dentro desta tabela, o intervalo D5 está selecionado. Essa seleção é após o estado, depois de executar o Range.getRangeEdge método para selecionar a célula na borda do intervalo usado na direção superior.
Selecione todas as células do intervalo atual para a borda mais distante do intervalo usado
O exemplo de código a seguir mostra como usar o Range.getExtendedRange método para selecionar todas as células do intervalo selecionado no momento até a borda mais distante do intervalo usado, na direção para baixo. Essa ação corresponde ao resultado do uso do atalho de teclado da tecla de seta Ctrl+Shift+Down enquanto um intervalo é selecionado.
await Excel.run(async (context) => {
// Get the selected range.
let range = context.workbook.getSelectedRange();
// Specify the direction with the `KeyboardDirection` enum.
let direction = Excel.KeyboardDirection.down;
// Get the active cell in the workbook.
let activeCell = context.workbook.getActiveCell();
// Get all the cells from the currently selected range to the bottom-most edge of the used range.
// This method acts like the Ctrl+Shift+Down arrow key keyboard shortcut while a range is selected.
let extendedRange = range.getExtendedRange(
direction,
activeCell
);
extendedRange.select();
await context.sync();
});
Antes de selecionar todas as células do intervalo atual até a borda do intervalo usado
A captura de tela a seguir mostra um intervalo usado e um intervalo selecionado dentro do intervalo usado. O intervalo usado é uma tabela com dados em C5:F12. Dentro desta tabela, o intervalo D8:E9 está selecionado. Essa seleção é o estado anterior , antes de executar o Range.getExtendedRange método.
Depois de selecionar todas as células do intervalo atual até a borda do intervalo usado
A captura de tela a seguir mostra a mesma tabela da captura de tela anterior, com dados no intervalo C5:F12. Dentro desta tabela, o intervalo D8:E12 está selecionado. Essa seleção é após o estado, depois de executar o Range.getExtendedRange método para selecionar todas as células do intervalo atual até a borda do intervalo usado na direção inferior.
