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

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.stringify`por 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.
onColumnSorted	Ocorre quando uma ou mais colunas são classificadas. Isso acontece como resultado de uma operação de classificação da esquerda para a direita.
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.
onFormulaChanged	Ocorre quando uma ou mais fórmulas são alteradas em qualquer folha de cálculo desta coleção. 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.
onMoved	Ocorre quando uma folha de cálculo é movida dentro de um livro. Este evento só é acionado quando uma folha de cálculo é movida diretamente dentro de um livro. Este evento não é acionado quando a posição de uma folha de cálculo é alterada indiretamente, como quando uma nova folha de cálculo é inserida e faz com que as folhas de cálculo existentes alterem as posições.
onNameChanged	Ocorre quando o nome da folha de cálculo é alterado na coleção de folhas de cálculo.
onProtectionChanged	Ocorre quando o estado de proteção da folha de cálculo é alterado.
onRowHiddenChanged	Ocorre quando o estado oculto de uma ou mais linhas foi alterado numa folha de cálculo específica.
onRowSorted	Ocorre quando uma ou mais linhas são classificadas. Isso ocorre como resultado de uma operação de classificação de cima para baixo.
onSelectionChanged	Ocorre quando a seleção é alterada em uma planilha.
onSingleClicked	Ocorre quando a operação clicada/tocada à esquerda ocorre na coleção de folhas 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.
onVisibilityChanged	Ocorre quando a visibilidade da folha de cálculo é alterada na coleção de folhas de cálculo.

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 ]

onColumnSorted

Ocorre quando uma ou mais colunas são classificadas. Isso acontece como resultado de uma operação de classificação da esquerda para a direita.

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

Tipo de evento

OfficeExtension.EventHandlers<Excel.WorksheetColumnSortedEventArgs>

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

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 ]

onFormulaChanged

Ocorre quando uma ou mais fórmulas são alteradas em qualquer folha de cálculo desta coleção. 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

OfficeExtension.EventHandlers<Excel.WorksheetFormulaChangedEventArgs>

Comentários

[ Conjunto de API: ExcelApi 1.13 ]

onMoved

Ocorre quando uma folha de cálculo é movida dentro de um livro. Este evento só é acionado quando uma folha de cálculo é movida diretamente dentro de um livro. Este evento não é acionado quando a posição de uma folha de cálculo é alterada indiretamente, como quando uma nova folha de cálculo é inserida e faz com que as folhas de cálculo existentes alterem as posições.

readonly onMoved: OfficeExtension.EventHandlers<Excel.WorksheetMovedEventArgs>;

Tipo de evento

OfficeExtension.EventHandlers<Excel.WorksheetMovedEventArgs>

Comentários

[ Conjunto de API: ExcelApi 1.17 ]

onNameChanged

Ocorre quando o nome da folha de cálculo é alterado na coleção de folhas de cálculo.

readonly onNameChanged: OfficeExtension.EventHandlers<Excel.WorksheetNameChangedEventArgs>;

Tipo de evento

OfficeExtension.EventHandlers<Excel.WorksheetNameChangedEventArgs>

Comentários

[ Conjunto de API: ExcelApi 1.17 ]

onProtectionChanged

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

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

Tipo de evento

OfficeExtension.EventHandlers<Excel.WorksheetProtectionChangedEventArgs>

Comentários

[ Conjunto de API: ExcelApi 1.14 ]

onRowHiddenChanged

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

OfficeExtension.EventHandlers<Excel.WorksheetRowHiddenChangedEventArgs>

Comentários

[ Conjunto de API: ExcelApi 1.11 ]

onRowSorted

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

OfficeExtension.EventHandlers<Excel.WorksheetRowSortedEventArgs>

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

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 ]

onSingleClicked

Ocorre quando a operação clicada/tocada à esquerda ocorre na coleção de folhas 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

OfficeExtension.EventHandlers<Excel.WorksheetSingleClickedEventArgs>

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

onVisibilityChanged

Ocorre quando a visibilidade da folha de cálculo é alterada na coleção de folhas de cálculo.

readonly onVisibilityChanged: OfficeExtension.EventHandlers<Excel.WorksheetVisibilityChangedEventArgs>;

Tipo de evento

OfficeExtension.EventHandlers<Excel.WorksheetVisibilityChangedEventArgs>

Comentários

[ Conjunto de API: ExcelApi 1.17 ]

Compartilhar via

Excel.WorksheetCollection class

Comentários

Propriedades

Métodos

Eventos

Detalhes da propriedade

context

Valor da propriedade

items

Valor da propriedade

Detalhes do método

add(name)

Parâmetros

Retornos

Comentários

Exemplos

getActiveWorksheet()

Retornos

Comentários

Exemplos

getCount(visibleOnly)

Parâmetros

Retornos

Comentários

getFirst(visibleOnly)

Parâmetros

Retornos

Comentários

Exemplos

getItem(key)

Parâmetros

Retornos

Comentários

getItemOrNullObject(key)

Parâmetros

Retornos

Comentários

getLast(visibleOnly)

Parâmetros

Retornos

Comentários

Exemplos

load(options)

Parâmetros

Retornos

load(propertyNames)

Parâmetros

Retornos

Exemplos

load(propertyNamesAndPaths)

Parâmetros

Retornos

toJSON()

Retornos

Detalhes do evento

onActivated

Tipo de evento

Comentários

Exemplos

onAdded

Tipo de evento

Comentários

Exemplos

onCalculated

Tipo de evento

Comentários

onChanged

Tipo de evento

Comentários

onColumnSorted

Tipo de evento

Comentários

onDeactivated

Tipo de evento

Comentários

Exemplos

onDeleted

Tipo de evento

Comentários