Поделиться через

Поиск специальных ячеек в диапазоне с помощью API JavaScript для Excel

  • Статья

В этой статье приведены примеры кода, которые находят специальные ячейки в диапазоне с помощью API JavaScript для Excel. Полный список свойств и методов, поддерживаемых объектом, см. в Rangeразделе Класс Excel.Range.

Поиск диапазонов с помощью специальных ячеек

Методы Range.getSpecialCells и Range.getSpecialCellsOrNullObject находят диапазоны на основе характеристик ячеек и типов значений ячеек. Оба этих метода возвращают объекты RangeAreas. Подписи методов из файла типов данных TypeScript:

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

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

В следующем примере кода метод используется getSpecialCells для поиска всех ячеек с формулами. Вот что нужно знать об этом коде:

  • Он ограничивает часть листа, в которой требуется выполнять поиск, путем вызова сначала метода Worksheet.getUsedRange, а затем метода getSpecialCells только для этого диапазона.
  • Метод getSpecialCells возвращает объект RangeAreas, поэтому все ячейки с формулами окрашены розовым цветом даже в том случае, если они не являются смежными.
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();
});

Если в диапазоне нет ячеек с целевыми характеристиками, метод getSpecialCells выдает ошибку ItemNotFound. Это приведет к переадресации потока управления к блоку catch, если таковой существует. Если блока нет catch , ошибка останавливает метод .

Если ожидается, что всегда должны существовать ячейки с целевыми характеристиками, скорее всего вы захотите, чтобы код выдавал ошибку при их отсутствии. Если отсутствие соответствующих ячеек является допустимым сценарием, ваш код должен проверить наличие такой возможности и корректно выполнить действие без выдачи ошибки. Добиться такого поведения можно с помощью метода getSpecialCellsOrNullObject и возвращаемого им свойства isNullObject. В следующем примере кода используется этот шаблон. Вот что нужно знать об этом коде:

  • Метод getSpecialCellsOrNullObject всегда возвращает прокси-объект, поэтому он никогда не null используется в обычном смысле JavaScript. Но если соответствующие ячейки не обнаружены, свойству isNullObject объекта присваивается значение true.
  • Он вызывает context.syncперед проверкой isNullObject свойства. Это требование для всех методов и свойств *OrNullObject, так как всегда нужно загружать и синхронизировать свойство, чтобы его прочесть. Однако явно загружать isNullObject свойство не требуется. Он автоматически загружается объектом , context.sync даже если load не вызывается для объекта . Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.
  • Этот код можно проверить, выбрав сначала диапазон без ячеек с формулами и запустив его. Затем следует выбрать диапазон, содержащий по крайней мере одну ячейку с формулой, и снова запустить его.
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();
});

Для простоты во всех других примерах кода в этой статье используется getSpecialCells метод вместо getSpecialCellsOrNullObject.

Ограничение целевых ячеек с помощью типа значений ячеек

Методы Range.getSpecialCells() и Range.getSpecialCellsOrNullObject() принимают необязательный второй параметр, используемый для дополнительного ограничения целевых ячеек. Этот второй параметр Excel.SpecialCellValueType используется для указания того, что требуются только ячейки, содержащие определенные типы значений.

Примечание.

Параметр Excel.SpecialCellValueType можно использовать, только если для параметра Excel.SpecialCellType задано значение Excel.SpecialCellType.formulas или Excel.SpecialCellType.constants.

Тестирование для ячеек с одним типом значений

Для перечисления Excel.SpecialCellValueType существует четыре основных типа (в дополнение к другим объединенным значениям, описанным ниже в этом разделе):

  • Excel.SpecialCellValueType.errors
  • Excel.SpecialCellValueType.logical (означает логическое значение)
  • Excel.SpecialCellValueType.numbers
  • Excel.SpecialCellValueType.text

Следующий пример кода находит специальные ячейки, которые являются числовыми константами, и цвет этих ячеек в розовый цвет. Вот что нужно знать об этом коде:

  • Он выделяет только ячейки с литеральным числом. Он не выделяет ячейки с формулой (даже если результатом является число) или логические ячейки, текстовые ячейки или ячейки состояния ошибки.
  • Чтобы протестировать код, убедитесь, что в листе есть ячейки с числовыми значениями литералов, ячейки с другими значениями литералов и ячейки с формулами.
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();
});

Тестирование для ячеек с несколькими типами значений

Иногда требуется работать с ячейками, имеющими несколько типов значений, например со всеми ячейками с текстовыми значениями и всеми ячейками с логическими значениями (Excel.SpecialCellValueType.logical). Для перечисления Excel.SpecialCellValueType существуют значения с объединенными типами. Например, Excel.SpecialCellValueType.logicalText обрабатывает все ячейки с логическими и текстовыми значениями. Excel.SpecialCellValueType.all является значением по умолчанию, которое не ограничивает возвращаемые типы значений ячеек. В следующем примере кода все ячейки окрашены формулами, которые создают число или логическое значение.

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();
});

См. также