Excel.Workbook class
O livro é o objeto de nível superior que contém objetos relacionados do livro, como folhas de cálculo, tabelas e intervalos. Para saber mais sobre o modelo de objeto do livro, leia Trabalhar com livros com a API javaScript do Excel.
- Extends
Comentários
[ Conjunto de API: ExcelApi 1.1 ]
Propriedades
| application | Representa a instância da aplicação Excel que contém este livro. |
| auto |
Especifica se o livro está no modo guardar automaticamente. |
| bindings | Representa uma coleção de ligações que fazem parte da pasta de trabalho. |
| calculation |
Retorna um número sobre a versão do Mecanismo de Cálculo do Excel. |
| chart |
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. |
| custom |
Representa a coleção de peças XML personalizadas contidas neste livro. |
| data |
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. |
| is |
Especifica se foram feitas alterações desde a última vez que o livro foi guardado. Pode definir esta propriedade como |
| 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). |
| pivot |
Representa uma coleção de Tabelas Dinâmicas associadas à pasta de trabalho. |
| pivot |
Representa uma coleção de Tabelas Dinâmicas associadas à pasta de trabalho. |
| previously |
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. |
| queries | Devolve uma coleção de Power Query consultas que fazem parte do livro. |
| read |
Devolve |
| settings | Representa uma coleção de definições associadas ao livro. |
| slicers | Representa uma coleção de segmentações de dados associadas ao livro. |
| slicer |
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. |
| table |
Representa uma coleção de TableStyles associadas à pasta de trabalho. |
| timeline |
Representa uma coleção de TimelineStyles associados à pasta de trabalho. |
| use |
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 |
| worksheets | Representa uma coleção de planilhas associadas à pasta de trabalho. |
Métodos
| close(close |
Fechar a pasta de trabalho atual. |
| close(close |
Fechar a pasta de trabalho atual. |
| get |
Obtém a célula ativa no momento da pasta de trabalho. |
| get |
Obtém o gráfico ativo no momento na pasta de trabalho. Se não existir nenhum gráfico ativo, é emitida uma exceção |
| get |
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 |
| get |
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 |
| get |
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 |
| get |
Devolve |
| get |
Devolve um |
| get |
Obtém o intervalo único selecionado atualmente a partir do livro. Se existirem vários intervalos selecionados, este método gerará um erro. |
| get |
Obtém um ou mais intervalos atualmente selecionados da pasta de trabalho. Ao contrário |
| insert |
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. |
| load(options) | Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar |
| load(property |
Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar |
| load(property |
Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar |
| save(save |
Salvar a pasta de trabalho atual. |
| save(save |
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 |
Eventos
| on |
Ocorre quando o livro é ativado. Nota: este evento não será acionado quando o livro for aberto. |
| on |
Ocorre quando a definição Guardar Automaticamente é alterada no livro. |
| on |
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
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
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
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
customXmlParts
Representa a coleção de peças XML personalizadas contidas neste livro.
readonly customXmlParts: Excel.CustomXmlPartCollection;Valor da propriedade
Comentários
dataConnections
Representa todas as ligações de dados no livro.
readonly dataConnections: Excel.DataConnectionCollection;Valor da propriedade
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
Comentários
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
Comentários
pivotTables
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}`);
});
});
pivotTableStyles
Representa uma coleção de Tabelas Dinâmicas associadas à pasta de trabalho.
readonly pivotTableStyles: Excel.PivotTableStyleCollection;Valor da propriedade
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
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.");
});
protection
Devolve o objeto de proteção de um livro.
readonly protection: Excel.WorkbookProtection;Valor da propriedade
Comentários
queries
Devolve uma coleção de Power Query consultas que fazem parte do livro.
readonly queries: Excel.QueryCollection;Valor da propriedade
Comentários
readOnly
Devolve true se o livro estiver aberto no modo só de leitura.
readonly readOnly: boolean;Valor da propriedade
boolean
Comentários
settings
Representa uma coleção de definições associadas ao livro.
readonly settings: Excel.SettingCollection;Valor da propriedade
Comentários
slicers
Representa uma coleção de segmentações de dados associadas ao livro.
readonly slicers: Excel.SlicerCollection;Valor da propriedade
Comentários
slicerStyles
Representa uma coleção de SlicerStyles associados à pasta de trabalho.
readonly slicerStyles: Excel.SlicerStyleCollection;Valor da propriedade
Comentários
styles
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.");
});
tables
Representa uma coleção de tabelas associadas à pasta de trabalho.
readonly tables: Excel.TableCollection;Valor da propriedade
Comentários
tableStyles
Representa uma coleção de TableStyles associadas à pasta de trabalho.
readonly tableStyles: Excel.TableStyleCollection;Valor da propriedade
Comentários
timelineStyles
Representa uma coleção de TimelineStyles associados à pasta de trabalho.
readonly timelineStyles: Excel.TimelineStyleCollection;Valor da propriedade
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
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
[ 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);
});
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
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);
});
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
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
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
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
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
getLinkedEntityCellValue(linkedEntityCellValueId)
Devolve um LinkedEntityCellValue com base no fornecido LinkedEntityId.
getLinkedEntityCellValue(linkedEntityCellValueId: LinkedEntityId): OfficeExtension.ClientResult<LinkedEntityCellValue>;Parâmetros
- linkedEntityCellValueId
- Excel.LinkedEntityId
Um identificador que especifica um indivíduo LinkedEntityCellValue.
Retornos
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
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);
});
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
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();
})
insertWorksheetsFromBase64(base64File, options)
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
- base64File
-
string
Obrigatório. A cadeia codificada em Base64 que representa o ficheiro do livro de origem.
- options
- Excel.InsertWorksheetOptions
Opcional. As opções que definem as folhas de cálculo a inserir e onde serão inseridas as novas folhas de cálculo no livro. Por predefinição, todas as folhas de cálculo do livro de origem são inseridas no final do livro atual.
Retornos
OfficeExtension.ClientResult<string[]>
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();
});
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
Fornece opções para as propriedades do objeto a carregar.
Retornos
load(propertyNames)
Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.
load(propertyNames?: string | string[]): Excel.Workbook;Parâmetros
- propertyNames
-
string | string[]
Uma cadeia delimitada por vírgulas ou uma matriz de cadeias que especificam as propriedades a carregar.
Retornos
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
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
[ 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);
});
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
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
Detalhes do evento
onActivated
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.");
});
onAutoSaveSettingChanged
Ocorre quando a definição Guardar Automaticamente é alterada no livro.
readonly onAutoSaveSettingChanged: OfficeExtension.EventHandlers<Excel.WorkbookAutoSaveSettingChangedEventArgs>;Tipo de evento
Comentários
onSelectionChanged
Ocorre quando a seleção no documento é alterada.
readonly onSelectionChanged: OfficeExtension.EventHandlers<Excel.SelectionChangedEventArgs>;