Работа с диапазонами с использованием API JavaScript для Excel (дополнительные задачи)Work with ranges using the Excel JavaScript API (advanced)

Эта статья основана на сведениях из статьи Работа с диапазонами с использованием API JavaScript для Excel (основные задачи) с предоставлением примеров кода, демонстрирующих способы выполнения более сложных задач с диапазонами с использованием API JavaScript для Excel.This article builds upon information in Work with ranges using the Excel JavaScript API (fundamental) by providing code samples that show how to perform more advanced tasks with ranges using the Excel JavaScript API. Полный список свойств и методов, Range поддерживаемых объектом, представлен в разделе объект Range (API JavaScript для Excel).For the complete list of properties and methods that the Range object supports, see Range Object (JavaScript API for Excel).

Работа с датами с использованием подключаемого модуля Moment-MSDateWork with dates using the Moment-MSDate plug-in

Библиотека JavaScript Moment предоставляет удобный способ использования дат и меток времени.The Moment JavaScript library provides a convenient way to use dates and timestamps. Подключаемый модуль Moment-MSDate преобразует формат моментов времени в предпочитаемый для Excel.The Moment-MSDate plug-in converts the format of moments into one preferable for Excel. Это тот же формат, который возвращает функция ТДАТА.This is the same format the NOW function returns.

В приведенном ниже коде показано, как установить для диапазона в B4 метку момента времени.The following code shows how to set the range at B4 to a moment's timestamp:

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");

    var now = Date.now();
    var nowMoment = moment(now);
    var nowMS = nowMoment.toOADate();

    var dateRange = sheet.getRange("B4");
    dateRange.values = [[nowMS]];

    dateRange.numberFormat = [["[$-409]m/d/yy h:mm AM/PM;@"]];

    return context.sync();
}).catch(errorHandlerFunction);

Это похоже на способ получения даты из ячейки и ее преобразования в формат момента времени или другой формат, как показано в приведенном ниже коде:It is a similar technique to get the date back out of the cell and convert it to a moment or other format, as demonstrated in the following code:

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");

    var dateRange = sheet.getRange("B4");
    dateRange.load("values");

    return context.sync().then(function () {
        var nowMS = dateRange.values[0][0];

        // log the date as a moment
        var nowMoment = moment.fromOADate(nowMS);
        console.log(`get (moment): ${JSON.stringify(nowMoment)}`);

        // log the date as a UNIX-style timestamp
        var now = nowMoment.unix();
        console.log(`get (timestamp): ${now}`);
    });
}).catch(errorHandlerFunction);

Вашей надстройке потребуется отформатировать диапазоны, чтобы отобразить даты в более понятной для человека форме.Your add-in will have to format the ranges to display the dates in a more human-readable form. В примере "[$-409]m/d/yy h:mm AM/PM;@" время отобразится как "12/3/18 3:57 PM".The example of "[$-409]m/d/yy h:mm AM/PM;@" displays a time like "12/3/18 3:57 PM". Дополнительные сведения о форматах чисел даты и времени см. в разделе "Рекомендации по форматам даты и времени" статьи Рекомендации по настройке числовых форматов.For more information about date and time number formats, please see the "Guidelines for date and time formats" in the Review guidelines for customizing a number format article.

Одновременное работу с несколькими диапазонамиWork with multiple ranges simultaneously

Объект RangeAreas позволяет надстройке выполнять операции над несколькими диапазонами одновременно.The RangeAreas object lets your add-in perform operations on multiple ranges at once. Эти диапазоны могут быть смежными, но это необязательно.These ranges may be contiguous, but do not have to be. Объект RangeAreas подробнее рассматривается в статье Работа с несколькими диапазонами одновременно в надстройках Excel.RangeAreas are further discussed in the article Work with multiple ranges simultaneously in Excel add-ins.

Поиск специальных ячеек в диапазонеFind special cells within a range

Методы Range. жетспеЦиалцеллс и Range. жетспеЦиалцеллсорнуллобжект находят диапазоны на основе характеристик их ячеек и типов значений их ячеек.The Range.getSpecialCells and Range.getSpecialCellsOrNullObject methods find ranges based on the characteristics of their cells and the types of values of their cells. Оба этих метода возвращают объекты RangeAreas.Both of these methods return RangeAreas objects. Подписи методов из файла типов данных TypeScript:Here are the signatures of the methods from the TypeScript data types file:

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

