Excel.Range class

Especifica a referência de intervalo no estilo A1. O valor do endereço contém a referência da folha (por exemplo, "Folha1! A1:B4").

readonly address: string;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Representa a referência de intervalo para o intervalo especificado no idioma do utilizador.

readonly addressLocal: string;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Especifica o número de células no intervalo. Essa API retornará -1 se a contagem de células exceder 2^31-1 (2.147.483.647).

readonly cellCount: number;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Especifica o número total de colunas no intervalo.

readonly columnCount: number;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Representa se todas as colunas no intervalo atual estão ocultas. O valor é true quando todas as colunas num intervalo estão ocultas. O valor é false quando não existem colunas no intervalo ocultadas. O valor é null quando algumas colunas num intervalo estão ocultas e outras colunas no mesmo intervalo não estão ocultas.

columnHidden: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

Especifica o número da coluna da primeira célula no intervalo. Indexados com zero.

readonly columnIndex: number;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

A coleção do ConditionalFormats que intersecta o intervalo.

readonly conditionalFormats: Excel.ConditionalFormatCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

O contexto do pedido associado ao objeto . Esta ação liga o processo do suplemento ao processo da aplicação anfitriã do Office.

context: RequestContext;

Valor da propriedade

Retorna um objeto de validação de dados.

readonly dataValidation: Excel.DataValidation;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.8 ]

Retorna um objeto de formato que encapsula a fonte, o preenchimento, as bordas, o alinhamento e outras propriedades do intervalo.

readonly format: Excel.RangeFormat;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Representa a fórmula em notação A1. Se uma célula não tiver nenhuma fórmula, é devolvido o respetivo valor.

formulas: any[][];

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Representa a fórmula em notação A1, na formatação de número da localidade e no idioma do usuário. Por exemplo, a fórmula "=SUM(A1, 1.5)" em inglês seria "=SOMA(A1; 1,5)" em português. Se uma célula não tiver nenhuma fórmula, é devolvido o respetivo valor.

formulasLocal: any[][];

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Representa a fórmula em notação no estilo L1C1. Se uma célula não tiver nenhuma fórmula, é devolvido o respetivo valor.

formulasR1C1: any[][];

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

Representa se todas as células têm uma borda de despejo. Devolve true se todas as células tiverem um limite de transposição ou false se todas as células não tiverem um limite de transposição. Devolve null se existirem células com e sem limites de transposição dentro do intervalo.

readonly hasSpill: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.12 ]

Devolve a distância em pontos, para 100% de zoom, desde a margem superior do intervalo até à margem inferior do intervalo.

readonly height: number;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

Representa se todas as células no intervalo atual estão ocultas. O valor é true quando todas as células num intervalo estão ocultas. O valor é false quando não existem células no intervalo ocultadas. O valor é null quando algumas células num intervalo estão ocultas e outras células no mesmo intervalo não estão ocultas.

readonly hidden: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

Representa a hiperligação para o intervalo atual.

hyperlink: Excel.RangeHyperlink;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-hyperlink.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Orders");

    let productsRange = sheet.getRange("A3:A5");
    productsRange.load("values");

    await context.sync();

    // Create a hyperlink to a URL 
    // for each product name in the first table.
    for (let i = 0; i < productsRange.values.length; i++) {
        let cellRange = productsRange.getCell(i, 0);
        let cellText = productsRange.values[i][0];

        let hyperlink = {
            textToDisplay: cellText,
            screenTip: "Search Bing for '" + cellText + "'",
            address: "https://www.bing.com?q=" + cellText
        }
        cellRange.hyperlink = hyperlink;
    }

    await context.sync();
});

Representa se o intervalo atual está em uma coluna inteira.

readonly isEntireColumn: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

Representa se o intervalo atual está em uma linha inteira.

readonly isEntireRow: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

Devolve a distância em pontos, para uma ampliação de 100%, desde a margem esquerda da folha de cálculo até à margem esquerda do intervalo.

readonly left: number;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

Representa o estado do tipo de dados de cada célula.

readonly linkedDataTypeState: Excel.LinkedDataTypeState[][];

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Representa o código de formato de número do Excel para o intervalo especificado. Para obter mais informações sobre a formatação de números do Excel, consulte Códigos de formato de número.

numberFormat: any[][];

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

// Set the text of the chart title to "My Chart" and display it as an overlay on the chart.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "F5:G7";
    const numberFormat = [[null, "d-mmm"], [null, "d-mmm"], [null, null]]
    const values = [["Today", 42147], ["Tomorrow", "5/24"], ["Difference in days", null]];
    const formulas = [[null,null], [null,null], [null,"=G6-G5"]];
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.numberFormat = numberFormat;
    range.values = values;
    range.formulas= formulas;
    range.load('text');
    await context.sync();
    
    console.log(range.text);
});

Representa a categoria do formato de número de cada célula.

readonly numberFormatCategories: Excel.NumberFormatCategory[][];

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.12 ]

Representa o código de formato de número do Excel para o intervalo especificado, com base nas definições de idioma do utilizador. O Excel não executa qualquer idioma ou coerção de formato ao obter ou definir a numberFormatLocal propriedade. Qualquer texto devolvido utiliza as cadeias formatadas localmente com base no idioma especificado nas definições do sistema.

numberFormatLocal: any[][];

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

Retorna o número total de linhas no intervalo.

readonly rowCount: number;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Representa se todas as linhas no intervalo atual estão ocultas. O valor é true quando todas as linhas num intervalo estão ocultas. O valor é false quando não existem linhas no intervalo ocultadas. O valor é null quando algumas linhas num intervalo estão ocultas e outras linhas no mesmo intervalo não estão ocultas.

rowHidden: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

Representa o número de linhas da primeira célula no intervalo. Indexados com zero.

