ExcelScript.Workbook interface

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

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

Parâmetros

Retornos

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, o InvalidReference erro será retornado.

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

Parâmetros

Retornos

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

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

Parâmetros

Retornos

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

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

Parâmetros

Retornos

Adiciona uma nova parte XML personalizada à pasta de trabalho.

addCustomXmlPart(xml: string): CustomXmlPart;

Parâmetros

Retornos

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

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

Parâmetros

Retornos

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

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

Retornos

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

Retornos

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

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

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

Parâmetros

Retornos

Adiciona um novo estilo para o conjunto.

addPredefinedCellStyle(name: string): void;

Parâmetros

Retornos

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

Retornos

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

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

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

Parâmetros

Retornos

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

Retornos

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

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

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

Parâmetros

Retornos

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

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

Parâmetros

Retornos

Adiciona uma nova planilha à pasta de trabalho. A planilha será adicionada ao final das planilhas existentes. Se quiser ativar a planilha recém-adicionada, chame-a .activate() .

addWorksheet(name?: string): Worksheet;

Parâmetros

Retornos

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

Quebra todos os links para as pastas de trabalho vinculadas. Depois que os links são quebrados, todas as fórmulas que fazem referência a links de pasta de trabalho são removidas inteiramente e substituídas pelos valores recuperados mais recentemente.

breakAllLinksToLinkedWorkbooks(): void;

Retornos

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

getActiveCell(): Range;

Retornos

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

Obtém o gráfico ativo no momento na pasta de trabalho. Se não houver um gráfico ativo, esse método retornará undefined.

getActiveChart(): Chart;

Retornos

Obtém a segmentação de dados ativa no momento na pasta de trabalho. Se não houver nenhuma segmentação ativa, esse método retornará undefined.

getActiveSlicer(): Slicer;

Retornos

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

getActiveWorksheet(): Worksheet;

Retornos

Representa a instância do aplicativo Excel que contém esta pasta de trabalho.

getApplication(): Application;

Retornos

Especifica se a pasta de trabalho está no modo de Salvamento Automático.

getAutoSave(): boolean;

Retornos

Obtém um objeto de associação pela ID. Se o objeto de associação não existir, esse método retornará undefined.

getBinding(id: string): Binding | undefined;

Parâmetros

Retornos

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

getBindings(): Binding[];

Retornos

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

getCalculationEngineVersion(): number;

Retornos

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 acompanharem o índice dos pontos de dados.

getChartDataPointTrack(): boolean;

Retornos

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

getComment(commentId: string): Comment | undefined;

Parâmetros

Retornos

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

getCommentByCell(cellAddress: Range | string): Comment;

Parâmetros

Retornos

Obtém o comentário ao qual a resposta fornecida está conectada.

getCommentByReplyId(replyId: string): Comment;

Parâmetros

Retornos

Representa uma coleção de comentários associados à pasta de trabalho.

getComments(): Comment[];

Retornos

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

getCustomXmlPart(id: string): CustomXmlPart | undefined;

Parâmetros

Retornos

Obtém uma nova coleção de partes XML personalizadas cujos namespaces correspondem ao namespace fornecido.

getCustomXmlPartByNamespace(namespaceUri: string): CustomXmlPart[];

Parâmetros

Retornos

Representa a coleção de partes XML personalizadas contidas nessa pasta de trabalho.

getCustomXmlParts(): CustomXmlPart[];

Retornos

Obtém uma nova coleção de partes XML personalizadas cujos namespaces correspondem ao namespace fornecido.

getCustomXmlPartsByNamespace(namespaceUri: string): CustomXmlPart[];

Parâmetros

Retornos

Obtém o estilo padrão de Tabela Dinâmica para o escopo do objeto pai.

getDefaultPivotTableStyle(): PivotTableStyle;

Retornos

Obtém o padrão SlicerStyle para o escopo do objeto pai.

getDefaultSlicerStyle(): SlicerStyle;

Retornos

Obtém o estilo de tabela padrão para o escopo do objeto pai.

getDefaultTableStyle(): TableStyle;

Retornos

Obtém o estilo de linha do tempo padrão para o escopo do objeto pai.

getDefaultTimelineStyle(): TimelineStyle;

Retornos

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

getFirstWorksheet(visibleOnly?: boolean): Worksheet;

Parâmetros

Retornos

Especifica se as alterações foram feitas desde que a pasta de trabalho foi salva pela última vez. Você pode definir essa propriedade true como se quiser fechar uma pasta de trabalho modificada sem salvá-la ou ser solicitado a salvá-la.

getIsDirty(): boolean;

Retornos

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

getLastWorksheet(visibleOnly?: boolean): Worksheet;

Parâmetros

Retornos

Obtém informações sobre uma pasta de trabalho vinculada por sua URL. Se a pasta de trabalho não existir, esse método retornará undefined.

getLinkedWorkbookByUrl(key: string): LinkedWorkbook | undefined;

Parâmetros

Retornos

Representa o modo de atualização dos links da pasta de trabalho. O modo é o mesmo para todos os links de pasta de trabalho presentes na pasta de trabalho.

getLinkedWorkbookRefreshMode(): WorkbookLinksRefreshMode;

Retornos

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

Retorna uma coleção de pastas de trabalho vinculadas. Em fórmulas, os links da pasta de trabalho podem ser usados para fazer referência a dados (valores e nomes de célula) fora da pasta de trabalho atual.

getLinkedWorkbooks(): LinkedWorkbook[];

Retornos

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

Obtém o nome da pasta de trabalho.

getName(): string;

Retornos

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

Obtém um NamedItem objeto usando seu nome. Se o objeto não existir, esse método retornará undefined.