В приведенном ниже примере используется метод getSpecialCells, чтобы найти все ячейки с формулами.The following example uses the getSpecialCells method to find all the cells with formulas. Вот что нужно знать об этом коде:About this code, note:

  • Он ограничивает часть листа, в которой требуется выполнять поиск, путем вызова сначала метода Worksheet.getUsedRange, а затем метода getSpecialCells только для этого диапазона.It limits the part of the sheet that needs to be searched by first calling Worksheet.getUsedRange and calling getSpecialCells for only that range.
  • Метод getSpecialCells возвращает объект RangeAreas, поэтому все ячейки с формулами окрашены розовым цветом даже в том случае, если они не являются смежными.The getSpecialCells method returns a RangeAreas object, so all of the cells with formulas will be colored pink even if they are not all contiguous.
Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getActiveWorksheet();
    var usedRange = sheet.getUsedRange();
    var formulaRanges = usedRange.getSpecialCells(Excel.SpecialCellType.formulas);
    formulaRanges.format.fill.color = "pink";

    return context.sync();
})

Если в диапазоне нет ячеек с целевыми характеристиками, метод getSpecialCells выдает ошибку ItemNotFound.If no cells with the targeted characteristic exist in the range, getSpecialCells throws an ItemNotFound error. Это приведет к переадресации потока управления к блоку catch, если таковой существует.This diverts the flow of control to a catch block, if there is one. Если catch блок отсутствует, то ошибка приостанавливается для метода.If there isn't a catch block, the error halts the method.

Если ожидается, что всегда должны существовать ячейки с целевыми характеристиками, скорее всего вы захотите, чтобы код выдавал ошибку при их отсутствии.If you expect that cells with the targeted characteristic should always exist, you'll likely want your code to throw an error if those cells aren't there. Если отсутствие соответствующих ячеек является допустимым сценарием, ваш код должен проверить наличие такой возможности и корректно выполнить действие без выдачи ошибки.If it's a valid scenario that there aren't any matching cells, your code should check for this possibility and handle it gracefully without throwing an error. Добиться такого поведения можно с помощью метода getSpecialCellsOrNullObject и возвращаемого им свойства isNullObject.You can achieve this behavior with the getSpecialCellsOrNullObject method and its returned isNullObject property. Этот шаблон используется в приведенном ниже примере.The following example uses this pattern. Вот что нужно знать об этом коде:About this code, note:

  • Метод getSpecialCellsOrNullObject всегда возвращает прокси-объект, поэтому он не может иметь значение null в обычном смысле JavaScript.The getSpecialCellsOrNullObject method always returns a proxy object, so it is never null in the ordinary JavaScript sense. Но если соответствующие ячейки не обнаружены, свойству isNullObject объекта присваивается значение true.But if no matching cells are found, the isNullObject property of the object is set to true.
  • Он вызывает context.sync перед тестированием свойства isNullObject.It calls context.sync before it tests the isNullObject property. Это требование для всех методов и свойств *OrNullObject, так как всегда нужно загружать и синхронизировать свойство, чтобы его прочесть.This is a requirement with all *OrNullObject methods and properties, because you always have to load and sync a property in order to read it. Однако необязательно явно загружать свойство isNullObject.However, it is not necessary to explicitly load the isNullObject property. Оно автоматически загружается с помощью context.sync, даже если load не вызывается для объекта.It is automatically loaded by the context.sync even if load is not called on the object. Дополнительные сведения см. в статье * методы и свойства орнуллобжект.For more information, see *OrNullObject methods and properties.
  • Этот код можно проверить, выбрав сначала диапазон без ячеек с формулами и запустив его.You can test this code by first selecting a range that has no formula cells and running it. Затем следует выбрать диапазон, содержащий по крайней мере одну ячейку с формулой, и снова запустить его.Then select a range that has at least one cell with a formula and run it again.
Excel.run(function (context) {
    var range = context.workbook.getSelectedRange();
    var formulaRanges = range.getSpecialCellsOrNullObject(Excel.SpecialCellType.formulas);
    return context.sync()
        .then(function() {
            if (formulaRanges.isNullObject) {
                console.log("No cells have formulas");
            }
            else {
                formulaRanges.format.fill.color = "pink";
            }
        })
        .then(context.sync);
})