readonly rowIndex: number;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Representa se todas as células seriam guardadas como uma fórmula de matriz. Devolve true se todas as células fossem guardadas como uma fórmula de matriz ou false se todas as células não fossem guardadas como uma fórmula de matriz. Devolve null se algumas células fossem guardadas como uma fórmula de matriz e algumas não seriam.

readonly savedAsArray: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.12 ]

Representa a classificação de intervalo do intervalo atual.

readonly sort: Excel.RangeSort;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/event-column-and-row-sort.yaml

async function sortTopToBottom(criteria: string) {
    await Excel.run(async (context) => {
        const sheet = context.workbook.worksheets.getActiveWorksheet();
        const range = sheet.getRange("A1:E5");

        // Find the column header that provides the sort criteria.
        const header = range.find(criteria, {});
        header.load("columnIndex");
        await context.sync();

        range.sort.apply(
            [
                {
                    key: header.columnIndex,
                    sortOn: Excel.SortOn.value
                }
            ],
            false /*matchCase*/,
            true /*hasHeaders*/,
            Excel.SortOrientation.rows
        );
        await context.sync();
    });
}

Representa o estilo de intervalo atual. Se os estilos das células forem inconsistentes, null serão devolvidos. Para estilos personalizados, o nome do estilo será devolvido. Para estilos incorporados, será devolvida uma cadeia que representa um valor na BuiltInStyle enumeração.

style: string;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/style.yaml

await Excel.run(async (context) => {
    let worksheet = context.workbook.worksheets.getItem("Sample");
    let range = worksheet.getRange("A1:E1");

    // Apply built-in style. 
    // Styles are in the Home tab ribbon.
    range.style = Excel.BuiltInStyle.neutral;
    range.format.horizontalAlignment = "Right";

    await context.sync();
});

Valores de texto do intervalo especificado. O valor de texto não depende da largura da célula. A substituição do sinal de número (#) que ocorre na IU do Excel não afetará o valor de texto devolvido pela API.

readonly text: string[][];

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Devolve a distância em pontos, para uma ampliação de 100%, desde a margem superior da folha de cálculo até à margem superior do intervalo.

readonly top: number;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

Representa os valores brutos do intervalo especificado. Os dados devolvidos podem ser uma cadeia, número ou booleano. Células que contêm um erro retornarão a cadeia de caracteres de erro. Se o valor devolvido começar com uma adição ("+"), sinal de subtração ("-"), ou sinal de igual ("="), o Excel interpreta este valor como uma fórmula.

values: any[][];

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Especifica o tipo de dados em cada célula.

readonly valueTypes: Excel.RangeValueType[][];

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Devolve a distância em pontos, para um zoom de 100%, desde a margem esquerda do intervalo até à margem direita do intervalo.

readonly width: number;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

A planilha que contém o intervalo atual.

readonly worksheet: Excel.Worksheet;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Preenche um intervalo entre o intervalo atual e o intervalo de destino com a lógica de Preenchimento Automático especificada. O intervalo de destino pode ser null ou pode expandir o intervalo de origem horizontal ou verticalmente. Os intervalos descontínuos não são suportados.

Para obter mais informações, veja Utilizar o Preenchimento Automático e a Pré-visualização da Conclusão Automática.

autoFill(destinationRange?: Range | string, autoFillType?: Excel.AutoFillType): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9, ExcelApi Preview for null destinationRange ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-auto-fill.yaml

await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const sumCell = sheet.getRange("P4");
  
  // Copy everything. The formulas will be contextually updated based on their new locations.
  sumCell.autoFill("P4:P7", Excel.AutoFillType.fillCopy);
  sumCell.format.autofitColumns();
  await context.sync();
});

Preenche um intervalo entre o intervalo atual e o intervalo de destino com a lógica de Preenchimento Automático especificada. O intervalo de destino pode ser null ou pode expandir o intervalo de origem horizontal ou verticalmente. Os intervalos descontínuos não são suportados.

Para obter mais informações, veja Utilizar o Preenchimento Automático e a Pré-visualização da Conclusão Automática.

autoFill(destinationRange?: Range | string, autoFillTypeString?: "FillDefault" | "FillCopy" | "FillSeries" | "FillFormats" | "FillValues" | "FillDays" | "FillWeekdays" | "FillMonths" | "FillYears" | "LinearTrend" | "GrowthTrend" | "FlashFill"): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9, ExcelApi Preview for null destinationRange ]

Calcula um intervalo de células em uma planilha.

calculate(): void;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

Limpar valores de intervalo e formatação, como preenchimento e limite.

clear(applyTo?: Excel.ClearApplyTo): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

// Clear the format and contents of the range.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D:F";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.clear();
    await context.sync(); 
});

Limpar valores de intervalo e formatação, como preenchimento e limite.

clear(applyToString?: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks"): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Converte as células de intervalo com tipos de dados em texto.

convertDataTypeToText(): void;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Converte as células de intervalo em tipos de dados ligados na folha de cálculo.

convertToLinkedDataType(serviceID: number, languageCulture: string): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Copia dados de células ou formatação do intervalo de origem ou RangeAreas para o intervalo atual. O intervalo de destino pode ter um tamanho diferente do intervalo de origem ou RangeAreas. O destino é expandido automaticamente se for menor do que a origem. Nota: tal como a funcionalidade de cópia na IU do Excel, se o intervalo de destino for um múltiplo exato maior do que o intervalo de origem em linhas ou colunas, o conteúdo de origem é replicado várias vezes. Por exemplo, uma cópia de intervalo 2x2 para um intervalo 2x6 resultará em 3 cópias do intervalo 2x2 original.

copyFrom(sourceRange: Range | RangeAreas | string, copyType?: Excel.RangeCopyType, skipBlanks?: boolean, transpose?: boolean): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-copyfrom.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    // Place a label in front of the copied data.
    sheet.getRange("F2").values = [["Copied Formula"]];

    // Copy a range preserving the formulas.
    // Note: non-formula values are copied over as is.
    sheet.getRange("G2").copyFrom("A1:E1", Excel.RangeCopyType.formulas);
    await context.sync();
});

