Excel.Worksheet class

Representa o AutoFilter objeto da folha de cálculo.

readonly autoFilter: Excel.AutoFilter;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

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

// This function adds a percentage AutoFilter to the active worksheet 
// and applies the filter to a column of the used range.
await Excel.run(async (context) => {
    // Retrieve the active worksheet and the used range on that worksheet.
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const farmData = sheet.getUsedRange();

    // Add a filter that will only show the rows with the top 50% of values in column 3.
    sheet.autoFilter.apply(farmData, 3, {
        criterion1: "50",
        filterOn: Excel.FilterOn.topPercent
    });

    await context.sync();
});

Devolve uma coleção de gráficos que fazem parte da folha de cálculo.

readonly charts: Excel.ChartCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Retorna um conjunto de todos os objetos Comments na planilha.

readonly comments: Excel.CommentCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

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

Obtém uma coleção de propriedades personalizadas ao nível da folha de cálculo.

readonly customProperties: Excel.WorksheetCustomPropertyCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.12 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/26-document/custom-properties.yaml

await Excel.run(async (context) => {
  // Load the keys and values of all custom properties in the current worksheet.
  const customWorksheetProperties = context.workbook.worksheets.getActiveWorksheet().customProperties;
  customWorksheetProperties.load(["key", "value"]);
  await context.sync();

  // Log each custom property to the console.
  // Note that your document may have more properties than those you have set using this snippet.
  customWorksheetProperties.items.forEach((property) => {
    console.log(`${property.key}:${property.value}`);
  });
});

Determina se o Excel deve recalcular a folha de cálculo quando necessário. Verdadeiro se o Excel recalcular a folha de cálculo quando necessário. False se o Excel não recalcular a planilha.

enableCalculation: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Obtém um objeto que pode ser utilizado para manipular painéis congelados na folha de cálculo.

readonly freezePanes: Excel.WorksheetFreezePanes;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

Obtém a coleção de quebra de página horizontal da planilha. Esta coleção contém apenas quebras de página manuais.

readonly horizontalPageBreaks: Excel.PageBreakCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

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 API: ExcelApi 1.1 ]

O nome de exibição da planilha. O nome tem de ter menos de 32 carateres.

name: string;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

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

readonly names: Excel.NamedItemCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.4 ]

Obtém o PageLayout objeto da folha de cálculo.

readonly pageLayout: Excel.PageLayout;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

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

readonly pivotTables: Excel.PivotTableCollection;

Valor da propriedade

Comentários

[ Conjunto de API: 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 API: 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(); 
});

Devolve o objeto de proteção de folha para uma folha de cálculo.

readonly protection: Excel.WorksheetProtection;

Valor da propriedade

Comentários

[ Conjunto de API: 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 coleção de todos os objetos Shape na planilha.

readonly shapes: Excel.ShapeCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Especifica se as linhas de grelha estão visíveis para o utilizador.

showGridlines: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.8 ]

Exemplos

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

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

    await context.sync();
});

Especifica se os cabeçalhos estão visíveis para o utilizador.

showHeadings: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.8 ]

Devolve uma coleção de segmentações de dados que fazem parte da folha de cálculo.

readonly slicers: Excel.SlicerCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

Exemplos

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Pivot");
    const slicer = sheet.slicers.add(
        "Farm Sales", /* The slicer data source. For PivotTables, this can be the PivotTable object reference or name. */
        "Type" /* The field in the data source to filter by. For PivotTables, this can be a PivotField object reference or ID. */
    );
    slicer.name = "Fruit Slicer";
    await context.sync();
});

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

readonly standardHeight: number;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

Especifica a largura padrão (predefinida) de todas as colunas na folha de cálculo. 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 API: ExcelApi 1.7 ]

A cor do separador da folha de cálculo. Ao obter a cor do separador, se a folha de cálculo for invisível, o valor será null. Se a folha de cálculo estiver visível, mas a cor do separador estiver definida como automática, será devolvida uma cadeia vazia. Caso contrário, a propriedade será definida como uma cor, no formato #RRGGBB (por exemplo, "FFA500"). Ao definir a cor, utilize uma cadeia vazia para definir uma cor "automática" ou uma cor real.

