Compartir a través de

Trabajo con varios intervalos de forma simultánea en los complementos de Excel

Puede aplicar operaciones o establecer propiedades en varios intervalos a la vez, incluso si no son contiguos. Esto hace que el código sea más corto y eficaz en comparación con el acceso a cada intervalo por separado.

Puntos clave

  • Use RangeAreas para leer o establecer lo mismo en varios intervalos independientes en una llamada.
  • Una propiedad es null a menos que todos los intervalos de miembros compartan el mismo valor.
  • Establezca una propiedad una vez en el RangeAreas objeto en lugar de bucle, a menos que cada intervalo necesite lógica diferente.
  • Evite objetos grandes RangeAreas hechos de muchas celdas únicas. Acotar primero con getSpecialCells u otros filtros.
  • Tenga cuidado con columnas o filas completas. Para obtener más información, consulte Lectura o escritura en un intervalo sin enlazar.

RangeAreas

Un objeto RangeAreas representa un conjunto de intervalos que pueden no tocarse. Comparte muchos miembros con Range, con algunas diferencias en cómo se devuelven los valores.

Ejemplos:

  • address devuelve una cadena delimitada por comas de todas las direcciones.
  • dataValidation devuelve un solo objeto solo si cada intervalo tiene la misma regla; de lo contrario, devuelve null.
  • cellCount es el total de celdas en todos los rangos.
  • calculate recalcula todas las celdas del conjunto.
  • getEntireColumn y getEntireRow devuelven una nueva RangeAreas expansión de columnas o filas completas para cada miembro.
  • copyFrom acepta o Range como RangeAreas origen.

Lista completa de los miembros del intervalo que también están disponibles en RangeAreas

Propiedades

Familiarícese con Leer las propiedades de RangeAreas antes de escribir código que lea las propiedades de la lista. Hay matices con respecto a lo que se devuelve.

  • address
  • addressLocal
  • cellCount
  • conditionalFormats
  • context
  • dataValidation
  • format
  • isEntireColumn
  • isEntireRow
  • style
  • worksheet

Métodos

  • calculate()
  • clear()
  • convertDataTypeToText()
  • convertToLinkedDataType()
  • copyFrom()
  • getEntireColumn()
  • getEntireRow()
  • getIntersection()
  • getIntersectionOrNullObject()
  • getOffsetRange() (denominado getOffsetRangeAreas en el RangeAreas objeto )
  • getSpecialCells()
  • getSpecialCellsOrNullObject()
  • getTables()
  • getUsedRange() (denominado getUsedRangeAreas en el RangeAreas objeto )
  • getUsedRangeOrNullObject() (denominado getUsedRangeAreasOrNullObject en el RangeAreas objeto )
  • load()
  • set()
  • setDirty()
  • toJSON()
  • track()
  • untrack()

Métodos y propiedades específicos de RangeArea

El tipo RangeAreas tiene algunas propiedades y métodos que no están en el objeto Range. A continuación se muestra una selección de ellos.

  • areas: un objeto RangeCollection que contiene todos los intervalos representados por el objeto RangeAreas. El objeto RangeCollection también es nuevo y es similar a otros objetos de la colección de Excel. Tiene una propiedad items que es una matriz de objetos Range que representan los intervalos.
  • areaCount: el número total de eventos de intervalos de RangeAreas.
  • getOffsetRangeAreas: funciona igual que Range.getOffsetRange, excepto que se devuelve un RangeAreas y contiene intervalos que se desplazan de uno de los intervalos del RangeAreas original.

Crear RangeAreas

Puede crear un RangeAreas objeto de varias maneras. En la lista siguiente se incluyen algunos ejemplos.

  • Llame a Worksheet.getRanges() y pásele una cadena con direcciones de intervalo delimitadas por comas. Si cualquier intervalo que desee incluir se ha realizado en un NamedItem, puede incluir el nombre, en lugar de la dirección, en la cadena.
  • Llame a Range.getSpecialCells() y devuelva un RangeAreas objeto con celdas de un tipo específico, como celdas que contienen fórmulas, validación de datos o formato condicional.
  • Llamar a Workbook.getSelectedRanges(). Este método devuelve un RangeAreas que representa todos los intervalos seleccionados en la hoja de cálculo activa.

Cuando tenga un objeto RangeAreas, puede crear otros con los métodos en el objeto que devuelve RangeAreas como getOffsetRangeAreas y getIntersection.

Nota:

No puede agregar directamente intervalos adicionales a un objeto RangeAreas. Por ejemplo, la colección de RangeAreas.areas no tiene un método add.

Advertencia