Для удобства во всех других примерах в этой статье используйте метод getSpecialCells вместо getSpecialCellsOrNullObject.For simplicity, all other examples in this article use the getSpecialCells method instead of getSpecialCellsOrNullObject.

Ограничение целевых ячеек с помощью типа значений ячеекNarrow the target cells with cell value types

Методы Range.getSpecialCells() и Range.getSpecialCellsOrNullObject() принимают необязательный второй параметр, используемый для дополнительного ограничения целевых ячеек.The Range.getSpecialCells() and Range.getSpecialCellsOrNullObject() methods accept an optional second parameter used to further narrow down the targeted cells. Этот второй параметр Excel.SpecialCellValueType используется для указания того, что требуются только ячейки, содержащие определенные типы значений.This second parameter is an Excel.SpecialCellValueType you use to specify that you only want cells that contain certain types of values.

Примечание

Параметр Excel.SpecialCellValueType можно использовать, только если для параметра Excel.SpecialCellType задано значение Excel.SpecialCellType.formulas или Excel.SpecialCellType.constants.The Excel.SpecialCellValueType parameter can only be used if the Excel.SpecialCellType is Excel.SpecialCellType.formulas or Excel.SpecialCellType.constants.

Тестирование для ячеек с одним типом значенийTest for a single cell value type

Для перечисления Excel.SpecialCellValueType существует четыре основных типа (в дополнение к другим объединенным значениям, описанным ниже в этом разделе):The Excel.SpecialCellValueType enum has these four basic types (in addition to the other combined values described later in this section):

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

В приведенном ниже примере выполняется поиск специальных ячеек, являющихся числовыми константами, и их окрашивание в розовый цвет.The following example finds special cells that are numerical constants and colors those cells pink. Вот что нужно знать об этом коде:About this code, note:

  • Он выделяет только ячейки с числовым значением литерала.It will only highlight cells that have a literal number value. Он не выделяет ячейки с формулой (даже если результат является числом), логическим значением, текстовым значением или ячейки с состоянием ошибки.It will not highlight cells that have a formula (even if the result is a number) or a boolean, text, or error state cells.
  • Чтобы протестировать код, убедитесь, что в листе есть ячейки с числовыми значениями литералов, ячейки с другими значениями литералов и ячейки с формулами.To test the code, be sure the worksheet has some cells with literal number values, some with other kinds of literal values, and some with formulas.
Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getActiveWorksheet();
    var usedRange = sheet.getUsedRange();
    var constantNumberRanges = usedRange.getSpecialCells(
        Excel.SpecialCellType.constants,
        Excel.SpecialCellValueType.numbers);
    constantNumberRanges.format.fill.color = "pink";

    return context.sync();
})

Тестирование для ячеек с несколькими типами значенийTest for multiple cell value types

Иногда требуется работать с ячейками, имеющими несколько типов значений, например со всеми ячейками с текстовыми значениями и всеми ячейками с логическими значениями (Excel.SpecialCellValueType.logical).Sometimes you need to operate on more than one cell value type, such as all text-valued and all boolean-valued (Excel.SpecialCellValueType.logical) cells. Для перечисления Excel.SpecialCellValueType существуют значения с объединенными типами.The Excel.SpecialCellValueType enum has values with combined types. Например, Excel.SpecialCellValueType.logicalText обрабатывает все ячейки с логическими и текстовыми значениями.For example, Excel.SpecialCellValueType.logicalText targets all boolean and all text-valued cells. Excel.SpecialCellValueType.all является значением по умолчанию, которое не ограничивает возвращаемые типы значений ячеек.Excel.SpecialCellValueType.all is the default value, which does not limit the cell value types returned. В приведенном ниже примере окрашены все ячейки с формулами, которые производят числовое или логическое значение.The following example colors all cells with formulas that produce number or boolean value.

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

    return context.sync();
})

Команды "Вырезать", "Копировать" и "Вставить"Cut, copy, and paste

Copy and pasteCopy and paste

Метод Range. copyFrom реплицирует действия копирования и вставки пользовательского интерфейса Excel.The Range.copyFrom method replicates the Copy and Paste actions of the Excel UI. Диапазон объекта, который вызывается copyFrom, является назначением.The range object that copyFrom is called on is the destination. Источник для копирования передается как диапазон или адрес строки, представляющий диапазон.The source to be copied is passed as a range or a string address representing a range.

