Compartilhar via

Excel.WorksheetCollection class

  • Referência
Pacote:
excel

Representa uma coleção de todos os objetos da planilha que fazem parte da pasta de trabalho.

Extends
OfficeExtension.ClientObject

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Propriedades

context

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

Obtém os itens filhos carregados nesta coleção.

Métodos

add(name)

Adiciona uma nova planilha à pasta de trabalho. A planilha será adicionada ao final das planilhas existentes. Se pretender ativar a folha de cálculo adicionada recentemente, chame-a .activate() .
getActiveWorksheet()

Obtém a planilha ativa no momento na pasta de trabalho.
getCount(visibleOnly)

Obtém o número de planilhas na coleção.
getFirst(visibleOnly)

Obtém a primeira planilha na coleção.
getItem(key)

Obtém um objeto de planilha usando o nome ou ID dele.
getItemOrNullObject(key)

Obtém um objeto de planilha usando o nome ou ID dele. Se a folha de cálculo não existir, 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).
getLast(visibleOnly)

Obtém a última planilha na coleção.
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.
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 original Excel.WorksheetCollection é um objeto de API, o toJSON método devolve um objeto JavaScript simples (escrito como Excel.Interfaces.WorksheetCollectionData) que contém uma matriz de "itens" com cópias rasas de quaisquer propriedades carregadas dos itens da coleção.

Eventos

onActivated

Ocorre quando uma folha de cálculo no livro é ativada.
onAdded

Ocorre quando uma nova folha de cálculo é adicionada ao livro.
onCalculated

Ocorre quando uma folha de cálculo no livro é calculada.
onChanged

Ocorre quando uma planilha da pasta de trabalho é alterada.
onDeactivated

Ocorre quando uma folha de cálculo no livro é desativada.
onDeleted

Ocorre quando uma folha de cálculo é eliminada do livro.
onFormatChanged

Ocorre quando uma folha de cálculo no livro tem um formato alterado.
onSelectionChanged

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

Detalhes da propriedade

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

items

Obtém os itens filhos carregados nesta coleção.

readonly items: Excel.Worksheet[];

Valor da propriedade

Excel.Worksheet[]

Detalhes do método

add(name)

Adiciona uma nova planilha à pasta de trabalho. A planilha será adicionada ao final das planilhas existentes. Se pretender ativar a folha de cálculo adicionada recentemente, chame-a .activate() .

add(name?: string): Excel.Worksheet;

Parâmetros

name

string

Opcional. O nome da planilha a ser adicionada. Se especificado, o nome deve ser exclusivo. Se não especificado, o Excel determina o nome da nova planilha.

Retornos

Excel.Worksheet

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const wSheetName = 'Sample Name';
    const worksheet = context.workbook.worksheets.add(wSheetName);
    worksheet.load('name');
    await context.sync();
    
    console.log(worksheet.name);
});

getActiveWorksheet()

Obtém a planilha ativa no momento na pasta de trabalho.

getActiveWorksheet(): Excel.Worksheet;

Retornos

Excel.Worksheet

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => {  
    const activeWorksheet = context.workbook.worksheets.getActiveWorksheet();
    activeWorksheet.load('name');
    await context.sync();
    console.log(activeWorksheet.name);
});

getCount(visibleOnly)

Obtém o número de planilhas na coleção.

getCount(visibleOnly?: boolean): OfficeExtension.ClientResult<number>;

Parâmetros

visibleOnly

boolean

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

Retornos

OfficeExtension.ClientResult<number>

Comentários

[ Conjunto de API: ExcelApi 1.4 ]

getFirst(visibleOnly)

Obtém a primeira planilha na coleção.

getFirst(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

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

getItem(key)

Obtém um objeto de planilha usando o nome ou ID dele.

getItem(key: string): Excel.Worksheet;

Parâmetros

key

string

O nome ou ID da folha de cálculo.

Retornos

Excel.Worksheet

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

getItemOrNullObject(key)

Obtém um objeto de planilha usando o nome ou ID dele. Se a folha de cálculo não existir, 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).

getItemOrNullObject(key: string): Excel.Worksheet;