getNamedItem(name: string): NamedItem | undefined;

Parâmetros

Retornos

Representa uma coleção de itens nomeados no escopo da pasta de trabalho (intervalos nomeados e constantes).

getNames(): NamedItem[];

Retornos

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

Obtém uma Tabela Dinâmica por nome. Se a Tabela Dinâmica não existir, esse método retornará undefined.

getPivotTable(name: string): PivotTable | undefined;

Parâmetros

Retornos

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

getPivotTables(): PivotTable[];

Retornos

Recebe um PivotTableStyle por nome. Se o PivotTableStyle não existir, esse método retornará undefined.

getPivotTableStyle(name: string): PivotTableStyle | undefined;

Parâmetros

Retornos

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

getPivotTableStyles(): PivotTableStyle[];

Retornos

Obtém um estilo por nome. Se o objeto de estilo não existir, esse método retornará undefined.

getPredefinedCellStyle(name: string): PredefinedCellStyle | undefined;

Parâmetros

Retornos

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

getPredefinedCellStyles(): PredefinedCellStyle[];

Retornos

Especifica se a pasta de trabalho já foi salva localmente ou online.

getPreviouslySaved(): boolean;

Retornos

Obtém as propriedades da pasta de trabalho.

getProperties(): DocumentProperties;

Retornos

Retorna o objeto de proteção para uma pasta de trabalho.

getProtection(): WorkbookProtection;

Retornos

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

Retorna uma coleção de consultas do Power Query que fazem parte da pasta de trabalho.

getQueries(): Query[];

Retornos

Obtém uma consulta da coleção com base em seu nome.

getQuery(key: string): Query;

Parâmetros

Retornos

Retorna true se a pasta de trabalho estiver aberta no modo somente leitura.

getReadOnly(): boolean;

Retornos

Obtém o intervalo único selecionado no momento da pasta de trabalho. Se houver vários intervalos selecionados, esse método gerará um erro.

getSelectedRange(): Range;

Retornos

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

getSelectedRanges(): RangeAreas;

Retornos

Obtém uma segmentação usando seu nome ou ID. Se a segmentação não existir, esse método retornará undefined.

getSlicer(key: string): Slicer | undefined;

Parâmetros

Retornos

Representa uma coleção de segmentações de dados associada à pasta de trabalho.

getSlicers(): Slicer[];

Retornos

Recebe um SlicerStyle por nome. Se o estilo de segmentação não existir, esse método retornará undefined.

getSlicerStyle(name: string): SlicerStyle | undefined;

Parâmetros

Retornos

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

getSlicerStyles(): SlicerStyle[];

Retornos

Obtém uma tabela pelo nome ou ID. Se a tabela não existir, esse método retornará undefined.

getTable(key: string): Table | undefined;

Parâmetros

Retornos

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

getTables(): Table[];

Retornos

Recebe um TableStyle por nome. Se o estilo de tabela não existir, esse método retornará undefined.

getTableStyle(name: string): TableStyle | undefined;

Parâmetros

Retornos

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

getTableStyles(): TableStyle[];

Retornos

Recebe um TimelineStyle por nome. Se o estilo da linha do tempo não existir, esse método retornará undefined.

getTimelineStyle(name: string): TimelineStyle | undefined;

Parâmetros

Retornos

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

getTimelineStyles(): TimelineStyle[];

Retornos

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 alternar essa propriedade de false para true.

getUsePrecisionAsDisplayed(): boolean;

Retornos

Obtém um objeto de planilha usando o nome ou ID dele. Se a planilha não existir, esse método retornará undefined.

getWorksheet(key: string): Worksheet | undefined;

Parâmetros

Retornos

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

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

getWorksheets(): Worksheet[];

Retornos

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

Atualiza todas as conexões de dados.

refreshAllDataConnections(): void;

Retornos

Faz uma solicitação para atualizar todos os links da pasta de trabalho.

refreshAllLinksToLinkedWorkbooks(): void;

Retornos

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

refreshAllPivotTables(): void;

Retornos

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 acompanharem o índice dos pontos de dados.

setChartDataPointTrack(chartDataPointTrack: boolean): void;

Parâmetros

Retornos

Define o estilo padrão da Tabela Dinâmica para uso no escopo do objeto pai.

setDefaultPivotTableStyle(
            newDefaultStyle: PivotTableStyle | string
        ): void;

Parâmetros

Retornos

Define o estilo de segmentação padrão para uso no escopo do objeto pai.

setDefaultSlicerStyle(newDefaultStyle: SlicerStyle | string): void;

Parâmetros

Retornos

Define o estilo de tabela padrão para uso no escopo do objeto pai.

setDefaultTableStyle(newDefaultStyle: TableStyle | string): void;

Parâmetros

Retornos

Define o estilo de linha do tempo padrão para uso no escopo do objeto pai.

setDefaultTimelineStyle(newDefaultStyle: TimelineStyle | string): void;

Parâmetros

Retornos

Especifica se as alterações foram feitas desde que a pasta de trabalho foi salva pela última vez. Você pode definir essa propriedade true como se quiser fechar uma pasta de trabalho modificada sem salvá-la ou ser solicitado a salvá-la.

setIsDirty(isDirty: boolean): void;

Parâmetros

Retornos

Representa o modo de atualização dos links da pasta de trabalho. O modo é o mesmo para todos os links de pasta de trabalho presentes na pasta de trabalho.

setLinkedWorkbookRefreshMode(
            linkedWorkbookRefreshMode: WorkbookLinksRefreshMode
        ): void;

Parâmetros

Retornos

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 alternar essa propriedade de false para true.

setUsePrecisionAsDisplayed(usePrecisionAsDisplayed: boolean): void;

Parâmetros

Retornos