Excel. Workbook class

Propriedades

application	Representa a instância da aplicação Excel que contém este livro.
autoSave	Especifica se o livro está no modo guardar automaticamente.
bindings	Representa uma coleção de ligações que fazem parte da pasta de trabalho.
calculationEngineVersion	Retorna um número sobre a versão do Mecanismo de Cálculo do Excel.
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.
comments	Representa uma coleção de comentários associados ao livro.
context	O contexto do pedido associado ao objeto . Esta ação liga o processo do suplemento ao processo da aplicação anfitriã do Office.
customXmlParts	Representa a coleção de peças XML personalizadas contidas neste livro.
dataConnections	Representa todas as ligações de dados no livro.
functions	Representa uma coleção de funções de folha de cálculo que podem ser utilizadas para computação.
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.
name	Obtém o nome da pasta de trabalho.
names	Representa uma coleção de itens nomeados com âmbito de livro (intervalos com nome e constantes).
pivotTables	Representa uma coleção de Tabelas Dinâmicas associadas à pasta de trabalho.
pivotTableStyles	Representa uma coleção de Tabelas Dinâmicas associadas à pasta de trabalho.
previouslySaved	Especifica se o livro já foi guardado localmente ou online.
properties	Obtém as propriedades da pasta de trabalho.
protection	Devolve o objeto de proteção de um livro.
readOnly	Devolve `true` se o livro estiver aberto no modo só de leitura.
settings	Representa uma coleção de definições associadas ao livro.
slicers	Representa uma coleção de segmentações de dados associadas ao livro.
slicerStyles	Representa uma coleção de SlicerStyles associados à pasta de trabalho.
styles	Representa uma coleção de estilos associados à pasta de trabalho.
tables	Representa uma coleção de tabelas associadas à pasta de trabalho.
tableStyles	Representa uma coleção de TableStyles associadas à pasta de trabalho.
timelineStyles	Representa uma coleção de TimelineStyles associados à pasta de trabalho.
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`.
worksheets	Representa uma coleção de planilhas associadas à pasta de trabalho.

Métodos

close(closeBehavior)	Fechar a pasta de trabalho atual.
close(closeBehaviorString)	Fechar a pasta de trabalho atual.
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, é emitida uma exceção `ItemNotFound` .
getActiveChartOrNullObject()	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).
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, é emitida uma exceção `ItemNotFound` .
getActiveSlicerOrNullObject()	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).
getIsActiveCollabSession()	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 .
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.
load(options)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar `context.sync()` antes de ler as propriedades.
load(propertyNames)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar `context.sync()` antes de ler as propriedades.
load(propertyNamesAndPaths)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar `context.sync()` antes de ler as propriedades.
save(saveBehavior)	Salvar a pasta de trabalho atual.
save(saveBehaviorString)	Salvar a pasta de trabalho atual.
set(properties, options)	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)	Define várias propriedades no objeto ao mesmo tempo, com base num objeto carregado existente.
toJSON()	Substitui o método JavaScript `toJSON()` para fornecer uma saída mais útil quando um objeto de API é transmitido para `JSON.stringify()`. (`JSON.stringify`por sua vez, chama o `toJSON` método do objeto que lhe é transmitido.) Enquanto o objeto original `Excel.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.

Eventos

onAutoSaveSettingChanged	Ocorre quando a definição Guardar Automaticamente é alterada no livro.
onSelectionChanged	Ocorre quando a seleção no documento é alterada.

Detalhes da propriedade

application

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

readonly application: Excel.Application;

Valor da propriedade

Excel.Application

Comentários

autoSave

Especifica se o livro está no modo guardar automaticamente.

readonly autoSave: boolean;

Valor da propriedade

boolean

Comentários

bindings

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

readonly bindings: Excel.BindingCollection;

Valor da propriedade

Excel.BindingCollection

Comentários

calculationEngineVersion

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

readonly calculationEngineVersion: number;

Valor da propriedade

number

Comentários

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.

chartDataPointTrack: boolean;

Valor da propriedade

boolean

Comentários

comments

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

readonly comments: Excel.CommentCollection;

Valor da propriedade

Excel.CommentCollection

Comentários

context

O contexto do pedido associado ao objeto . Esta ação liga o processo do suplemento ao processo da aplicação anfitriã do Office.

context: RequestContext;

Valor da propriedade

Excel.RequestContext

customXmlParts

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

readonly customXmlParts: Excel.CustomXmlPartCollection;

Valor da propriedade

Excel.CustomXmlPartCollection

Comentários

[ Conjunto de API: ExcelApi 1.5 ]

dataConnections

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

readonly dataConnections: Excel.DataConnectionCollection;

Valor da propriedade

Excel.DataConnectionCollection

Comentários

functions

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

Excel.Functions

Comentários

[ Conjunto de API: ExcelApi 1.2 ]

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.

isDirty: boolean;

Valor da propriedade

boolean

Comentários

name

Obtém o nome da pasta de trabalho.

readonly name: string;

Valor da propriedade

string

Comentários

names

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

readonly names: Excel.NamedItemCollection;

Valor da propriedade

Excel.NamedItemCollection

Comentários

pivotTables

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

readonly pivotTables: Excel.PivotTableCollection;

Valor da propriedade

Excel.PivotTableCollection

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

pivotTableStyles

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

readonly pivotTableStyles: Excel.PivotTableStyleCollection;

