Excel.Worksheet class

Referencia

Paquete:: excel

Una hoja de cálculo de Excel es una cuadrícula de celdas. Puede contener datos, tablas, gráficos, etc. Para obtener más información sobre el modelo de objetos de hoja de cálculo, lea Trabajar con hojas de cálculo mediante la API de JavaScript de Excel.

Extends: OfficeExtension.ClientObject

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Propiedades

charts	Devuelve una colección de gráficos que forman parte de la hoja de cálculo.
context	Contexto de solicitud asociado al objeto . Esto conecta el proceso del complemento al proceso de la aplicación host de Office.
id	Devuelve un valor que identifica de forma única la hoja de cálculo de un libro determinado. El valor del identificador permanece igual, incluso cuando se cambia el nombre de la hoja de cálculo o cuando esta se mueve.
name	Nombre para mostrar de la hoja de cálculo.
names	Colección de nombres en el ámbito de la hoja de cálculo actual.
pivotTables	Colección de tablas dinámicas que forman parte de la hoja de cálculo.
position	Posición de base cero de la hoja de cálculo dentro del libro.
protection	Devuelve el objeto de protección de hoja de una hoja de cálculo.
tables	Colección de tablas que forman parte de la hoja de cálculo.
visibility	Visibilidad de la hoja de cálculo.

Métodos