В следующем примере кода копируются данные из A1:E1 в диапазон, начиная с G1 (который заканчивается вставкой в G1:K1).The following code sample copies the data from A1:E1 into the range starting at G1 (which ends up pasting into G1:K1).

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");
    // copy everything from "A1:E1" into "G1" and the cells afterwards ("G1:K1")
    sheet.getRange("G1").copyFrom("A1:E1");
    return context.sync();
}).catch(errorHandlerFunction);

У функции Range.copyFrom есть три необязательных параметра.Range.copyFrom has three optional parameters.

copyFrom(sourceRange: Range | RangeAreas | string, copyType?: Excel.RangeCopyType, skipBlanks?: boolean, transpose?: boolean): void;

copyType указывает, какие данные копируются из источника в назначение.copyType specifies what data gets copied from the source to the destination.

  • Excel.RangeCopyType.formulas передает формулы в исходных ячейках и сохраняет относительное расположение диапазонов этих формул.Excel.RangeCopyType.formulas transfers the formulas in the source cells and preserves the relative positioning of those formulas' ranges. Все записи, не являющиеся формулами, копируются в исходном виде.Any non-formula entries are copied as-is.
  • Excel.RangeCopyType.values копирует значения данных, а в случае формул — результат формулы.Excel.RangeCopyType.values copies the data values and, in the case of formulas, the result of the formula.
  • Excel.RangeCopyType.formats копирует форматирование диапазона, включая шрифт, цвет и другие параметры форматирования, но без значений.Excel.RangeCopyType.formats copies the formatting of the range, including font, color, and other format settings, but no values.
  • Excel.RangeCopyType.all (параметр по умолчанию) копирует данные и форматирование, сохраняя формулы ячеек, если они найдены.Excel.RangeCopyType.all (the default option) copies both data and formatting, preserving cells' formulas if found.

skipBlanks устанавливает, будут ли копироваться пустые ячейки в назначение.skipBlanks sets whether blank cells are copied into the destination. Если значение равно true, copyFrom пропускает пустые ячейки в диапазоне источника.When true, copyFrom skips blank cells in the source range. Пропущенные ячейки не перезапишут существующие данные в соответствующих им ячейках конечного диапазона.Skipped cells will not overwrite the existing data of their corresponding cells in the destination range. Значение по умолчанию: false.The default is false.

transpose определяет, переставляются ли данные в исходное расположение, то есть переключаются ли строки и столбцы.transpose determines whether or not the data is transposed, meaning its rows and columns are switched, into the source location. Переставленный диапазон переключается на главной диагонали, поэтому строки 1, 2 и 3 становятся столбцами A, B и C.A transposed range is flipped along the main diagonal, so rows 1, 2, and 3 will become columns A, B, and C.

В приведенном ниже примере кода и изображениях демонстрируется это поведение в простом сценарии.The following code sample and images demonstrate this behavior in a simple scenario.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");
    // copy a range, omitting the blank cells so existing data is not overwritten in those cells
    sheet.getRange("D1").copyFrom("A1:C1",
        Excel.RangeCopyType.all,
        true, // skipBlanks
        false); // transpose
    // copy a range, including the blank cells which will overwrite existing data in the target cells
    sheet.getRange("D2").copyFrom("A2:C2",
        Excel.RangeCopyType.all,
        false, // skipBlanks
        false); // transpose
    return context.sync();
}).catch(errorHandlerFunction);

Прежде чем предыдущая функция была запущена.Before the preceding function has been run.

Данные в Excel перед запуском метода копирования диапазона

После запуска предыдущей функции.After the preceding function has been run.

Данные в Excel после запуска метода копирования диапазона

Вырезание и вставка (перемещение) ячеекCut and paste (move) cells

Метод Range. moveTo перемещает ячейки в новое расположение в книге.The Range.moveTo method moves cells to a new location in the workbook. Поведение перемещения ячейки работает так же, как при перемещении ячеек, перетаскивая границу диапазона или при выполнении действий по вырезанию и вставке .This cell movement behavior works the same as when cells are moved by dragging the range border or when taking the Cut and Paste actions. Форматирование и значения диапазона перемещаются в расположение, указанное в качестве destinationRange параметра.Both the formatting and values of the range are moved to the location specified as the destinationRange parameter.

