Excel.Workbook class

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

readonly application: Excel.Application;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Especifica se o livro está no modo guardar automaticamente.

readonly autoSave: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

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

readonly bindings: Excel.BindingCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

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

readonly calculationEngineVersion: number;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

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.

chartDataPointTrack: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

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

readonly comments: Excel.CommentCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

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

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

readonly customXmlParts: Excel.CustomXmlPartCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.5 ]

Representa todas as ligações de dados no livro.

readonly dataConnections: Excel.DataConnectionCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

Especifica o período máximo de tempo, em segundos, atribuído a uma fórmula que depende de um serviço de código externo a concluir. O intervalo válido é de 1 a 86400, inclusive.

externalCodeServiceTimeout: number;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi BETA (APENAS PRÉ-VISUALIZAÇÃO) ]

Representa uma coleção de funções de folha de cálculo que podem ser utilizadas para computação.

readonly functions: Excel.Functions;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

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.

isDirty: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Devolve uma coleção de tipos de dados ligados que fazem parte do livro.

readonly linkedDataTypes: Excel.LinkedDataTypeCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi BETA (APENAS PRÉ-VISUALIZAÇÃO) ]

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.

readonly linkedWorkbooks: Excel.LinkedWorkbookCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApiOnline 1.1 ]

Devolve o LocalImage objeto associado ao livro.

readonly localImage: Excel.LocalImage;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi BETA (APENAS PRÉ-VISUALIZAÇÃO) ]

Obtém o nome da pasta de trabalho.

readonly name: string;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

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

readonly names: Excel.NamedItemCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

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

readonly pivotTables: Excel.PivotTableCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.3 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/38-pivottable/pivottable-get-pivottables.yaml

await Excel.run(async (context) => {
  // Get the names of all the PivotTables in the workbook.
  const pivotTables = context.workbook.pivotTables;
  pivotTables.load("name");
  await context.sync();

  // Display the names in the console.
  console.log("PivotTables in the workbook:")
  pivotTables.items.forEach((pivotTable) => {
    console.log(`\t${pivotTable.name}`);
  });
});

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

readonly pivotTableStyles: Excel.PivotTableStyleCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

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

readonly previouslySaved: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Obtém as propriedades da pasta de trabalho.

readonly properties: Excel.DocumentProperties;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/26-document/properties.yaml

await Excel.run(async (context) => {
    let titleValue = "Excel document properties API";
    let subjectValue = "Set and get document properties";
    let keywordsValue = "Set and get operations";
    let commentsValue = "This is an Excel document properties API code sample";
    let categoryValue = "Office Add-ins";
    let managerValue = "John";
    let companyValue = "Microsoft";

    let docProperties = context.workbook.properties;

    // Set the writeable document properties.
    docProperties.title = titleValue;
    docProperties.subject = subjectValue;
    docProperties.keywords = keywordsValue;
    docProperties.comments = commentsValue;
    docProperties.category = categoryValue;
    docProperties.manager = managerValue;
    docProperties.company = companyValue;

    await context.sync();

    console.log("Set the following document properties: title, subject, keywords, comments, category, manager, company.");
});

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

readonly protection: Excel.WorkbookProtection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

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

readonly queries: Excel.QueryCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.14 ]

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

readonly readOnly: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.8 ]

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

readonly settings: Excel.SettingCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.4 ]

Especifica se o painel de lista de campos da tabela dinâmica é apresentado ao nível do livro.

showPivotFieldList: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi BETA (APENAS PRÉ-VISUALIZAÇÃO) ]

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

readonly slicers: Excel.SlicerCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

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

readonly slicerStyles: Excel.SlicerStyleCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

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

readonly styles: Excel.StyleCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/style.yaml

await Excel.run(async (context) => {
    let styles = context.workbook.styles;

    // Add a new style to the style collection.
    // Styles is in the Home tab ribbon.
    styles.add("Diagonal Orientation Style");
          
    let newStyle = styles.getItem("Diagonal Orientation Style");
    
    // The "Diagonal Orientation Style" properties.
    newStyle.textOrientation = 38;
    newStyle.autoIndent = true;
    newStyle.includeProtection = true;
    newStyle.shrinkToFit = true;
    newStyle.locked = false;
    
    await context.sync();

    console.log("Successfully added a new style with diagonal orientation to the Home tab ribbon.");
});

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

readonly tables: Excel.TableCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

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

readonly tableStyles: Excel.TableStyleCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

Devolve uma coleção de tarefas que estão presentes no livro.

readonly tasks: Excel.DocumentTaskCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi BETA (APENAS PRÉ-VISUALIZAÇÃO) ]

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

readonly timelineStyles: Excel.TimelineStyleCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

True se a pasta de trabalho usar o sistema de dados 1904.

use1904DateSystem: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi BETA (APENAS PRÉ-VISUALIZAÇÃO) ]

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.

usePrecisionAsDisplayed: boolean;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

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

readonly worksheets: Excel.WorksheetCollection;

Valor da propriedade

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Fechar a pasta de trabalho atual.

close(closeBehavior?: Excel.CloseBehavior): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.11 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/workbook-save-and-close.yaml

await Excel.run(async (context) => {
    context.workbook.close(Excel.CloseBehavior.save);
});

Fechar a pasta de trabalho atual.

close(closeBehaviorString?: "Save" | "SkipSave"): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.11 ]

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

getActiveCell(): Excel.Range;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/workbook-get-active-cell.yaml

await Excel.run(async (context) => {

    let myWorkbook = context.workbook;
    let activeCell = myWorkbook.getActiveCell();
    activeCell.load("address");

    await context.sync();
    
    console.log("The active cell is " + activeCell.address);
});