Copia dados de células ou formatação do intervalo de origem ou RangeAreas para o intervalo atual. O intervalo de destino pode ter um tamanho diferente do intervalo de origem ou RangeAreas. O destino é expandido automaticamente se for menor do que a origem. Nota: tal como a funcionalidade de cópia na IU do Excel, se o intervalo de destino for um múltiplo exato maior do que o intervalo de origem em linhas ou colunas, o conteúdo de origem é replicado várias vezes. Por exemplo, uma cópia de intervalo 2x2 para um intervalo 2x6 resultará em 3 cópias do intervalo 2x2 original.

copyFrom(sourceRange: Range | RangeAreas | string, copyTypeString?: "All" | "Formulas" | "Values" | "Formats" | "Link", skipBlanks?: boolean, transpose?: boolean): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exclui as células associadas ao intervalo.

delete(shift: Excel.DeleteShiftDirection): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D:F";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.delete("Left");
    await context.sync(); 
});

Exclui as células associadas ao intervalo.

delete(shiftString: "Up" | "Left"): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Localiza certa cadeia de caracteres com base em critérios especificados. Se o intervalo atual for maior do que uma única célula, a pesquisa será limitada a esse intervalo, caso contrário, a pesquisa cobrirá toda a folha a partir dessa célula.

find(text: string, criteria: Excel.SearchCriteria): Excel.Range;

Parâmetros

Retornos

O Range objeto que representa a primeira célula que contém um valor que corresponde ao texto e critérios de pesquisa.

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-find.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const table = sheet.tables.getItem("ExpensesTable");
    const searchRange = table.getRange();

    // NOTE: If no match is found, an ItemNotFound error
    // is thrown when Range.find is evaluated.
    const foundRange = searchRange.find($("#searchText").val().toString(), {
        completeMatch: isCompleteMatchToggle,
        matchCase: isMatchCaseToggle,
        searchDirection: searchDirectionToggle
    });
    
    foundRange.load("address");
    await context.sync();


    console.log(foundRange.address);
});

Localiza certa cadeia de caracteres com base em critérios especificados. Se o intervalo atual for maior do que uma única célula, a pesquisa será limitada a esse intervalo, caso contrário, a pesquisa cobrirá toda a folha a partir dessa célula. Se não existirem correspondências, este método devolve um objeto com a respetiva isNullObject propriedade definida como true. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

findOrNullObject(text: string, criteria: Excel.SearchCriteria): Excel.Range;

Parâmetros

Retornos

O Range que corresponde aos critérios de pesquisa.

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-find.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const table = sheet.tables.getItem("ExpensesTable");
    const searchRange = table.getRange();
    const foundRange = searchRange.findOrNullObject($("#searchText").val().toString(), {
        completeMatch: isCompleteMatchToggle,
        matchCase: isMatchCaseToggle,
        searchDirection: searchDirectionToggle
    });
    
    foundRange.load("address");
    await context.sync();

    if (foundRange.isNullObject) {
        console.log("Text not found");
    } else {
        console.log(foundRange.address);
    }
});

Efetua uma Pré-visualização da Conclusão Automática para o intervalo atual. A Pré-visualização da Conclusão Automática preenche automaticamente os dados quando detetar um padrão, pelo que o intervalo tem de ser um intervalo de colunas único e ter dados à sua volta para encontrar um padrão.

flashFill(): void;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Obtém um Range objeto com a mesma célula superior esquerda que o objeto atual Range , mas com os números especificados de linhas e colunas.

getAbsoluteResizedRange(numRows: number, numColumns: number): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

Obtém o menor objeto de intervalo que abrange os intervalos determinados. Por exemplo, " GetBoundingRect B2:C5" e "D10:E15" é "B2:E15".

getBoundingRect(anotherRange: Range | string): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D4:G6";
    let range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range = range.getBoundingRect("G4:H8");
    range.load('address');
    await context.sync();
    
    console.log(range.address); // Prints Sheet1!D4:H8
});

Obtém o objeto de intervalo que contém a célula única com base nos números de linha e de coluna. A célula pode estar fora dos limites do respetivo intervalo principal, desde que permaneça na grelha da folha de cálculo. A localização da célula retornada está relacionada à célula superior esquerda do intervalo.

getCell(row: number, column: number): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const range = worksheet.getRange(rangeAddress);
    const cell = range.getCell(0,0);
    cell.load('address');
    await context.sync();
    
    console.log(cell.address);
});

Retorna uma matriz 2D encapsulando os dados de fonte, preenchimento, bordas, alinhamento e outras propriedades de cada célula.

getCellProperties(cellPropertiesLoadOptions: CellPropertiesLoadOptions): OfficeExtension.ClientResult<CellProperties[][]>;

Parâmetros

Retornos

Uma matriz 2D em que cada item representa as propriedades pedidas da célula correspondente.

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/cell-properties.yaml

await Excel.run(async (context) => {
    const cell = context.workbook.getActiveCell();

    // Define the cell properties to get by setting the matching LoadOptions to true.
    const propertiesToGet = cell.getCellProperties({
        address: true,
        format: {
            fill: {
                color: true
            },
            font: {
                color: true
            }
        },
        style: true
    });

    // Sync to get the data from the workbook.
    await context.sync();
    const cellProperties = propertiesToGet.value[0][0];
    console.log(
        `Address: ${cellProperties.address}\nStyle: ${cellProperties.style}\nFill Color: ${cellProperties.format.fill.color}\nFont Color: ${cellProperties.format.font.color}`);
});

Obtém uma coluna incluída no intervalo.

getColumn(column: number): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet19";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getColumn(1);
    range.load('address');
    await context.sync();

    console.log(range.address); // prints Sheet1!B1:B8
});

Retorna uma única matriz dimensional encapsulando os dados de fonte, preenchimento, bordas, alinhamento e outras propriedades de cada coluna. Para propriedades que não são consistentes nas células de uma determinada coluna, será retornado null.

