Пустые значения и значения NULL в надстройках Excel

2023-04-07

Значения null и пустые строки имеют специальные применения в API JavaScript для Excel. Они используются для представления пустых ячеек, отсутствия форматирования или значений по умолчанию. В этом разделе описано использование значения null и пустой строки при получении и настройке свойств.

Входное значение null в двумерном массиве

В Excel диапазон представлен двумерным массивом, в котором первое измерение — это строки, а второе — столбцы. Чтобы задать значения, формат чисел или формулу только для определенных ячеек в диапазоне, укажите значения, формат чисел или формулу для этих ячеек в двумерном массиве, а для всех остальных ячеек в этом массиве укажите значение null.

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

range.values = [['Eurasia', '29.96', '0.25', '15-Feb' ]];
range.numberFormat = [[null, null, null, 'm/d/yyyy;@']];

Входное значение null для свойства

null не является допустимым входным значением для одного свойства. Например, следующий фрагмент кода недопустим, так как свойству values диапазона нельзя присвоить значение null.

range.values = null; // This is not a valid snippet.

Аналогично, указанный ниже фрагмент кода не является допустимым, так как null — недопустимое значение для свойства color.

range.format.fill.color =  null;  // This is not a valid snippet.

Значения свойств null в ответе

Если в указанном диапазоне имеются другие значения, свойства форматирования, например size и color будут содержать значения null в ответе. Например, если вы получаете диапазон и загружаете его свойство format.font.color:

Если у всех ячеек в диапазоне один и тот же цвет шрифта, свойство range.format.font.color указывает этот цвет.
Если в диапазоне используется несколько цветов шрифтов, свойство range.format.font.color имеет значение null.

Пустое входное значение для свойства

Когда вы указываете пустое значение для свойства (то есть две кавычки подряд без других знаков между ''), это будет интерпретировано как инструкция по очистке или сбросу свойства. Например:

Если вы укажете пустое значение для свойства values диапазона, содержимое диапазона будет очищено.
Если вы укажете пустое значение для свойства numberFormat, формат чисел будет "сброшен" до формата General.
Если вы укажете пустое значение для свойств formula и formulaLocale, значения формул будут очищены.

Значения пустых свойств в ответе

Для операций чтения пустое значение свойства в ответе (то есть две кавычки подряд без других знаков между '') указывает, что ячейка не содержит данных или значения. В первом примере ниже первая и последняя ячейки в диапазоне не содержат данных. Во втором примере две первые ячейки в диапазоне не содержат формул.

range.values = [['', 'some', 'data', 'in', 'other', 'cells', '']];

range.formula = [['', '', '=Rand()']];