Parâmetros

key

string

O nome ou ID da folha de cálculo.

Retornos

Excel.Worksheet

Comentários

[ Conjunto de API: ExcelApi 1.4 ]

getLast(visibleOnly)

Obtém a última planilha na coleção.

getLast(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

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

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.WorksheetCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions): Excel.WorksheetCollection;

Parâmetros

options

Excel.Interfaces.WorksheetCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions

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

Retornos

Excel.WorksheetCollection

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

Parâmetros

propertyNames

string | string[]

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

Retornos

Excel.WorksheetCollection

Exemplos

await Excel.run(async (context) => { 
    const worksheets = context.workbook.worksheets;
    worksheets.load('items');
    await context.sync();
    
    for (let i = 0; i < worksheets.items.length; i++) {
        console.log(worksheets.items[i].name);
    }
});

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?: OfficeExtension.LoadOption): Excel.WorksheetCollection;

Parâmetros

propertyNamesAndPaths
OfficeExtension.LoadOption

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.WorksheetCollection

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 original Excel.WorksheetCollection é um objeto de API, o toJSON método devolve um objeto JavaScript simples (escrito como Excel.Interfaces.WorksheetCollectionData) que contém uma matriz de "itens" com cópias rasas de quaisquer propriedades carregadas dos itens da coleção.

toJSON(): Excel.Interfaces.WorksheetCollectionData;

Retornos

Excel.Interfaces.WorksheetCollectionData

Detalhes do evento

onActivated

Ocorre quando uma folha de cálculo no livro é ativada.

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

Tipo de evento

OfficeExtension.EventHandlers<Excel.WorksheetActivatedEventArgs>

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-workbook-and-worksheet-collection.yaml

await Excel.run(async (context) => {
    let sheets = context.workbook.worksheets;
    sheets.onActivated.add(onActivate);

    await context.sync();
    console.log("A handler has been registered for the OnActivate event.");
});

onAdded

Ocorre quando uma nova folha de cálculo é adicionada ao livro.

readonly onAdded: OfficeExtension.EventHandlers<Excel.WorksheetAddedEventArgs>;

Tipo de evento

OfficeExtension.EventHandlers<Excel.WorksheetAddedEventArgs>

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-workbook-and-worksheet-collection.yaml

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets;
    sheet.onAdded.add(onWorksheetAdd);

    await context.sync();
    console.log("A handler has been registered for the OnAdded event.");
});

onCalculated

Ocorre quando uma folha de cálculo no livro é calculada.

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

Tipo de evento

OfficeExtension.EventHandlers<Excel.WorksheetCalculatedEventArgs>

Comentários

[ Conjunto de API: ExcelApi 1.8 ]

onChanged

Ocorre quando uma planilha da pasta de trabalho é alterada.

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

Tipo de evento

OfficeExtension.EventHandlers<Excel.WorksheetChangedEventArgs>

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

onDeactivated

Ocorre quando uma folha de cálculo no livro é desativada.

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

Tipo de evento

OfficeExtension.EventHandlers<Excel.WorksheetDeactivatedEventArgs>

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-workbook-and-worksheet-collection.yaml

await Excel.run(async (context) => {
    let sheets = context.workbook.worksheets;
    sheets.onDeactivated.add(onDeactivate);

    await context.sync();
    console.log("A handler has been registered for the OnDeactivate event.");
});

onDeleted

Ocorre quando uma folha de cálculo é eliminada do livro.

readonly onDeleted: OfficeExtension.EventHandlers<Excel.WorksheetDeletedEventArgs>;

Tipo de evento

OfficeExtension.EventHandlers<Excel.WorksheetDeletedEventArgs>

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

onFormatChanged

Ocorre quando uma folha de cálculo no livro tem um formato alterado.

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

Tipo de evento

OfficeExtension.EventHandlers<Excel.WorksheetFormatChangedEventArgs>

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

onSelectionChanged

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

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

Tipo de evento

OfficeExtension.EventHandlers<Excel.WorksheetSelectionChangedEventArgs>

Comentários

[ Conjunto de API: ExcelApi 1.9 ]