ExcelScript.Workbook interface

Referência

Pacote:: ExcelScript

O livro é o objeto de nível superior que contém objetos relacionados do livro, como folhas de cálculo, tabelas e intervalos.

Comentários

Exemplos

/**
 * This script adds a new worksheet to the workbook, then switches to it.
 */
function main(workbook: ExcelScript.Workbook) {
  // Add a new worksheet with the default name.
  let worksheet = workbook.addWorksheet();

  // Switch focus to the new worksheet.
  worksheet.activate();
}

Métodos

addBinding(range, bindingType, id)	Adiciona uma nova associação a um intervalo específico.
addBindingFromNamedItem(name, bindingType, id)	Adiciona uma nova associação com base em um item nomeado na pasta de trabalho. Se o item nomeado fizer referência a várias áreas, será devolvido o `InvalidReference` erro.
addBindingFromSelection(bindingType, id)	Adiciona uma nova associação com base na seleção atual. Se a seleção tiver várias áreas, será devolvido o `InvalidReference` erro.
addComment(cellAddress, content, contentType)	Cria um novo comentário com o conteúdo fornecido na célula especificada. É `InvalidArgument` apresentado um erro se o intervalo fornecido for maior do que uma célula.
addCustomXmlPart(xml)	Adiciona uma nova parte XML personalizada à pasta de trabalho.
addNamedItem(name, reference, comment)	Adiciona um novo nome à coleção do escopo fornecido.
addNamedItemFormulaLocal(name, formula, comment)	Adiciona um novo nome à coleção de escopo fornecido usando a localidade do usuário para a fórmula.
addPivotTable(name, source, destination)	Adicione uma tabela dinâmica com base nos dados de origem especificados e insira-a na célula superior esquerda do intervalo de destino.
addPivotTableStyle(name, makeUniqueName)	Cria um espaço em branco `PivotTableStyle` com o nome especificado.
addPredefinedCellStyle(name)	Adiciona um novo estilo para o conjunto.
addSlicer(slicerSource, sourceField, slicerDestination)	Adiciona uma nova segmentação de dados à pasta de trabalho.
addSlicerStyle(name, makeUniqueName)	Cria um estilo de segmentação de dados em branco com o nome especificado.
addTable(address, hasHeaders)	Cria uma nova tabela. O objeto de intervalo ou endereço de origem determina a planilha à qual a tabela será adicionada. Se a tabela não puder ser adicionada (por exemplo, porque o endereço é inválido ou a tabela se sobreporia a outra), será gerado um erro.
addTableStyle(name, makeUniqueName)	Cria um espaço em branco `TableStyle` com o nome especificado.
addTimelineStyle(name, makeUniqueName)	Cria um espaço em branco `TimelineStyle` com o nome especificado.
addWorksheet(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()` .
breakAllLinksToLinkedWorkbooks()	Quebra todas as ligações para os livros ligados. Depois de as ligações serem quebradas, todas as fórmulas que referenciam ligações de livros são removidas por completo e substituídas pelos valores obtidos mais recentemente.
getActiveCell()	Obtém a célula ativa no momento da pasta de trabalho.
getActiveChart()	Obtém o gráfico ativo no momento na pasta de trabalho. Se não existir nenhum gráfico ativo, este método devolve `undefined`.
getActiveSlicer()	Obtém a segmentação de dados ativa no momento na pasta de trabalho. Se não existir uma segmentação de dados ativa, este método devolve `undefined`.
getActiveWorksheet()	Obtém a planilha ativa no momento na pasta de trabalho.
getApplication()	Representa a instância da aplicação Excel que contém este livro.
getAutoSave()	Especifica se o livro está no modo guardar automaticamente.
getBinding(id)	Obtém um objeto de associação pela ID. Se o objeto de enlace não existir, este método devolve `undefined`.
getBindings()	Representa uma coleção de ligações que fazem parte da pasta de trabalho.
getCalculationEngineVersion()	Retorna um número sobre a versão do Mecanismo de Cálculo do Excel.
getChartDataPointTrack()	True se todos os gráficos na pasta de trabalho estiverem rastreando os pontos de dados reais aos quais eles estão anexados. Falso se os gráficos controlarem o índice dos pontos de dados.
getComment(commentId)	Obtém um comentário da coleção com base em seu ID. Se o objeto de comentário não existir, este método devolve `undefined`.
getCommentByCell(cellAddress)	Obtém o comentário da célula especificada. Se não existir nenhum comentário na célula, é gerado um erro.
getCommentByReplyId(replyId)	Obtém o comentário ao qual a resposta especificada está ligada.
getComments()	Representa uma coleção de comentários associados ao livro.
getCustomXmlPart(id)	Obtém uma parte XML personalizada com base em sua ID. Se o `CustomXmlPart` não existir, este método devolve `undefined`.
getCustomXmlPartByNamespace(namespaceUri)	Obtém uma nova coleção de partes XML personalizadas cujos espaços de nomes correspondem ao espaço de nomes especificado.
getCustomXmlParts()	Representa a coleção de peças XML personalizadas contidas neste livro.
getCustomXmlPartsByNamespace(namespaceUri)	Obtém uma nova coleção de partes XML personalizadas cujos espaços de nomes correspondem ao espaço de nomes especificado.
getDefaultPivotTableStyle()	Obtém o estilo de Tabela Dinâmica predefinido para o âmbito do objeto principal.
getDefaultSlicerStyle()	Obtém a predefinição `SlicerStyle` para o âmbito do objeto principal.
getDefaultTableStyle()	Obtém o estilo de tabela predefinido para o âmbito do objeto principal.
getDefaultTimelineStyle()	Obtém o estilo de linha cronológica predefinido para o âmbito do objeto principal.
getFirstWorksheet(visibleOnly)	Obtém a primeira planilha na coleção.
getIsDirty()	Especifica se foram feitas alterações desde a última vez que o livro foi guardado. Pode definir esta propriedade como `true` se pretendesse fechar um livro modificado sem guardá-lo ou ser-lhe pedido para guardá-lo.
getLastWorksheet(visibleOnly)	Obtém a última planilha na coleção.
getLinkedWorkbookByUrl(key)	Obtém informações sobre um livro ligado através do respetivo URL. Se o livro não existir, este método devolve `undefined`.
getLinkedWorkbookRefreshMode()	Representa o modo de atualização das ligações do livro. O modo é o mesmo para todas as ligações do livro presentes no livro.
getLinkedWorkbooks()	Devolve uma coleção de livros ligados. Nas fórmulas, as ligações do livro podem ser utilizadas para referenciar dados (valores de células e nomes) fora do livro atual.
getName()	Obtém o nome da pasta de trabalho.
getNamedItem(name)	Obtém um `NamedItem` objeto com o respetivo nome. Se o objeto não existir, este método devolve `undefined`.
getNames()	Representa uma coleção de itens nomeados com âmbito de livro (intervalos com nome e constantes).
getPivotTable(name)	Obtém uma Tabela Dinâmica por nome. Se a tabela dinâmica não existir, este método devolve `undefined`.
getPivotTables()	Representa uma coleção de Tabelas Dinâmicas associadas à pasta de trabalho.
getPivotTableStyle(name)	Obtém um `PivotTableStyle` pelo nome. Se o `PivotTableStyle` não existir, este método devolve `undefined`.
getPivotTableStyles()	Representa uma coleção de Tabelas Dinâmicas associadas à pasta de trabalho.
getPredefinedCellStyle(name)	Obtém um estilo por nome. Se o objeto de estilo não existir, este método devolve `undefined`.
getPredefinedCellStyles()	Representa uma coleção de estilos associados à pasta de trabalho.
getPreviouslySaved()	Especifica se o livro já foi guardado localmente ou online.
getProperties()	Obtém as propriedades da pasta de trabalho.
getProtection()	Devolve o objeto de proteção de um livro.
getQueries()	Devolve uma coleção de consultas do Power Query que fazem parte do livro.
getQuery(key)	Obtém uma consulta da coleção com base no respetivo nome.
getReadOnly()	Devolve `true` se o livro estiver aberto no modo só de leitura.
getSelectedRange()	Obtém o intervalo único selecionado atualmente a partir do livro. Se existirem vários intervalos selecionados, este método gerará um erro.
getSelectedRanges()	Obtém um ou mais intervalos atualmente selecionados da pasta de trabalho. Ao contrário `getSelectedRange()`de , este método devolve um `RangeAreas` objeto que representa todos os intervalos selecionados.
getSlicer(key)	Obtém uma segmentação de dados com o respetivo nome ou ID. Se a segmentação de dados não existir, este método devolve `undefined`.
getSlicers()	Representa uma coleção de segmentações de dados associadas ao livro.
getSlicerStyle(name)	Obtém um `SlicerStyle` pelo nome. Se o estilo de segmentação de dados não existir, este método devolve `undefined`.
getSlicerStyles()	Representa uma coleção de SlicerStyles associados à pasta de trabalho.
getTable(key)	Obtém uma tabela pelo nome ou ID. Se a tabela não existir, este método devolve `undefined`.
getTables()	Representa uma coleção de tabelas associadas à pasta de trabalho.
getTableStyle(name)	Obtém um `TableStyle` pelo nome. Se o estilo de tabela não existir, este método devolve `undefined`.
getTableStyles()	Representa uma coleção de TableStyles associadas à pasta de trabalho.
getTimelineStyle(name)	Obtém um `TimelineStyle` pelo nome. Se o estilo da linha cronológica não existir, este método devolve `undefined`.
getTimelineStyles()	Representa uma coleção de TimelineStyles associados à pasta de trabalho.
getUsePrecisionAsDisplayed()	True se os cálculos dessa pasta de trabalho forem efetuados usando apenas a precisão dos números conforme forem exibidos. Os dados perderão permanentemente a precisão ao mudar esta propriedade de `false` para `true`.
getWorksheet(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 `undefined`.
getWorksheets()	Representa uma coleção de planilhas associadas à pasta de trabalho.
refreshAllDataConnections()	Atualiza todas as Ligações de Dados.
refreshAllLinksToLinkedWorkbooks()	Faz um pedido para atualizar todas as ligações do livro.
refreshAllPivotTables()	Atualiza todas as tabelas dinâmicas da coleção.
setChartDataPointTrack(chartDataPointTrack)	True se todos os gráficos na pasta de trabalho estiverem rastreando os pontos de dados reais aos quais eles estão anexados. Falso se os gráficos controlarem o índice dos pontos de dados.
setDefaultPivotTableStyle(newDefaultStyle)	Define o estilo de tabela dinâmica predefinido para utilização no âmbito do objeto principal.
setDefaultSlicerStyle(newDefaultStyle)	Define o estilo de segmentação de dados predefinido para utilização no âmbito do objeto principal.
setDefaultTableStyle(newDefaultStyle)	Define o estilo de tabela predefinido para utilização no âmbito do objeto principal.
setDefaultTimelineStyle(newDefaultStyle)	Define o estilo de linha cronológica predefinido para utilização no âmbito do objeto principal.
setIsDirty(isDirty)	Especifica se foram feitas alterações desde a última vez que o livro foi guardado. Pode definir esta propriedade como `true` se pretendesse fechar um livro modificado sem guardá-lo ou ser-lhe pedido para guardá-lo.
setLinkedWorkbookRefreshMode(linkedWorkbookRefreshMode)	Representa o modo de atualização das ligações do livro. O modo é o mesmo para todas as ligações do livro presentes no livro.
setUsePrecisionAsDisplayed(usePrecisionAsDisplayed)	True se os cálculos dessa pasta de trabalho forem efetuados usando apenas a precisão dos números conforme forem exibidos. Os dados perderão permanentemente a precisão ao mudar esta propriedade de `false` para `true`.

Detalhes do método

addBinding(range, bindingType, id)

Adiciona uma nova associação a um intervalo específico.

addBinding(
            range: Range | string,
            bindingType: BindingType,
            id: string
        ): Binding;

Parâmetros

range: ExcelScript.Range | string

Intervalo para vincular a associação. Pode ser um Range objeto ou uma cadeia. Se for uma cadeia de caracteres, deve conter o endereço completo, incluindo o nome da planilha

bindingType: ExcelScript.BindingType

Tipo de associação. Consulte ExcelScript.BindingType.

id: string

Nome do enlace.

Retornos

ExcelScript.Binding

addBindingFromNamedItem(name, bindingType, id)

Adiciona uma nova associação com base em um item nomeado na pasta de trabalho. Se o item nomeado fizer referência a várias áreas, será devolvido o InvalidReference erro.

addBindingFromNamedItem(
            name: string,
            bindingType: BindingType,
            id: string
        ): Binding;

Parâmetros

name: string

Nome do qual deseja criar a associação.

bindingType: ExcelScript.BindingType

Tipo de associação. Consulte ExcelScript.BindingType.

id: string

Nome do enlace.

Retornos

ExcelScript.Binding

addBindingFromSelection(bindingType, id)

Adiciona uma nova associação com base na seleção atual. Se a seleção tiver várias áreas, será devolvido o InvalidReference erro.

addBindingFromSelection(bindingType: BindingType, id: string): Binding;

Parâmetros

bindingType: ExcelScript.BindingType

Tipo de associação. Consulte ExcelScript.BindingType.

id: string

Nome do enlace.

Retornos

ExcelScript.Binding

addComment(cellAddress, content, contentType)

Cria um novo comentário com o conteúdo fornecido na célula especificada. É InvalidArgument apresentado um erro se o intervalo fornecido for maior do que uma célula.

addComment(
            cellAddress: Range | string,
            content: CommentRichContent | string,
            contentType?: ContentType
        ): Comment;

Parâmetros

cellAddress: ExcelScript.Range | string

A célula à qual o comentário é adicionado. Pode ser um Range objeto ou uma cadeia. Se for uma cadeia, tem de conter o endereço completo, incluindo o nome da folha. É InvalidArgument apresentado um erro se o intervalo fornecido for maior do que uma célula.

content: ExcelScript.CommentRichContent | string

O conteúdo do comentário. Isto pode ser uma cadeia ou CommentRichContent objeto. As cadeias são utilizadas para texto simples. CommentRichContent os objetos permitem outras funcionalidades de comentários, como menções.

contentType: ExcelScript.ContentType

Opcional. O tipo de conteúdo contido no comentário. O valor predefinido é enum ContentType.Plain.

Retornos

ExcelScript.Comment

addCustomXmlPart(xml)

Adiciona uma nova parte XML personalizada à pasta de trabalho.

addCustomXmlPart(xml: string): CustomXmlPart;

Parâmetros

xml: string

Conteúdo XML. Tem de ser um fragmento XML válido.

Retornos

ExcelScript.CustomXmlPart

addNamedItem(name, reference, comment)

Adiciona um novo nome à coleção do escopo fornecido.

addNamedItem(
            name: string,
            reference: Range | string,
            comment?: string
        ): NamedItem;

Parâmetros

name: string

O nome do item nomeado.

reference: ExcelScript.Range | string

A fórmula ou o intervalo ao qual o nome fará referência.

comment: string

Opcional. O comentário associado ao item com nome.

Retornos

ExcelScript.NamedItem

Exemplos

/**
 * This script creates a named formula and uses it in another part of the workbook.
 */
function main(workbook: ExcelScript.Workbook) {
  // Create a named item for a formula.
  // This formula is the sum of the cells F2:F21 on Sheet1.
  const namedItem: ExcelScript.NamedItem = workbook.addNamedItem(
    "GrandTotal", 
    "=SUM(Sheet1!$F$2:$F$21)", 
    "The sum of table sums."
  );

  // Add this named formula to a new sheet in the workbook.
  const otherSheet = workbook.addWorksheet();
  otherSheet.getRange("A1").setFormula(namedItem.getFormula());

  // Switch to the new worksheet.
  otherSheet.activate();
}

addNamedItemFormulaLocal(name, formula, comment)

Adiciona um novo nome à coleção de escopo fornecido usando a localidade do usuário para a fórmula.

addNamedItemFormulaLocal(
            name: string,
            formula: string,
            comment?: string
        ): NamedItem;

Parâmetros

name: string

O nome do item nomeado.

formula: string

A fórmula na localidade do usuário à qual o nome se referirá.

comment: string

Opcional. O comentário associado ao item com nome.

Retornos

ExcelScript.NamedItem

addPivotTable(name, source, destination)

Adicione uma tabela dinâmica com base nos dados de origem especificados e insira-a na célula superior esquerda do intervalo de destino.

addPivotTable(
            name: string,
            source: Range | string | Table,
            destination: Range | string
        ): PivotTable;

Parâmetros

name: string

O nome da nova tabela dinâmica.

source: ExcelScript.Range | string | ExcelScript.Table

Os dados de origem da nova tabela dinâmica podem ser um intervalo (ou um endereço de cadeia, incluindo o nome da folha de cálculo) ou uma tabela.

destination: ExcelScript.Range | string

A célula no canto superior esquerdo do intervalo de destino do relatório de tabela dinâmica (o intervalo na planilha em que o relatório resultante será inserido).

Retornos

ExcelScript.PivotTable

Exemplos

/**
 * This script creates a PivotTable from an existing table and adds it to an existing worksheet.
 * This script assumes there is a table in the current worksheet with columns named "Type" and "Sales".
 * It also assumes there is a worksheet named "PivotSheet".
 */
function main(workbook: ExcelScript.Workbook) {
  // Create a PivotTable based on a table in the current worksheet.
  let sheet = workbook.getActiveWorksheet();
  let table = sheet.getTables()[0];
  let pivotTable = workbook.addPivotTable("My Pivot", table, "PivotSheet!A1");

  // Add fields to the PivotTable to show "Sales" per "Type".
  pivotTable.addRowHierarchy(pivotTable.getHierarchy("Type"));
  pivotTable.addDataHierarchy(pivotTable.getHierarchy("Sales"));
}

addPivotTableStyle(name, makeUniqueName)

Cria um espaço em branco PivotTableStyle com o nome especificado.

addPivotTableStyle(
            name: string,
            makeUniqueName?: boolean
        ): PivotTableStyle;

Parâmetros

name: string

O nome exclusivo do novo estilo de tabela dinâmica. Emitirá um InvalidArgument erro se o nome já estiver a ser utilizado.

makeUniqueName: boolean

Opcional. A predefinição é false. Se true, irá acrescentar números ao nome para torná-lo exclusivo, se necessário.

Retornos

ExcelScript.PivotTableStyle

addPredefinedCellStyle(name)

Adiciona um novo estilo para o conjunto.

addPredefinedCellStyle(name: string): void;

Parâmetros

name: string

Nome do estilo a adicionar.

Retornos

void

addSlicer(slicerSource, sourceField, slicerDestination)

Adiciona uma nova segmentação de dados à pasta de trabalho.

addSlicer(
            slicerSource: string | PivotTable | Table,
            sourceField: string | PivotField | number | TableColumn,
            slicerDestination?: string | Worksheet
        ): Slicer;

Parâmetros

slicerSource: string | ExcelScript.PivotTable | ExcelScript.Table

A origem de dados na qual a nova segmentação de dados será baseada. Pode ser um PivotTable objeto, um Table objeto ou uma cadeia. Quando um objeto de tabela dinâmica é transmitido, a origem de dados é a origem do PivotTable objeto. Quando um Table objeto é transmitido, a origem de dados é o Table objeto . Quando uma cadeia é transmitida, é interpretada como o nome ou ID de uma tabela dinâmica ou tabela.

sourceField: string | ExcelScript.PivotField | number | ExcelScript.TableColumn

O campo na origem de dados pelo qual filtrar. Pode ser um PivotField objeto, um TableColumn objeto, o ID de um PivotField ou o nome ou ID de um TableColumn.

slicerDestination: string | ExcelScript.Worksheet

Opcional. A folha de cálculo na qual a nova segmentação de dados será criada. Pode ser um Worksheet objeto ou o nome ou ID de uma folha de cálculo. Este parâmetro pode ser omitido se a coleção de segmentação de dados for obtida a partir de uma folha de cálculo.

Retornos

ExcelScript.Slicer

Exemplos

/**
 * This script adds a slicer for an existing PivotTable.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the PivotTable named "Farm Pivot".
  const farmPivot = workbook.getPivotTable("Farm Pivot");

  // Create the slicer. 
  // Note that this assumes "Type" is already added as a hierarchy to the PivotTable.
  const fruitSlicer: ExcelScript.Slicer = workbook.addSlicer(
    farmPivot, /* The table or PivotTale to be sliced. */
    farmPivot.getHierarchy("Type").getFields()[0] /* What source field to use as the slicer options. */
  );

  // Select the items to display.
  fruitSlicer.selectItems(["Lemon", "Lime"]);

  // Set the left margin of the slicer.
  fruitSlicer.setLeft(400);
}

addSlicerStyle(name, makeUniqueName)

Cria um estilo de segmentação de dados em branco com o nome especificado.

addSlicerStyle(name: string, makeUniqueName?: boolean): SlicerStyle;

Parâmetros

name: string

O nome exclusivo do novo estilo de segmentação de dados. Emitirá uma exceção InvalidArgument se o nome já estiver a ser utilizado.

makeUniqueName: boolean

Opcional. A predefinição é false. Se true, irá acrescentar números ao nome para torná-lo exclusivo, se necessário.

Retornos

ExcelScript.SlicerStyle

addTable(address, hasHeaders)

Cria uma nova tabela. O objeto de intervalo ou endereço de origem determina a planilha à qual a tabela será adicionada. Se a tabela não puder ser adicionada (por exemplo, porque o endereço é inválido ou a tabela se sobreporia a outra), será gerado um erro.

addTable(address: Range | string, hasHeaders: boolean): Table;

Parâmetros

address: ExcelScript.Range | string

Um Range objeto ou um endereço de cadeia ou nome do intervalo que representa a origem de dados. Se o endereço não contiver o nome de uma planilha, a folha ativa no momento será usada.

hasHeaders: boolean

Um valor booleano que indica se os dados que estão a ser importados têm etiquetas de coluna. Se a origem não contiver cabeçalhos (ou seja, quando esta propriedade estiver definida como false), o Excel irá gerar automaticamente um cabeçalho e deslocar os dados para baixo uma linha.

Retornos

ExcelScript.Table

Exemplos

/**
 * This sample converts the information in the first worksheet
 * into a table with headers.
*/
function main(workbook: ExcelScript.Workbook) {
  // This assumes there is one contiguous range in the first worksheet.
  const dataRange = workbook.getFirstWorksheet().getUsedRange();
  
  // Add a table at the workbook level.
  workbook.addTable(dataRange.getAddress(), true);
}

addTableStyle(name, makeUniqueName)

Cria um espaço em branco TableStyle com o nome especificado.

addTableStyle(name: string, makeUniqueName?: boolean): TableStyle;

Parâmetros

name: string

O nome exclusivo do novo estilo de tabela. Emitirá um InvalidArgument erro se o nome já estiver a ser utilizado.

makeUniqueName: boolean

Opcional. A predefinição é false. Se true, irá acrescentar números ao nome para torná-lo exclusivo, se necessário.

Retornos

ExcelScript.TableStyle

addTimelineStyle(name, makeUniqueName)

Cria um espaço em branco TimelineStyle com o nome especificado.

addTimelineStyle(name: string, makeUniqueName?: boolean): TimelineStyle;

Parâmetros

name: string

O nome exclusivo do novo estilo de linha cronológica. Emitirá um InvalidArgument erro se o nome já estiver a ser utilizado.

makeUniqueName: boolean

Opcional. A predefinição é false. Se true, irá acrescentar números ao nome para torná-lo exclusivo, se necessário.

Retornos

ExcelScript.TimelineStyle

addWorksheet(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() .

addWorksheet(name?: string): 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

ExcelScript.Worksheet

Exemplos

/**
 * This script adds a new worksheet named "Data" to the workbook.
 * If a worksheet with that name already exists, the script logs a note.
 */
function main(workbook: ExcelScript.Workbook) {
  // Check if the "Data" worksheet already exists.
  if (workbook.getWorksheet("Data")) {
    console.log("The Data worksheet is already in the workbook.");
  } else {
    // Add a new worksheet.
    let worksheet = workbook.addWorksheet("Data");
  }
}

breakAllLinksToLinkedWorkbooks()

Quebra todas as ligações para os livros ligados. Depois de as ligações serem quebradas, todas as fórmulas que referenciam ligações de livros são removidas por completo e substituídas pelos valores obtidos mais recentemente.

breakAllLinksToLinkedWorkbooks(): void;

Retornos

void

getActiveCell()

Obtém a célula ativa no momento da pasta de trabalho.

getActiveCell(): Range;

Retornos

ExcelScript.Range

Exemplos

/**
 * This script logs the value of the current active cell. 
 * If multiple cells are selected, the top-leftmost cell will be logged.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current active cell in the workbook.
  let cell = workbook.getActiveCell();
  console.log(`The current cell's value is ${cell.getValue()}`);
}