Obtém o gráfico ativo no momento na pasta de trabalho. Se não existir nenhum gráfico ativo, é emitida uma exceção ItemNotFound .

getActiveChart(): Excel.Chart;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Obtém o gráfico ativo no momento na pasta de trabalho. Se não existir nenhum gráfico ativo, 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).

getActiveChartOrNullObject(): Excel.Chart;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Obtém a segmentação de dados ativa no momento na pasta de trabalho. Se não existir uma segmentação de dados ativa, é emitida uma exceção ItemNotFound .

getActiveSlicer(): Excel.Slicer;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

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

getActiveSlicerOrNullObject(): Excel.Slicer;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

Devolve true se o livro estiver a ser editado por vários utilizadores (através da cocriação). Tenha em atenção que pode haver algum atraso entre quando o livro status é alterado e quando as alterações são refletidas no resultado do método .

getIsActiveCollabSession(): OfficeExtension.ClientResult<boolean>;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Devolve um LinkedEntityCellValue com base no fornecido LinkedEntityId.

getLinkedEntityCellValue(linkedEntityCellValueId: LinkedEntityId): OfficeExtension.ClientResult<LinkedEntityCellValue>;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.16 ]

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

getSelectedRange(): Excel.Range;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

await Excel.run(async (context) => { 
    const selectedRange = context.workbook.getSelectedRange();
    selectedRange.load('address');
    await context.sync();
    console.log(selectedRange.address);
});

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(): Excel.RangeAreas;

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-areas.yaml

await Excel.run(async (context) => {

    const selectedRanges = context.workbook.getSelectedRanges();
    selectedRanges.format.fill.color = "lightblue";

    await context.sync();
})

Insere as folhas de cálculo especificadas de um livro de origem no livro atual.

Nota*: Atualmente, esta API só é suportada para o Office no Windows, Mac e na Web.

insertWorksheetsFromBase64(base64File: string, options?: Excel.InsertWorksheetOptions): OfficeExtension.ClientResult<string[]>;

Parâmetros

Retornos

Uma matriz de IDs correspondente a cada folha de cálculo recentemente inserida.

Comentários

[ Conjunto de API: ExcelApi 1.13 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/workbook-insert-external-worksheets.yaml

// Retrieve the file and set up an HTML FileReader element. 
const myFile = <HTMLInputElement>document.getElementById("file");
const reader = new FileReader();

reader.onload = (event) => {
    // Remove the metadata before the Base64-encoded string.
    const startIndex = reader.result.toString().indexOf("base64,");
    externalWorkbook = reader.result.toString().substr(startIndex + 7);
};

// Read the file as a data URL so that we can parse the Base64-encoded string.
reader.readAsDataURL(myFile.files[0]);

...

await Excel.run(async (context) => {
    // Retrieve the source workbook.
    const workbook = context.workbook;
    
    // Set up the insert options.
    const options = {
        sheetNamesToInsert: [], // Insert all the worksheets from the source workbook.
        positionType: Excel.WorksheetPositionType.after, // Insert after the `relativeTo` sheet.
        relativeTo: "Sheet1" // The sheet relative to which the other worksheets will be inserted. Used with `positionType`.
    };
    
    // Insert the new worksheets.
    workbook.insertWorksheetsFromBase64(externalWorkbook, options);
    await context.sync();
});

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.WorkbookLoadOptions): Excel.Workbook;

Parâmetros

Retornos

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

Parâmetros

Retornos

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.Workbook;

Parâmetros

Retornos

Salvar a pasta de trabalho atual.

save(saveBehavior?: Excel.SaveBehavior): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.11 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/workbook-save-and-close.yaml

await Excel.run(async (context) => {
    context.workbook.save(Excel.SaveBehavior.save);
});

Salvar a pasta de trabalho atual.

save(saveBehaviorString?: "Save" | "Prompt"): void;

Parâmetros

Retornos

Comentários

[ Conjunto de API: ExcelApi 1.11 ]

Define várias propriedades de um objeto ao mesmo tempo. Pode transmitir um objeto simples com as propriedades adequadas ou outro objeto de API do mesmo tipo.

set(properties: Interfaces.WorkbookUpdateData, options?: OfficeExtension.UpdateOptions): void;

Parâmetros

Retornos

Define várias propriedades no objeto ao mesmo tempo, com base num objeto carregado existente.

set(properties: Excel.Workbook): void;

Parâmetros

Retornos

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.Workbook é um objeto de API, o toJSON método devolve um objeto JavaScript simples (escrito como Excel.Interfaces.WorkbookData) que contém cópias rasas de quaisquer propriedades subordinadas carregadas do objeto original.

toJSON(): Excel.Interfaces.WorkbookData;

Retornos

Ocorre quando o livro é ativado. Nota: este evento não será acionado quando o livro for aberto.

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

Tipo de evento

Comentários

[ Conjunto de API: ExcelApi 1.13 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-workbook-activated.yaml

async function workbookActivated(event: Excel.WorkbookActivatedEventArgs) {
  await Excel.run(async (context) => {
    // Callback function for when the workbook is activated.
    console.log("The workbook was activated.");
  });
}

...

await Excel.run(async (context) => {
  const workbook = context.workbook;

  // Register the workbook activated event handler.
  workbook.onActivated.add(workbookActivated);

  await context.sync();
  console.log("Added event handler for workbook activated.");
});

Ocorre quando a definição Guardar Automaticamente é alterada no livro.

readonly onAutoSaveSettingChanged: OfficeExtension.EventHandlers<Excel.WorkbookAutoSaveSettingChangedEventArgs>;

Tipo de evento

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Ocorre quando a seleção no documento é alterada.

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

Tipo de evento

Comentários

[ Conjunto de API: ExcelApi 1.2 ]