getColumnProperties(columnPropertiesLoadOptions: ColumnPropertiesLoadOptions): OfficeExtension.ClientResult<ColumnProperties[]>;

Parâmetros

Retornos

Uma matriz em que cada item representa as propriedades pedidas da coluna correspondente.

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Obtém um determinado número de colunas à direita do objeto atual Range .

getColumnsAfter(count?: number): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

Obtém um determinado número de colunas à esquerda do objeto atual Range .

getColumnsBefore(count?: number): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

Devolve um WorkbookRangeAreas objeto que representa o intervalo que contém todas as células dependentes diretas de um intervalo especificado na mesma folha de cálculo ou em várias folhas de cálculo. Nota: esta API devolve um ItemNotFound erro se não forem encontrados dependentes.

getDirectDependents(): Excel.WorkbookRangeAreas;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.13 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-direct-dependents.yaml

await Excel.run(async (context) => {
  // Direct dependents are cells that contain formulas that refer to other cells.
  let range = context.workbook.getActiveCell();
  let directDependents = range.getDirectDependents();
  range.load("address");
  directDependents.areas.load("address");
  await context.sync();
  
  console.log(`Direct dependent cells of ${range.address}:`);
  
  // Use the direct dependents API to loop through direct dependents of the active cell.
  for (let i = 0; i < directDependents.areas.items.length; i++) {
    // Highlight and print the address of each dependent cell.
    directDependents.areas.items[i].format.fill.color = "Yellow";
    console.log(`  ${directDependents.areas.items[i].address}`);
  }
  await context.sync();
});

Devolve um WorkbookRangeAreas objeto que representa o intervalo que contém todas as células precedentes diretas de um intervalo especificado na mesma folha de cálculo ou em várias folhas de cálculo. Nota: esta API devolve um ItemNotFound erro se não forem encontrados precedentes.

getDirectPrecedents(): Excel.WorkbookRangeAreas;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.12 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/precedents.yaml

await Excel.run(async (context) => {
  // Precedents are cells referenced by the formula in a cell.
  // A "direct precedent" is a cell directly referenced by the selected formula.
  let range = context.workbook.getActiveCell();
  let directPrecedents = range.getDirectPrecedents();
  range.load("address");
  directPrecedents.areas.load("address");
  await context.sync();

  console.log(`Direct precedent cells of ${range.address}:`);

  // Use the direct precedents API to loop through precedents of the active cell.
  for (let i = 0; i < directPrecedents.areas.items.length; i++) {
    // Highlight and console the address of each precedent cell.
    directPrecedents.areas.items[i].format.fill.color = "Yellow";
    console.log(`  ${directPrecedents.areas.items[i].address}`);
  }
  await context.sync();
});

Obtém um objeto que representa toda a coluna do intervalo (por exemplo, se o intervalo atual representar as células "B4:E11", getEntireColumn é um intervalo que representa as colunas "B:E").

getEntireColumn(): Excel.Range;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

// Note: the grid properties of the Range (values, numberFormat, formulas) 
// contains null since the Range in question is unbounded.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D:F";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    const rangeEC = range.getEntireColumn();
    rangeEC.load('address');
    await context.sync();
    
    console.log(rangeEC.address);
});

Obtém um objeto que representa toda a linha do intervalo (por exemplo, se o intervalo atual representar as células "B4:E11", GetEntireRow é um intervalo que representa as linhas "4:11").

getEntireRow(): Excel.Range;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

// Gets an object that represents the entire row of the range 
// (for example, if the current range represents cells "B4:E11", 
// its GetEntireRow is a range that represents rows "4:11").
await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "D:F"; 
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    const rangeER = range.getEntireRow();
    rangeER.load('address');
    await context.sync();
    
    console.log(rangeER.address);
});

Devolve um objeto de intervalo que inclui o intervalo atual e até à margem do intervalo, com base na direção fornecida. Isto corresponde ao comportamento de Ctrl+Shift+Tecla de Seta na IU do Excel no Windows.

getExtendedRange(direction: Excel.KeyboardDirection, activeCell?: Range | string): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.13 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-get-range-edge.yaml

await Excel.run(async (context) => {
  // Get the selected range.
  const range = context.workbook.getSelectedRange();

  // Specify the direction with the `KeyboardDirection` enum.
  const direction = Excel.KeyboardDirection.down;

  // Get the active cell in the workbook.
  const 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+Arrow key keyboard shortcut while a range is selected.
  const extendedRange = range.getExtendedRange(
    direction,
    activeCell // If the selected range contains more than one cell, the active cell must be defined.
  );
  extendedRange.select();

  await context.sync();
});

Devolve um objeto de intervalo que inclui o intervalo atual e até à margem do intervalo, com base na direção fornecida. Isto corresponde ao comportamento de Ctrl+Shift+Tecla de Seta na IU do Excel no Windows.

getExtendedRange(directionString: "Left" | "Right" | "Up" | "Down", activeCell?: Range | string): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.13 ]

Compõe o intervalo como uma imagem PNG codificada com Base64. Importante*: esta API não é atualmente suportada no Excel para Mac. Visite o Problema do OfficeDev/office-js n.º 235 da status atual.

getImage(): OfficeExtension.ClientResult<string>;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

Obtém o objeto de intervalo que representa a interseção retangular dos intervalos determinados.

getIntersection(anotherRange: Range | string): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = 
        context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getIntersection("D4:G6");
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!D4:F6
});

Obtém o objeto de intervalo que representa a interseção retangular dos intervalos determinados. Se não for encontrada nenhuma interseção, este método devolve um objeto com a respetiva isNullObject propriedade definida como true. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