getActiveChart()

Obtém o gráfico ativo no momento na pasta de trabalho. Se não existir nenhum gráfico ativo, este método devolve undefined.

getActiveChart(): Chart;

Retornos

ExcelScript.Chart

getActiveSlicer()

Obtém a segmentação de dados ativa no momento na pasta de trabalho. Se não existir uma segmentação de dados ativa, este método devolve undefined.

getActiveSlicer(): Slicer;

Retornos

ExcelScript.Slicer

getActiveWorksheet()

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

getActiveWorksheet(): Worksheet;

Retornos

ExcelScript.Worksheet

getApplication()

Representa a instância da aplicação Excel que contém este livro.

getApplication(): Application;

Retornos

ExcelScript.Application

getAutoSave()

Especifica se o livro está no modo guardar automaticamente.

getAutoSave(): boolean;

Retornos

boolean

getBinding(id)

Obtém um objeto de associação pela ID. Se o objeto de enlace não existir, este método devolve undefined.

getBinding(id: string): Binding | undefined;

Parâmetros

id: string

ID do objeto Binding a recuperar.

Retornos

ExcelScript.Binding | undefined

getBindings()

Representa uma coleção de ligações que fazem parte da pasta de trabalho.

getBindings(): Binding[];

Retornos

ExcelScript.Binding[]