Valor da propriedade

Excel.PivotTableStyleCollection

Comentários

previouslySaved

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

readonly previouslySaved: boolean;

Valor da propriedade

boolean

Comentários

properties

Obtém as propriedades da pasta de trabalho.

readonly properties: Excel.DocumentProperties;

Valor da propriedade

Excel.DocumentProperties

Comentários

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

protection

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

readonly protection: Excel.WorkbookProtection;

Valor da propriedade

Excel.WorkbookProtection

Comentários

readOnly

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

readonly readOnly: boolean;

Valor da propriedade

boolean

Comentários

[ Conjunto de API: ExcelApi 1.8 ]

settings

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

readonly settings: Excel.SettingCollection;

Valor da propriedade

Excel.SettingCollection

Comentários

[ Conjunto de API: ExcelApi 1.4 ]

slicers

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

readonly slicers: Excel.SlicerCollection;

Valor da propriedade

Excel.SlicerCollection

Comentários

slicerStyles

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

readonly slicerStyles: Excel.SlicerStyleCollection;

Valor da propriedade

Excel.SlicerStyleCollection

Comentários

styles

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

readonly styles: Excel.StyleCollection;

Valor da propriedade

Excel.StyleCollection

Comentários

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

tables

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

readonly tables: Excel.TableCollection;

Valor da propriedade

Excel.TableCollection

Comentários

tableStyles

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

readonly tableStyles: Excel.TableStyleCollection;

Valor da propriedade

Excel.TableStyleCollection

Comentários

timelineStyles

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

readonly timelineStyles: Excel.TimelineStyleCollection;

Valor da propriedade

Excel.TimelineStyleCollection

Comentários

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.

usePrecisionAsDisplayed: boolean;

Valor da propriedade

boolean

Comentários

worksheets

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

readonly worksheets: Excel.WorksheetCollection;

Valor da propriedade

Excel.WorksheetCollection

Comentários

Detalhes do método

close(closeBehavior)

Fechar a pasta de trabalho atual.

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

Parâmetros

closeBehavior: Excel.CloseBehavior

comportamento de fecho do livro.

Retornos

void

Comentários

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

close(closeBehaviorString)

Fechar a pasta de trabalho atual.

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

Parâmetros

closeBehaviorString: "Save" | "SkipSave"

comportamento de fecho do livro.

Retornos

void

Comentários

getActiveCell()

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

getActiveCell(): Excel.Range;

Retornos

Excel.Range

Comentários

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

getActiveChart()

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

Excel.Chart

Comentários

getActiveChartOrNullObject()

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

Excel.Chart

Comentários

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, é emitida uma exceção ItemNotFound .

getActiveSlicer(): Excel.Slicer;

Retornos

Excel.Slicer

Comentários

getActiveSlicerOrNullObject()

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

Excel.Slicer

Comentários

getIsActiveCollabSession()

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

OfficeExtension.ClientResult<boolean>

Comentários

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

Retornos

Excel.Range

Comentários

Exemplos

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

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

Retornos

Excel.RangeAreas

Comentários

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

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

Parâmetros

options: Excel.Interfaces.WorkbookLoadOptions

Fornece opções para as propriedades do objeto a carregar.

Retornos

Excel.Workbook

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

Parâmetros

propertyNames: string | string[]

Uma cadeia delimitada por vírgulas ou uma matriz de cadeias que especificam as propriedades a carregar.

Retornos

Excel.Workbook

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?: {
            select?: string;
            expand?: string;
        }): Excel.Workbook;

Parâmetros

propertyNamesAndPaths: { select?: string; expand?: string; }

propertyNamesAndPaths.select é uma cadeia delimitada por vírgulas que especifica as propriedades a carregar e propertyNamesAndPaths.expand é uma cadeia delimitada por vírgulas que especifica as propriedades de navegação a carregar.

Retornos

Excel.Workbook

save(saveBehavior)

Salvar a pasta de trabalho atual.

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

Parâmetros

saveBehavior: Excel.SaveBehavior

O comportamento de guardar tem de ser "Guardar" ou "Pedido". O valor predefinido é "Guardar".

Retornos

void

Comentários

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

save(saveBehaviorString)

Salvar a pasta de trabalho atual.

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

Parâmetros

saveBehaviorString: "Save" | "Prompt"

O comportamento de guardar tem de ser "Guardar" ou "Pedido". O valor predefinido é "Guardar".

Retornos

void

Comentários

OfficeExtension.EventHandlers<Excel.WorkbookAutoSaveSettingChangedEventArgs>

set(properties, options)

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

properties: Excel.Interfaces.WorkbookUpdateData

Um objeto JavaScript com propriedades que são estruturadas isomorfoticamente para as propriedades do objeto no qual o método é chamado.

options: OfficeExtension.UpdateOptions

Fornece uma opção para suprimir erros se o objeto de propriedades tentar definir quaisquer propriedades só de leitura.

Retornos

void

set(properties)

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

set(properties: Excel.Workbook): void;

Parâmetros

properties: Excel.Workbook

Retornos

void

toJSON()

Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é transmitido para JSON.stringify(). (JSON.stringifypor sua vez, chama o toJSON método do objeto que lhe é transmitido.) Enquanto o objeto original Excel.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

Excel.Interfaces.WorkbookData

Detalhes do evento

onAutoSaveSettingChanged

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

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

Tipo de evento

Comentários