getIntersectionOrNullObject(anotherRange: Range | string): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.4 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-relationships.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const salesTable = sheet.tables.getItem("SalesTable");
    const dataRange = salesTable.getDataBodyRange();

    // We want the most recent quarter that has data, so
    // exclude quarters without data and get the last of
    // the remaining columns.
    const usedDataRange = dataRange.getUsedRange(true /* valuesOnly */);
    const currentQuarterRange = usedDataRange.getLastColumn();

    // Asian and European teams have separate contests.
    const asianSalesRange = sheet.getRange("A2:E4");
    const europeanSalesRange = sheet.getRange("A5:E7");

    // The data for each chart is the intersection of the
    // current quarter column and the rows for the continent.
    const asianContestRange = asianSalesRange.getIntersectionOrNullObject(currentQuarterRange);
    const europeanContestRange = europeanSalesRange.getIntersectionOrNullObject(currentQuarterRange);

    // Must sync before you can test the output of *OrNullObject
    // method/property.
    await context.sync();

    if (asianContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("Asian");
    } else {
        createContinentChart(
            sheet,
            "Asian",
            asianContestRange,
            "A9",
            "F24"
        );
    }

    if (europeanContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("European");
    } else {
        createContinentChart(
            sheet,
            "European",
            europeanContestRange,
            "A25",
            "F40"
        );
    }

    await context.sync();
});

Obtém a última célula do intervalo. Por exemplo, a última célula de "B2:D5" é "D5".

getLastCell(): Excel.Range;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastCell();
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!F8
});

Obtém a última coluna do intervalo. Por exemplo, a última coluna de "B2:D5" é "D2:D5".

getLastColumn(): Excel.Range;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastColumn();
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!F1:F8
});

Obtém a última linha do intervalo. Por exemplo, a última linha de "B2:D5" é "B5:D5".

getLastRow(): Excel.Range;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastRow();
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!A8:F8
});

Devolve um RangeAreas objeto que representa as áreas unidas neste intervalo. Tenha em atenção que se a contagem de áreas unidas neste intervalo for superior a 512, este método não devolverá o resultado. Se o objeto não existir, esta função devolverá um objeto com a RangeAreas respetiva propriedade definida como true.isNullObject Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

getMergedAreasOrNullObject(): Excel.RangeAreas;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.13 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-merged-ranges.yaml

await Excel.run(async (context) => {
  // Retrieve the worksheet and the table in that worksheet.
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const tableRange = sheet.getRange("B2:E6");

  // Retrieve the merged range within the table and load its details.
  const mergedAreas = tableRange.getMergedAreasOrNullObject();
  mergedAreas.load("address");
  mergedAreas.load("cellCount");

  // Select the merged range.
  const range = mergedAreas.areas.getItemAt(0);
  range.select();
  await context.sync();

  // Print out the details of the `mergedAreas` range object.
  console.log(`Address of the merged range: ${mergedAreas.address}`);
  console.log(`Number of cells in the merged range: ${mergedAreas.cellCount}`);

  await context.sync();
});

Obtém um objeto que representa um intervalo deslocado do intervalo especificado. A dimensão do intervalo retornado corresponde a esse intervalo. Se o intervalo resultante for imposto para fora dos limites da grade da planilha, o sistema gerará um erro.

getOffsetRange(rowOffset: number, columnOffset: number): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D4:F6";
    const range = 
        context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getOffsetRange(-1,4);
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!H3:J5
});

Obtém uma coleção de tabelas dinâmicas no âmbito que se sobrepõem ao intervalo.

getPivotTables(fullyContained?: boolean): Excel.PivotTableScopedCollection;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.12 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/38-pivottable/pivottable-get-pivottables.yaml

await Excel.run(async (context) => {
  const activeRange = context.workbook.getSelectedRange();

  // Get all the PivotTables that intersect with this range.
  const partiallyContainedPivotTables = activeRange.getPivotTables();
  // Get all the PivotTables that are completely contained within this range.
  const fullyContainedPivotTables = activeRange.getPivotTables(true);

  partiallyContainedPivotTables.load("name");
  fullyContainedPivotTables.load("name");
  await context.sync();

  // Display the names in the console.
  console.log("PivotTables in the current range:")
  partiallyContainedPivotTables.items.forEach((pivotTable) => {
    console.log(`\t${pivotTable.name}`);
  });
  console.log("PivotTables completely contained in the current range:")
  fullyContainedPivotTables.items.forEach((pivotTable) => {
    console.log(`\t${pivotTable.name}`);
  });
});

Devolve um objeto de intervalo que é a célula de limite da região de dados que corresponde à direção fornecida. Isto corresponde ao comportamento da tecla Ctrl+Seta na IU do Excel no Windows.

getRangeEdge(direction: Excel.KeyboardDirection, activeCell?: Range | string): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.13 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-get-range-edge.yaml

await Excel.run(async (context) => {
  // Get the selected range.
  const range = context.workbook.getSelectedRange();

  // Specify the direction with the `KeyboardDirection` enum.
  const direction = Excel.KeyboardDirection.up;

  // Get the active cell in the workbook.
  const activeCell = context.workbook.getActiveCell();

  // Get the top-most cell of the current used range.
  // This method acts like the Ctrl+Arrow key keyboard shortcut while a range is selected.
  const rangeEdge = range.getRangeEdge(
    direction,
    activeCell // If the selected range contains more than one cell, the active cell must be defined.
  );
  rangeEdge.select();

  await context.sync();
});

Devolve um objeto de intervalo que é a célula de limite da região de dados que corresponde à direção fornecida. Isto corresponde ao comportamento da tecla Ctrl+Seta na IU do Excel no Windows.

getRangeEdge(directionString: "Left" | "Right" | "Up" | "Down", activeCell?: Range | string): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.13 ]

Obtém um Range objeto semelhante ao objeto atual Range , mas com o canto inferior direito expandido (ou contratado) por algumas linhas e colunas.

getResizedRange(deltaRows: number, deltaColumns: number): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

Obtém uma linha contida no intervalo.

getRow(row: number): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getRow(1);
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!A2:F2
});