getCalculationEngineVersion()

Retorna um número sobre a versão do Mecanismo de Cálculo do Excel.

getCalculationEngineVersion(): number;

Retornos

number

getChartDataPointTrack()

True se todos os gráficos na pasta de trabalho estiverem rastreando os pontos de dados reais aos quais eles estão anexados. Falso se os gráficos controlarem o índice dos pontos de dados.

getChartDataPointTrack(): boolean;

Retornos

boolean

getComment(commentId)

Obtém um comentário da coleção com base em seu ID. Se o objeto de comentário não existir, este método devolve undefined.

getComment(commentId: string): Comment | undefined;

Parâmetros

commentId: string

O identificador do comentário.

Retornos

ExcelScript.Comment | undefined

getCommentByCell(cellAddress)

Obtém o comentário da célula especificada. Se não existir nenhum comentário na célula, é gerado um erro.

getCommentByCell(cellAddress: Range | string): Comment;

Parâmetros

cellAddress: ExcelScript.Range | string

A célula na qual o comentário se encontra. Pode ser um Range objeto ou uma cadeia. Se for uma cadeia, tem de conter o endereço completo, incluindo o nome da folha. É InvalidArgument apresentado um erro se o intervalo fornecido for maior do que uma célula.

Retornos

ExcelScript.Comment