activate()	Activa la hoja de cálculo en la interfaz de usuario de Excel.
delete()	Elimina la hoja de cálculo del libro. Tenga en cuenta que si la visibilidad de la hoja de cálculo está establecida en "VeryHidden", se producirá un error en la operación de eliminación con una `InvalidOperation` excepción. Primero debe cambiar su visibilidad a oculta o visible antes de eliminarla.
getCell(row, column)	Obtiene el `Range` objeto que contiene la celda única en función de los números de fila y columna. La celda puede estar fuera de los límites de su rango primario, siempre y cuando permanezca dentro de la cuadrícula de la hoja de cálculo.
getNext(visibleOnly)	Obtiene la hoja de cálculo que sigue a esta. Si no hay ninguna hoja de cálculo después de esta, este método producirá un error.
getNextOrNullObject(visibleOnly)	Obtiene la hoja de cálculo que sigue a esta. Si no hay ninguna hoja de cálculo después de esta, 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).
getPrevious(visibleOnly)	Obtiene la hoja de cálculo que precede a esta. Si no hay hojas de cálculo anteriores, este método producirá un error.
getPreviousOrNullObject(visibleOnly)	Obtiene la hoja de cálculo que precede a esta. Si no hay hojas de cálculo anteriores, 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).
getRange(address)	Obtiene el `Range` objeto , que representa un único bloque rectangular de celdas, especificado por la dirección o el nombre.
getUsedRange(valuesOnly)	El rango usado es el rango más pequeño que abarque todas las celdas que tengan asignado un valor o un formato. Si toda la hoja de cálculo está en blanco, esta función devolverá la celda superior izquierda (es decir, no producirá un error).
getUsedRangeOrNullObject(valuesOnly)	El rango usado es el rango más pequeño que abarque todas las celdas que tengan asignado un valor o un formato. Si toda la hoja de cálculo está en blanco, 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).
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(propertyNames)	Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a `context.sync()` antes de leer las propiedades.
load(propertyNamesAndPaths)	Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a `context.sync()` antes de leer las propiedades.
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 `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 Excel.Worksheet original es un objeto de API, el `toJSON` método devuelve un objeto JavaScript sin formato (escrito como `Excel.Interfaces.WorksheetData`) que contiene copias superficiales de las propiedades secundarias cargadas del objeto original.

Detalles de las propiedades

charts

Devuelve una colección de gráficos que forman parte de la hoja de cálculo.

readonly charts: Excel.ChartCollection;

Valor de propiedad

Excel.ChartCollection

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

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

Excel.RequestContext

id

Devuelve un valor que identifica de forma única la hoja de cálculo de un libro determinado. El valor del identificador permanece igual, incluso cuando se cambia el nombre de la hoja de cálculo o cuando esta se mueve.

readonly id: string;

Valor de propiedad

string

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

name

Nombre para mostrar de la hoja de cálculo.

name: string;

Valor de propiedad

string

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

names

Colección de nombres en el ámbito de la hoja de cálculo actual.

readonly names: Excel.NamedItemCollection;

Valor de propiedad

Excel.NamedItemCollection

Comentarios

[ Conjunto de API: ExcelApi 1.4 ]

pivotTables

Colección de tablas dinámicas que forman parte de la hoja de cálculo.

readonly pivotTables: Excel.PivotTableCollection;

Valor de propiedad

Excel.PivotTableCollection

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 current worksheet.
  const pivotTables = context.workbook.worksheets.getActiveWorksheet().pivotTables;
  pivotTables.load("name");
  await context.sync();

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

position

Posición de base cero de la hoja de cálculo dentro del libro.

position: number;

Valor de propiedad

number

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Ejemplos

// Set worksheet position.
await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.position = 2;
    await context.sync(); 
});

protection

Devuelve el objeto de protección de hoja de una hoja de cálculo.

readonly protection: Excel.WorksheetProtection;

Valor de propiedad

Excel.WorksheetProtection

Comentarios

[ Conjunto de API: ExcelApi 1.2 ]

Ejemplos

// Unprotecting a worksheet with unprotect() will remove all 
// WorksheetProtectionOptions options applied to a worksheet.
// To remove only a subset of WorksheetProtectionOptions use the 
// protect() method and set the options you wish to remove to true.
await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getItem("Sheet1");
  sheet.protection.protect({
    allowInsertRows: false, // Protect row insertion
    allowDeleteRows: true // Unprotect row deletion
  });
});

tables

Colección de tablas que forman parte de la hoja de cálculo.

readonly tables: Excel.TableCollection;

Valor de propiedad

Excel.TableCollection

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

visibility

Visibilidad de la hoja de cálculo.

visibility: Excel.SheetVisibility | "Visible" | "Hidden" | "VeryHidden";

Valor de propiedad

Excel.SheetVisibility | "Visible" | "Hidden" | "VeryHidden"

Comentarios

[ Conjunto de API: ExcelApi 1.1 para leer la visibilidad; 1.2 para establecerla. ]

Detalles del método

activate()

Activa la hoja de cálculo en la interfaz de usuario de Excel.

activate(): void;

Devoluciones

void

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Ejemplos

await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.activate();
    await context.sync(); 
});

delete()

Elimina la hoja de cálculo del libro. Tenga en cuenta que si la visibilidad de la hoja de cálculo está establecida en "VeryHidden", se producirá un error en la operación de eliminación con una InvalidOperation excepción. Primero debe cambiar su visibilidad a oculta o visible antes de eliminarla.

delete(): void;

Devoluciones

void

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Ejemplos

await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.delete();
    await context.sync(); 
});

getCell(row, column)

Obtiene el Range objeto que contiene la celda única en función de los números de fila y columna. La celda puede estar fuera de los límites de su rango primario, siempre y cuando permanezca dentro de la cuadrícula de la hoja de cálculo.

getCell(row: number, column: number): Excel.Range;

Parámetros

row: number

Número de fila de la celda que se va a recuperar. Indizado con cero.

column: number

Número de columna de la celda que se va a recuperar. Indizado con cero.

Devoluciones

Excel.Range

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Ejemplos

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const cell = worksheet.getCell(0,0);
    cell.load('address');
    await context.sync();

    console.log(cell.address);
});

getNext(visibleOnly)

Obtiene la hoja de cálculo que sigue a esta. Si no hay ninguna hoja de cálculo después de esta, este método producirá un error.

getNext(visibleOnly?: boolean): Excel.Worksheet;

Parámetros

visibleOnly: boolean

Opcional. Si truees , solo tiene en cuenta las hojas de cálculo visibles, omitiendo las ocultas.

Devoluciones

Excel.Worksheet

Comentarios

[ Conjunto de API: ExcelApi 1.5 ]

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/reference-worksheets-by-relative-position.yaml

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

    // We don't want to include the default worksheet that was created
    // when the workbook was created, so our "firstSheet" will be the one
    // after the literal first. Note chaining of navigation methods.
    const firstSheet = sheets.getFirst().getNext();
    const lastSheet = sheets.getLast();
    const firstTaxRateRange = firstSheet.getRange("B2");
    const lastTaxRateRange = lastSheet.getRange("B2");

    firstSheet.load("name");
    lastSheet.load("name");
    firstTaxRateRange.load("text");
    lastTaxRateRange.load("text");

    await context.sync();

    let firstYear = firstSheet.name.substr(5, 4);
    let lastYear = lastSheet.name.substr(5, 4);
    console.log(`Tax Rate change from ${firstYear} to ${lastYear}`, `Tax rate for ${firstYear}: ${firstTaxRateRange.text[0][0]}\nTax rate for ${lastYear}: ${lastTaxRateRange.text[0][0]}`)

    await context.sync();
});

getNextOrNullObject(visibleOnly)

Obtiene la hoja de cálculo que sigue a esta. Si no hay ninguna hoja de cálculo después de esta, 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).

getNextOrNullObject(visibleOnly?: boolean): Excel.Worksheet;

Parámetros

visibleOnly: boolean

Opcional. Si truees , solo tiene en cuenta las hojas de cálculo visibles, omitiendo las ocultas.

Devoluciones

Excel.Worksheet

Comentarios

[ Conjunto de API: ExcelApi 1.5 ]

getPrevious(visibleOnly)

Obtiene la hoja de cálculo que precede a esta. Si no hay hojas de cálculo anteriores, este método producirá un error.

getPrevious(visibleOnly?: boolean): Excel.Worksheet;

Parámetros

visibleOnly: boolean

Opcional. Si truees , solo tiene en cuenta las hojas de cálculo visibles, omitiendo las ocultas.

Devoluciones

Excel.Worksheet

Comentarios

[ Conjunto de API: ExcelApi 1.5 ]

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/reference-worksheets-by-relative-position.yaml

await Excel.run(async (context) => {
    const sheets = context.workbook.worksheets;
    const currentSheet = sheets.getActiveWorksheet();
    const previousYearSheet = currentSheet.getPrevious();
    const currentTaxDueRange = currentSheet.getRange("C2");
    const previousTaxDueRange = previousYearSheet.getRange("C2");

    currentSheet.load("name");
    previousYearSheet.load("name");
    currentTaxDueRange.load("text");
    previousTaxDueRange.load("text");

    await context.sync();

    let currentYear = currentSheet.name.substr(5, 4);
    let previousYear = previousYearSheet.name.substr(5, 4);
    console.log("Two Year Tax Due Comparison", `Tax due for ${currentYear} was ${currentTaxDueRange.text[0][0]}\nTax due for ${previousYear} was ${previousTaxDueRange.text[0][0]}`)

    await context.sync();
});

getPreviousOrNullObject(visibleOnly)

Obtiene la hoja de cálculo que precede a esta. Si no hay hojas de cálculo anteriores, 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).

getPreviousOrNullObject(visibleOnly?: boolean): Excel.Worksheet;

Parámetros

visibleOnly: boolean

Opcional. Si truees , solo tiene en cuenta las hojas de cálculo visibles, omitiendo las ocultas.

Devoluciones

Excel.Worksheet

Comentarios

[ Conjunto de API: ExcelApi 1.5 ]

getRange(address)

Obtiene el Range objeto , que representa un único bloque rectangular de celdas, especificado por la dirección o el nombre.

getRange(address?: string): Excel.Range;

Parámetros

address: string

Opcional. Cadena que representa la dirección o el nombre del intervalo. Por ejemplo, "A1:B2". Si no se especifica, se devuelve todo el intervalo de la hoja de cálculo.

Devoluciones

Excel.Range

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Ejemplos

// Use the range address to get the range object.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const range = worksheet.getRange(rangeAddress);
    range.load('cellCount');
    await context.sync();
    
    console.log(range.cellCount);
});

getUsedRange(valuesOnly)

El rango usado es el rango más pequeño que abarque todas las celdas que tengan asignado un valor o un formato. Si toda la hoja de cálculo está en blanco, esta función devolverá la celda superior izquierda (es decir, no producirá un error).

getUsedRange(valuesOnly?: boolean): Excel.Range;

Parámetros

valuesOnly: boolean

Opcional. Si truees , solo tiene en cuenta las celdas con valores como celdas usadas (omitiendo el formato). [Conjunto de api: ExcelApi 1.2]

Devoluciones

Excel.Range

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Ejemplos

await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    const usedRange = worksheet.getUsedRange();
    usedRange.load('address');
    await context.sync();
    
    console.log(usedRange.address);
});

getUsedRangeOrNullObject(valuesOnly)

El rango usado es el rango más pequeño que abarque todas las celdas que tengan asignado un valor o un formato. Si toda la hoja de cálculo está en blanco, 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).

getUsedRangeOrNullObject(valuesOnly?: boolean): Excel.Range;

Parámetros

valuesOnly: boolean

Opcional. Solo tiene en cuenta las celdas con valores como celdas usadas.

Devoluciones

Excel.Range

Comentarios

[ Conjunto de API: ExcelApi 1.4 ]

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.WorksheetLoadOptions): Excel.Worksheet;

Parámetros

options: Excel.Interfaces.WorksheetLoadOptions

Proporciona opciones para las propiedades del objeto que se van a cargar.

Devoluciones

Excel.Worksheet

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

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

Excel.Worksheet

Ejemplos

// Get worksheet properties based on sheet name.
await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.load('position')
    await context.sync();
    
    console.log(worksheet.position);
});

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

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

Excel.Worksheet

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.WorksheetUpdateData, options?: OfficeExtension.UpdateOptions): void;

Parámetros

properties: Excel.Interfaces.WorksheetUpdateData

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

Ejemplos

// Set the color and name of the current worksheet.
await Excel.run(async (context) => {
  const activeSheet = context.workbook.worksheets.getActiveWorksheet();
  activeSheet.set({
    tabColor: "yellow",
    name: "MySheet"
  });

  await context.sync();
});

set(properties)

Establece varias propiedades en el objeto al mismo tiempo, en función de un objeto cargado existente.

set(properties: Excel.Worksheet): void;

Parámetros

properties: Excel.Worksheet

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.stringifya su vez, llama al toJSON método del objeto que se le pasa). Mientras que el objeto Excel.Worksheet original es un objeto de API, el toJSON método devuelve un objeto JavaScript sin formato (escrito como Excel.Interfaces.WorksheetData) que contiene copias superficiales de las propiedades secundarias cargadas del objeto original.

toJSON(): Excel.Interfaces.WorksheetData;

Devoluciones

Excel.Interfaces.WorksheetData