Excel.Worksheet class

Retorna uma coleção de gráficos que fazem parte da planilha.

readonly charts: Excel.ChartCollection;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/10-chart/chart-create-several-charts.yaml

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

  let dataRange = sheet.getRange("A1:E7");

  // Create an XY scatter chart.
  let chart = sheet.charts.add(Excel.ChartType.xyscatter, dataRange, "Auto");
  chart.title.text = "Bicycle Parts Quarterly Sales";
  chart.setPosition("A36", "F48");

  await context.sync();
});

O contexto de solicitação associado ao objeto. Isso conecta o processo do suplemento ao processo do aplicativo host do Office.

context: RequestContext;

Valor da propriedade

Obtém um objeto que pode ser usado para manipular painéis congelados na planilha.

readonly freezePanes: Excel.WorksheetFreezePanes;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.7

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-freeze-panes.yaml

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

    await context.sync();
});

Retorna um valor que identifica de forma exclusiva a planilha em uma determinada pasta de trabalho. O valor do identificador permanece o mesmo, ainda que a planilha seja renomeada ou movida.

readonly id: string;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

O nome de exibição da planilha. O nome deve ter menos de 32 caracteres.

name: string;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/add-delete-rename-move-worksheet.yaml

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

    currentSheet.name = await uniqueWorksheetName(context);

    await context.sync();
    console.log(`Renamed worksheet to "${currentSheet.name}"`);
});

Coleção de nomes com escopo para a planilha atual.

readonly names: Excel.NamedItemCollection;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.4

Coleção de Tabelas Dinâmicas que fazem parte da planilha.

readonly pivotTables: Excel.PivotTableCollection;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.3

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) => {
  // Get the names of all the PivotTables in the current worksheet.
  const pivotTables = context.workbook.worksheets.getActiveWorksheet().pivotTables;
  pivotTables.load("name");
  await context.sync();

  // Display the names in the console.
  console.log("PivotTables in the current worksheet:")
  pivotTables.items.forEach((pivotTable) => {
    console.log(`\t${pivotTable.name}`);
  });
});

A posição baseada em zero da planilha na pasta de trabalho.

position: number;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

Exemplos

// Set worksheet position.
await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.position = 2;
    await context.sync(); 
});

Retorna o objeto de proteção da planilha para uma planilha.

readonly protection: Excel.WorksheetProtection;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.2

Exemplos

// Unprotecting a worksheet with unprotect() will remove all 
// WorksheetProtectionOptions options applied to a worksheet.
// To remove only a subset of WorksheetProtectionOptions use the 
// protect() method and set the options you wish to remove to true.
await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getItem("Sheet1");
  sheet.protection.protect({
    allowInsertRows: false, // Protect row insertion
    allowDeleteRows: true // Unprotect row deletion
  });
});

Retorna a altura padrão de todas as linhas na planilha, em pontos.

readonly standardHeight: number;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.7

Especifica a largura padrão (padrão) de todas as colunas na planilha. Uma unidade de largura de coluna equivale à largura de um caractere no estilo Normal. Para fontes proporcionais, será usada a largura do caractere 0 (zero).

standardWidth: number;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.7

A cor da guia da planilha. Ao recuperar a cor da guia, se a planilha estiver invisível, o valor será null. Se a planilha estiver visível, mas a cor da guia estiver definida como automática, uma cadeia de caracteres vazia será retornada. Caso contrário, a propriedade será definida como uma cor no formato #RRGGBB (por exemplo, "FFA500"). Ao definir a cor, use uma string vazia para definir uma cor "automática" ou uma cor real caso contrário.

tabColor: string;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.7

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/tab-color.yaml

await Excel.run(async (context) => {
    const activeSheet = context.workbook.worksheets.getActiveWorksheet();
    activeSheet.tabColor = "#FF0000";

    await context.sync();
});

Coleção de tabelas que fazem parte da planilha.

readonly tables: Excel.TableCollection;

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1

A visibilidade da planilha.

visibility: Excel.SheetVisibility | "Visible" | "Hidden" | "VeryHidden";

Valor da propriedade

Comentários

Conjunto de APIs: ExcelApi 1.1 para visibilidade de leitura; 1.2 para configurá-lo.

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-visibility.yaml

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

    // Load the visibility property so it can be read after context.sync().
    sheet.load("name, visibility");

    await context.sync();

    console.log(`The visibility of worksheet "${sheet.name}" is ${sheet.visibility}.`);
});