В следующем примере кода показан диапазон, перемещенный с Range.moveTo методом.The following code sample shows a range being moved with the Range.moveTo method. Обратите внимание, что если конечный диапазон меньше исходного, он будет развернут, чтобы охватывать исходное содержимое.Note that if the destination range is smaller than the source, it will be expanded to encompass the source content.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getActiveWorksheet();
    sheet.getRange("F1").values = [["Moved Range"]];

    // Move the cells "A1:E1" to "G1" (which fills the range "G1:K1").
    sheet.getRange("A1:E1").moveTo("G1");
    return context.sync();
});

Удаление дубликатовRemove duplicates

Метод Range. removeDuplicates удаляет строки с повторяющимися записями в указанных столбцах.The Range.removeDuplicates method removes rows with duplicate entries in the specified columns. Метод проходит через каждую строку в диапазоне от самого низкого значения до индекса с максимальным значением в диапазоне (сверху вниз).The method goes through each row in the range from the lowest-valued index to the highest-valued index in the range (from top to bottom). Строка удаляется, если значение в ее указанном столбце или столбцах уже встречалось в диапазоне.A row is deleted if a value in its specified column or columns appeared earlier in the range. Строки в диапазоне под удаленной строкой сдвигаются вверх.Rows in the range below the deleted row are shifted up. Функция removeDuplicates не влияет на положение ячеек вне диапазона.removeDuplicates does not affect the position of cells outside of the range.

Функция removeDuplicates использует параметр number[], представляющий индексы столбцов, которые проверяются на наличие дубликатов.removeDuplicates takes in a number[] representing the column indices which are checked for duplicates. Этот массив отсчитывается от нуля относительно диапазона, а не листа.This array is zero-based and relative to the range, not the worksheet. Метод также использует логический параметр, указывающий, является ли первая строка заголовком.The method also takes in a boolean parameter that specifies whether the first row is a header. При значении true верхняя строка игнорируется при поиске дубликатов.When true, the top row is ignored when considering duplicates. removeDuplicatesМетод возвращает RemoveDuplicatesResult объект, указывающий количество удаленных строк и количество оставшихся уникальных строк.The removeDuplicates method returns a RemoveDuplicatesResult object that specifies the number of rows removed and the number of unique rows remaining.

При использовании метода диапазона учитывайте removeDuplicates следующее:When using a range's removeDuplicates method, keep the following in mind:

  • Функция removeDuplicates рассматривает значения ячеек, а не результаты функций.removeDuplicates considers cell values, not function results. Если две разные функции вычисляют одинаковый результат, значения ячеек не считаются повторяющимися.If two different functions evaluate to the same result, the cell values are not considered duplicates.
  • Пустые ячейки не игнорируются функцией removeDuplicates.Empty cells are not ignored by removeDuplicates. Значение пустой ячейки обрабатывается как любое другое значение.The value of an empty cell is treated like any other value. Это означает, что пустые строки, содержащиеся в диапазоне, будут включены в объект RemoveDuplicatesResult.This means empty rows contained within in the range will be included in the RemoveDuplicatesResult.

В приведенном ниже примере показано удаление записей с повторяющимися значениями в первом столбце.The following sample shows the removal of entries with duplicate values in the first column.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");
    var range = sheet.getRange("B2:D11");

    var deleteResult = range.removeDuplicates([0],true);
    deleteResult.load();

    return context.sync().then(function () {
        console.log(deleteResult.removed + " entries with duplicate names removed.");
        console.log(deleteResult.uniqueRemaining + " entries with unique names remain in the range.");
    });
}).catch(errorHandlerFunction);

Прежде чем предыдущая функция была запущена.Before the preceding function has been run.

Данные в Excel перед выполнением метода удаления дубликатов в диапазоне

После запуска предыдущей функции.After the preceding function has been run.

Данные в Excel после запуска метода удаления повторяющихся значений диапазона

Группирование данных для структурыGroup data for an outline