Retorna uma única matriz dimensional encapsulando os dados de fonte, preenchimento, bordas, alinhamento e outras propriedades de cada célula. Para propriedades que não são consistentes em cada célula dentro de uma determinada linha, null serão devolvidas.

getRowProperties(rowPropertiesLoadOptions: RowPropertiesLoadOptions): OfficeExtension.ClientResult<RowProperties[]>;

Parâmetros

Retornos

Uma matriz em que cada item representa as propriedades pedidas da linha correspondente.

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Obtém um determinado número de linhas acima do objeto atual Range .

getRowsAbove(count?: number): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

Obtém um determinado número de linhas abaixo do objeto atual Range .

getRowsBelow(count?: number): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

Obtém o RangeAreas objeto, composto por um ou mais intervalos retangulares, que representa todas as células que correspondem ao tipo e valor especificados. Se não forem encontradas células especiais, será apresentado um ItemNotFound erro.

getSpecialCells(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-areas.yaml

await Excel.run(async (context) => {

    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const usedRange = sheet.getUsedRange();

    // Find the ranges with either text or logical (boolean) values.
    const formulaRanges = usedRange.getSpecialCells("Constants", "LogicalText");
    formulaRanges.format.fill.color = "orange";

    return context.sync();
});

Obtém o RangeAreas objeto, composto por um ou mais intervalos retangulares, que representa todas as células que correspondem ao tipo e valor especificados. Se não forem encontradas células especiais, será apresentado um ItemNotFound erro.

getSpecialCells(cellTypeString: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible", cellValueTypeString?: "All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"): Excel.RangeAreas;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Obtém o RangeAreas objeto, composto por um ou mais intervalos, que representa todas as células que correspondem ao tipo e valor especificados. Se não forem encontradas células especiais, este método devolve um objeto com a respetiva isNullObject propriedade definida como true. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

getSpecialCellsOrNullObject(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Obtém o RangeAreas objeto, composto por um ou mais intervalos, que representa todas as células que correspondem ao tipo e valor especificados. Se não forem encontradas células especiais, este método devolve um objeto com a respetiva isNullObject propriedade definida como true. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

getSpecialCellsOrNullObject(cellTypeString: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible", cellValueTypeString?: "All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"): Excel.RangeAreas;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Obtém objeto range que contém o intervalo de despejo quando chamado em uma célula âncora. Falha se aplicado a um intervalo com mais de uma célula.

getSpillingToRange(): Excel.Range;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.12 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/dynamic-arrays.yaml

await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getItem("Sample");

  // Set G4 to a formula that returns a dynamic array.
  const targetCell = sheet.getRange("G4");
  targetCell.formulas = [["=A4:D4"]];

  // Get the address of the cells that the dynamic array spilled into.
  const spillRange = targetCell.getSpillingToRange();
  spillRange.load("address");

  // Fit the columns for readability.
  sheet.getUsedRange().format.autofitColumns();
  await context.sync();

  console.log(`Copying the table headers spilled into ${spillRange.address}.`);
});

Obtém objeto range que contém o intervalo de despejo quando chamado em uma célula âncora. Se o intervalo não for uma célula de âncora ou não for possível localizar o intervalo de derrames, este método devolve um objeto com a respetiva isNullObject propriedade definida como true. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

getSpillingToRangeOrNullObject(): Excel.Range;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.12 ]

Obtém o objeto range que contém a célula âncora para uma célula que recebe o despejo. Falha se aplicado a um intervalo com mais de uma célula.

getSpillParent(): Excel.Range;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.12 ]

Obtém o objeto de intervalo que contém a célula de âncora para a célula a ser transbordada. Se não for uma célula transbordada ou se for fornecida mais do que uma célula, este método devolve um objeto com a respetiva isNullObject propriedade definida como true. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

getSpillParentOrNullObject(): Excel.Range;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.12 ]

Devolve um Range objeto que representa a região circundante para a célula superior esquerda neste intervalo. Uma região ao redor é um intervalo limitado por qualquer combinação de linhas e colunas em branco em relação a esse intervalo.

getSurroundingRegion(): Excel.Range;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

Obtém uma coleção de tabelas com escopo que se sobrepõe ao intervalo.

getTables(fullyContained?: boolean): Excel.TableScopedCollection;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Retorna o intervalo usado do objeto de intervalo determinado. Se não existirem células utilizadas dentro do intervalo, esta função gerará um ItemNotFound erro.

getUsedRange(valuesOnly?: boolean): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-relationships.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const salesTable = sheet.tables.getItem("SalesTable");
    const dataRange = salesTable.getDataBodyRange();

    // We want the most recent quarter that has data, so
    // exclude quarters without data and get the last of
    // the remaining columns.
    const usedDataRange = dataRange.getUsedRange(true /* valuesOnly */);
    const currentQuarterRange = usedDataRange.getLastColumn();

    // Asian and European teams have separate contests.
    const asianSalesRange = sheet.getRange("A2:E4");
    const europeanSalesRange = sheet.getRange("A5:E7");

    // The data for each chart is the intersection of the
    // current quarter column and the rows for the continent.
    const asianContestRange = asianSalesRange.getIntersectionOrNullObject(currentQuarterRange);
    const europeanContestRange = europeanSalesRange.getIntersectionOrNullObject(currentQuarterRange);

    // Must sync before you can test the output of *OrNullObject
    // method/property.
    await context.sync();

    if (asianContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("Asian");
    } else {
        createContinentChart(
            sheet,
            "Asian",
            asianContestRange,
            "A9",
            "F24"
        );
    }

    if (europeanContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("European");
    } else {
        createContinentChart(
            sheet,
            "European",
            europeanContestRange,
            "A25",
            "F40"
        );
    }

    await context.sync();
});

Retorna o intervalo usado do objeto de intervalo determinado. Se não existirem células utilizadas dentro do intervalo, este método devolve um objeto com a respetiva isNullObject propriedade definida como true. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