getCommentByReplyId(replyId)

Obtém o comentário ao qual a resposta especificada está ligada.

getCommentByReplyId(replyId: string): Comment;

Parâmetros

replyId: string

O identificador da resposta a comentários.

Retornos

ExcelScript.Comment

getComments()

Representa uma coleção de comentários associados ao livro.

getComments(): Comment[];

Retornos

ExcelScript.Comment[]

getCustomXmlPart(id)

Obtém uma parte XML personalizada com base em sua ID. Se o CustomXmlPart não existir, este método devolve undefined.

getCustomXmlPart(id: string): CustomXmlPart | undefined;

Parâmetros

id: string

ID do objeto a obter.

Retornos

ExcelScript.CustomXmlPart | undefined

getCustomXmlPartByNamespace(namespaceUri)

Aviso

Essa API foi preterida.

Use getCustomXmlPartsByNamespace instead.

Obtém uma nova coleção de partes XML personalizadas cujos espaços de nomes correspondem ao espaço de nomes especificado.

getCustomXmlPartByNamespace(namespaceUri: string): CustomXmlPart[];

Parâmetros

namespaceUri: string

Tem de ser um URI de esquema completamente qualificado; por exemplo, "http://schemas.contoso.com/review/1.0".

Retornos

ExcelScript.CustomXmlPart[]

