Share via

Búsqueda de celdas especiales dentro de un intervalo mediante la API de JavaScript de Excel

  • Artículo

En este artículo se proporcionan ejemplos de código que buscan celdas especiales dentro de un intervalo mediante la API de JavaScript de Excel. Para obtener la lista completa de propiedades y métodos que admite el Range objeto, vea Clase Excel.Range.

Búsqueda de rangos con celdas especiales

Los métodos Range.getSpecialCells y Range.getSpecialCellsOrNullObject buscan rangos basados en las características de sus celdas y los tipos de valores de sus celdas. Ambos métodos devuelven objetos RangeAreas. Estas son las firmas de los métodos del archivo de los tipos de datos TypeScript:

getSpecialCells(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

getSpecialCellsOrNullObject(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

En el ejemplo de código siguiente se usa el getSpecialCells método para buscar todas las celdas con fórmulas. Sobre este código, tenga en cuenta:

  • Limita la parte de la hoja que necesita buscarse llamando a Worksheet.getUsedRange y después a getSpecialCells solo para ese intervalo.
  • El método getSpecialCells devuelve un objeto RangeAreas de forma que todas las celdas con fórmulas tendrán un color rosa aunque no sean todas contiguas.
await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let usedRange = sheet.getUsedRange();
    let formulaRanges = usedRange.getSpecialCells(Excel.SpecialCellType.formulas);
    formulaRanges.format.fill.color = "pink";

    await context.sync();
});

Si no hay celdas con la características especificadas en el rango, getSpecialCells genera un error ItemNotFound. Esto redirige el flujo de control hacia un bloque catch, si hay alguno. Si no hay un catch bloque, el error detiene el método .

Si espera que siempre haya celdas con las características especificadas, probablemente querrá que el código genere un error si las celdas no están presentes. Si es posible que no haya celdas coincidentes, el código debería comprobar esta posibilidad y gestionarla correctamente sin producir un error. Puede lograr este comportamiento con el método getSpecialCellsOrNullObject y su propiedad devuelta isNullObject. En el ejemplo de código siguiente se usa este patrón. Sobre este código, tenga en cuenta:

  • El getSpecialCellsOrNullObject método siempre devuelve un objeto proxy, por lo que nunca null es en el sentido común de JavaScript. Pero si no encuentra ninguna coincidencia de celdas, la propiedad isNullObject del objeto se establece en true.
  • Llama a context.syncantes de probar la isNullObject propiedad . Este es un requisito con todos los métodos y propiedades de *OrNullObject porque siempre debe cargar y sincronizar una propiedad para poder leerla. Sin embargo, no es necesario cargar explícitamente la isNullObject propiedad . El objeto lo carga context.sync automáticamente, incluso si load no se llama a él. Para obtener más información, vea *OrNullObject methods and properties(Métodos y propiedades de *OrNullObject).
  • Puede probar el código seleccionando un intervalo que no contenga celdas con fórmulas y ejecutándolo. Después seleccione un intervalo que tenga al menos una celda con una fórmula y ejecútelo de nuevo.
await Excel.run(async (context) => {
    let range = context.workbook.getSelectedRange();
    let formulaRanges = range.getSpecialCellsOrNullObject(Excel.SpecialCellType.formulas);
    await context.sync();
        
    if (formulaRanges.isNullObject) {
        console.log("No cells have formulas");
    }
    else {
        formulaRanges.format.fill.color = "pink";
    }
    
    await context.sync();
});

Por motivos de simplicidad, todos los demás ejemplos de código de este artículo usan el getSpecialCells método en lugar de getSpecialCellsOrNullObject.

Restricción de las celdas de destino con tipos de valores de celda

Los métodos Range.getSpecialCells() y Range.getSpecialCellsOrNullObject() aceptan un segundo parámetro opcional utilizado para restringir aún más las celdas buscadas. Este segundo parámetro es un Excel.SpecialCellValueType que se usa para especificar que solo quiere las celdas que contienen ciertos tipos de valores.

Nota:

El parámetro Excel.SpecialCellValueType solamente se puede usar si el Excel.SpecialCellType es Excel.SpecialCellType.formulas o Excel.SpecialCellType.constants.

Prueba para un tipo de valor de celda

El Excel.SpecialCellValueType enum tiene estos cuatro tipos básicos (además de otros valores combinados que se describen más adelante en esta sección):

  • Excel.SpecialCellValueType.errors
  • Excel.SpecialCellValueType.logical (lo que significa booleano)
  • Excel.SpecialCellValueType.numbers
  • Excel.SpecialCellValueType.text

El ejemplo de código siguiente busca celdas especiales que son constantes numéricas y colorea esas celdas de color rosa. Sobre este código, tenga en cuenta:

  • Solo resalta las celdas que tienen un valor de número literal. No resaltará las celdas que tienen una fórmula (incluso si el resultado es un número) ni una celda booleana, de texto o de estado de error.
  • Para probar el código, asegúrese de que la hoja de cálculo tiene algunas celdas con valores numéricos literales, algunas con otros tipos de valores literales y algunas con fórmulas.
await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let usedRange = sheet.getUsedRange();
    let constantNumberRanges = usedRange.getSpecialCells(
        Excel.SpecialCellType.constants,
        Excel.SpecialCellValueType.numbers);
    constantNumberRanges.format.fill.color = "pink";

    await context.sync();
});

Prueba para varios tipos de valor de celda

A veces es necesario trabajar con más de un tipo de valor de celda, como las celdas que solo tienen valores de texto y celdas que solo tienen valores booleanos (Excel.SpecialCellValueType.logical). El Excel.SpecialCellValueType enum tiene valores con tipos combinados. Por ejemplo,Excel.SpecialCellValueType.logicalText tendrá como objetivo todas las celdas con valores booleanos y de texto. Excel.SpecialCellValueType.all es el valor predeterminado, que no limita los tipos de valores de celda devueltos. El ejemplo de código siguiente colorea todas las celdas con fórmulas que generan número o valor booleano.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let usedRange = sheet.getUsedRange();
    let formulaLogicalNumberRanges = usedRange.getSpecialCells(
        Excel.SpecialCellType.formulas,
        Excel.SpecialCellValueType.logicalNumbers);
    formulaLogicalNumberRanges.format.fill.color = "pink";

    await context.sync();
});

Vea también