getUsedRangeOrNullObject(valuesOnly?: boolean): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.4 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/used-range.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const salesTable = sheet.tables.getItem("SalesTable");
    const dataRange = salesTable.getDataBodyRange();

    // Pass true so only cells with values count as used
    const usedDataRange = dataRange.getUsedRangeOrNullObject(
        true /* valuesOnly */
    );

    //Must sync before reading value returned from *OrNullObject method/property.
    await context.sync();

    if (usedDataRange.isNullObject) {
        console.log("Need Data to Make Chart");
        console.log("To create a meaningful chart, press 'Fill the table' (or add names to the Product column and numbers to some of the other cells). Then press 'Try to create chart' again.");
    } else {
        const chart = sheet.charts.add(
            Excel.ChartType.columnClustered,
            dataRange,
            "Columns"
        );
        chart.setPosition("A15", "F30");
        chart.title.text = "Quarterly sales chart";
        chart.legend.position = "Right";
        chart.legend.format.fill.setSolidColor("white");
        chart.dataLabels.format.font.size = 15;
        chart.dataLabels.format.font.color = "black";
    }

    await context.sync();
});

Representa as linhas visíveis do intervalo atual.

getVisibleView(): Excel.RangeView;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.3 ]

Grupos colunas e linhas para um destaque.

group(groupOption: Excel.GroupOption): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/outline.yaml

Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    
    // Group the larger, main level. Note that the outline controls
    // will be on row 10, meaning 4-9 will collapse and expand.
    sheet.getRange("4:9").group(Excel.GroupOption.byRows);

    // Group the smaller, sublevels. Note that the outline controls
    // will be on rows 6 and 9, meaning 4-5 and 7-8 will collapse and expand.
    sheet.getRange("4:5").group(Excel.GroupOption.byRows);
    sheet.getRange("7:8").group(Excel.GroupOption.byRows);
    await context.sync();
});

Grupos colunas e linhas para um destaque.

group(groupOptionString: "ByRows" | "ByColumns"): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

Oculta os detalhes do grupo de linhas ou colunas.

hideGroupDetails(groupOption: Excel.GroupOption): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

Oculta os detalhes do grupo de linhas ou colunas.

hideGroupDetails(groupOptionString: "ByRows" | "ByColumns"): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

Insere uma célula ou um intervalo de células na planilha, no lugar desse intervalo, e desloca as outras células para liberar espaço. Devolve um novo Range objeto no espaço em branco agora.

insert(shift: Excel.InsertShiftDirection): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "F5:F10";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.insert(Excel.InsertShiftDirection.down);
    await context.sync();
});

Insere uma célula ou um intervalo de células na planilha, no lugar desse intervalo, e desloca as outras células para liberar espaço. Devolve um novo Range objeto no espaço em branco agora.

insert(shiftString: "Down" | "Right"): Excel.Range;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(options?: Excel.Interfaces.RangeLoadOptions): Excel.Range;

Parâmetros

Retornos

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(propertyNames?: string | string[]): Excel.Range;

Parâmetros

Retornos

Exemplos

// Use the range address to get the range object.
await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8"; 
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const range = worksheet.getRange(rangeAddress);
    range.load('cellCount');
    await context.sync();
    
    console.log(range.cellCount);
});

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.Range;

Parâmetros

Retornos

Mescla as células do intervalo em uma região da planilha.

merge(across?: boolean): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:C3";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.merge(true);
    await context.sync(); 
});

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-merged-ranges.yaml

await Excel.run(async (context) => {
  // Retrieve the worksheet and the table in that worksheet.
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const tableRange = sheet.getRange("B2:E6");

  // Create a merged range in the first row of the table.
  const chartTitle = tableRange.getRow(0);
  chartTitle.merge(true);

  // Format the merged range.
  chartTitle.format.horizontalAlignment = "Center";

  await context.sync();
});

Move valores de células, formatação e fórmulas do intervalo atual para o intervalo de destino, substituindo as informações antigas nessas células. O intervalo de destino será expandido automaticamente se for menor do que o intervalo atual. As células no intervalo de destino que estejam fora da área do intervalo original não são alteradas.

moveTo(destinationRange: Range | string): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.11 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-copyfrom.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    // Place a label in front of the moved data.
    sheet.getRange("F12").values = [["Moved Range:"]];

    // Move the range from A1:E1 to G12:K12.
    sheet.getRange("A1:E1").moveTo("G12");
    await context.sync();
});

Remove valores duplicados do intervalo especificado pelas colunas.

removeDuplicates(columns: number[], includesHeader: boolean): Excel.RemoveDuplicatesResult;

Parâmetros

Retornos

O objeto resultante que contém o número de linhas removidas e o número de linhas exclusivas restantes.

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-remove-duplicates.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getRange("B2:D11");

    const deleteResult = range.removeDuplicates([0],true);    
    deleteResult.load();    
    await context.sync();

    console.log(deleteResult.removed + " entries with duplicate names removed.");
    console.log(deleteResult.uniqueRemaining + " entries with unique names remain in the range.");
});

Localiza e substitui a cadeia de caracteres fornecida com base nos critérios especificados no intervalo atual.

replaceAll(text: string, replacement: string, criteria: Excel.ReplaceCriteria): OfficeExtension.ClientResult<number>;

Parâmetros

Retornos

O número de substituições efetuadas.

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Seleciona o intervalo especificado na interface do usuário do Excel.

select(): void;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "F5:F10"; 
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.select();
    await context.sync(); 
});

Define várias propriedades de um objeto ao mesmo tempo. Pode transmitir um objeto simples com as propriedades adequadas ou outro objeto de API do mesmo tipo.

set(properties: Interfaces.RangeUpdateData, options?: OfficeExtension.UpdateOptions): void;

Parâmetros

Retornos

Define várias propriedades no objeto ao mesmo tempo, com base num objeto carregado existente.

set(properties: Excel.Range): void;

Parâmetros

