Excel. Worksheet class

Exemplos

// Get a Worksheet object by its name and activate it.
await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.activate();
    await context.sync(); 
});

Propriedades

autoFilter	Representa o `AutoFilter` objeto da folha de cálculo.
charts	Devolve uma coleção de gráficos que fazem parte da folha de cálculo.
context	O contexto do pedido associado ao objeto . Esta ação liga o processo do suplemento ao processo da aplicação anfitriã do Office.
enableCalculation	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.
freezePanes	Obtém um objeto que pode ser utilizado para manipular painéis congelados na folha de cálculo.
horizontalPageBreaks	Obtém a coleção de quebra de página horizontal da planilha. Esta coleção contém apenas quebras de página manuais.
id	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.
name	O nome de exibição da planilha. O nome tem de ter menos de 32 carateres.
names	Coleção de nomes com escopo para a planilha atual.
pageLayout	Obtém o `PageLayout` objeto da folha de cálculo.
pivotTables	Coleção de Tabelas Dinâmicas que fazem parte da planilha.
position	A posição baseada em zero da planilha na pasta de trabalho.
protection	Devolve o objeto de proteção de folha para uma folha de cálculo.
shapes	Retorna a coleção de todos os objetos Shape na planilha.
showGridlines	Especifica se as linhas de grelha estão visíveis para o utilizador.
showHeadings	Especifica se os cabeçalhos estão visíveis para o utilizador.
standardHeight	Retorna a altura padrão de todas as linhas na planilha, em pontos.
standardWidth	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).
tabColor	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.
tables	Coleção de tabelas que fazem parte da planilha.
verticalPageBreaks	Obtém a coleção de quebra de página vertical da planilha. Esta coleção contém apenas quebras de página manuais.
visibility	A visibilidade da planilha.

Métodos

activate()	Ative a planilha na interface do usuário do Excel.
calculate(markAllDirty)	Calcula todas as células em uma planilha.
copy(positionType, relativeTo)	Copia uma folha de cálculo e coloca-a na posição especificada.
copy(positionTypeString, relativeTo)	Copia uma folha de cálculo e coloca-a na posição especificada.
delete()	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.
findAll(text, criteria)	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, criteria)	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.
getCell(row, column)	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.
getNext(visibleOnly)	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.
getNextOrNullObject(visibleOnly)	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).
getPrevious(visibleOnly)	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.
getPreviousOrNullObject(visibleOnly)	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).
getRange(address)	Obtém o `Range` objeto, representando um único bloco retangular de células, especificado pelo endereço ou nome.
getRangeByIndexes(startRow, startColumn, rowCount, columnCount)	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.
getRanges(address)	Obtém o `RangeAreas` objeto, representando um ou mais blocos de intervalos retangulares, especificados pelo endereço ou nome.
getUsedRange(valuesOnly)	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).
getUsedRangeOrNullObject(valuesOnly)	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).
load(options)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar `context.sync()` antes de ler as propriedades.
load(propertyNames)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar `context.sync()` antes de ler as propriedades.
load(propertyNamesAndPaths)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar `context.sync()` antes de ler as propriedades.
replaceAll(text, replacement, criteria)	Localiza e substitui a cadeia de caracteres fornecida com base nos critérios especificados na planilha atual.
set(properties, options)	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)	Define várias propriedades no objeto ao mesmo tempo, com base num objeto carregado existente.
toJSON()	Substitui o método JavaScript `toJSON()` para fornecer uma saída mais útil quando um objeto de API é transmitido para `JSON.stringify()`. (`JSON.stringify`por sua vez, chama o `toJSON` método do objeto que lhe é transmitido.) Enquanto o objeto Excel.Worksheet original é 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.

Eventos

onActivated	Ocorre quando a folha de cálculo é ativada.
onCalculated	Ocorre quando a folha de cálculo é calculada.
onChanged	Ocorre quando os dados são alterados numa folha de cálculo específica.
onDeactivated	Ocorre quando a folha de cálculo é desativada.
onFormatChanged	Ocorre quando o formato é alterado em uma planilha específica.
onSelectionChanged	Ocorre quando a seleção é alterada numa folha de cálculo específica.

Detalhes da propriedade

autoFilter

Representa o AutoFilter objeto da folha de cálculo.

readonly autoFilter: Excel.AutoFilter;

Valor da propriedade

Excel.AutoFilter

Comentários

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

charts

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

readonly charts: Excel.ChartCollection;

Valor da propriedade

Excel.ChartCollection

Comentários

context

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

Excel.RequestContext

enableCalculation

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

boolean

Comentários

freezePanes

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

Excel.WorksheetFreezePanes

Comentários