No intente agregar ni eliminar directamente miembros de la RangeAreas.areas.items matriz. Esto provocará un comportamiento no deseado en el código. Por ejemplo, es posible insertar un objeto Range adicional en la matriz, pero si lo hace, producirá errores porque los métodos y propiedades de RangeAreas se comportan como si el nuevo elemento no existiese. Por ejemplo, la propiedad areaCount no incluye intervalos insertados de esta forma y se produce un error de RangeAreas.getItemAt(index) si index es mayor que areasCount-1. De forma similar, al eliminar un objeto Range en la matriz RangeAreas.areas.items obteniendo una referencia a él y llamando a su método Range.delete se producen errores: aunque el objeto Rangese elimina, las propiedades y métodos del objeto RangeAreas primario se comportan, o intentan hacerlo, como si siguiese existiendo. Por ejemplo, si el código llama a RangeAreas.calculate, Office intentará calcular el intervalo, pero se producirá un error porque el objeto de intervalo ha desaparecido.

Establecer propiedades en varios rangos

Establecer una propiedad de un objeto RangeAreas establece la propiedad correspondiente en todos los intervalos de la colección de RangeAreas.areas.

Este es un ejemplo del establecimiento de una propiedad en varios intervalos. La función resalta los intervalos F3:F5 y H3:H5.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let rangeAreas = sheet.getRanges("F3:F5, H3:H5");
    rangeAreas.format.fill.color = "pink";

    await context.sync();
});

Este ejemplo se aplica a los escenarios donde se pueden codificar las direcciones del intervalo que se pasan a getRanges o calcularlas fácilmente en tiempo de ejecución. Algunos de los escenarios en los que esto puede ocurrir son:

  • El código se ejecuta en el contexto de una plantilla conocida.
  • El código se ejecuta en el contexto de datos importados donde se conoce el esquema de los datos.

Combinar RangeAreas con getSpecialCells

Filtre un RangeAreas elemento hasta solo las celdas que coincidan con un criterio, como fórmulas, antes de aplicar formato o validación.

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

    // Two discontiguous vertical bands.
    const targets = sheet.getRanges("A1:A100, C1:C100");

    // Narrow to only the formula cells within those bands.
    const formulaCells = targets.getSpecialCells(Excel.SpecialCellType.formulas);
    formulaCells.format.fill.color = "lightYellow";
    await context.sync();
});

Obtener celdas especiales de varios rangos

Los métodos getSpecialCells y getSpecialCellsOrNullObject en el objeto RangeAreas funcionan de forma análoga a los métodos del mismo nombre en el objeto Range. Estos métodos devuelven las celdas con la característica especificada de todos los rangos de la colección RangeAreas.areas. Para obtener más detalles sobre las celdas especiales, vea Buscar celdas especiales dentro de un rango.

Cuando se llama al método getSpecialCells o getSpecialCellsOrNullObject en un objeto RangeAreas:

  • Si pasa Excel.SpecialCellType.sameConditionalFormat como primer parámetro, el método devuelve todas las celdas con el mismo formato condicional que la celda superior izquierda del primer rango en la colección RangeAreas.areas.
  • Si pasa Excel.SpecialCellType.sameDataValidation como primer parámetro, el método devuelve todas las celdas con la misma validación de datos que la celda superior izquierda del primer rango en la colección RangeAreas.areas.

Lectura de propiedades de RangeAreas

Es necesario prestar atención al leer los valores de propiedad de RangeAreas, ya que una propiedad determinada puede tener diferentes valores para diferentes intervalos de RangeAreas. La regla general es que, si un valor coherente puede devolverse, se devolverá. Por ejemplo, en el código siguiente, el código RGB para rosa (#FFC0CB) y true se registrará en la consola porque ambos rangos del RangeAreas objeto tienen un relleno rosa y ambos son columnas completas.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();

    // The ranges are the F column and the H column.
    let rangeAreas = sheet.getRanges("F:F, H:H");  
    rangeAreas.format.fill.color = "pink";

    rangeAreas.load("format/fill/color, isEntireColumn");
    await context.sync();

    console.log(rangeAreas.format.fill.color); // #FFC0CB
    console.log(rangeAreas.isEntireColumn); // true
});

Puesto que los valores de propiedad pueden diferir, tenga en cuenta estas reglas sencillas.

  • Las propiedades booleanas solo son true si son true en todos los intervalos; de lo contrario, son false.
  • address siempre devuelve la cadena de direcciones delimitadas por comas.
  • Otras propiedades son a menos que todos los intervalos compartan null el mismo valor.

Por ejemplo, el siguiente código crea un RangeAreas donde solo un intervalo es una columna completa y solo uno se rellena con color rosa. La consola mostrará null para el color de relleno, false para la propiedad isEntireRow y "Hoja1!F3:F5, Hoja1!H:H" (suponiendo que el nombre de la hoja es "Hoja1") para la propiedad address.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let rangeAreas = sheet.getRanges("F3:F5, H:H");

    let pinkColumnRange = sheet.getRange("H:H");
    pinkColumnRange.format.fill.color = "pink";

    rangeAreas.load("format/fill/color, isEntireColumn, address");
    await context.sync();

    console.log(rangeAreas.format.fill.color); // null
    console.log(rangeAreas.isEntireColumn); // false
    console.log(rangeAreas.address); // "Sheet1!F3:F5, Sheet1!H:H"
});

Vea también

  • Last updated on