Строки или столбцы диапазона можно объединять для создания структуры.Rows or columns of a range can be grouped together to create an outline. Эти группы можно сворачивать и разворачивать для скрытия и отображения соответствующих ячеек.These groups can be collapsed and expanded to hide and show the corresponding cells. Это упрощает быстрый анализ данных в верхней строке.This makes quick analysis of top-line data easier. Используйте Range. Group , чтобы сделать эти группы структуры.Use Range.group to make these outline groups.

Структура может иметь иерархию, где небольшие группы вложены в крупные группы.An outline can have a hierarchy, where smaller groups are nested under larger groups. Это позволяет просматривать структуру на разных уровнях.This allows the outline to be viewed at different levels. Изменение видимого уровня структуры можно выполнить программным способом с помощью метода листа. шоваутлинелевелс .Changing the visible outline level can be done programmatically through the Worksheet.showOutlineLevels method. Обратите внимание, что Excel поддерживает только восемь уровней групп структуры.Note that Excel only supports eight levels of outline groups.

В приведенном ниже примере кода показано, как создать структуру с двумя уровнями групп для строк и столбцов.The following code sample shows how to create an outline with two levels of groups for both the rows and columns. На следующем изображении показаны группирования этой структуры.The subsequent image shows the groupings of that outline. Обратите внимание, что в примере кода сгруппированные диапазоны не включают строку или столбец элемента управления структуры (итоговые значения для этого примера).Note that in the code sample, the ranges being grouped do not include the row or column of the outline control (the "Totals" for this example). Группа определяет, что будет свернуто, а не как строка или столбец с элементом управления.A group defines what will be collapsed, not the row or column with the control.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");

    // Group the larger, main level. Note that the outline controls
    // will be on row 10, meaning 4-9 will collapse and expand.
    sheet.getRange("4:9").group(Excel.GroupOption.byRows);

    // Group the smaller, sublevels. Note that the outline controls
    // will be on rows 6 and 9, meaning 4-5 and 7-8 will collapse and expand.
    sheet.getRange("4:5").group(Excel.GroupOption.byRows);
    sheet.getRange("7:8").group(Excel.GroupOption.byRows);

    // Group the larger, main level. Note that the outline controls
    // will be on column R, meaning C-Q will collapse and expand.
    sheet.getRange("C:Q").group(Excel.GroupOption.byColumns);

    // Group the smaller, sublevels. Note that the outline controls
    // will be on columns G, L, and R, meaning C-F, H-K, and M-P will collapse and expand.
    sheet.getRange("C:F").group(Excel.GroupOption.byColumns);
    sheet.getRange("H:K").group(Excel.GroupOption.byColumns);
    sheet.getRange("M:P").group(Excel.GroupOption.byColumns);
    return context.sync();
}).catch(errorHandlerFunction);

Диапазон с двумя уровнями структуры с двумя измерениями

Чтобы разгруппировать группу строк или столбцов, используйте метод Range. Ungroup .To ungroup a row or column group, use the Range.ungroup method. Это приведет к удалению внешнего уровня структуры.This removes the outermost level from the outline. Если несколько групп одного и того же типа строк или столбцов находятся на одном уровне в пределах указанного диапазона, все эти группы размещаются в разгруппировании.If multiple groups of the same row or column type are at the same level within the specified range, all of those groups are ungrouped.

Обработка динамических массивов и сбросHandle dynamic arrays and spilling

Некоторые формулы Excel возвращают динамические массивы.Some Excel formulas return Dynamic arrays. Эти значения заполняют значения нескольких ячеек за прев ячейке оргинал в формуле.These fill the values of multiple cells outside of the formula's orginal cell. Это значение переполнения называется "Spill".This value overflow is referred to as a "spill". Надстройка может найти диапазон, используемый для Spill, с помощью метода Range. жетспиллингторанже .Your add-in can find the range used for a spill with the Range.getSpillingToRange method. Кроме того, существует версия * орнуллобжект, Range.getSpillingToRangeOrNullObject .There is also a *OrNullObject version, Range.getSpillingToRangeOrNullObject.