Retornos

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/90-scenarios/multiple-property-set.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");

    const sourceRange = sheet.getRange("B2:E2");
    sourceRange.load("format/fill/color, format/font/name, format/font/color");
    await context.sync();

    // Set properties based on the loaded and synced 
    // source range.
    const targetRange = sheet.getRange("B7:E7");
    targetRange.set(sourceRange); 
    targetRange.format.autofitColumns();
    await context.sync();
});

Atualizações o intervalo com base numa matriz 2D de propriedades de células, encapsulando elementos como tipo de letra, preenchimento, limites e alinhamento.

setCellProperties(cellPropertiesData: SettableCellProperties[][]): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/cell-properties.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();

    // Creating the SettableCellProperties objects to use for the range.
    // In your add-in, these should be created once, outside the function.
    const topHeaderProps: Excel.SettableCellProperties = {
        // The style property takes a string matching the name of an Excel style.
        // Built-in style names are listed in the `BuiltInStyle` enum.
        // Note that a style will overwrite any formatting,
        // so do not use the format property with the style property.
        style: "Heading1"
    };

    const headerProps: Excel.SettableCellProperties = {
        // Any subproperties of format that are not set will not be changed when these cell properties are set.
        format: {
            fill: {
                color: "Blue"
            },
            font: {
                color: "White",
                bold: true
            }
        }
    };

    const nonApplicableProps: Excel.SettableCellProperties = {
        format: {
            fill: {
                pattern: Excel.FillPattern.gray25
            },
            font: {
                color: "Gray",
                italic: true
            }
        }
    };

    const matchupScoreProps: Excel.SettableCellProperties = {
        format: {
            borders: {
                bottom: {
                    style: Excel.BorderLineStyle.continuous
                },
                left: {
                    style: Excel.BorderLineStyle.continuous
                },
                right: {
                    style: Excel.BorderLineStyle.continuous
                },
                top: {
                    style: Excel.BorderLineStyle.continuous
                }
            }
        }
    };

    const range = sheet.getRange("A1:E5");

    // You can use empty JSON objects to avoid changing a cell's properties.
    range.setCellProperties([
        [topHeaderProps, {}, {}, {}, {}],
        [{}, {}, headerProps, headerProps, headerProps],
        [{}, headerProps, nonApplicableProps, matchupScoreProps, matchupScoreProps],
        [{}, headerProps, matchupScoreProps, nonApplicableProps, matchupScoreProps],
        [{}, headerProps, matchupScoreProps, matchupScoreProps, nonApplicableProps]
    ]);

    sheet.getUsedRange().format.autofitColumns();
    await context.sync();
});

Atualizações o intervalo com base numa matriz unidimensional de propriedades de coluna, encapsulando elementos como tipo de letra, preenchimento, limites e alinhamento.

setColumnProperties(columnPropertiesData: SettableColumnProperties[]): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Define um intervalo a ser recalculado quando o próximo recálculo ocorrer.

setDirty(): void;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Atualizações o intervalo com base numa matriz unidimensional de propriedades de linha, encapsulando elementos como tipo de letra, preenchimento, limites e alinhamento.

setRowProperties(rowPropertiesData: SettableRowProperties[]): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exibe o cartão para uma célula ativa se ele tiver um conteúdo valioso.

showCard(): void;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

Mostra os detalhes do grupo de linhas ou colunas.

showGroupDetails(groupOption: Excel.GroupOption): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

Mostra os detalhes do grupo de linhas ou colunas.

showGroupDetails(groupOptionString: "ByRows" | "ByColumns"): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é transmitido para JSON.stringify(). (JSON.stringifypor sua vez, chama o toJSON método do objeto que lhe é transmitido.) Enquanto o objeto original Excel.Range é um objeto de API, o toJSON método devolve um objeto JavaScript simples (escrito como Excel.Interfaces.RangeData) que contém cópias rasas de quaisquer propriedades subordinadas carregadas do objeto original.

toJSON(): Excel.Interfaces.RangeData;

Retornos

Acompanha o objeto para ajuste automático com base nas alterações adjacentes no documento. Esta chamada é uma abreviatura de context.trackedObjects.add(thisObject). Se estiver a utilizar este objeto entre .sync chamadas e fora da execução sequencial de um lote ".run" e receber um erro "InvalidObjectPath" ao definir uma propriedade ou invocar um método no objeto, terá de adicionar o objeto à coleção de objetos controlados quando o objeto foi criado pela primeira vez.

track(): Excel.Range;

Retornos

Desagrupar colunas e linhas para um destaque.

ungroup(groupOption: Excel.GroupOption): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/outline.yaml

Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    
    // This removes two levels of groups from the "A1-R10" range.
    // Any groups at the same level on the same dimension will be removed by a single call.
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byRows);
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byRows);
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byColumns);
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byColumns);
    await context.sync();
});

Desagrupar colunas e linhas para um destaque.

ungroup(groupOptionString: "ByRows" | "ByColumns"): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

Desfaz a mesclagem das células do intervalo em células separadas.

unmerge(): void;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

Exemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:C3";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.unmerge();
    await context.sync(); 
});

Libere a memória associada a este objeto, se ele já tiver sido rastreado anteriormente. Esta chamada é abreviada para context.trackedObjects.remove(thisObject). Ter muitos objetos rastreados desacelera o aplicativo host, por isso, lembre-se de liberar todos os objetos adicionados após usá-los. Terá de chamar context.sync() antes de a libertação da memória ser aplicada.

untrack(): Excel.Range;

Retornos

Exemplos

await Excel.run(async (context) => {
    const largeRange = context.workbook.getSelectedRange();
    largeRange.load(["rowCount", "columnCount"]);
    await context.sync();

    for (let i = 0; i < largeRange.rowCount; i++) {
        for (let j = 0; j < largeRange.columnCount; j++) {
            const cell = largeRange.getCell(i, j);
            cell.values = [[i *j]];

            // Call untrack() to release the range from memory.
            cell.untrack();
        }
    }

    await context.sync();
});