tabColor: 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/54-worksheet/tab-color.yaml

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

    await context.sync();
});

Devolve um valor que representa esta folha de cálculo que pode ser lida por Open Office XML. Trata-se de um valor inteiro, diferente de worksheet.id (que devolve um identificador exclusivo global) e worksheet.name (que devolve um valor como "Folha1").

readonly tabId: number;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.14 ]

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

readonly tables: Excel.TableCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Obtém a coleção de quebra de página vertical da planilha. Esta coleção contém apenas quebras de página manuais.

readonly verticalPageBreaks: Excel.PageBreakCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

A visibilidade da planilha.

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

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 para visibilidade de leitura; 1.2 para defini-lo. ]

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

activate(): void;

Retornos

Comentários

[ Conjunto de API: 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 API: ExcelApi 1.6 ]

Copia uma folha de cálculo e coloca-a na posição especificada.

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

Parâmetros

Retornos

A folha de cálculo recém-criada.

Comentários

[ Conjunto de API: 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 folha de cálculo e coloca-a na posição especificada.

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

Parâmetros

Retornos

A folha de cálculo recém-criada.

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

Exclui a planilha da pasta de trabalho. Tenha em atenção que se a visibilidade da folha de cálculo estiver definida como "VeryHidden", a operação de eliminação falhará com uma exceção InvalidOperation . Primeiro, deve alterar a visibilidade para oculta ou visível antes de a eliminar.

delete(): void;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

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

Localiza todas as ocorrências da cadeia especificada com base nos critérios especificados e devolve-as como um RangeAreas objeto, composto por um ou mais intervalos retangulares.

findAll(text: string, criteria: Excel.WorksheetSearchCriteria): Excel.RangeAreas;

Parâmetros

Retornos

Um RangeAreas objeto, composto por um ou mais intervalos retangulares, que corresponde aos critérios de pesquisa. Se nenhuma célula cumprir estes critérios, será gerado um ItemNotFound erro.

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Localiza todas as ocorrências da cadeia especificada com base nos critérios especificados e devolve-as como um RangeAreas objeto, composto por um ou mais intervalos retangulares.

findAllOrNullObject(text: string, criteria: Excel.WorksheetSearchCriteria): Excel.RangeAreas;

Parâmetros

Retornos

Um RangeAreas objeto, composto por um ou mais intervalos retangulares, que corresponde aos critérios de pesquisa. 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).

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const foundRanges = sheet.findAllOrNullObject("Complete", {
        completeMatch: true,
        matchCase: false
    });

    await context.sync();

    if (foundRanges.isNullObject) {
        console.log("No complete projects");
    } else {
        foundRanges.format.fill.color = "green"
    }
});

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

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 cell = worksheet.getCell(0,0);
    cell.load('address');
    await context.sync();

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

Obtém a folha de cálculo que se segue a esta. Se não existirem folhas de cálculo a seguir a esta, este método gerará um erro.

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

Parâmetros

Retornos

Comentários

[ Conjunto de API: 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 folha de cálculo que se segue a esta. Se não existirem folhas de cálculo a seguir a esta, 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).

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

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.5 ]

Obtém a folha de cálculo que precede esta. Se não existirem folhas de cálculo anteriores, este método gerará um erro.

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

Parâmetros

Retornos

Comentários

[ Conjunto de API: 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 folha de cálculo que precede esta. Se não existirem folhas de cálculo anteriores, 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).

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

Parâmetros

Retornos

Comentários

[ Conjunto de API: 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 API: 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);
});

Obtém o Range objeto a começar num índice de linha e índice de colunas específico e abrange 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 API: ExcelApi 1.7 ]

Obtém o RangeAreas objeto, representando um ou mais blocos de intervalos retangulares, especificados pelo endereço ou nome.

getRanges(address?: string): 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 specifiedRanges = sheet.getRanges("D3:D5, G3:G5");
    specifiedRanges.format.fill.color = "pink";

    await context.sync();
})

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 folha de cálculo estiver em branco, esta função devolverá a célula superior esquerda (ou seja, não gerará um erro).

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

Parâmetros

Retornos

Comentários

[ Conjunto de API: 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 folha de cálculo estiver em branco, 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 ]

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

