Definir e obter o intervalo selecionado com 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 suportados pelo Range objeto, consulte Excel.Range class (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 seguinte exemplo de código obtém o intervalo selecionado, carrega a respetiva address propriedade e escreve uma mensagem na consola do .
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}"`);
});
Selecionar o limite de um intervalo utilizado
Os métodos Range.getRangeEdge e Range.getExtendedRange permitem que o suplemento replique o comportamento dos atalhos de seleção de teclado, selecionando a margem do intervalo utilizado com base no intervalo atualmente selecionado. Para saber mais sobre os intervalos utilizados, veja Obter intervalo utilizado.
Na captura de ecrã seguinte, o intervalo utilizado é a tabela com valores em cada célula, C5:F12. As células vazias fora desta tabela estão fora do intervalo utilizado.
Selecione a célula na extremidade do intervalo utilizado atual
O seguinte exemplo de código mostra como utilizar o Range.getRangeEdge método para selecionar a célula na extremidade mais distante do intervalo utilizado atual, na direção para cima. Esta ação corresponde ao resultado da utilização do atalhode tecladoctrl+ seta para cima enquanto está selecionado um intervalo.
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 extremidade do intervalo utilizado
A seguinte captura de ecrã mostra um intervalo utilizado e um intervalo selecionado dentro do intervalo utilizado. O intervalo utilizado é uma tabela com dados em C5:F12. Dentro desta tabela, o intervalo D8:E9 está selecionado. Esta seleção é o estado anterior , antes de executar o Range.getRangeEdge método .
Depois de selecionar a célula na extremidade do intervalo utilizado
A captura de ecrã seguinte mostra a mesma tabela que a captura de ecrã anterior, com dados no intervalo C5:F12. Dentro desta tabela, o intervalo D5 está selecionado. Esta seleção é após o estado, depois de executar o Range.getRangeEdge método para selecionar a célula na extremidade do intervalo utilizado na direção superior.
Selecionar todas as células do intervalo atual para a margem mais distante do intervalo utilizado
O seguinte exemplo de código mostra como utilizar o Range.getExtendedRange método para selecionar todas as células do intervalo atualmente selecionado até à margem mais distante do intervalo utilizado, na direção para baixo. Esta ação corresponde ao resultado da utilização do atalho de teclado Ctrl+Shift Seta+Para Baixo enquanto está selecionado um intervalo.
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 para o limite do intervalo utilizado
A seguinte captura de ecrã mostra um intervalo utilizado e um intervalo selecionado dentro do intervalo utilizado. O intervalo utilizado é uma tabela com dados em C5:F12. Dentro desta tabela, o intervalo D8:E9 está selecionado. Esta seleção é o estado anterior , antes de executar o Range.getExtendedRange método .
Depois de selecionar todas as células do intervalo atual para o limite do intervalo utilizado
A captura de ecrã seguinte mostra a mesma tabela que a captura de ecrã anterior, com dados no intervalo C5:F12. Dentro desta tabela, o intervalo D8:E12 está selecionado. Esta seleção é após o estado, depois de executar o Range.getExtendedRange método para selecionar todas as células do intervalo atual para o limite do intervalo utilizado na direção inferior.