getCustomXmlParts()

Representa a coleção de peças XML personalizadas contidas neste livro.

getCustomXmlParts(): CustomXmlPart[];

Retornos

ExcelScript.CustomXmlPart[]

getCustomXmlPartsByNamespace(namespaceUri)

Obtém uma nova coleção de partes XML personalizadas cujos espaços de nomes correspondem ao espaço de nomes especificado.

getCustomXmlPartsByNamespace(namespaceUri: string): CustomXmlPart[];

Parâmetros

namespaceUri: string

Tem de ser um URI de esquema completamente qualificado; por exemplo, "http://schemas.contoso.com/review/1.0".

Retornos

ExcelScript.CustomXmlPart[]

getDefaultPivotTableStyle()

Obtém o estilo de Tabela Dinâmica predefinido para o âmbito do objeto principal.

getDefaultPivotTableStyle(): PivotTableStyle;

Retornos

ExcelScript.PivotTableStyle

getDefaultSlicerStyle()

Obtém a predefinição SlicerStyle para o âmbito do objeto principal.

getDefaultSlicerStyle(): SlicerStyle;

Retornos

ExcelScript.SlicerStyle

getDefaultTableStyle()

Obtém o estilo de tabela predefinido para o âmbito do objeto principal.

getDefaultTableStyle(): TableStyle;