Localiza e substitui a cadeia de caracteres fornecida com base nos critérios especificados na planilha 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 ]

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.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 num objeto carregado existente.

set(properties: Excel.Worksheet): void;

Parâmetros

Retornos

Mostra grupos de linhas ou colunas pelos respetivos níveis hierárquico. Descreve grupos e resume uma lista de dados na folha de cálculo. Os rowLevels parâmetros e columnLevels especificam quantos níveis do destaque serão apresentados. O intervalo de argumentos aceitável está entre 0 e 8. Um valor de 0 não altera a apresentação atual. Um valor maior do que o número atual de níveis apresenta todos os níveis.

showOutlineLevels(rowLevels: number, columnLevels: number): 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 shows the top 3 outline levels; collapsing any additional sublevels.
    sheet.showOutlineLevels(3, 3);
    await context.sync();
});

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.Worksheet é um objeto de API, o toJSON método devolve um objeto JavaScript simples (escrito como Excel.Interfaces.WorksheetData) que contém cópias rasas de quaisquer propriedades subordinadas carregadas do objeto original.

toJSON(): Excel.Interfaces.WorksheetData;

Retornos

Ocorre quando a folha de cálculo é ativada.

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

Tipo de evento

Comentários

[ Conjunto de API: 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 a folha de cálculo é calculada.

readonly onCalculated: OfficeExtension.EventHandlers<Excel.WorksheetCalculatedEventArgs>;

Tipo de evento

Comentários

[ Conjunto de API: ExcelApi 1.8 ]

Exemplos

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    sheet.onCalculated.add(function (event) {
        return Excel.run(async (context) => {
            console.log("The worksheet has recalculated.");
            await context.sync();
        });
    });
    await context.sync();
});

Ocorre quando os dados são alterados numa folha de cálculo específica.

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

Tipo de evento

Comentários

[ Conjunto de API: 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 uma ou mais colunas são classificadas. Isto acontece como resultado de uma operação de ordenação da esquerda para a direita.

readonly onColumnSorted: OfficeExtension.EventHandlers<Excel.WorksheetColumnSortedEventArgs>;

Tipo de evento

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

Exemplos

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

await Excel.run(async (context) => {
    console.log("Adding column handler");
    const sheet = context.workbook.worksheets.getActiveWorksheet();

    // This will fire whenever a column has been moved as the result of a sort action.
    sheet.onColumnSorted.add((event) => {
        return Excel.run((context) => {
            console.log("Column sorted: " + event.address);
            const sheet = context.workbook.worksheets.getActiveWorksheet();

            // Clear formatting for section, then highlight the sorted area.
            sheet.getRange("A1:E5").format.fill.clear();
            if (event.address !== "") {
                sheet.getRanges(event.address).format.fill.color = "yellow";
            }

            return context.sync();
        });
    });
});

Ocorre quando a folha de cálculo é desativada.

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

Tipo de evento

Comentários

[ Conjunto de API: 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 o formato é alterado em uma planilha específica.

readonly onFormatChanged: OfficeExtension.EventHandlers<Excel.WorksheetFormatChangedEventArgs>;

Tipo de evento

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Ocorre quando uma ou mais fórmulas são alteradas nesta folha de cálculo. Este evento destina-se a quando a própria fórmula é alterada e não o valor de dados resultante do cálculo da fórmula.

readonly onFormulaChanged: OfficeExtension.EventHandlers<Excel.WorksheetFormulaChangedEventArgs>;

Tipo de evento

Comentários

[ Conjunto de API: ExcelApi 1.13 ]

Exemplos

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

await Excel.run(async (context) => {
  // Retrieve the worksheet named "Sample".
  let sheet = context.workbook.worksheets.getItem("Sample");
  
  // Register the formula changed event handler for this worksheet.
  sheet.onFormulaChanged.add(formulaChangeHandler);
  await context.sync();
  
  console.log("Registered a formula changed event handler for this worksheet.");
});

...

async function formulaChangeHandler(event: Excel.WorksheetFormulaChangedEventArgs) {
  await Excel.run(async (context) => {
    // Retrieve details about the formula change event.
    const cellAddress = event.formulaDetails[0].cellAddress;
    const previousFormula = event.formulaDetails[0].previousFormula;
    const source = event.source;
    
    // Print out the change event details.
    console.log(
      `The formula in cell ${cellAddress} changed. 
      The previous formula was: ${previousFormula}. 
      The source of the change was: ${source}.`
    );
  });
}

Ocorre quando o estado de proteção da folha de cálculo é alterado.

readonly onProtectionChanged: OfficeExtension.EventHandlers<Excel.WorksheetProtectionChangedEventArgs>;

Tipo de evento

Comentários

[ Conjunto de API: ExcelApi 1.14 ]

Exemplos

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

// This function registers an event handler for the onProtectionChanged event of a worksheet.
await Excel.run(async (context) => {
    // Set "Sample" as the active worksheet.
    context.workbook.worksheets.getItemOrNullObject("Sample").delete();
    const sheet = context.workbook.worksheets.add("Sample");
    sheet.activate();

    // Register the onProtectionChanged event handler.
    sheet.onProtectionChanged.add(checkProtection);
    await context.sync();
    console.log("Added a worksheet protection change event handler.");
});

...

async function checkProtection(event: Excel.WorksheetProtectionChangedEventArgs) {
    // This function is an event handler that returns the protection status of a worksheet
    // and information about the changed worksheet.
    await Excel.run(async (context) => {
        const protectionStatus = event.isProtected;
        const worksheetId = event.worksheetId;
        const source = event.source;
        console.log("Protection status changed. Protection status is now: " + protectionStatus + ".");
        console.log("    ID of changed worksheet: " + worksheetId + ".");
        console.log("    Source of change event: " + source + ".");
    });
}

Ocorre quando o estado oculto de uma ou mais linhas foi alterado numa folha de cálculo específica.

readonly onRowHiddenChanged: OfficeExtension.EventHandlers<Excel.WorksheetRowHiddenChangedEventArgs>;

Tipo de evento

Comentários

[ Conjunto de API: ExcelApi 1.11 ]

Exemplos

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    sheet.onRowHiddenChanged.add(function (event) {
        return Excel.run(async (context) => {
            console.log(`Row ${event.address} is now ${event.changeType}`);
            await context.sync();
        });
    });
    await context.sync();
});