Ative a planilha na interface do usuário do Excel.

activate(): void;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.1

Exemplos

await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.activate();
    await context.sync(); 
});

Calcula todas as células em uma planilha.

calculate(markAllDirty: boolean): void;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.6

Copia uma planilha e a coloca na posição especificada.

copy(positionType?: Excel.WorksheetPositionType, relativeTo?: Excel.Worksheet): Excel.Worksheet;

Parâmetros

Retornos

A planilha recém-criada.

Comentários

Conjunto de APIs: ExcelApi 1.7

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-copy.yaml

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

    let myWorkbook = context.workbook;
    let sampleSheet = myWorkbook.worksheets.getActiveWorksheet();
    let copiedSheet = sampleSheet.copy("End")

    sampleSheet.load("name");
    copiedSheet.load("name");

    await context.sync();

    console.log("'" + sampleSheet.name + "' was copied to '" + copiedSheet.name + "'")
});

Copia uma planilha e a coloca na posição especificada.

copy(positionType?: "None" | "Before" | "After" | "Beginning" | "End", relativeTo?: Excel.Worksheet): Excel.Worksheet;

Parâmetros

Retornos

A planilha recém-criada.

Comentários

Conjunto de APIs: ExcelApi 1.7

Exclui a planilha da pasta de trabalho. Observe que se a visibilidade da planilha for definida como "VeryHidden", a operação de exclusão falhará com uma InvalidOperation exceção. Primeiro, você deve alterar sua visibilidade para oculto ou visível antes de excluí-lo.

delete(): void;

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.1

Exemplos

await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.delete();
    await context.sync(); 
});

Obtém o Range objeto que contém a única célula com base em números de linha e coluna. A célula pode estar fora dos limites de seu intervalo pai, desde que permaneça dentro da grade da planilha.

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.1

Exemplos

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

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

Obtém a planilha seguinte a esta. Se não houver planilhas após esta, esse método gerará um erro.

getNext(visibleOnly?: boolean): Excel.Worksheet;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.5

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/reference-worksheets-by-relative-position.yaml

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

    // We don't want to include the default worksheet that was created
    // when the workbook was created, so our "firstSheet" will be the one
    // after the literal first. Note chaining of navigation methods.
    const firstSheet = sheets.getFirst().getNext();
    const lastSheet = sheets.getLast();
    const firstTaxRateRange = firstSheet.getRange("B2");
    const lastTaxRateRange = lastSheet.getRange("B2");

    firstSheet.load("name");
    lastSheet.load("name");
    firstTaxRateRange.load("text");
    lastTaxRateRange.load("text");

    await context.sync();

    let firstYear = firstSheet.name.substr(5, 4);
    let lastYear = lastSheet.name.substr(5, 4);
    console.log(`Tax Rate change from ${firstYear} to ${lastYear}`, `Tax rate for ${firstYear}: ${firstTaxRateRange.text[0][0]}\nTax rate for ${lastYear}: ${lastTaxRateRange.text[0][0]}`)

    await context.sync();
});

Obtém a planilha seguinte a esta. Se não houver planilhas após esta, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte métodos e propriedades *OrNullObject.

getNextOrNullObject(visibleOnly?: boolean): Excel.Worksheet;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.5

Obtém a planilha que antecede esta. Se não houver planilhas anteriores, esse método gerará um erro.

getPrevious(visibleOnly?: boolean): Excel.Worksheet;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.5

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/reference-worksheets-by-relative-position.yaml

await Excel.run(async (context) => {
    const sheets = context.workbook.worksheets;
    const currentSheet = sheets.getActiveWorksheet();
    const previousYearSheet = currentSheet.getPrevious();
    const currentTaxDueRange = currentSheet.getRange("C2");
    const previousTaxDueRange = previousYearSheet.getRange("C2");

    currentSheet.load("name");
    previousYearSheet.load("name");
    currentTaxDueRange.load("text");
    previousTaxDueRange.load("text");

    await context.sync();

    let currentYear = currentSheet.name.substr(5, 4);
    let previousYear = previousYearSheet.name.substr(5, 4);
    console.log("Two Year Tax Due Comparison", `Tax due for ${currentYear} was ${currentTaxDueRange.text[0][0]}\nTax due for ${previousYear} was ${previousTaxDueRange.text[0][0]}`)

    await context.sync();
});

Obtém a planilha que antecede esta. Se não houver planilhas anteriores, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte métodos e propriedades *OrNullObject.