Retornos

ExcelScript.TableStyle

getDefaultTimelineStyle()

Obtém o estilo de linha cronológica predefinido para o âmbito do objeto principal.

getDefaultTimelineStyle(): TimelineStyle;

Retornos

ExcelScript.TimelineStyle

getFirstWorksheet(visibleOnly)

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

getFirstWorksheet(visibleOnly?: boolean): Worksheet;

Parâmetros

visibleOnly: boolean

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

Retornos

ExcelScript.Worksheet

getIsDirty()

Especifica se foram feitas alterações desde a última vez que o livro foi guardado. Pode definir esta propriedade como true se pretendesse fechar um livro modificado sem guardá-lo ou ser-lhe pedido para guardá-lo.

getIsDirty(): boolean;

Retornos

boolean

getLastWorksheet(visibleOnly)

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

getLastWorksheet(visibleOnly?: boolean): Worksheet;

Parâmetros

visibleOnly: boolean

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

Retornos

ExcelScript.Worksheet

getLinkedWorkbookByUrl(key)

Obtém informações sobre um livro ligado através do respetivo URL. Se o livro não existir, este método devolve undefined.

getLinkedWorkbookByUrl(key: string): LinkedWorkbook | undefined;

Parâmetros

key: string

O URL do livro ligado.

Retornos

ExcelScript.LinkedWorkbook | undefined

getLinkedWorkbookRefreshMode()

Representa o modo de atualização das ligações do livro. O modo é o mesmo para todas as ligações do livro presentes no livro.

getLinkedWorkbookRefreshMode(): WorkbookLinksRefreshMode;

Retornos

ExcelScript.WorkbookLinksRefreshMode

Exemplos

/**
 * This script refreshes all the links to external workbooks, 
 * if the linked workbook refresh mode is set to manual.
 * To learn about linked workbooks, see https://support.microsoft.com/office/c98d1803-dd75-4668-ac6a-d7cca2a9b95f.
 */