Ocorre quando uma ou mais linhas são classificadas. Isso ocorre como resultado de uma operação de classificação de cima para baixo.

readonly onRowSorted: OfficeExtension.EventHandlers<Excel.WorksheetRowSortedEventArgs>;

Tipo de evento

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

Exemplos

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

await Excel.run(async (context) => {
    console.log("Adding row handler");
    const sheet = context.workbook.worksheets.getActiveWorksheet();

    // This will fire whenever a row has been moved as the result of a sort action.
    sheet.onRowSorted.add((event) => {
        return Excel.run((context) => {
            console.log("Row sorted: " + event.address);
            const sheet = context.workbook.worksheets.getActiveWorksheet();

            // Clear formatting for section, then highlight the sorted area.
            sheet.getRange("A1:E5").format.fill.clear();
            if (event.address !== "") {
                sheet.getRanges(event.address).format.fill.color = "yellow";
            }

            return context.sync();
        });
    });
});

Ocorre quando a seleção é alterada numa folha de cálculo específica.

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

Tipo de evento

Comentários

[ Conjunto de API: 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();
});

Ocorre quando uma ação clicada/tocada à esquerda ocorre na folha de cálculo. Este evento não será acionado ao clicar nos seguintes casos:

• O utilizador arrasta o rato para seleção múltipla.

• O utilizador seleciona uma célula no modo quando os argumentos de célula são selecionados para referências de fórmulas.

readonly onSingleClicked: OfficeExtension.EventHandlers<Excel.WorksheetSingleClickedEventArgs>;

Tipo de evento

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

Exemplos

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    sheet.onSingleClicked.add((event) => {
        return Excel.run((context) => {
            console.log(`Click detected at ${event.address} (pixel offset from upper-left cell corner: ${event.offsetX}, ${event.offsetY})`);
            return context.sync();
        });
    });

    console.log("The worksheet click handler is registered.");

    await context.sync();
});