Excel.WorksheetCollection class
Representa uma coleção de todos os objetos da planilha que fazem parte da pasta de trabalho.
- Extends
Comentários
[ Conjunto de API: ExcelApi 1.1 ]
Propriedades
| context | O contexto de solicitação associado ao objeto. Isso conecta o processo do suplemento ao processo do aplicativo host 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 você quiser ativar a planilha recém-adicionada, chame-a |
| add |
Insere as planilhas especificadas de uma pasta de trabalho na pasta de trabalho atual. Observação*: atualmente, essa API só tem suporte para o Office no Windows e no Mac. E ele foi preterido, use |
| add |
Insere as planilhas especificadas de uma pasta de trabalho na pasta de trabalho atual. Observação*: atualmente, essa API só tem suporte para o Office no Windows e no Mac. E ele foi preterido, use |
| get |
Obtém a planilha ativa no momento na pasta de trabalho. |
| get |
Obtém o número de planilhas na coleção. |
| get |
Obtém a primeira planilha na coleção. |
| get |
Obtém um objeto de planilha usando o nome ou ID dele. |
| get |
Obtém um objeto de planilha usando o nome ou ID dele. Se a planilha não existir, esse método retornará um objeto com sua |
| get |
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 |
| load(property |
Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar |
| load(property |
Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar |
| toJSON() | Substitui o método JavaScript |
Eventos
| on |
Ocorre quando qualquer planilha na pasta de trabalho é ativada. |
| on |
Ocorre quando uma nova planilha é adicionada à pasta de trabalho. |
| on |
Ocorre quando qualquer planilha na pasta de trabalho é calculada. |
| on |
Ocorre quando uma planilha da pasta de trabalho é alterada. |
| on |
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. |
| on |
Ocorre quando qualquer planilha na pasta de trabalho é desativada. |
| on |
Ocorre quando uma planilha é excluída da pasta de trabalho. |
| on |
Ocorre quando filtro de uma planilha é aplicado na pasta de trabalho. |
| on |
Ocorre quando qualquer planilha na pasta de trabalho tem um formato alterado. |
| on |
Ocorre quando uma ou mais fórmulas são alteradas em qualquer planilha desta coleção. Esse evento é para quando a fórmula em si é alterada, não o valor de dados resultante do cálculo da fórmula. |
| on |
Ocorre quando uma planilha é movida dentro de uma pasta de trabalho. Esse evento só dispara quando uma planilha é movida diretamente dentro de uma pasta de trabalho. Esse evento não é disparado quando a posição de uma planilha é alterada indiretamente, como quando uma nova planilha é inserida e faz com que as planilhas existentes alterem posições. |
| on |
Ocorre quando o nome da planilha é alterado na coleção de planilhas. |
| on |
Ocorre quando o estado de proteção de planilha é alterado. |
| on |
Ocorre quando o estado oculto de uma ou mais linhas é alterado em uma planilha específica. |
| on |
Ocorre quando uma ou mais linhas são classificadas. Isso ocorre como resultado de uma operação de classificação de cima para baixo. |
| on |
Ocorre quando a seleção é alterada em uma planilha. |
| on |
Ocorre quando a operação clicada/grampeada à esquerda acontece na coleção de planilhas. Esse evento não será disparado ao clicar nos seguintes casos: – O usuário arrasta o mouse para várias seleções. - O usuário seleciona uma célula no modo quando os argumentos de célula são selecionados para referências de fórmula. |
| on |
Ocorre quando a visibilidade da planilha é alterada na coleção de planilhas. |
Detalhes da propriedade
context
O contexto de solicitação associado ao objeto. Isso conecta o processo do suplemento ao processo do aplicativo host do Office.
context: RequestContext;Valor da propriedade
items
Obtém os itens filhos carregados nesta coleção.
readonly items: Excel.Worksheet[];Valor da propriedade
Detalhes do método
add(name)
Adiciona uma nova planilha à pasta de trabalho. A planilha será adicionada ao final das planilhas existentes. Se você quiser ativar a planilha recém-adicionada, 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
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);
});
addFromBase64(base64File, sheetNamesToInsert, positionType, relativeTo)
Observação
Esta API é fornecida como uma versão prévia para desenvolvedores e pode ser alterada com base nos comentários que recebemos. Não use esta API em um ambiente de produção.
Insere as planilhas especificadas de uma pasta de trabalho na pasta de trabalho atual.
Observação*: atualmente, essa API só tem suporte para o Office no Windows e no Mac. E ele foi preterido, use Workbook.insertWorksheetFromBase64 em vez disso.
addFromBase64(base64File: string, sheetNamesToInsert?: string[], positionType?: Excel.WorksheetPositionType, relativeTo?: Worksheet | string): OfficeExtension.ClientResult<string[]>;Parâmetros
- base64File
-
string
Obrigatório. A cadeia de caracteres codificada base64 que representa o arquivo de pasta de trabalho de origem.
- sheetNamesToInsert
-
string[]
Opcional. Os nomes das planilhas individuais a serem inseridas. Por padrão, todas as planilhas da pasta de trabalho de origem são inseridas.
- positionType
- Excel.WorksheetPositionType
Opcional. Onde na pasta de trabalho atual as novas planilhas serão inseridas. Confira Excel.WorksheetPositionType detalhes. O padrão é "Iniciar".
- relativeTo
-
Excel.Worksheet | string
Opcional. A planilha na pasta de trabalho atual que é referenciada para o positionType parâmetro. O padrão é null e, com base em positionType, ele inserirá planilhas no início ou no final da pasta de trabalho atual.
Retornos
OfficeExtension.ClientResult<string[]>
Uma matriz de IDs correspondente a cada planilha recém-inserida.
Comentários
addFromBase64(base64File, sheetNamesToInsert, positionTypeString, relativeTo)
Observação
Esta API é fornecida como uma versão prévia para desenvolvedores e pode ser alterada com base nos comentários que recebemos. Não use esta API em um ambiente de produção.
Insere as planilhas especificadas de uma pasta de trabalho na pasta de trabalho atual.
Observação*: atualmente, essa API só tem suporte para o Office no Windows e no Mac. E ele foi preterido, use Workbook.insertWorksheetFromBase64 em vez disso.
addFromBase64(base64File: string, sheetNamesToInsert?: string[], positionTypeString?: "None" | "Before" | "After" | "Beginning" | "End", relativeTo?: Worksheet | string): OfficeExtension.ClientResult<string[]>;Parâmetros
- base64File
-
string
Obrigatório. A cadeia de caracteres codificada base64 que representa o arquivo de pasta de trabalho de origem.
- sheetNamesToInsert
-
string[]
Opcional. Os nomes das planilhas individuais a serem inseridas. Por padrão, todas as planilhas da pasta de trabalho de origem são inseridas.
- positionTypeString
-
"None" | "Before" | "After" | "Beginning" | "End"
Opcional. Onde na pasta de trabalho atual as novas planilhas serão inseridas. Confira Excel.WorksheetPositionType detalhes. O padrão é "Iniciar".
- relativeTo
-
Excel.Worksheet | string
Opcional. A planilha na pasta de trabalho atual que é referenciada para o positionType parâmetro. O padrão é null e, com base em positionType, ele inserirá planilhas no início ou no final da pasta de trabalho atual.
Retornos
OfficeExtension.ClientResult<string[]>
Uma matriz de IDs correspondente a cada planilha recém-inserida.
Comentários
getActiveWorksheet()
Obtém a planilha ativa no momento na pasta de trabalho.
getActiveWorksheet(): Excel.Worksheet;Retornos
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, considerar apenas planilhas visíveis, ignorando todas as ocultas.
Retornos
OfficeExtension.ClientResult<number>
Comentários
getFirst(visibleOnly)
Obtém a primeira planilha na coleção.
getFirst(visibleOnly?: boolean): Excel.Worksheet;Parâmetros
- visibleOnly
-
boolean
Opcional. Se true, considerar apenas planilhas visíveis, ignorando todas as ocultas.
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();
});
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 planilha.
Retornos
Comentários
getItemOrNullObject(key)
Obtém um objeto de planilha usando o nome ou ID dele. Se a planilha não existir, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte *Métodos e propriedades orNullObject.
getItemOrNullObject(key: string): Excel.Worksheet;Parâmetros
- key
-
string
O nome ou ID da planilha.
Retornos
Comentários
getLast(visibleOnly)
Obtém a última planilha na coleção.
getLast(visibleOnly?: boolean): Excel.Worksheet;Parâmetros
- visibleOnly
-
boolean
Opcional. Se true, considerar apenas planilhas visíveis, ignorando todas as ocultas.
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();
});
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
Fornece opções para quais propriedades do objeto carregar.
Retornos
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 de caracteres delimitada por vírgulas ou uma matriz de cadeias de caracteres que especificam as propriedades a serem carregadas.
Retornos
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 de caracteres delimitada por vírgulas que especifica as propriedades a serem carregadas e propertyNamesAndPaths.expand é uma cadeia de caracteres delimitada por vírgulas que especifica as propriedades de navegação a serem carregadas.
Retornos
toJSON()
Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é passado para JSON.stringify(). (JSON.stringifypor sua vez, chama o toJSON método do objeto que é passado para ele.) Considerando que o objeto original Excel.WorksheetCollection é um objeto API, o toJSON método retorna um objeto JavaScript simples (digitado 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
Detalhes do evento
onActivated
Ocorre quando qualquer planilha na pasta de trabalho é ativada.
readonly onActivated: OfficeExtension.EventHandlers<Excel.WorksheetActivatedEventArgs>;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-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 planilha é adicionada à pasta de trabalho.
readonly onAdded: OfficeExtension.EventHandlers<Excel.WorksheetAddedEventArgs>;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-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 qualquer planilha na pasta de trabalho é calculada.
readonly onCalculated: OfficeExtension.EventHandlers<Excel.WorksheetCalculatedEventArgs>;Tipo de evento
Comentários
onChanged
Ocorre quando uma planilha da pasta de trabalho é alterada.
readonly onChanged: OfficeExtension.EventHandlers<Excel.WorksheetChangedEventArgs>;Tipo de evento
Comentários
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
Comentários
onDeactivated
Ocorre quando qualquer planilha na pasta de trabalho é desativada.
readonly onDeactivated: OfficeExtension.EventHandlers<Excel.WorksheetDeactivatedEventArgs>;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-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 planilha é excluída da pasta de trabalho.
readonly onDeleted: OfficeExtension.EventHandlers<Excel.WorksheetDeletedEventArgs>;Tipo de evento
Comentários
onFiltered
Observação
Esta API é fornecida como uma versão prévia para desenvolvedores e pode ser alterada com base nos comentários que recebemos. Não use esta API em um ambiente de produção.
Ocorre quando filtro de uma planilha é aplicado na pasta de trabalho.
readonly onFiltered: OfficeExtension.EventHandlers<Excel.WorksheetFilteredEventArgs>;Tipo de evento
Comentários
onFormatChanged
Ocorre quando qualquer planilha na pasta de trabalho tem um formato alterado.
readonly onFormatChanged: OfficeExtension.EventHandlers<Excel.WorksheetFormatChangedEventArgs>;Tipo de evento
Comentários
onFormulaChanged
Ocorre quando uma ou mais fórmulas são alteradas em qualquer planilha desta coleção. Esse evento é para quando a fórmula em si é alterada, não o valor de dados resultante do cálculo da fórmula.
readonly onFormulaChanged: OfficeExtension.EventHandlers<Excel.WorksheetFormulaChangedEventArgs>;Tipo de evento
Comentários
onMoved
Ocorre quando uma planilha é movida dentro de uma pasta de trabalho. Esse evento só dispara quando uma planilha é movida diretamente dentro de uma pasta de trabalho. Esse evento não é disparado quando a posição de uma planilha é alterada indiretamente, como quando uma nova planilha é inserida e faz com que as planilhas existentes alterem posições.
readonly onMoved: OfficeExtension.EventHandlers<Excel.WorksheetMovedEventArgs>;Tipo de evento
Comentários
onNameChanged
Ocorre quando o nome da planilha é alterado na coleção de planilhas.
readonly onNameChanged: OfficeExtension.EventHandlers<Excel.WorksheetNameChangedEventArgs>;Tipo de evento
Comentários
onProtectionChanged
Ocorre quando o estado de proteção de planilha é alterado.
readonly onProtectionChanged: OfficeExtension.EventHandlers<Excel.WorksheetProtectionChangedEventArgs>;Tipo de evento
Comentários
onRowHiddenChanged
Ocorre quando o estado oculto de uma ou mais linhas é alterado em uma planilha específica.
readonly onRowHiddenChanged: OfficeExtension.EventHandlers<Excel.WorksheetRowHiddenChangedEventArgs>;Tipo de evento
Comentários
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
Comentários
onSelectionChanged
Ocorre quando a seleção é alterada em uma planilha.
readonly onSelectionChanged: OfficeExtension.EventHandlers<Excel.WorksheetSelectionChangedEventArgs>;Tipo de evento
Comentários
onSingleClicked
Ocorre quando a operação clicada/grampeada à esquerda acontece na coleção de planilhas. Esse evento não será disparado ao clicar nos seguintes casos: – O usuário arrasta o mouse para várias seleções. - O usuário seleciona uma célula no modo quando os argumentos de célula são selecionados para referências de fórmula.
readonly onSingleClicked: OfficeExtension.EventHandlers<Excel.WorksheetSingleClickedEventArgs>;Tipo de evento
Comentários
onVisibilityChanged
Ocorre quando a visibilidade da planilha é alterada na coleção de planilhas.
readonly onVisibilityChanged: OfficeExtension.EventHandlers<Excel.WorksheetVisibilityChangedEventArgs>;Tipo de evento
Comentários
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de