function main(workbook: ExcelScript.Workbook) {
  // Check the refresh mode.
  if (workbook.getLinkedWorkbookRefreshMode() === ExcelScript.WorkbookLinksRefreshMode.manual) {
    console.log("Refreshing workbook links");

    // Trigger a refresh of linked workbook content.
    workbook.refreshAllLinksToLinkedWorkbooks();
  }

getLinkedWorkbooks()

Devolve uma coleção de livros ligados. Nas fórmulas, as ligações do livro podem ser utilizadas para referenciar dados (valores de células e nomes) fora do livro atual.

getLinkedWorkbooks(): LinkedWorkbook[];

Retornos

ExcelScript.LinkedWorkbook[]

Exemplos

/**
 * This script removes all links to other workbooks.
 */
function main(workbook: ExcelScript.Workbook) {
    // Get all the linked workbook references.
    const externalWorkbooks: ExcelScript.LinkedWorkbook[] = workbook.getLinkedWorkbooks();
    console.log(`There are ${externalWorkbooks.length} other workbooks linked to from this workbook.`);

    // Remove all the links to those workbooks.
    // This changes the value of cells with workbook links to "#CONNECT!".
    externalWorkbooks.forEach((workbookLink) => {
        workbookLink.breakLinks();
    });
}

getName()

Obtém o nome da pasta de trabalho.

getName(): string;

Retornos

string

Exemplos

/**
 * This script logs the name of the workbook without the ".xlsx" extension.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the workbook's name.
  let name = workbook.getName();

  // Remove the file extension.
  name = name.substring(0, name.lastIndexOf(".xlsx"));

  // Display the name in the console.
  console.log(name);
}

getNamedItem(name)

Obtém um NamedItem objeto com o respetivo nome. Se o objeto não existir, este método devolve undefined.

getNamedItem(name: string): NamedItem | undefined;

Parâmetros

name: string

Nome nameitem.

Retornos

ExcelScript.NamedItem | undefined

getNames()

Representa uma coleção de itens nomeados com âmbito de livro (intervalos com nome e constantes).

getNames(): NamedItem[];

Retornos

ExcelScript.NamedItem[]

Exemplos

/**
 * This script looks for every named range with "Review" in the name 
 * and marks the range with a yellow fill.
 */
function main(workbook: ExcelScript.Workbook) {
  // Look at every named item in the workbook.
  workbook.getNames().forEach((namedItem) => {
    // Find names containing "Review".
    if (namedItem.getName().includes("Review")) {
      // Only change the fill color if the named item is a range (not a formula).
      let itemType: ExcelScript.NamedItemType = namedItem.getType();
      if (itemType === ExcelScript.NamedItemType.range) {
        // Set the range's fill color to yellow.
        namedItem.getRange().getFormat().getFill().setColor("yellow");
      }
    }
  });
}

getPivotTable(name)

Obtém uma Tabela Dinâmica por nome. Se a tabela dinâmica não existir, este método devolve undefined.

getPivotTable(name: string): PivotTable | undefined;

Parâmetros

name: string

Nome da Tabela Dinâmica a ser recuperada.

Retornos

ExcelScript.PivotTable | undefined

getPivotTables()

Representa uma coleção de Tabelas Dinâmicas associadas à pasta de trabalho.

getPivotTables(): PivotTable[];

Retornos

ExcelScript.PivotTable[]

getPivotTableStyle(name)

Obtém um PivotTableStyle pelo nome. Se o PivotTableStyle não existir, este método devolve undefined.

getPivotTableStyle(name: string): PivotTableStyle | undefined;

Parâmetros

name: string

Nome do estilo de tabela dinâmica a obter.

Retornos

ExcelScript.PivotTableStyle | undefined

getPivotTableStyles()

Representa uma coleção de Tabelas Dinâmicas associadas à pasta de trabalho.

getPivotTableStyles(): PivotTableStyle[];

Retornos

ExcelScript.PivotTableStyle[]

getPredefinedCellStyle(name)

Obtém um estilo por nome. Se o objeto de estilo não existir, este método devolve undefined.

getPredefinedCellStyle(name: string): PredefinedCellStyle | undefined;

Parâmetros

name: string

Nome do estilo a obter.

Retornos

ExcelScript.PredefinedCellStyle | undefined

getPredefinedCellStyles()

Representa uma coleção de estilos associados à pasta de trabalho.

getPredefinedCellStyles(): PredefinedCellStyle[];

Retornos

ExcelScript.PredefinedCellStyle[]

getPreviouslySaved()

Especifica se o livro já foi guardado localmente ou online.

getPreviouslySaved(): boolean;

Retornos

boolean

getProperties()

Obtém as propriedades da pasta de trabalho.

getProperties(): DocumentProperties;

Retornos

ExcelScript.DocumentProperties

getProtection()

Devolve o objeto de proteção de um livro.

getProtection(): WorkbookProtection;

Retornos

ExcelScript.WorkbookProtection

Exemplos

/**
 * This script protects the workbook with a password, if it isn't already protected.
 * The password is provided by the user through a prompt.
 */
function main(workbook: ExcelScript.Workbook, password?: string) {
  // Get the workbook-level protection object.
  const protection = workbook.getProtection();

  // Check if the workbook is already protected.
  if (!protection.getProtected()) {
      // Protect the workbook with the given password.
      // If the optional password was omitted, 
      // no password will be needed to unprotect the workbook.
    protection.protect(password);
  }
}

getQueries()

Devolve uma coleção de consultas do Power Query que fazem parte do livro.

getQueries(): Query[];

Retornos

ExcelScript.Query[]

getQuery(key)

Obtém uma consulta da coleção com base no respetivo nome.

getQuery(key: string): Query;

Parâmetros

key: string

O nome da consulta não é sensível a maiúsculas e minúsculas.

Retornos

ExcelScript.Query

getReadOnly()

Devolve true se o livro estiver aberto no modo só de leitura.

getReadOnly(): boolean;

Retornos

boolean

getSelectedRange()

Obtém o intervalo único selecionado atualmente a partir do livro. Se existirem vários intervalos selecionados, este método gerará um erro.

getSelectedRange(): Range;

Retornos

ExcelScript.Range

getSelectedRanges()

Obtém um ou mais intervalos atualmente selecionados da pasta de trabalho. Ao contrário getSelectedRange()de , este método devolve um RangeAreas objeto que representa todos os intervalos selecionados.

getSelectedRanges(): RangeAreas;

Retornos

ExcelScript.RangeAreas

getSlicer(key)

Obtém uma segmentação de dados com o respetivo nome ou ID. Se a segmentação de dados não existir, este método devolve undefined.

getSlicer(key: string): Slicer | undefined;

Parâmetros

key: string

Nome ou ID da segmentação de dados a obter.

Retornos

ExcelScript.Slicer | undefined

getSlicers()

Representa uma coleção de segmentações de dados associadas ao livro.

getSlicers(): Slicer[];

Retornos

ExcelScript.Slicer[]

getSlicerStyle(name)

Obtém um SlicerStyle pelo nome. Se o estilo de segmentação de dados não existir, este método devolve undefined.

getSlicerStyle(name: string): SlicerStyle | undefined;

Parâmetros

name: string

Nome do estilo de segmentação de dados a obter.

Retornos

ExcelScript.SlicerStyle | undefined

getSlicerStyles()

Representa uma coleção de SlicerStyles associados à pasta de trabalho.

getSlicerStyles(): SlicerStyle[];

Retornos

ExcelScript.SlicerStyle[]

getTable(key)

Obtém uma tabela pelo nome ou ID. Se a tabela não existir, este método devolve undefined.

getTable(key: string): Table | undefined;

Parâmetros

key: string

Nome ou ID da tabela a ser recuperada.

Retornos

ExcelScript.Table | undefined

getTables()

Representa uma coleção de tabelas associadas à pasta de trabalho.

getTables(): Table[];

Retornos

ExcelScript.Table[]

getTableStyle(name)

Obtém um TableStyle pelo nome. Se o estilo de tabela não existir, este método devolve undefined.

getTableStyle(name: string): TableStyle | undefined;

Parâmetros

name: string

Nome do estilo de tabela a obter.

Retornos

ExcelScript.TableStyle | undefined

getTableStyles()

Representa uma coleção de TableStyles associadas à pasta de trabalho.

getTableStyles(): TableStyle[];

Retornos

ExcelScript.TableStyle[]

getTimelineStyle(name)

Obtém um TimelineStyle pelo nome. Se o estilo da linha cronológica não existir, este método devolve undefined.

getTimelineStyle(name: string): TimelineStyle | undefined;

Parâmetros

name: string

Nome do estilo de linha cronológica a obter.

Retornos

ExcelScript.TimelineStyle | undefined

getTimelineStyles()

Representa uma coleção de TimelineStyles associados à pasta de trabalho.

getTimelineStyles(): TimelineStyle[];

Retornos

ExcelScript.TimelineStyle[]

getUsePrecisionAsDisplayed()

True se os cálculos dessa pasta de trabalho forem efetuados usando apenas a precisão dos números conforme forem exibidos. Os dados perderão permanentemente a precisão ao mudar esta propriedade de false para true.

getUsePrecisionAsDisplayed(): boolean;

Retornos

boolean

getWorksheet(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 undefined.

getWorksheet(key: string): Worksheet | undefined;

Parâmetros

key: string

O nome ou ID da folha de cálculo.

Retornos

ExcelScript.Worksheet | undefined

Exemplos

/**
 * This script switches the active view to a worksheet named "Data", if it exists.
 */
function main(workbook: ExcelScript.Workbook) {
  // Check if the "Data" worksheet exists.
  let dataWorksheet = workbook.getWorksheet("Data");
  if (dataWorksheet) {
    // Switch to the "Data" worksheet.
    dataWorksheet.activate();
  } else {
    console.log(`No worksheet named "Data" in this workbook.`);
  }
}

getWorksheets()

Representa uma coleção de planilhas associadas à pasta de trabalho.

getWorksheets(): Worksheet[];

Retornos

ExcelScript.Worksheet[]

Exemplos

/**
 * This script logs the names of all the worksheets in the workbook.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get all the worksheets in the workbook. 
  let sheets = workbook.getWorksheets();

  // Get a list of all the worksheet names.
  let names = sheets.map ((sheet) => sheet.getName());

  // Write in the console all the worksheet names and the total count.
  console.log(names);
  console.log(`Total worksheets inside of this workbook: ${sheets.length}`);
}

refreshAllDataConnections()

Atualiza todas as Ligações de Dados.

refreshAllDataConnections(): void;

Retornos

void

refreshAllLinksToLinkedWorkbooks()

Faz um pedido para atualizar todas as ligações do livro.

refreshAllLinksToLinkedWorkbooks(): void;

Retornos

void

refreshAllPivotTables()

Atualiza todas as tabelas dinâmicas da coleção.

refreshAllPivotTables(): void;

Retornos

void

setChartDataPointTrack(chartDataPointTrack)

True se todos os gráficos na pasta de trabalho estiverem rastreando os pontos de dados reais aos quais eles estão anexados. Falso se os gráficos controlarem o índice dos pontos de dados.

setChartDataPointTrack(chartDataPointTrack: boolean): void;

Parâmetros

chartDataPointTrack: boolean

Retornos

void

setDefaultPivotTableStyle(newDefaultStyle)

Define o estilo de tabela dinâmica predefinido para utilização no âmbito do objeto principal.

setDefaultPivotTableStyle(
            newDefaultStyle: PivotTableStyle | string
        ): void;

Parâmetros

newDefaultStyle: ExcelScript.PivotTableStyle | string

O PivotTableStyle objeto, ou nome do PivotTableStyle objeto, que deve ser a nova predefinição.

Retornos

void

setDefaultSlicerStyle(newDefaultStyle)

Define o estilo de segmentação de dados predefinido para utilização no âmbito do objeto principal.

setDefaultSlicerStyle(newDefaultStyle: SlicerStyle | string): void;

Parâmetros

newDefaultStyle: ExcelScript.SlicerStyle | string

O SlicerStyle objeto, ou nome do SlicerStyle objeto, que deve ser a nova predefinição.

Retornos

void

setDefaultTableStyle(newDefaultStyle)

Define o estilo de tabela predefinido para utilização no âmbito do objeto principal.

setDefaultTableStyle(newDefaultStyle: TableStyle | string): void;

Parâmetros

newDefaultStyle: ExcelScript.TableStyle | string

O TableStyle objeto, ou nome do TableStyle objeto, que deve ser a nova predefinição.

Retornos

void

setDefaultTimelineStyle(newDefaultStyle)

Define o estilo de linha cronológica predefinido para utilização no âmbito do objeto principal.

setDefaultTimelineStyle(newDefaultStyle: TimelineStyle | string): void;

Parâmetros

newDefaultStyle: ExcelScript.TimelineStyle | string

O TimelineStyle objeto, ou nome do TimelineStyle objeto, que deve ser a nova predefinição.

Retornos

void

setIsDirty(isDirty)

setIsDirty(isDirty: boolean): void;

Parâmetros

isDirty: boolean

Retornos

void

setLinkedWorkbookRefreshMode(linkedWorkbookRefreshMode)

Representa o modo de atualização das ligações do livro. O modo é o mesmo para todas as ligações do livro presentes no livro.

setLinkedWorkbookRefreshMode(
            linkedWorkbookRefreshMode: WorkbookLinksRefreshMode
        ): void;

Parâmetros

linkedWorkbookRefreshMode: ExcelScript.WorkbookLinksRefreshMode

Retornos

void

setUsePrecisionAsDisplayed(usePrecisionAsDisplayed)

setUsePrecisionAsDisplayed(usePrecisionAsDisplayed: boolean): void;

Parâmetros

usePrecisionAsDisplayed: boolean

Retornos

void

Compartilhar via

ExcelScript.Workbook interface

Comentários

Exemplos

Métodos

Detalhes do método

addBinding(range, bindingType, id)

Parâmetros

Retornos

addBindingFromNamedItem(name, bindingType, id)

Parâmetros

Retornos

addBindingFromSelection(bindingType, id)

Parâmetros

Retornos

addComment(cellAddress, content, contentType)

Parâmetros

Retornos

addCustomXmlPart(xml)

Parâmetros

Retornos

addNamedItem(name, reference, comment)

Parâmetros

Retornos

Exemplos

addNamedItemFormulaLocal(name, formula, comment)

Parâmetros

Retornos

addPivotTable(name, source, destination)

Parâmetros

Retornos

Exemplos

addPivotTableStyle(name, makeUniqueName)

Parâmetros

Retornos

addPredefinedCellStyle(name)

Parâmetros

Retornos

addSlicer(slicerSource, sourceField, slicerDestination)

Parâmetros

Retornos

Exemplos

addSlicerStyle(name, makeUniqueName)

Parâmetros

Retornos

addTable(address, hasHeaders)

Parâmetros

Retornos

Exemplos

addTableStyle(name, makeUniqueName)

Parâmetros

Retornos

addTimelineStyle(name, makeUniqueName)

Parâmetros

Retornos

addWorksheet(name)

Parâmetros

Retornos

Exemplos

breakAllLinksToLinkedWorkbooks()

Retornos

getActiveCell()

Retornos

Exemplos

getActiveChart()

Retornos

getActiveSlicer()

Retornos

getActiveWorksheet()

Retornos

getApplication()

Retornos

getAutoSave()

Retornos

getBinding(id)

Parâmetros

Retornos

getBindings()

Retornos

getCalculationEngineVersion()