horizontalPageBreaks

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

Excel.PageBreakCollection

Comentários

id

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

string

Comentários

name

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

name: string;

Valor da propriedade

string

Comentários

names

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

readonly names: Excel.NamedItemCollection;

Valor da propriedade

Excel.NamedItemCollection

Comentários

[ Conjunto de API: ExcelApi 1.4 ]

pageLayout

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

readonly pageLayout: Excel.PageLayout;

Valor da propriedade

Excel.PageLayout

Comentários

pivotTables

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

readonly pivotTables: Excel.PivotTableCollection;

Valor da propriedade

Excel.PivotTableCollection

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

position

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

position: number;

Valor da propriedade

number

Comentários

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

protection

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

readonly protection: Excel.WorksheetProtection;

Valor da propriedade

Excel.WorksheetProtection

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

shapes

Retorna a coleção de todos os objetos Shape na planilha.

readonly shapes: Excel.ShapeCollection;

Valor da propriedade

Excel.ShapeCollection

Comentários

showGridlines

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

showGridlines: boolean;

Valor da propriedade

boolean

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

showHeadings

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

showHeadings: boolean;

Valor da propriedade

boolean

Comentários

[ Conjunto de API: ExcelApi 1.8 ]

standardHeight

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

readonly standardHeight: number;

Valor da propriedade

number

Comentários

standardWidth

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

number

Comentários

tabColor

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

string

Comentários

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

tables

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

readonly tables: Excel.TableCollection;

Valor da propriedade

Excel.TableCollection

Comentários

verticalPageBreaks

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

Excel.PageBreakCollection

Comentários

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

visibility

A visibilidade da planilha.

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

Valor da propriedade

Excel.SheetVisibility | "Visible" | "Hidden" | "VeryHidden"

Comentários

Detalhes do método

activate()

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

activate(): void;

Retornos

void

Comentários

Exemplos

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

calculate(markAllDirty)

Calcula todas as células em uma planilha.

calculate(markAllDirty: boolean): void;

Parâmetros

markAllDirty: boolean

É verdade, marcar tudo como sujo.

Retornos

void

Comentários

[ Conjunto de API: ExcelApi 1.6 ]

copy(positionType, relativeTo)

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

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

Parâmetros

positionType: Excel.WorksheetPositionType

A localização no livro para colocar a folha de cálculo criada recentemente. O valor predefinido é "Nenhum", que insere a folha de cálculo no início da folha de cálculo.

relativeTo: Excel.Worksheet

A folha de cálculo existente que determina a posição da folha de cálculo recentemente criada. Isto só é necessário se positionType for "Antes" ou "Depois".

Retornos

Excel.Worksheet

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

Comentários

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 + "'")
});

copy(positionTypeString, relativeTo)

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

positionTypeString: "None" | "Before" | "After" | "Beginning" | "End"

A localização no livro para colocar a folha de cálculo criada recentemente. O valor predefinido é "Nenhum", que insere a folha de cálculo no início da folha de cálculo.

relativeTo: Excel.Worksheet

A folha de cálculo existente que determina a posição da folha de cálculo recentemente criada. Isto só é necessário se positionType for "Antes" ou "Depois".

Retornos

Excel.Worksheet

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

Comentários

delete()

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

void

Comentários

Exemplos

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

findAll(text, criteria)

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

text: string

A cadeia a localizar.

criteria: Excel.WorksheetSearchCriteria

Critérios de pesquisa adicionais, incluindo se a pesquisa precisa de corresponder a toda a célula ou ser sensível a maiúsculas e minúsculas.

Retornos

Excel.RangeAreas

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

findAllOrNullObject(text, criteria)

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

text: string

A cadeia a localizar.

criteria: Excel.WorksheetSearchCriteria

Critérios de pesquisa adicionais, incluindo se a pesquisa precisa de corresponder a toda a célula ou ser sensível a maiúsculas e minúsculas.

Retornos

Excel.RangeAreas

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

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

getCell(row, column)

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

row: number

O número da linha da célula a ser recuperada. Indexados com zero.

column: number

O número da coluna da célula a ser recuperada. Indexados com zero.

Retornos

Excel.Range

Comentários

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

getNext(visibleOnly)

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

visibleOnly: boolean

Opcional. Se true, considera apenas folhas de cálculo visíveis, ignorando quaisquer folhas ocultas.

Retornos

Excel.Worksheet

Comentários

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

getNextOrNullObject(visibleOnly)

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

visibleOnly: boolean

Opcional. Se true, considera apenas folhas de cálculo visíveis, ignorando quaisquer folhas ocultas.

Retornos

Excel.Worksheet

Comentários

getPrevious(visibleOnly)

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