В следующем примере показана базовая формула, которая копирует содержимое диапазона в ячейку, которая переводится в соседние ячейки.The following sample shows a basic formula that copies the contents of a range into a cell, which spills into neighboring cells. Затем надстройка заносит в журнал диапазон, содержащий сброс.The add-in then logs the range that contains the spill.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");

    // Set G4 to a formula that returns a dynamic array.
    var targetCell = sheet.getRange("G4");
    targetCell.formulas = [["=A4:D4"]];

    // Get the address of the cells that the dynamic array spilled into.
    var spillRange = targetCell.getSpillingToRange();
    spillRange.load("address");

    // Sync and log the spilled-to range.
    return context.sync().then(function () {
        // This will log the range as "G4:J4".
        console.log(`Copying the table headers spilled into ${spillRange.address}.`);
    });
}).catch(errorHandlerFunction);

Кроме того, можно найти ячейку, отвечающую за прохождение в заданную ячейку, с помощью метода Range. жетспиллпарент .You can also find the cell responsible for spilling into a given cell by using the Range.getSpillParent method. Обратите внимание, что getSpillParent работает, только если объект Range является одной ячейкой.Note that getSpillParent only works when the range object is a single cell. Вызов getSpillParent в диапазоне с несколькими ячейками приведет к ошибке (или возвращаемому диапазону значений NULL Range.getSpillParentOrNullObject ).Calling getSpillParent on a range with multiple cells will result in an error being thrown (or a null range being returned for Range.getSpillParentOrNullObject).

Получение ячеек формулыGet formula precedents

Формула Excel часто ссылается на другие ячейки.An Excel formula often refers to other cells. Когда ячейка предоставляет данные формуле, она называется "влияющей" формулой.When a cell provides data to a formula, it is known as a formula "precedent". Дополнительные сведения о функциях Excel, связанных с отношениями между ячейками, приведены в статье Отображение связей между формулами и ячейками .To learn more about Excel features related to relationships between cells, see the Display the relationships between formulas and cells article.

С помощью Range. жетдиректпрецедентснадстройка может искать прямые влияющие ячейки формулы.With Range.getDirectPrecedents, your add-in can locate a formula's direct precedent cells. Range.getDirectPrecedents Возвращает WorkbookRangeAreas объект.Range.getDirectPrecedents returns a WorkbookRangeAreas object. Этот объект содержит адреса всех влияющих ячеек в книге.This object contains the addresses of all the precedents in the workbook. У него есть отдельный RangeAreas объект для каждого листа, содержащего по крайней мере одну формулу.It has a separate RangeAreas object for each worksheet containing at least one formula precedent. Узнайте , как работать с несколькими диапазонами одновременно в надстройках Excel, чтобы получить дополнительные сведения о работе с RangeAreas объектом.See Work with multiple ranges simultaneously in Excel add-ins for more information on working with the RangeAreas object.

В пользовательском интерфейсе Excel кнопка трассировки влияющих элементов рисует стрелку от влияющих ячеек до выбранной формулы.In the Excel UI, the Trace Precedents button draws an arrow from precedent cells to the selected formula. В отличие от кнопки пользовательского интерфейса Excel, getDirectPrecedents метод не рисует стрелки.Unlike the Excel UI button, the getDirectPrecedents method does not draw arrows.

Важно!

getDirectPrecedentsМетод не может получать влияющие ячейки между книгами.The getDirectPrecedents method can't retrieve precedent cells across workbooks.

В примере ниже показано, как получить прямые и влияющие границы для активного диапазона, а затем изменить цвет фона этих ячеек на желтый.The following sample gets the direct precedents for the active range and then changes the background color of those precedent cells to yellow.

Примечание

Активный диапазон должен содержать формулу, ссылающуюся на другие ячейки в той же книге, чтобы выделение работало должным образом.The active range must contain a formula that references other cells in the same workbook for the highlighting to work properly.

Excel.run(function (context) {
    // Precedents are cells that provide data to the selected formula.
    var range = context.workbook.getActiveCell();
    var directPrecedents = range.getDirectPrecedents();
    range.load("address");
    directPrecedents.areas.load("address");
    
    return context.sync()
        .then(function () {
            console.log(`Direct precedent cells of ${range.address}:`);

            // Use the direct precedents API to loop through precedents of the active cell.
            for (var i = 0; i < directPrecedents.areas.items.length; i++) {
              // Highlight and print out the address of each precedent cell.
              directPrecedents.areas.items[i].format.fill.color = "Yellow";
              console.log(`  ${directPrecedents.areas.items[i].address}`);
            }
        })
        .then(context.sync);
}).catch(errorHandlerFunction);

См. такжеSee also