Excel.Workbook class
Workbook es el objeto de nivel superior que contiene objetos de libro relacionados, como hojas de cálculo, tablas y rangos. Para obtener más información sobre el modelo de objetos de libro, lea Trabajo con libros mediante la API de JavaScript de Excel.
- Extends
Comentarios
[ Conjunto de API: ExcelApi 1.1 ]
Propiedades
application | Representa la instancia de la aplicación de Excel que contiene este libro. |
auto |
Especifica si el libro está en modo autoguardado. |
bindings | Representa una colección de enlaces que forman parte del libro. |
calculation |
Devuelve un número acerca de la versión del motor de cálculo de Excel. |
chart |
True si todos los gráficos en el libro están siguiendo los puntos de datos reales a los que están conectados. False si los gráficos realizan un seguimiento del índice de los puntos de datos. |
comments | Representa una colección de comentarios asociados al libro. |
context | Contexto de solicitud asociado al objeto . Esto conecta el proceso del complemento al proceso de la aplicación host de Office. |
custom |
Representa la colección de elementos XML personalizados contenidos en este libro. |
data |
Representa todas las conexiones de datos del libro. |
functions | Representa una colección de funciones de hoja de cálculo que se pueden usar para el cálculo. |
is |
Especifica si se han realizado cambios desde la última vez que se guardó el libro. Puede establecer esta propiedad |
name | Obtiene el nombre del libro. |
names | Representa una colección de elementos con nombre con ámbito de libro (intervalos y constantes con nombre). |
pivot |
Representa una colección de tablas dinámicas asociadas con el libro. |
pivot |
Representa una colección de PivotTableStyles asociados con el libro. |
previously |
Especifica si el libro se ha guardado alguna vez localmente o en línea. |
properties | Obtiene las propiedades del libro. |
protection | Devuelve el objeto de protección de un libro. |
read |
Devuelve |
settings | Representa una colección de valores asociados al libro. |
slicers | Representa una colección de segmentaciones de datos asociadas al libro. |
slicer |
Representa una colección de SlicerStyles asociados con el libro. |
styles | Representa una colección de estilos asociada con el libro. |
tables | Representa una colección de tablas asociadas con el libro. |
table |
Representa una colección de TableStyles asociados con el libro. |
timeline |
Representa una colección de TimelineStyles asociados con el libro. |
use |
True si los cálculos de este libro se llevan a cabo con la misma precisión con que se muestran los números. Los datos perderán precisión de forma permanente al cambiar esta propiedad de |
worksheets | Representa una colección de hojas de cálculo asociadas con el libro. |
Métodos
close(close |
Cierra el libro actual. |
close(close |
Cierra el libro actual. |
get |
Obtiene la celda activa del libro. |
get |
Obtiene el gráfico activo del libro. Si no hay ningún gráfico activo, se produce una |
get |
Obtiene el gráfico activo del libro. Si no hay ningún gráfico activo, este método devuelve un objeto con su |
get |
Obtiene la segmentación activa del libro. Si no hay ninguna segmentación activa, se produce una |
get |
Obtiene la segmentación activa del libro. Si no hay ninguna segmentación de datos activa, este método devuelve un objeto con su |
get |
Devuelve |
get |
Obtiene el intervalo único seleccionado actualmente del libro. Si hay varios intervalos seleccionados, este método producirá un error. |
get |
Obtiene los intervalos seleccionados actualmente en el libro. A diferencia de |
insert |
Inserta las hojas de cálculo especificadas de un libro de origen en el libro actual. Nota*: Esta API solo se admite actualmente para Office en Windows, Mac y la web. |
load(options) | Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a |
load(property |
Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a |
load(property |
Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a |
save(save |
Guarda el libro actual. |
save(save |
Guarda el libro actual. |
set(properties, options) | Establece varias propiedades de un objeto al mismo tiempo. Puede pasar un objeto sin formato con las propiedades adecuadas u otro objeto de API del mismo tipo. |
set(properties) | Establece varias propiedades en el objeto al mismo tiempo, en función de un objeto cargado existente. |
toJSON() | Invalida el método JavaScript |
Eventos
on |
Se produce cuando se activa el libro. Nota: Este evento no se desencadenará cuando se abra el libro. |
on |
Se produce cuando se cambia la configuración Autoguardar en el libro. |
on |
Se genera al cambiar la selección en el documento. |
Detalles de las propiedades
application
Representa la instancia de la aplicación de Excel que contiene este libro.
readonly application: Excel.Application;
Valor de propiedad
Comentarios
autoSave
Especifica si el libro está en modo autoguardado.
readonly autoSave: boolean;
Valor de propiedad
boolean
Comentarios
bindings
Representa una colección de enlaces que forman parte del libro.
readonly bindings: Excel.BindingCollection;
Valor de propiedad
Comentarios
calculationEngineVersion
Devuelve un número acerca de la versión del motor de cálculo de Excel.
readonly calculationEngineVersion: number;
Valor de propiedad
number
Comentarios
chartDataPointTrack
True si todos los gráficos en el libro están siguiendo los puntos de datos reales a los que están conectados. False si los gráficos realizan un seguimiento del índice de los puntos de datos.
chartDataPointTrack: boolean;
Valor de propiedad
boolean
Comentarios
comments
Representa una colección de comentarios asociados al libro.
readonly comments: Excel.CommentCollection;
Valor de propiedad
Comentarios
context
Contexto de solicitud asociado al objeto . Esto conecta el proceso del complemento al proceso de la aplicación host de Office.
context: RequestContext;
Valor de propiedad
customXmlParts
Representa la colección de elementos XML personalizados contenidos en este libro.
readonly customXmlParts: Excel.CustomXmlPartCollection;
Valor de propiedad
Comentarios
dataConnections
Representa todas las conexiones de datos del libro.
readonly dataConnections: Excel.DataConnectionCollection;
Valor de propiedad
Comentarios
functions
Representa una colección de funciones de hoja de cálculo que se pueden usar para el cálculo.
readonly functions: Excel.Functions;
Valor de propiedad
Comentarios
isDirty
Especifica si se han realizado cambios desde la última vez que se guardó el libro. Puede establecer esta propiedad true
en si desea cerrar un libro modificado sin guardarlo o se le pide que lo guarde.
isDirty: boolean;
Valor de propiedad
boolean
Comentarios
name
Obtiene el nombre del libro.
readonly name: string;
Valor de propiedad
string
Comentarios
names
Representa una colección de elementos con nombre con ámbito de libro (intervalos y constantes con nombre).
readonly names: Excel.NamedItemCollection;
Valor de propiedad
Comentarios
pivotTables
Representa una colección de tablas dinámicas asociadas con el libro.
readonly pivotTables: Excel.PivotTableCollection;
Valor de propiedad
Comentarios
[ Conjunto de API: ExcelApi 1.3 ]
Ejemplos
// 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 una colección de PivotTableStyles asociados con el libro.
readonly pivotTableStyles: Excel.PivotTableStyleCollection;
Valor de propiedad
Comentarios
previouslySaved
Especifica si el libro se ha guardado alguna vez localmente o en línea.
readonly previouslySaved: boolean;
Valor de propiedad
boolean
Comentarios
properties
Obtiene las propiedades del libro.
readonly properties: Excel.DocumentProperties;
Valor de propiedad
Comentarios
[ Conjunto de API: ExcelApi 1.7 ]
Ejemplos
// 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
Devuelve el objeto de protección de un libro.
readonly protection: Excel.WorkbookProtection;
Valor de propiedad
Comentarios
readOnly
Devuelve true
si el libro está abierto en modo de solo lectura.
readonly readOnly: boolean;
Valor de propiedad
boolean
Comentarios
settings
Representa una colección de valores asociados al libro.
readonly settings: Excel.SettingCollection;
Valor de propiedad
Comentarios
slicers
Representa una colección de segmentaciones de datos asociadas al libro.
readonly slicers: Excel.SlicerCollection;
Valor de propiedad
Comentarios
slicerStyles
Representa una colección de SlicerStyles asociados con el libro.
readonly slicerStyles: Excel.SlicerStyleCollection;
Valor de propiedad
Comentarios
styles
Representa una colección de estilos asociada con el libro.
readonly styles: Excel.StyleCollection;
Valor de propiedad
Comentarios
[ Conjunto de API: ExcelApi 1.7 ]
Ejemplos
// 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 una colección de tablas asociadas con el libro.
readonly tables: Excel.TableCollection;
Valor de propiedad
Comentarios
tableStyles
Representa una colección de TableStyles asociados con el libro.
readonly tableStyles: Excel.TableStyleCollection;
Valor de propiedad
Comentarios
timelineStyles
Representa una colección de TimelineStyles asociados con el libro.
readonly timelineStyles: Excel.TimelineStyleCollection;
Valor de propiedad
Comentarios
usePrecisionAsDisplayed
True si los cálculos de este libro se llevan a cabo con la misma precisión con que se muestran los números. Los datos perderán precisión de forma permanente al cambiar esta propiedad de false
a true
.
usePrecisionAsDisplayed: boolean;
Valor de propiedad
boolean
Comentarios
worksheets
Representa una colección de hojas de cálculo asociadas con el libro.
readonly worksheets: Excel.WorksheetCollection;
Valor de propiedad
Comentarios
Detalles del método
close(closeBehavior)
Cierra el libro actual.
close(closeBehavior?: Excel.CloseBehavior): void;
Parámetros
- closeBehavior
- Excel.CloseBehavior
comportamiento de cierre del libro.
Devoluciones
void
Comentarios
[ Conjunto de API: ExcelApi 1.11 ]
Ejemplos
// 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)
Cierra el libro actual.
close(closeBehaviorString?: "Save" | "SkipSave"): void;
Parámetros
- closeBehaviorString
-
"Save" | "SkipSave"
comportamiento de cierre del libro.
Devoluciones
void
Comentarios
getActiveCell()
Obtiene la celda activa del libro.
getActiveCell(): Excel.Range;
Devoluciones
Comentarios
[ Conjunto de API: ExcelApi 1.7 ]
Ejemplos
// 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()
Obtiene el gráfico activo del libro. Si no hay ningún gráfico activo, se produce una ItemNotFound
excepción.
getActiveChart(): Excel.Chart;
Devoluciones
Comentarios
getActiveChartOrNullObject()
Obtiene el gráfico activo del libro. Si no hay ningún gráfico activo, este método devuelve un objeto con su isNullObject
propiedad establecida en true
. Para obtener más información, vea *OrNullObject methods and properties( Métodos y propiedades de *OrNullObject).
getActiveChartOrNullObject(): Excel.Chart;
Devoluciones
Comentarios
getActiveSlicer()
Obtiene la segmentación activa del libro. Si no hay ninguna segmentación activa, se produce una ItemNotFound
excepción.
getActiveSlicer(): Excel.Slicer;
Devoluciones
Comentarios
getActiveSlicerOrNullObject()
Obtiene la segmentación activa del libro. Si no hay ninguna segmentación de datos activa, este método devuelve un objeto con su isNullObject
propiedad establecida en true
. Para obtener más información, vea *OrNullObject methods and properties( Métodos y propiedades de *OrNullObject).
getActiveSlicerOrNullObject(): Excel.Slicer;
Devoluciones
Comentarios
getIsActiveCollabSession()
Devuelve true
si varios usuarios están editando el libro (a través de la coautoría). Tenga en cuenta que puede haber algún retraso entre cuándo cambia el estado del libro y cuándo se reflejan los cambios en el resultado del método.
getIsActiveCollabSession(): OfficeExtension.ClientResult<boolean>;
Devoluciones
OfficeExtension.ClientResult<boolean>
Comentarios
getSelectedRange()
Obtiene el intervalo único seleccionado actualmente del libro. Si hay varios intervalos seleccionados, este método producirá un error.
getSelectedRange(): Excel.Range;
Devoluciones
Comentarios
[ Conjunto de API: ExcelApi 1.1 ]
Ejemplos
await Excel.run(async (context) => {
const selectedRange = context.workbook.getSelectedRange();
selectedRange.load('address');
await context.sync();
console.log(selectedRange.address);
});
getSelectedRanges()
Obtiene los intervalos seleccionados actualmente en el libro. A diferencia de getSelectedRange()
, este método devuelve un RangeAreas
objeto que representa todos los intervalos seleccionados.
getSelectedRanges(): Excel.RangeAreas;
Devoluciones
Comentarios
[ Conjunto de API: ExcelApi 1.9 ]
Ejemplos
// 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)
Inserta las hojas de cálculo especificadas de un libro de origen en el libro actual.
Nota*: Esta API solo se admite actualmente para Office en Windows, Mac y la web.
insertWorksheetsFromBase64(base64File: string, options?: Excel.InsertWorksheetOptions): OfficeExtension.ClientResult<string[]>;
Parámetros
- base64File
-
string
Obligatorio. Cadena codificada en Base64 que representa el archivo de libro de origen.
- options
- Excel.InsertWorksheetOptions
Opcional. Opciones que definen qué hojas de cálculo se van a insertar y dónde se insertarán las nuevas hojas de cálculo en el libro. De forma predeterminada, todas las hojas de cálculo del libro de origen se insertan al final del libro actual.
Devoluciones
OfficeExtension.ClientResult<string[]>
Matriz de identificadores correspondientes a cada hoja de cálculo recién insertada.
Comentarios
[ Conjunto de API: ExcelApi 1.13 ]
Ejemplos
// 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)
Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync()
antes de leer las propiedades.
load(options?: Excel.Interfaces.WorkbookLoadOptions): Excel.Workbook;
Parámetros
Proporciona opciones para las propiedades del objeto que se van a cargar.
Devoluciones
load(propertyNames)
Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync()
antes de leer las propiedades.
load(propertyNames?: string | string[]): Excel.Workbook;
Parámetros
- propertyNames
-
string | string[]
Una cadena delimitada por comas o una matriz de cadenas que especifican las propiedades que se van a cargar.
Devoluciones
load(propertyNamesAndPaths)
Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync()
antes de leer las propiedades.
load(propertyNamesAndPaths?: {
select?: string;
expand?: string;
}): Excel.Workbook;
Parámetros
- propertyNamesAndPaths
-
{ select?: string; expand?: string; }
propertyNamesAndPaths.select
es una cadena delimitada por comas que especifica las propiedades que se van a cargar y propertyNamesAndPaths.expand
es una cadena delimitada por comas que especifica las propiedades de navegación que se van a cargar.
Devoluciones
save(saveBehavior)
Guarda el libro actual.
save(saveBehavior?: Excel.SaveBehavior): void;
Parámetros
- saveBehavior
- Excel.SaveBehavior
El comportamiento de guardado debe ser "Guardar" o "Preguntar". El valor predeterminado es "Guardar".
Devoluciones
void
Comentarios
[ Conjunto de API: ExcelApi 1.11 ]
Ejemplos
// 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)
Guarda el libro actual.
save(saveBehaviorString?: "Save" | "Prompt"): void;
Parámetros
- saveBehaviorString
-
"Save" | "Prompt"
El comportamiento de guardado debe ser "Guardar" o "Preguntar". El valor predeterminado es "Guardar".
Devoluciones
void
Comentarios
set(properties, options)
Establece varias propiedades de un objeto al mismo tiempo. Puede pasar un objeto sin formato con las propiedades adecuadas u otro objeto de API del mismo tipo.
set(properties: Interfaces.WorkbookUpdateData, options?: OfficeExtension.UpdateOptions): void;
Parámetros
- properties
- Excel.Interfaces.WorkbookUpdateData
Objeto JavaScript con propiedades estructuradas isomórficamente con las propiedades del objeto al que se llama al método.
- options
- OfficeExtension.UpdateOptions
Proporciona una opción para suprimir errores si el objeto properties intenta establecer propiedades de solo lectura.
Devoluciones
void
set(properties)
Establece varias propiedades en el objeto al mismo tiempo, en función de un objeto cargado existente.
set(properties: Excel.Workbook): void;
Parámetros
- properties
- Excel.Workbook
Devoluciones
void
toJSON()
Invalida el método JavaScript toJSON()
para proporcionar una salida más útil cuando se pasa un objeto de API a JSON.stringify()
. (JSON.stringify
a su vez, llama al toJSON
método del objeto que se le pasa). Mientras que el objeto original Excel.Workbook
es un objeto de API, el toJSON
método devuelve un objeto JavaScript sin formato (escrito como Excel.Interfaces.WorkbookData
) que contiene copias superficiales de las propiedades secundarias cargadas del objeto original.
toJSON(): Excel.Interfaces.WorkbookData;
Devoluciones
Detalles del evento
onActivated
Se produce cuando se activa el libro. Nota: Este evento no se desencadenará cuando se abra el libro.
readonly onActivated: OfficeExtension.EventHandlers<Excel.WorkbookActivatedEventArgs>;
Tipo de evento
Comentarios
[ Conjunto de API: ExcelApi 1.13 ]
Ejemplos
// 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
Se produce cuando se cambia la configuración Autoguardar en el libro.
readonly onAutoSaveSettingChanged: OfficeExtension.EventHandlers<Excel.WorkbookAutoSaveSettingChangedEventArgs>;
Tipo de evento
Comentarios
onSelectionChanged
Se genera al cambiar la selección en el documento.
readonly onSelectionChanged: OfficeExtension.EventHandlers<Excel.SelectionChangedEventArgs>;