visibleOnly: boolean

Opcional. Se true, considera apenas folhas de cálculo visíveis, ignorando quaisquer folhas ocultas.

Retornos

Excel.Worksheet

Comentários

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

getPreviousOrNullObject(visibleOnly)

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

visibleOnly: boolean

Opcional. Se true, considera apenas folhas de cálculo visíveis, ignorando quaisquer folhas ocultas.

Retornos

Excel.Worksheet

Comentários

getRange(address)

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

address: string

Opcional. A cadeia que representa o endereço ou nome do intervalo. Por exemplo, "A1:B2". Caso não seja especificado, todo o intervalo da planilha será retornado.

Retornos

Excel.Range

Comentários

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

getRangeByIndexes(startRow, startColumn, rowCount, columnCount)

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

startRow: number

Linha inicial (indexada a zero).

startColumn: number

Coluna Inicial (indexada a zero).

rowCount: number

Número de linhas a incluir no intervalo.

columnCount: number

Número de colunas a incluir no intervalo.

Retornos

Excel.Range

Comentários

getRanges(address)

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

address: string

Opcional. Uma cadeia que contém os endereços separados por vírgulas ou separados por ponto e vírgula ou nomes dos intervalos individuais. Por exemplo, "A1:B2, A5:B5" ou "A1:B2; A5:B5". Se não for especificado, é devolvido um RangeAreas objeto para toda a folha de cálculo.

Retornos

Excel.RangeAreas

Comentários

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

getUsedRange(valuesOnly)

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

valuesOnly: boolean

Opcional. Se true, considera apenas as células com valores como células utilizadas (ignorando a formatação). [Conjunto de API: ExcelApi 1.2]

Retornos

Excel.Range

Comentários

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

getUsedRangeOrNullObject(valuesOnly)

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

valuesOnly: boolean

Opcional. Considera apenas as células com valores como células usadas.

Retornos

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.4 ]

load(options)

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

options: Excel.Interfaces.WorksheetLoadOptions

Fornece opções para as propriedades do objeto a carregar.

Retornos

Excel.Worksheet

load(propertyNames)

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

propertyNames: string | string[]

Uma cadeia delimitada por vírgulas ou uma matriz de cadeias que especificam as propriedades a carregar.

Retornos

Excel.Worksheet

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

load(propertyNamesAndPaths)

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

propertyNamesAndPaths: { select?: string; expand?: string; }

propertyNamesAndPaths.select é uma cadeia delimitada por vírgulas que especifica as propriedades a carregar e propertyNamesAndPaths.expand é uma cadeia delimitada por vírgulas que especifica as propriedades de navegação a carregar.

Retornos

Excel.Worksheet

replaceAll(text, replacement, criteria)

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

text: string

Cadeia a localizar.

replacement: string

A cadeia que substitui a cadeia original.

criteria: Excel.ReplaceCriteria

Critérios de substituição adicionais.

Retornos

OfficeExtension.ClientResult<number>

O número de substituições efetuadas.

Comentários

OfficeExtension.EventHandlers<Excel.WorksheetActivatedEventArgs>

set(properties, options)

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

properties: Excel.Interfaces.WorksheetUpdateData

Um objeto JavaScript com propriedades que são estruturadas isomorfoticamente para as propriedades do objeto no qual o método é chamado.

options: OfficeExtension.UpdateOptions

Fornece uma opção para suprimir erros se o objeto de propriedades tentar definir quaisquer propriedades só de leitura.

Retornos

void

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

set(properties)

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

set(properties: Excel.Worksheet): void;

Parâmetros

properties: Excel.Worksheet

Retornos

void

toJSON()

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 Excel.Worksheet original é 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

Excel.Interfaces.WorksheetData

Detalhes do evento

onActivated

Ocorre quando a folha de cálculo é ativada.

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

Tipo de evento

Comentários

OfficeExtension.EventHandlers<Excel.WorksheetCalculatedEventArgs>

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

onCalculated

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

onChanged

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

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

Tipo de evento

OfficeExtension.EventHandlers<Excel.WorksheetChangedEventArgs>

Comentários

OfficeExtension.EventHandlers<Excel.WorksheetDeactivatedEventArgs>

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

onDeactivated

Ocorre quando a folha de cálculo é desativada.

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

Tipo de evento

Comentários

OfficeExtension.EventHandlers<Excel.WorksheetFormatChangedEventArgs>

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

onFormatChanged

Ocorre quando o formato é alterado em uma planilha específica.

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

Tipo de evento

Comentários

OfficeExtension.EventHandlers<Excel.WorksheetSelectionChangedEventArgs>

onSelectionChanged

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

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

Tipo de evento

Comentários