getPreviousOrNullObject(visibleOnly?: boolean): Excel.Worksheet;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.5

Obtém o Range objeto, representando um único bloco retangular de células, especificado pelo endereço ou nome.

getRange(address?: string): Excel.Range;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.1

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);
});

Faz com que o Range objeto comece em um determinado índice de linha e índice de coluna, e abrangendo um determinado número de linhas e colunas.

getRangeByIndexes(startRow: number, startColumn: number, rowCount: number, columnCount: number): Excel.Range;

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.7

O intervalo usado é o menor intervalo que abrange todas as células que têm um valor ou uma formatação atribuída a elas. Se toda a planilha estiver em branco, esta função retornará a célula superior esquerda (ou seja, não gerará um erro).

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.1

Exemplos

await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    const usedRange = worksheet.getUsedRange();
    usedRange.load('address');
    await context.sync();
    
    console.log(usedRange.address);
});

O intervalo usado é o menor intervalo que abrange todas as células que têm um valor ou uma formatação atribuída a elas. Se toda a planilha estiver em branco, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte métodos e propriedades *OrNullObject.

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

Parâmetros

Retornos

Comentários

Conjunto de APIs: ExcelApi 1.4

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.WorksheetLoadOptions): Excel.Worksheet;

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.Worksheet;

Parâmetros

Retornos

Exemplos

// Get worksheet properties based on sheet name.
await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.load('position')
    await context.sync();
    
    console.log(worksheet.position);
});

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.Worksheet;

Parâmetros

Retornos

Define várias propriedades de um objeto ao mesmo tempo. Você pode passar um objeto simples com as propriedades apropriadas ou outro objeto de API do mesmo tipo.

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

Parâmetros

Retornos

Exemplos

// Set the color and name of the current worksheet.
await Excel.run(async (context) => {
  const activeSheet = context.workbook.worksheets.getActiveWorksheet();
  activeSheet.set({
    tabColor: "yellow",
    name: "MySheet"
  });

  await context.sync();
});

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

set(properties: Excel.Worksheet): void;

Parâmetros

Retornos

Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é passado para JSON.stringify(). (JSON.stringify, por sua vez, chama o toJSON método do objeto que é passado para ele.) Enquanto o objeto original Excel.Worksheet é um objeto de API, o toJSON método retorna um objeto JavaScript simples (digitado como Excel.Interfaces.WorksheetData) que contém cópias superficiais de todas as propriedades filho carregadas do objeto original.

toJSON(): Excel.Interfaces.WorksheetData;

Retornos

Ocorre quando a planilha é ativada.

readonly onActivated: OfficeExtension.EventHandlers<Excel.WorksheetActivatedEventArgs>;

Tipo de Evento

Comentários

Conjunto de APIs: ExcelApi 1.7

Exemplos

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    sheet.onActivated.add(function (event) {
        return Excel.run(async (context) => {
            console.log("The activated worksheet ID is: " + event.worksheetId);
            await context.sync();
        });
    });
    await context.sync();
});

Ocorre quando os dados são alterados em uma planilha específica.

readonly onChanged: OfficeExtension.EventHandlers<Excel.WorksheetChangedEventArgs>;

Tipo de Evento

Comentários

Conjunto de APIs: ExcelApi 1.7

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-worksheet.yaml

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("Sample");
    sheet.onChanged.add(onChange);
    await context.sync();

    console.log("Added a worksheet-level data-changed event handler.");
});

Ocorre quando a planilha é desativada.

readonly onDeactivated: OfficeExtension.EventHandlers<Excel.WorksheetDeactivatedEventArgs>;

Tipo de Evento

Comentários

Conjunto de APIs: ExcelApi 1.7

Exemplos

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    sheet.onDeactivated.add(function (event) {
        return Excel.run(async (context) => {
            console.log("The deactivated worksheet is: " + event.worksheetId);
            await context.sync();
        });
    });
    await context.sync();
});

Ocorre quando a seleção é alterada em uma planilha específica.

readonly onSelectionChanged: OfficeExtension.EventHandlers<Excel.WorksheetSelectionChangedEventArgs>;

Tipo de Evento

Comentários

Conjunto de APIs: ExcelApi 1.7

Exemplos

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    sheet.onSelectionChanged.add(function (event) {
        return Excel.run(async (context) => {
            console.log("The selected range has changed to: " + event.address);
            await context.sync();
        });
    });
    await context.sync();
});