Учебник: Создание надстройки области задач ExcelTutorial: Create an Excel task pane add-in

С помощью данного учебника вы сможете создать надстройку области задач Excel, которая выполняет следующие действия:In this tutorial, you'll create an Excel task pane add-in that:

  • Создание таблицыCreates a table
  • Фильтрация и сортировка таблицыFilters and sorts a table
  • Создание графикаCreates a chart
  • Закрепление заголовка таблицыFreezes a table header
  • Защита листаProtects a worksheet
  • Открытие диалогового окнаOpens a dialog

Необходимые компонентыPrerequisites

Для работы с этим учебником необходимо установить указанные ниже компоненты.To use this tutorial, you need to have the following installed.

  • Excel 2016, версия 1711 (сборка 8730.1000 "нажми и работай") или более поздняя. Чтобы установить эту версию, необходимо быть участником программы предварительной оценки Office. Дополнительные сведенияExcel 2016, version 1711 (Build 8730.1000 Click-to-Run) or later. You might need to be an Office Insider to get this version. For more information, see Be an Office Insider.

  • NodeNode

  • Git Bash (или другой клиент Git)Git Bash (or another Git client)

  • Чтобы протестировать надстройку в этом руководстве, необходимо подключиться к Интернету.You need to have an Internet connection to test the add-in in this tutorial.

Создание проекта надстройкиCreate your add-in project

Выполните указанные ниже действия для создания проекта надстройки Excel, который будет использоваться в качестве основы для этого учебника.Complete the following steps to create the Excel add-in project that you'll use as the basis for this tutorial.

  1. Клонируйте репозиторий GitHub Excel Add-in Tutorial.Clone the GitHub repository Excel add-in tutorial.

  2. Откройте окно Git Bash или системную командную строку с поддержкой Node.JS и перейдите к папке Start проекта.Open a Git bash window, or Node.JS-enabled system prompt, and navigate to the Start folder of the project.

  3. Выполните команду npm install, чтобы установить инструменты и библиотеки, указанные в файле package.json.Run the command npm install to install the tools and libraries listed in the package.json file.

  4. Выполните действия, описанные в статье Установка самозаверяющего сертификата , чтобы доверять сертификату операционной системы на компьютере разработчика.Carry out the steps in Installing the self-signed certificate to trust the certificate for your development computer's operating system.

Создание таблицыCreate a table

На этом этапе руководства мы проверим программным способом, поддерживает ли надстройка текущую версию Excel, установленную у пользователя, а также добавим таблицу на лист, заполним ее данными и отформатируем.In this step of the tutorial, you'll programmatically test that your add-in supports the user's current version of Excel, add a table to a worksheet, populate the table with data, and format it.

Написание кода надстройкиCode the add-in

  1. Откройте проект в редакторе кода.Open the project in your code editor.

  2. Откройте файл index.html.Open the file index.html.

  3. Замените TODO1 на следующую разметку:Replace the TODO1 with the following markup:

    <button class="ms-Button" id="create-table">Create Table</button>
    
  4. Откройте файл app.js.Open the app.js file.

  5. Замените TODO1 на приведенный ниже код. Этот код определяет, поддерживает ли установленная у пользователя версия Excel ту версию файла Excel.js, которая включает все API, используемые в этой серии руководств. В рабочей надстройке можно использовать текст условного блока, чтобы скрыть или отключить пользовательский интерфейс, где вызываются неподдерживаемые API. При этом пользователь по-прежнему сможет использовать те части надстройки, которые поддерживаются в его версии Excel.Replace the TODO1 with the following code. This code determines whether the user's version of Excel supports a version of Excel.js that includes all the APIs that this series of tutorials will use. In a production add-in, use the body of the conditional block to hide or disable the UI that would call unsupported APIs. This will enable the user to still make use of the parts of the add-in that are supported by their version of Excel.

    if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
        console.log('Sorry. The tutorial add-in uses Excel.js APIs that are not available in your version of Office.');
    }
    
  6. Замените TODO2 на следующий код:Replace the TODO2 with the following code:

    $('#create-table').click(createTable);
    
  7. Замените TODO3 приведенным ниже кодом.Replace the TODO3 with the following code. Примечание.Note:

    • Бизнес-логика Excel.js будет добавлена в функцию, передаваемую методу Excel.run. Эта логика выполняется не сразу. Вместо этого она добавляется в очередь ожидания команд.Your Excel.js business logic will be added to the function that is passed to Excel.run. This logic does not execute immediately. Instead, it is added to a queue of pending commands.

    • Метод context.sync отправляет все команды из очереди в Excel для выполнения.The context.sync method sends all queued commands to Excel for execution.

    • За методом Excel.run следует блок catch. Рекомендуется всегда следовать этой методике.The Excel.run is followed by a catch block. This is a best practice that you should always follow.

    function createTable() {
        Excel.run(function (context) {
    
            // TODO4: Queue table creation logic here.
    
            // TODO5: Queue commands to populate the table with data.
    
            // TODO6: Queue commands to format the table.
    
            return context.sync();
        })
        .catch(function (error) {
            console.log("Error: " + error);
            if (error instanceof OfficeExtension.Error) {
                console.log("Debug info: " + JSON.stringify(error.debugInfo));
            }
        });
    }
    
  8. Замените TODO4 на приведенный ниже код. Обратите внимание:Replace TODO4 with the following code. Note:

    • код создает таблицу с помощью метода add коллекции таблиц на листе, которая всегда существует, даже если она пуста. Это стандартный способ создания объектов Excel.js. API конструкторов классов не существуют, а для создания объекта Excel никогда не следует использовать оператор new. Вместо этого следует добавить его к объекту родительской коллекции.The code creates a table by using add method of a worksheet's table collection, which always exists even if it is empty. This is the standard way that Excel.js objects are created. There are no class constructor APIs, and you never use a new operator to create an Excel object. Instead, you add to a parent collection object.

    • Первый параметр метода add— это диапазон, содержащий только первую строку, а не весь диапазон таблицы, который мы в конечном итоге будем использовать. Это связано с тем, что при заполнении строк данных (на следующем этапе) надстройка добавляет к таблице новые строки, а не записывает их в ячейки имеющихся строк. Такой шаблон более распространен, так как количество строк в таблице часто неизвестно на момент ее создания.The first parameter of the add method is the range of only the top row of the table, not the entire range the table will ultimately use. This is because when the add-in populates the data rows (in the next step), it will add new rows to the table instead of writing values to the cells of existing rows. This is a more common pattern because the number of rows that a table will have is often not known when the table is created.

    • Имена таблиц должны быть уникальными в рамках всей книги, а не только одного листа.Table names must be unique across the entire workbook, not just the worksheet.

    var currentWorksheet = context.workbook.worksheets.getActiveWorksheet();
    var expensesTable = currentWorksheet.tables.add("A1:D1", true /*hasHeaders*/);
    expensesTable.name = "ExpensesTable";
    
  9. Замените TODO5 приведенным ниже кодом.Replace TODO5 with the following code. Примечание:Note:

    • значения ячеек диапазона задаются с помощью массива массивов.The cell values of a range are set with an array of arrays.

    • Новые строки создаются в таблице путем вызова метода add коллекции ее строк. Вы можете добавить несколько строк в одном вызове метода add, включив несколько массивов значений ячеек в родительский массив, передаваемый в качестве второго параметра.New rows are created in a table by calling the add method of the table's row collection. You can add multiple rows in a single call of add by including multiple cell value arrays in the parent array that is passed as the second parameter.

    expensesTable.getHeaderRowRange().values =
        [["Date", "Merchant", "Category", "Amount"]];
    
    expensesTable.rows.add(null /*add at the end*/, [
        ["1/1/2017", "The Phone Company", "Communications", "120"],
        ["1/2/2017", "Northwind Electric Cars", "Transportation", "142.33"],
        ["1/5/2017", "Best For You Organics Company", "Groceries", "27.9"],
        ["1/10/2017", "Coho Vineyard", "Restaurant", "33"],
        ["1/11/2017", "Bellows College", "Education", "350.1"],
        ["1/15/2017", "Trey Research", "Other", "135"],
        ["1/15/2017", "Best For You Organics Company", "Groceries", "97.88"]
    ]);
    
  10. Замените TODO6 на приведенный ниже код. Примечание:Replace TODO6 with the following code. Note:

  • код получает ссылку на столбец Сумма, передавая его индекс (с отсчетом от нуля) в метод getItemAt коллекции столбцов таблицы.The code gets a reference to the Amount column by passing its zero-based index to the getItemAt method of the table's column collection.

    Примечание

    У объектов коллекций Excel.js (например, TableCollection, WorksheetCollection и TableColumnCollection) есть свойство items, представляющее собой массив дочерних типов объектов (например, Table, Worksheet или TableColumn). Однако сам объект *Collection не является массивом.Excel.js collection objects, such as TableCollection, WorksheetCollection, and TableColumnCollection have an items property that is an array of the child object types, such as Table or Worksheet or TableColumn; but a *Collection object is not itself an array.

  • Затем код форматирует диапазон столбца Сумма как денежные суммы в евро с точностью до второго знака после запятой.The code then formats the range of the Amount column as Euros to the second decimal.

  • Напоследок он обеспечивает достаточные ширину столбцов и высоту строк для размещения самого длинного (или самого высокого) элемента данных. Обратите внимание, что код должен привести объекты Range к нужному формату. У объектов TableColumn и TableRow нет свойств формата.Finally, it ensures that the width of the columns and height of the rows is big enough to fit the longest (or tallest) data item. Notice that the code must get Range objects to format. TableColumn and TableRow objects do not have format properties.

    expensesTable.columns.getItemAt(3).getRange().numberFormat = [['€#,##0.00']];
    expensesTable.getRange().format.autofitColumns();
    expensesTable.getRange().format.autofitRows();
    

Тестирование надстройкиTest the add-in

  1. Откройте окно Git Bash или системную командную строку с поддержкой Node.JS и перейдите к папке Start проекта.Open a Git bash window, or Node.JS-enabled system prompt, and navigate to the Start folder of the project.

  2. Выполните команду npm run build , чтобы преES6 исходный код в более раннюю версию JavaScript, поддерживаемую Internet Explorer (которая используется в некоторых версиях Excel для запуска надстроек Excel).Run the command npm run build to transpile your ES6 source code to an earlier version of JavaScript that is supported by Internet Explorer (which is used by some versions of Excel to run Excel add-ins).

  3. Выполните команду npm start, чтобы запустить веб-сервер, работающий на localhost.Run the command npm start to start a web server running on localhost.

  4. Загрузите неопубликованную надстройку одним из следующих способов:Sideload the add-in by using one of the following methods:

  5. В меню Главная выберите пункт Показать область задач.On the Home menu, choose Show Taskpane.

  6. В области задач нажмите кнопку Create Table (Создать таблицу).In the task pane, choose Create Table.

    Руководство по Excel: создание таблицы

Фильтрация и сортировка таблицыFilter and sort a table

Из этого раздела руководства вы узнаете, как отфильтровать и отсортировать созданную ранее таблицу.In this step of the tutorial, you'll filter and sort the table that you created previously.

Фильтрация таблицыFilter the table

  1. Откройте проект в редакторе кода.Open the project in your code editor.

  2. Откройте файл index.html.Open the file index.html.

  3. Под элементом div, содержащим кнопку create-table, добавьте следующую разметку:Just below the div that contains the create-table button, add the following markup:

    <div class="padding">
        <button class="ms-Button" id="filter-table">Filter Table</button>
    </div>
    
  4. Откройте файл app.js.Open the app.js file.

  5. Под строкой, назначающей обработчик нажатия кнопки create-table, добавьте следующий код:Just below the line that assigns a click handler to the create-table button, add the following code:

    $('#filter-table').click(filterTable);
    
  6. Под функцией createTable добавьте следующую функцию:Just below the createTable function, add the following function:

    function filterTable() {
        Excel.run(function (context) {
    
            // TODO1: Queue commands to filter out all expense categories except
            //        Groceries and Education.
    
            return context.sync();
        })
        .catch(function (error) {
            console.log("Error: " + error);
            if (error instanceof OfficeExtension.Error) {
                console.log("Debug info: " + JSON.stringify(error.debugInfo));
            }
        });
    }
    
  7. Замените TODO1 приведенным ниже кодом.Replace TODO1 with the following code. Обратите внимание:Note:

    • Код получает ссылку на столбец, который нужно отфильтровать, передавая имя столбца методу getItem, а не передавая его индекс методу getItemAt, как это делает метод createTable. Так как пользователи могут перемещать столбцы, по заданному индексу может располагаться уже другой столбец. Следовательно, для получения ссылки безопаснее использовать имя столбца. Мы спокойно использовали метод getItemAt в предыдущем разделе, потому что мы использовали его в методе, который создает таблицу, и пользователь никак не мог переместить столбец.The code first gets a reference to the column that needs filtering by passing the column name to the getItem method, instead of passing its index to the getItemAt method as the createTable method does. Since users can move table columns, the column at a given index might change after the table is created. Hence, it is safer to use the column name to get a reference to the column. We used getItemAt safely in the preceding tutorial, because we used it in the very same method that creates the table, so there is no chance that a user has moved the column.

    • Метод applyValuesFilter является одним из нескольких методов фильтрации объекта Filter.The applyValuesFilter method is one of several filtering methods on the Filter object.

    var currentWorksheet = context.workbook.worksheets.getActiveWorksheet();
    var expensesTable = currentWorksheet.tables.getItem('ExpensesTable');
    var categoryFilter = expensesTable.columns.getItem('Category').filter;
    categoryFilter.applyValuesFilter(["Education", "Groceries"]);
    

Сортировка таблицыSort the table

  1. Откройте файл index.html.Open the file index.html.

  2. Под элементом div, содержащим кнопку filter-table, добавьте следующую разметку:Below the div that contains the filter-table button, add the following markup:

    <div class="padding">
        <button class="ms-Button" id="sort-table">Sort Table</button>
    </div>
    
  3. Откройте файл app.js.Open the app.js file.

  4. Под строкой, назначающей обработчик нажатия кнопки filter-table, добавьте следующий код:Below the line that assigns a click handler to the filter-table button, add the following code:

    $('#sort-table').click(sortTable);
    
  5. Под функцией filterTable добавьте приведенную ниже функцию.Below the filterTable function add the following function.

    function sortTable() {
        Excel.run(function (context) {
    
            // TODO1: Queue commands to sort the table by Merchant name.
    
            return context.sync();
        })
        .catch(function (error) {
            console.log("Error: " + error);
            if (error instanceof OfficeExtension.Error) {
                console.log("Debug info: " + JSON.stringify(error.debugInfo));
            }
        });
    }
    
  6. Замените TODO1 приведенным ниже кодом.Replace TODO1 with the following code. Обратите внимание:Note:

    • Код создает массив объектов SortField, состоящий из одного элемента, так как надстройка сортирует таблицу только по столбцу Merchant.The code creates an array of SortField objects which has just one member since the add-in only sorts on the Merchant column.

    • Свойство key объекта SortField — это отсчитываемый от нуля индекс столбца, по которому необходимо сортировать таблицу.The key property of a SortField object is the zero-based index of the column to sort-on.

    • Элемент sort объекта Table — это объект TableSort, а не метод.The sort member of a Table is a TableSort object, not a method. Объекты SortField передаются методу apply объекта TableSort.The SortFields are passed to the TableSort object's apply method.

    var currentWorksheet = context.workbook.worksheets.getActiveWorksheet();
    var expensesTable = currentWorksheet.tables.getItem('ExpensesTable');
    var sortFields = [
        {
            key: 1,            // Merchant column
            ascending: false,
        }
    ];
    
    expensesTable.sort.apply(sortFields);
    

Тестирование надстройкиTest the add-in

  1. Если окно Git Bash или системная командная строка с поддержкой Node.JS, открытые на предыдущем этапе руководства, все еще открыты, дважды нажмите клавиши Ctrl+C, чтобы остановить работу веб-сервера.If the Git bash window, or Node.JS-enabled system prompt, from the previous stage tutorial is still open, enter Ctrl+C twice to stop the running web server. Если они закрыты, откройте окно Git Bash или системную командную строку с поддержкой Node.JS и перейдите к папке Start проекта.Otherwise, open a Git bash window, or Node.JS-enabled system prompt, and navigate to the Start folder of the project.

    Примечание

    Хотя сервер синхронизации браузера будет повторно загружать надстройку в области задач при каждом изменении любого файла (в том числе app.js), он не передает повторно код JavaScript, поэтому нужно будет снова выполнить команду сборки, чтобы изменения, внесенные в файл app.js, вступили в силу.Although the browser-sync server reloads your add-in in the task pane every time you make a change to any file, including the app.js file, it does not retranspile the JavaScript, so you must repeat the build command in order for your changes to app.js to take effect. Для этого следует завершить процесс сервера, чтобы можно было получить приглашение на ввод команды сборки.In order to do this, you need to kill the server process so that you can get a prompt to enter the build command. После сборки необходимо перезапустить сервер.After the build, you restart the server. Для этого выполните указанные ниже действия.The next few steps carry out this process.

  2. Выполните команду npm run build , чтобы преES6 исходный код в более раннюю версию JavaScript, поддерживаемую Internet Explorer (которая используется в некоторых версиях Excel для запуска надстроек Excel).Run the command npm run build to transpile your ES6 source code to an earlier version of JavaScript that is supported by Internet Explorer (which is used by some versions of Excel to run Excel add-ins).

  3. Выполните команду npm start, чтобы запустить веб-сервер, работающий на localhost.Run the command npm start to start a web server running on localhost.

  4. Перезагрузите область задач. Для этого закройте ее, а затем выберите в меню Главная пункт Показать область задач, чтобы заново открыть надстройку.Reload the task pane by closing it, and then on the Home menu, select Show Taskpane to reopen the add-in.

  5. Если по той или иной причине на открытом листе нет таблицы, нажмите в области задач кнопку Create Table (Создать таблицу).If for any reason the table is not in the open worksheet, in the task pane, choose Create Table.

  6. Нажмите кнопки Filter Table (Фильтровать таблицу) и Sort Table (Сортировать таблицу) в любом порядке.Choose the Filter Table and Sort Table buttons, in either order.

    Учебник Excel - Фильтрация и сортировка таблицы

Создание диаграммыCreate a chart

На этом этапе руководства мы создадим диаграмму, используя данные из ранее созданной таблицы, а затем отформатируем эту диаграмму.In this step of the tutorial, you'll create a chart using data from the table that you created previously, and then format the chart.

Создание диаграммы с помощью таблицы данныхChart a chart using table data

  1. Откройте проект в редакторе кода.Open the project in your code editor.

  2. Откройте файл index.html.Open the file index.html.

  3. Под элементом div, содержащим кнопку sort-table, добавьте следующую разметку:Below the div that contains the sort-table button, add the following markup:

    <div class="padding">
        <button class="ms-Button" id="create-chart">Create Chart</button>
    </div>
    
  4. Откройте файл app.js.Open the app.js file.

  5. Под строкой, назначающей обработчик нажатия кнопки sort-chart, добавьте следующий код:Below the line that assigns a click handler to the sort-chart button, add the following code:

    $('#create-chart').click(createChart);
    
  6. Под функцией sortTable добавьте приведенную ниже функцию.Below the sortTable function add the following function.

    function createChart() {
        Excel.run(function (context) {
    
            // TODO1: Queue commands to get the range of data to be charted.
    
            // TODO2: Queue command to create the chart and define its type.
    
            // TODO3: Queue commands to position and format the chart.
    
            return context.sync();
        })
        .catch(function (error) {
            console.log("Error: " + error);
            if (error instanceof OfficeExtension.Error) {
                console.log("Debug info: " + JSON.stringify(error.debugInfo));
            }
        });
    }
    
  7. Замените TODO1 приведенным ниже кодом. Обратите внимание на то, что для исключения строки заголовков в коде вместо метода Table.getDataBodyRange используется метод getRange, чтобы получить нужный диапазон данных для диаграммы.Replace TODO1 with the following code. Note that in order to exclude the header row, the code uses the Table.getDataBodyRange method to get the range of data you want to chart instead of the getRange method.

    var currentWorksheet = context.workbook.worksheets.getActiveWorksheet();
    var expensesTable = currentWorksheet.tables.getItem('ExpensesTable');
    var dataRange = expensesTable.getDataBodyRange();
    
  8. Замените TODO2 приведенным ниже кодом. Обратите внимание на следующие параметры:Replace TODO2 with the following code. Note the following parameters:

    • Первый параметр метода add задает тип диаграммы. Существует несколько десятков типов.The first parameter to the add method specifies the type of chart. There are several dozen types.

    • Второй параметр задает диапазон данных, включаемых в диаграмму.The second parameter specifies the range of data to include in the chart.

    • Третий параметр определяет, как следует отображать на диаграмме ряд точек данных из таблицы: по строкам или по столбцам.The third parameter determines whether a series of data points from the table should be charted row-wise or column-wise. Значение auto сообщает Excel, что следует выбрать оптимальный способ.The option auto tells Excel to decide the best method.

    var chart = currentWorksheet.charts.add('ColumnClustered', dataRange, 'auto');
    
  9. Замените TODO3 на приведенный ниже код. Большая часть этого кода не требует объяснений. Примечание.Replace TODO3 with the following code. Most of this code is self-explanatory. Note:

    • Параметры метода setPosition задают левую верхнюю и правую нижнюю ячейки области листа, которые должны содержать диаграмму. Excel может настраивать такие параметры, как ширина линий, чтобы диаграмма хорошо выглядела в выделенном для нее пространстве.The parameters to the setPosition method specify the upper left and lower right cells of the worksheet area that should contain the chart. Excel can adjust things like line width to make the chart look good in the space it has been given.

    • "Ряд" — это набор точек данных из столбца таблицы. Так как в таблице есть только один нестроковый столбец, Excel делает вывод, что это единственный столбец точек данных для диаграммы. Он рассматривает другие столбцы как метки диаграммы. Следовательно, в диаграмме будет только один ряд, обозначенный индексом 0. К нему следует добавить метку "Значение в €".A "series" is a set of data points from a column of the table. Since there is only one non-string column in the table, Excel infers that the column is the only column of data points to chart. It interprets the other columns as chart labels. So there will be just one series in the chart and it will have index 0. This is the one to label with "Value in €".

    chart.setPosition("A15", "F30");
    chart.title.text = "Expenses";
    chart.legend.position = "right"
    chart.legend.format.fill.setSolidColor("white");
    chart.dataLabels.format.font.size = 15;
    chart.dataLabels.format.font.color = "black";
    chart.series.getItemAt(0).name = 'Value in €';
    

Тестирование надстройкиTest the add-in

  1. Если окно Git Bash или системная командная строка с поддержкой Node.JS, открытые на предыдущем этапе руководства, все еще открыты, дважды нажмите клавиши Ctrl+C, чтобы остановить работу веб-сервера.If the Git bash window, or Node.JS-enabled system prompt, from the previous stage tutorial is still open, enter Ctrl+C twice to stop the running web server. Если они закрыты, откройте окно Git Bash или системную командную строку с поддержкой Node.JS и перейдите к папке Start проекта.Otherwise, open a Git bash window, or Node.JS-enabled system prompt, and navigate to the Start folder of the project.

    Примечание

    Хотя сервер синхронизации браузера будет повторно загружать надстройку в области задач при каждом изменении любого файла (в том числе app.js), он не передает повторно код JavaScript, поэтому нужно будет снова выполнить команду сборки, чтобы изменения, внесенные в файл app.js, вступили в силу. Для этого следует завершить процесс сервера, чтобы можно было получить приглашение на ввод команды сборки. После сборки необходимо перезапустить сервер. Для этого выполните указанные ниже действия.Although the browser-sync server reloads your add-in in the task pane every time you make a change to any file, including the app.js file, it does not retranspile the JavaScript, so you must repeat the build command in order for your changes to app.js to take effect. In order to do this, you need to kill the server process in so that you can get a prompt to enter the build command. After the build, you restart the server. The next few steps carry out this process.

  2. Выполните команду npm run build , чтобы преES6 исходный код в более раннюю версию JavaScript, поддерживаемую Internet Explorer (которая используется в некоторых версиях Excel для запуска надстроек Excel).Run the command npm run build to transpile your ES6 source code to an earlier version of JavaScript that is supported by Internet Explorer (which is used by some versions of Excel to run Excel add-ins).

  3. Выполните команду npm start, чтобы запустить веб-сервер, работающий на localhost.Run the command npm start to start a web server running on localhost.

  4. Перезагрузите область задач. Для этого закройте ее, а затем выберите в меню Главная пункт Показать область задач, чтобы заново открыть надстройку.Reload the task pane by closing it, and then on the Home menu, select Show Taskpane to reopen the add-in.

  5. Если по той или иной причине на открытом листе нет таблицы, нажмите в области задач кнопку Create Table (Создать таблицу), а затем — кнопки Filter Table (Фильтровать таблицу) и Sort Table (Сортировать таблицу) в любом порядке.If for any reason the table is not in the open worksheet, in the task pane, choose Create Table and then Filter Table and Sort Table buttons, in either order.

  6. Нажмите кнопку Create Chart (Создать диаграмму). Будет создана диаграмма, включающая только данные из отфильтрованных строк. Метки точек данных в нижней части диаграммы отсортированы согласно заданному для нее порядку, то есть по именам продавцов в обратном алфавитном порядке.Choose the Create Chart button. A chart is created and only the data from the rows that have been filtered are included. The labels on the data points across the bottom are in the sort order of the chart; that is, merchant names in reverse alphabetical order.

    Руководство по Excel - Создание диаграммы

Закрепление заголовка таблицыFreeze a table header

Когда таблица достаточно длинная, при прокрутке строка заголовков может исчезать с экрана. В этом разделе учебника мы расскажем, как закрепить строку заголовков созданной ранее таблицы, чтобы она была видна, даже когда пользователь прокручивает лист.When a table is long enough that a user must scroll to see some rows, the header row can scroll out of sight. In this step of the tutorial, you'll freeze the header row of the table that you created previously, so that it remains visible even as the user scrolls down the worksheet.

Закрепление строки заголовков таблицыFreeze the table's header row

  1. Откройте проект в редакторе кода.Open the project in your code editor.

  2. Откройте файл index.html.Open the file index.html.

  3. Под элементом div, содержащим кнопку create-chart, добавьте следующую разметку:Below the div that contains the create-chart button, add the following markup:

    <div class="padding">
        <button class="ms-Button" id="freeze-header">Freeze Header</button>
    </div>
    
  4. Откройте файл app.js.Open the app.js file.

  5. Под строкой, назначающей обработчик нажатия кнопки create-chart, добавьте следующий код:Below the line that assigns a click handler to the create-chart button, add the following code:

    $('#freeze-header').click(freezeHeader);
    
  6. Под функцией createChart добавьте следующую функцию:Below the createChart function add the following function:

    function freezeHeader() {
        Excel.run(function (context) {
    
            // TODO1: Queue commands to keep the header visible when the user scrolls.
    
            return context.sync();
        })
        .catch(function (error) {
            console.log("Error: " + error);
            if (error instanceof OfficeExtension.Error) {
                console.log("Debug info: " + JSON.stringify(error.debugInfo));
            }
        });
    }
    
  7. Замените TODO1 приведенным ниже кодом. Обратите внимание:Replace TODO1 with the following code. Note:

    • Коллекция Worksheet.freezePanes — это набор закрепленных строк, которые не исчезают с экрана при прокрутке листа.The Worksheet.freezePanes collection is a set of panes in the worksheet that are pinned, or frozen, in place when the worksheet is scrolled.

    • Метод freezeRows принимает в качестве параметра количество строк сверху, которые необходимо закрепить. Мы передаем значение 1, чтобы закрепить первую строку.The freezeRows method takes as a parameter the number of rows, from the top that are to be pinned in place. We pass 1 to pin the first row in place.

    var currentWorksheet = context.workbook.worksheets.getActiveWorksheet();
    currentWorksheet.freezePanes.freezeRows(1);
    

Тестирование надстройкиTest the add-in

  1. Если окно Git Bash или системная командная строка с поддержкой Node.JS, открытые на предыдущем этапе руководства, все еще открыты, дважды нажмите клавиши Ctrl+C, чтобы остановить работу веб-сервера.If the Git bash window, or Node.JS-enabled system prompt, from the previous stage tutorial is still open, enter Ctrl+C twice to stop the running web server. Если они закрыты, откройте окно Git Bash или системную командную строку с поддержкой Node.JS и перейдите к папке Start проекта.Otherwise, open a Git bash window, or Node.JS-enabled system prompt, and navigate to the Start folder of the project.

    Примечание

    Хотя сервер синхронизации браузера будет повторно загружать надстройку в области задач при каждом изменении любого файла (в том числе app.js), он не передает повторно код JavaScript, поэтому нужно будет снова выполнить команду сборки, чтобы изменения, внесенные в файл app.js, вступили в силу. Для этого следует завершить процесс сервера, чтобы можно было получить приглашение на ввод команды сборки. После сборки необходимо перезапустить сервер. Для этого выполните указанные ниже действия.Although the browser-sync server reloads your add-in in the task pane every time you make a change to any file, including the app.js file, it does not retranspile the JavaScript, so you must repeat the build command in order for your changes to app.js to take effect. In order to do this, you need to kill the server process in so that you can get a prompt to enter the build command. After the build, you restart the server. The next few steps carry out this process.

  2. Выполните команду npm run build , чтобы преES6 исходный код в более раннюю версию JavaScript, поддерживаемую Internet Explorer (которая используется в некоторых версиях Excel для запуска надстроек Excel).Run the command npm run build to transpile your ES6 source code to an earlier version of JavaScript that is supported by Internet Explorer (which is used by some versions of Excel to run Excel add-ins).

  3. Выполните команду npm start, чтобы запустить веб-сервер, работающий на localhost.Run the command npm start to start a web server running on localhost.

  4. Повторно загрузите область задач. Для этого закройте ее, а затем выберите в меню Главная пункт Показать область задач.Reload the task pane by closing it, and then on the Home menu, select Show Taskpane to reopen the add-in.

  5. Если таблица на листе, удалите ее.If the table is in the worksheet, delete it.

  6. В области задач нажмите кнопку Create Table (Создать таблицу).In the task pane, choose Create Table.

  7. Нажмите кнопку Freeze Header (Закрепить заголовок).Choose the Freeze Header button.

  8. Прокрутите лист вниз, чтобы убедиться, что заголовок таблицы по-прежнему остается на экране, даже когда более высокие строки исчезают.Scroll down the worksheet enough to to see that the table header remains visible at the top even when the higher rows scroll out of sight.

    Учебник Excel - Закрепление заголовка

Защита листаProtect a worksheet

На данном этапе, описанном в руководстве, вы добавите на ленту еще одну кнопку, при нажатии которой будет выполнена определенная вами функция включения или выключения защиты листа.In this step of the tutorial, you'll add another button to the ribbon that, when chosen, executes a function that you'll define to toggle worksheet protection on and off.

Настройка манифеста для добавления второй кнопки на лентуConfigure the manifest to add a second ribbon button

  1. Откройте файл манифеста my-office-add-in-manifest.xml.Open the manifest file my-office-add-in-manifest.xml.

  2. Найдите элемент <Control>. Этот элемент определяет кнопку Show Taskpane (Показать область задач) на вкладке Главная, которую вы используете для запуска надстройки. Мы добавим вторую кнопку в эту же группу на ленте Главная. Добавьте приведенный ниже код между закрывающим тегом элемента управления (</Control>) и закрывающим тегом группы (</Group>).Find the <Control> element. This element defines the Show Taskpane button on the Home ribbon you have been using to launch the add-in. We're going to add a second button to the same group on the Home ribbon. In between the end Control tag (</Control>) and the end Group tag (</Group>), add the following markup.

    <Control xsi:type="Button" id="<!--TODO1: Unique (in manifest) name for button -->">
        <Label resid="<!--TODO2: Button label -->" />
        <Supertip>            
            <Title resid="<!-- TODO3: Button tool tip title -->" />
            <Description resid="<!-- TODO4: Button tool tip description -->" />
        </Supertip>
        <Icon>
            <bt:Image size="16" resid="Contoso.tpicon_16x16" />
            <bt:Image size="32" resid="Contoso.tpicon_32x32" />
            <bt:Image size="80" resid="Contoso.tpicon_80x80" />
        </Icon>
        <Action xsi:type="<!-- TODO5: Specify the type of action-->">
            <!-- TODO6: Identify the function.-->
        </Action>
    </Control>
    
  3. Замените TODO1 строкой, которая присваивает кнопке идентификатор, уникальный в пределах этого файла манифеста.Replace TODO1 with a string that gives the button an ID that is unique within this manifest file. Так как кнопка будет включать и выключать защиту листа, укажите "ToggleProtection".Since our button is going to toggle protection of the worksheet on and off, use "ToggleProtection". Когда сделаете это, весь открывающий тег элемента управления должен выглядеть следующим образом:When you are done, the entire start Control tag should look like the following:

    <Control xsi:type="Button" id="ToggleProtection">
    
  4. Следующие три элемента TODO устанавливают "resid", или идентификаторы ресурса. Ресурс должен быть строкой, и вы создадите эти три строки на следующем этапе. Сейчас вам нужно присвоить идентификаторы ресурсам. Кнопка должна называться "Toggle Protection" (Переключение защиты), но у строки должен быть идентификатор "ProtectionButtonLabel", поэтому готовый элемент Label выглядит следующим образом:The next three TODOs set "resid"s, which is short for resource ID. A resource is a string, and you'll create these three strings in a later step. For now, you need to give IDs to the resources. The button label should read "Toggle Protection", but the ID of this string should be "ProtectionButtonLabel", so the completed Label element should look like the following code:

    <Label resid="ProtectionButtonLabel" />
    
  5. Элемент SuperTip определяет подсказку для кнопки. Заголовок этой подсказки должен совпадать с названием кнопки, поэтому мы используем тот же ИД ресурса — "ProtectionButtonLabel". Описание подсказки будет следующим: "Click to turn protection of the worksheet on and off" (Нажмите для включения или выключения защиты листа). У ID должно быть значение "ProtectionButtonToolTip". После выполнения весь код SuperTip должен выглядеть следующим образом:The SuperTip element defines the tool tip for the button. The tool tip title should be the same as the button label, so we use the very same resource ID: "ProtectionButtonLabel". The tool tip description will be "Click to turn protection of the worksheet on and off". But the ID should be "ProtectionButtonToolTip". So, when you are done, the whole SuperTip markup should look like the following code:

    <Supertip>            
        <Title resid="ProtectionButtonLabel" />
        <Description resid="ProtectionButtonToolTip" />
    </Supertip>
    

    Примечание

    В рабочей надстройке не нужно использовать один и тот же значок для двух разных кнопок, но сейчас мы предлагаем сделать это для простоты. Поэтому код Icon в новом теге Control представляет собой лишь копию элемента Icon из существующего тега Control.In a production add-in, you would not want to use the same icon for two different buttons; but to simplify this tutorial, we'll do that. So the Icon markup in our new Control is just a copy of the Icon element from the existing Control.

  6. Для элемента Action в исходном элементе Control, уже присутствующем в манифесте, задан тип ShowTaskpane, но новая кнопка будет не открывать область задач, а выполнять специальную функцию, которую вы создадите позже. Поэтому замените TODO5 на ExecuteFunction(тип действия для кнопок, запускающих специальные функции). Открывающий тег Action должен выглядеть следующим образом:The Action element inside the original Control element that was already present in the manifest, has its type set to ShowTaskpane, but our new button isn't going to open a task pane; it's going to run a custom function that you create in a later step. So replace TODO5 with ExecuteFunction which is the action type for buttons that trigger custom functions. The start Action tag should look like the following code:

    <Action xsi:type="ExecuteFunction">
    
  7. У исходного элемента Action есть дочерние элементы, определяющие идентификатор области задач и URL-адрес страницы, которая должна быть открыта в области задач. Но у элемента Action типа ExecuteFunction есть один дочерний элемент, который именует функцию, выполняемую элементом управления. На более позднем этапе вы создадите функцию toggleProtection. Поэтому замените TODO6 следующим кодом:The original Action element has child elements that specify a task pane ID and a URL of the page that should be opened in the task pane. But an Action element of the ExecuteFunction type has a single child element that names the function that the control executes. You'll create that function in a later step, and it will be called toggleProtection. So, replace TODO6 with the following markup:

    <FunctionName>toggleProtection</FunctionName>
    

    Теперь весь код Control должен выглядеть вот так:The entire Control markup should now look like the following:

    <Control xsi:type="Button" id="ToggleProtection">
        <Label resid="ProtectionButtonLabel" />
        <Supertip>            
            <Title resid="ProtectionButtonLabel" />
            <Description resid="ProtectionButtonToolTip" />
        </Supertip>
        <Icon>
            <bt:Image size="16" resid="Contoso.tpicon_16x16" />
            <bt:Image size="32" resid="Contoso.tpicon_32x32" />
            <bt:Image size="80" resid="Contoso.tpicon_80x80" />
        </Icon>
        <Action xsi:type="ExecuteFunction">
           <FunctionName>toggleProtection</FunctionName>
        </Action>
    </Control>
    
  8. Прокрутите страницу вниз до раздела Resources манифеста.Scroll down to the Resources section of the manifest.

  9. Добавьте приведенный ниже код в качестве дочернего элемента bt:ShortStrings.Add the following markup as a child of the bt:ShortStrings element.

    <bt:String id="ProtectionButtonLabel" DefaultValue="Toggle Worksheet Protection" />
    
  10. Добавьте приведенный ниже код в качестве дочернего элемента bt:LongStrings.Add the following markup as a child of the bt:LongStrings element.

    <bt:String id="ProtectionButtonToolTip" DefaultValue="Click to protect or unprotect the current worksheet." />
    
  11. Сохраните файл.Save the file.

Создание функции защиты листаCreate the function that protects the sheet

  1. Откройте файл \function-file\function-file.js.Open the file \function-file\function-file.js.

  2. В файле уже есть функция-выражение, вызываемая сразу после создания (IIFE).The file already has an Immediately Invoked Function Expression (IFFE). Добавьте в иифеследующий код.Outside of the IIFE, add the following code. Обратите внимание на то, что мы указываем параметр args для метода, а самая последняя строка метода вызывает args.completed.Note that we specify an args parameter to the method and the very last line of the method calls args.completed. Это требование для всех команд надстройки типа ExecuteFunction.This is a requirement for all add-in commands of type ExecuteFunction. Это сигнализирует ведущему приложению Office о том, что работа функции завершена и пользовательский интерфейс снова может реагировать.It signals the Office host application that the function has finished and the UI can become responsive again.

    function toggleProtection(args) {
        Excel.run(function (context) {
    
            // TODO1: Queue commands to reverse the protection status of the current worksheet.
    
            return context.sync();
        })
        .catch(function (error) {
            console.log("Error: " + error);
            if (error instanceof OfficeExtension.Error) {
                console.log("Debug info: " + JSON.stringify(error.debugInfo));
            }
        });
        args.completed();
    }
    
  3. Замените TODO1 приведенным ниже кодом. В этом коде используется свойство защиты объекта листа в стандартном шаблоне переключателя. Объяснение TODO2 будет приведено в следующем разделе.Replace TODO1 with the following code. This code uses the worksheet object's protection property in a standard toggle pattern. The TODO2 will be explained in the next section.

    var sheet = context.workbook.worksheets.getActiveWorksheet();
    
    // TODO2: Queue command to load the sheet's "protection.protected" property from
    //        the document and re-synchronize the document and task pane.
    
     if (sheet.protection.protected) {
        sheet.protection.unprotect();
    } else {
        sheet.protection.protect();
    }
    

Добавление кода для получения свойств документа в объекты скрипта области задачAdd code to fetch document properties into the task pane's script objects

В случае всех описанных ранее функций из этой серии руководств вы ставили в очередь команды для записи данных в документ Office. Каждая функция заканчивалась вызовом метода context.sync(), который отправляет выставленные в очередь команды документу для выполнения. Но код, который вы добавили на последнем этапе, вызывает свойство sheet.protection.protected, и в этом заключается существенное отличие от ранее написанных функций, так как sheet является лишь объектом прокси, существующим в скрипте вашей области задач. В нем нет сведений о фактическом состоянии защиты документа, поэтому его свойство protection.protected не может иметь реального значения. Сначала нужно получить сведения о состоянии защиты от документа и задать значение sheet.protection.protected, используя их. Только после этого станет возможным вызов sheet.protection.protected без исключения. Процесс получения делится на три этапа:In all the earlier functions in this series of tutorials, you queued commands to write to the Office document. Each function ended with a call to the context.sync() method which sends the queued commands to the document to be executed. But the code you added in the last step calls the sheet.protection.protected property, and this is a significant difference from the earlier functions you wrote, because the sheet object is only a proxy object that exists in your task pane's script. It doesn't know what the actual protection state of the document is, so its protection.protected property can't have a real value. It is necessary to first fetch the protection status from the document and use it set the value of sheet.protection.protected. Only then can sheet.protection.protected be called without causing an exception to be thrown. This fetching process has three steps:

  1. Добавление в очередь команды для загрузки (т. е. получения) свойств, которые должен прочесть ваш код.Queue a command to load (that is; fetch) the properties that your code needs to read.

  2. Вызов метода sync объекта контекста, чтобы можно было отправить документу находящуюся в очереди команду для выполнения, а также для возврата запрошенных данных.Call the context object's sync method to send the queued command to the document for execution and return the requested information.

  3. Метод sync асинхронный, поэтому его выполнение должно быть завершено до того, как код вызовет полученные свойства.Because the sync method is asynchronous, ensure that it has completed before your code calls the properties that were fetched.

Эти три действия должны выполняться каждый раз, когда коду нужно прочесть данные из документа Office.These steps must be completed whenever your code needs to read information from the Office document.

  1. В функции toggleProtection замените TODO2 приведенным ниже кодом. Обратите внимание:In the toggleProtection function, replace TODO2 with the following code. Note:

    • У каждого объекта Excel есть метод load. Вы указываете свойства объекта, которые нужно прочесть в параметре как строку имен, разделенных запятыми. В этом случае нужно прочесть подсвойство свойства protection. На подсвойство нужно ссылаться почти так же, как и в остальных частях кода. Отличие заключается в том, что вместо символа "." нужно указать косую черту ("/").Every Excel object has a load method. You specify the properties of the object that you want to read in the parameter as a string of comma-delimited names. In this case, the property you need to read is a subproperty of the protection property. You reference the subproperty almost exactly as you would anywhere else in your code, with the exception that you use a forward slash ('/') character instead of a "." character.

    • Чтобы логика переключения, которая считывает sheet.protection.protected, не срабатывала до выполнения sync и присвоения sheet.protection.protected правильного значения, полученного из документа, она будет перемещена (на следующем этапе) в функцию then, которая не выполняется до завершения sync.To ensure that the toggle logic, which reads sheet.protection.protected, does not run until after the sync is complete and the sheet.protection.protected has been assigned the correct value that is fetched from the document, it will be moved (in the next step) into a then function that won't run until the sync has completed.

    sheet.load('protection/protected');
    return context.sync()
        .then(
            function() {
                // TODO3: Move the queued toggle logic here.
            }
        )
        // TODO4: Move the final call of `context.sync` here and ensure that it
        //        does not run until the toggle logic has been queued.
    
  2. Для двух операторов return не может использоваться один путь кода, который не разветвляется, поэтому удалите последнюю строку return context.sync(); в конце Excel.run. Вы добавите новую последнюю строку context.sync позже.You can't have two return statements in the same unbranching code path, so delete the final line return context.sync(); at the end of the Excel.run. You will add a new final context.sync, in a later step.

  3. Вырежьте структуру if ... else в функции toggleProtection и вставьте вместо TODO3.Cut the if ... else structure in the toggleProtection function and paste it in place of TODO3.

  4. Замените TODO4 приведенным ниже кодом. Примечание:Replace TODO4 with the following code. Note:

    • Благодаря тому, что метод sync передается функции then, он не будет запускаться до добавления sheet.protection.unprotect() или sheet.protection.protect() в очередь.Passing the sync method to a then function ensures that it does not run until either sheet.protection.unprotect() or sheet.protection.protect() has been queued.

    • Метод then вызывает любую функцию, которая ему передана. Не нужно вызывать sync дважды, поэтому уберите "()" после context.sync.The then method invokes whatever function is passed to it, and you don't want sync to be invoked twice, so leave off the "()" from the end of context.sync.

    .then(context.sync);
    

    Когда все будет готово, функция должна выглядеть так:When you are done, the entire function should look like the following:

    function toggleProtection(args) {
        Excel.run(function (context) {            
          var sheet = context.workbook.worksheets.getActiveWorksheet();          
          sheet.load('protection/protected');
    
          return context.sync()
              .then(
                  function() {
                    if (sheet.protection.protected) {
                        sheet.protection.unprotect();
                    } else {
                        sheet.protection.protect();
                    }
                  }
              )
              .then(context.sync);
        })
        .catch(function (error) {
            console.log("Error: " + error);
            if (error instanceof OfficeExtension.Error) {
                console.log("Debug info: " + JSON.stringify(error.debugInfo));
            }
        });
        args.completed();
    }
    

Настройка HTML-файла для загрузки скриптаConfigure the script-loading HTML file

Откройте файл /function-file/function-file.html. Это HTML-файл без пользовательского интерфейса, вызываемый, когда пользователь нажимает кнопку Toggle Worksheet Protection (Переключение защиты листа). Он предназначен для загрузки метода JavaScript, который должен выполняться при нажатии кнопки. Вы не будете изменять этот файл. Просто обратите внимание на то, что второй тег <script> загружает functionfile.js.Open the /function-file/function-file.html file. This is a UI-less HTML file that is called when the user presses the Toggle Worksheet Protection button. Its purpose is to load the JavaScript method that should run when the button is pushed. You are not going to change this file. Simply note that the second <script> tag loads the functionfile.js.

Примечание

Файл function-file.html и загружаемый им файл function-file.js выполняются в полностью отдельном процессе IE из области задач надстройки. Если файл function-file.js был передан в тот же файл bundle.js, что и файл app.js, надстройка загрузит два экземпляра файла bundle.js, и это отменяет цель объединения. Кроме того, файл function-file.js не содержит код JavaScript, который не поддерживается в IE. По этим двум причинам такая надстройка не передает файл function-file.js вообще.The function-file.html file and the function-file.js file that it loads run in an entirely separate IE process from the add-in's task pane. If the function-file.js was transpiled into the same bundle.js file as the app.js file, then the add-in would have to load two copies of the bundle.js file, which defeats the purpose of bundling. In addition, the function-file.js file does not contain any JavaScript that is unsupported by IE. For these two reasons, this add-in does not transpile the function-file.js at all.

Тестирование надстройкиTest the add-in

  1. Закройте все приложения Office, в том числе Excel.Close all Office applications, including Excel.

  2. Очистите кэш Office, удалив содержимое папки кэша. Это необходимо, чтобы можно было полностью удалить старую версию надстройки из ведущего приложения.Delete the Office cache by deleting the contents of the cache folder. This is necessary to completely clear the old version of the add-in from the host.

    • Для Windows: %LOCALAPPDATA%\Microsoft\Office\16.0\Wef\.For Windows: %LOCALAPPDATA%\Microsoft\Office\16.0\Wef\.

    • Для Mac: ~/Library/Containers/com.Microsoft.OsfWebHost/Data/.For Mac: ~/Library/Containers/com.Microsoft.OsfWebHost/Data/.

      Как правило, надстройки кэшируются в Office для Mac по соображениям производительности.Add-ins are often cached in Office for Mac, for performance reasons. Как правило, для очистки кэша необходимо перезагрузить надстройку.Normally, the cache is cleared by reloading the add-in. Если в одном документе есть несколько надстроек, процесс автоматической очистки кэша при перезагрузке может быть ненадежным.If more than one add-in exists in the same document, the process of automatically clearing the cache on reload might not be reliable.

      Вы можете очистить кэш с помощью меню "личные" любой надстройки области задач.You can clear the cache by using the personality menu of any task pane add-in.

      • Выберите меню личные данные.Choose the personality menu. Затем выберите очистить веб-кэш.Then choose Clear Web Cache.

        Примечание

        Для просмотра меню "личные" необходимо запустить macOS версии 10.13.6 или более поздней версии.You must run macOS version 10.13.6 or later to see the personality menu.

        Снимок экрана: параметр "очистить веб-кэш" в меню "личные".

      Кроме того, можно очистить кэш вручную, удалив содержимое ~/Library/Containers/com.Microsoft.OsfWebHost/Data/ папки.You can also clear the cache manually by deleting the contents of the ~/Library/Containers/com.Microsoft.OsfWebHost/Data/ folder.

      Примечание

      Если эта папка не существует, проверьте наличие следующих папок и, если она найдена, удалите содержимое папки:If that folder doesn't exist, check for the following folders and if found, delete the contents of the folder:

      • ~/Library/Containers/com.microsoft.{host}/Data/Library/Caches/где {host} находится ведущее приложение Office (например, Excel);~/Library/Containers/com.microsoft.{host}/Data/Library/Caches/ where {host} is the Office host (e.g., Excel)
      • com.microsoft.Office365ServiceV2/Data/Caches/com.microsoft.Office365ServiceV2/
  3. Если по той или иной причине ваш сервер не работает, в окне Git Bash или системной командной строке с поддержкой Node.JS перейдите к папке Start проекта и выполните команду npm start. Повторную сборку проекта выполнять не нужно, так как единственный файл JavaScript, который вы изменили, не относится к сборке bundle.js.If for any reason, your server is not running, then in a Git Bash window, or Node.JS-enabled system prompt, navigate to the Start folder of the project and run the command npm start. You do not need to rebuild the project because the only JavaScript file you changed is not part of the built bundle.js.

  4. Используя новую версию измененного файла манифеста, повторите процесс загрузки неопубликованного приложения с помощью одного из указанных далее методов. Нужно перезаписать предыдущий экземпляр файла манифеста.Using the new version of the changed manifest file, repeat the sideloading process by using one of the following methods. You should overwrite the previous copy of the manifest file.

  5. Откройте любой лист в Excel.Open any worksheet in Excel.

  6. На ленте Главная нажмите кнопку Toggle Worksheet Protection (Переключение защиты листа). Обратите внимание на то, что большинство элементов управления на ленте отключены (серые), как показано на приведенном ниже снимке экрана.On the Home ribbon, choose Toggle Worksheet Protection. Note that most of the controls on the ribbon are disabled (and visually grayed-out) as seen in screenshot below.

  7. Выберите ячейку, как если бы вы хотели изменить ее содержимое. Появится сообщение об ошибке и защите листа.Choose a cell as you would if you wanted to change its content. You get an error telling you that the worksheet is protected.

  8. Нажмите кнопку Toggle Worksheet Protection (Переключение защиты листа) еще раз, и элементы управления включатся, после чего вы сможете изменить значения ячеек.Choose Toggle Worksheet Protection again, and the controls are reenabled, and you can change cell values again.

    Руководство по Excel: лента с включенной защитой

Открытие диалогового окнаOpen a dialog

На данном заключительном этапе, указанном в руководстве, вы откроете диалоговое окно в своей надстройке, передадите сообщение из процесса диалогового окна в процесс области задач и закроете диалоговое окно. Диалоговые окна надстройки Office не модальные: пользователь может продолжать работать и с документом в ведущем приложении Office, и с главной страницей в области задач.In this final step of the tutorial, you'll open a dialog in your add-in, pass a message from the dialog process to the task pane process, and close the dialog. Office Add-in dialogs are nonmodal: a user can continue to interact with both the document in the host Office application and with the host page in the task pane.

Создание страницы диалогового окнаCreate the dialog page

  1. Откройте проект в редакторе кода.Open the project in your code editor.

  2. Создайте в корневой папке проекта (где находится index.html) файл popup.html.Create a file in the root of the project (where index.html is) called popup.html.

  3. Добавьте в файл popup.html приведенный ниже код. Обратите внимание:Add the following markup to popup.html. Note:

    • На странице находится <input>, где пользователь будет вводить свое имя, и кнопка, при нажатии которой имя будет отправлено на страницу области задач, где оно отобразится.The page has a <input> where the user will enter their name and a button that will send the name to the page in the task pane where it will be displayed.

    • Код загружает скрипт под названием popup.js, который будет создан на более позднем этапе.The markup loads a script called popup.js that you will create in a later step.

    • Он загружает также библиотеку Office.JS и jQuery, так как они будут использоваться в popup.js.It also loads the Office.JS library and jQuery because they will be used in popup.js.

    <!DOCTYPE html>
    <html>
        <head lang="en">
            <title>Dialog for My Office Add-in</title>
            <meta charset="UTF-8">
            <meta name="viewport" content="width=device-width, initial-scale=1">
    
            <link rel="stylesheet" href="node_modules/office-ui-fabric-js/dist/css/fabric.min.css" />
            <link rel="stylesheet" href="node_modules/office-ui-fabric-js/dist/css/fabric.components.css" />
            <link rel="stylesheet" href="app.css" />
    
            <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js"></script>
            <script type="text/javascript" src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.2.1.min.js"></script>
            <script type="text/javascript" src="popup.js"></script>
    
        </head>
        <body style="display:flex;flex-direction:column;align-items:center;justify-content:center">
            <div class="padding">
                <p class="ms-font-xl">ENTER YOUR NAME</p>
            </div>
            <div class="padding">
                <input id="name-box" type="text"/>
            </div>
            <div class="padding">
                <button id="ok-button" class="ms-Button">OK</button>
            </div>
        </body>
    </html>
    
  4. Создайте в корневой папке проекта файл popup.js.Create a file in the root of the project called popup.js.

  5. Добавьте указанный ниже код в файл popup.js.Add the following code to popup.js. Обратите внимание на указанные ниже особенности этого кода.Note the following about this code:

    • Каждая страница, вызывающая API в библиотеке Office.JS, должна сначала убедиться, что библиотека полностью инициализирована.Every page that calls APIs in the Office.JS library must first ensure that the library is fully initialized. Лучший способ сделать это — вызвать метод Office.onReady().The best way to do that is to call the Office.onReady() method. Если у вашей надстройки есть собственные задачи инициализации, код должен перейти к методу then(), связанному с вызовом Office.onReady().If your add-in has its own initialization tasks, the code should go in a then() method that is chained to the call of Office.onReady(). Файл app.js в корневом каталоге проекта можно рассматривать как пример.For an example, see the app.js file in the project root. Вызов метода Office.onReady() должен выполняться до каких-либо вызовов Office.JS, поэтому назначение указано в файле скрипта, загружаемом страницей, как в этом случае.The call of Office.onReady() must run before any calls to Office.JS; hence the assignment is in a script file that is loaded by the page, as it is in this case.
    • Функция jQuery ready вызывается в методе then().The jQuery ready function is called inside the then() method. В большинстве случаев код загрузки (в том числе начальной) или инициализации из других библиотек JavaScript должен находиться в методе then(), связанном с вызовом Office.onReady().In most cases, the loading, initializing, or bootstrapping code of other JavaScript libraries should be inside the then() method that is chained to the call of Office.onReady().
    (function () {
    "use strict";
    
        Office.onReady()
            .then(function() {
                $(document).ready(function () {  
    
                    // TODO1: Assign handler to the OK button.
    
                });
            });
    
        // TODO2: Create the OK button handler
    
    }());
    
  6. Замените TODO1 приведенным ниже кодом. Вы создадите функцию sendStringToParentPage на следующем этапе.Replace TODO1 with the following code. You'll create the sendStringToParentPage function in the next step.

    $('#ok-button').click(sendStringToParentPage);
    
  7. Замените TODO2 приведенным ниже кодом. Метод messageParent передает свой параметр родительской странице (в данном случае это страница на панели задач). Параметр может быть логическим или строковым. Во втором случае подразумевается все, что можно сериализовать, представив в виде строки (например, XML или JSON).Replace TODO2 with the following code. The messageParent method passes its parameter to the parent page, in this case, the page in the task pane. The parameter can be a boolean or a string, which includes anything that can be serialized as a string, such as XML or JSON.

    function sendStringToParentPage() {
        var userName = $('#name-box').val();
        Office.context.ui.messageParent(userName);
    }
    
  8. Сохраните файл.Save the file.

    Примечание

    Файл Popup. HTML и загружаемый файл Popup. js выполняются в полностью отдельном процессе Microsoft EDGE или Internet Explorer 11 из области задач надстройки.The popup.html file, and the popup.js file that it loads, run in an entirely separate Microsoft Edge or Internet Explorer 11 process from the add-in's task pane. Если файл popup.js был передан в тот же файл bundle.js, что и файл app.js, надстройка загрузит два экземпляра файла bundle.js, и это отменяет цель объединения.If the popup.js was transpiled into the same bundle.js file as the app.js file, then the add-in would have to load two copies of the bundle.js file, which defeats the purpose of bundling. Кроме того, файл Popup. js не содержит JavaScript, не поддерживаемый Internet Explorer 11.In addition, the popup.js file does not contain any JavaScript that is unsupported by Internet Explorer 11. По этим двум причинам эта надстройка не передает файл popup.js вообще.For these two reasons, this add-in does not transpile the popup.js file at all.

Открытие диалогового окна из области задачOpen the dialog from the task pane

  1. Откройте файл index.html.Open the file index.html.

  2. Под div с кнопкой freeze-header добавьте приведенный ниже код.Below the div that contains the freeze-header button, add the following markup:

    <div class="padding">
        <button class="ms-Button" id="open-dialog">Open Dialog</button>
    </div>
    
  3. В диалоговом окне пользователю будет предложено ввести имя и передать имя пользователя в область задач. Область задач отобразит его в подписи. Непосредственно под только что добавленным тегом div добавьте приведенный ниже код.The dialog will prompt the user to enter a name and pass the user's name to the task pane. The task pane will display it in a label. Immediately below the div that you just added, add the following markup:

    <div class="padding">
        <label id="user-name"></label>
    </div>
    
  4. Откройте файл app.js.Open the app.js file.

  5. Под строкой, назначающей обработчик щелчков для кнопки freeze-header, добавьте приведенный ниже код. Вы создадите метод openDialog на одном из следующих шагов.Below the line that assigns a click handler to the freeze-header button, add the following code. You'll create the openDialog method in a later step.

    $('#open-dialog').click(openDialog);
    
  6. Под функцией freezeHeader добавьте указанное ниже объявление. Эта переменная удерживает объект в контексте выполнения родительской страницы, который служит посредником для контекста выполнения страницы диалогового окна.Below the freezeHeader function add the following declaration. This variable is used to hold an object in the parent page's execution context that acts as an intermediator to the dialog page's execution context.

    var dialog = null;
    
  7. Добавьте приведенную ниже функцию под объявлением dialog. Важно отметить, что в этом коде отсутствует вызов Excel.run. Это связано с тем, что API, открывающий диалоговое окно, совместно используется всеми ведущими приложениями Office, поэтому относится к общему API JavaScript для Office, а не API для Excel.Below the declaration of dialog, add the following function. The important thing to notice about this code is what is not there: there is no call of Excel.run. This is because the API to open a dialog is shared among all Office hosts, so it is part of the Office JavaScript Common API, not the Excel-specific API.

    function openDialog() {
        // TODO1: Call the Office Common API that opens a dialog
    }
    
  8. Замените TODO1 приведенным ниже кодом.Replace TODO1 with the following code. Примечание:Note:

    • Метод displayDialogAsync открывает диалоговое окно в центре экрана.The displayDialogAsync method opens a dialog in the center of the screen.

    • Первый параметр — это URL-адрес открываемой страницы.The first parameter is the URL of the page to open.

    • Второй параметр передает параметры. height и width — процентные значения размера окна для приложения Office.The second parameter passes options. height and width are percentages of the size of the Office application's window.

    Office.context.ui.displayDialogAsync(
        'https://localhost:3000/popup.html',
        {height: 45, width: 55},
    
        // TODO2: Add callback parameter.
    );
    

Обработка сообщения из диалогового окна и закрытие диалогового окнаProcess the message from the dialog and close the dialog

  1. Продолжайте работать в файле app.js. Замените TODO2 приведенным ниже кодом. Обратите внимание:Continue in the app.js file, and replace TODO2 with the following code. Note:

    • Обратный вызов выполняется сразу же после успешного открытия диалогового окна и до того, как пользователь предпримет какие-либо действия в диалоговом окне.The callback is executed immediately after the dialog successfully opens and before the user has taken any action in the dialog.

    • result.value — это объект, который выступает в качестве посредника между контекстами выполнения родительских страниц и страниц диалоговых окон.The result.value is the object that acts as a kind of middleman between the execution contexts of the parent and dialog pages.

    • Функция processMessage будет создана на более позднем этапе. Этот обработчик будет обрабатывать любые значения, которые отправляются со страницы диалогового окна с вызовами функции messageParent.The processMessage function will be created in a later step. This handler will process any values that are sent from the dialog page with calls of the messageParent function.

    function (result) {
        dialog = result.value;
        dialog.addEventHandler(Microsoft.Office.WebExtension.EventType.DialogMessageReceived, processMessage);
    }
    
  2. Добавьте указанную ниже функцию под функцией openDialog.Below the openDialog function, add the following function.

    function processMessage(arg) {
        $('#user-name').text(arg.message);
        dialog.close();
    }
    

Тестирование надстройкиTest the add-in

  1. Если окно Git Bash или системная командная строка с поддержкой Node.JS, открытые на предыдущем этапе руководства, все еще открыты, дважды нажмите клавиши Ctrl+C, чтобы остановить работу веб-сервера.If the Git bash window, or Node.JS-enabled system prompt, from the previous stage tutorial is still open, enter Ctrl+C twice to stop the running web server. Если они закрыты, откройте окно Git Bash или системную командную строку с поддержкой Node.JS и перейдите к папке Start проекта.Otherwise, open a Git bash window, or Node.JS-enabled system prompt, and navigate to the Start folder of the project.

    Примечание

    Хотя сервер синхронизации браузера будет повторно загружать надстройку в области задач при каждом изменении любого файла (в том числе app.js), он не передает повторно код JavaScript, поэтому нужно будет снова выполнить команду сборки, чтобы изменения, внесенные в файл app.js, вступили в силу. Для этого следует завершить процесс сервера, чтобы можно было получить приглашение на ввод команды сборки. После сборки необходимо перезапустить сервер. Для этого выполните указанные ниже действия.Although the browser-sync server reloads your add-in in the task pane every time you make a change to any file, including the app.js file, it does not retranspile the JavaScript, so you must repeat the build command in order for your changes to app.js to take effect. In order to do this, you need to kill the server process in so that you can get a prompt to enter the build command. After the build, you restart the server. The next few steps carry out this process.

  2. Выполните команду npm run build , чтобы преES6 исходный код в более раннюю версию JavaScript, поддерживаемую Internet Explorer (которая используется в некоторых версиях Excel для запуска надстроек Excel).Run the command npm run build to transpile your ES6 source code to an earlier version of JavaScript that is supported by Internet Explorer (which is used by some versions of Excel to run Excel add-ins).

  3. Выполните команду npm start, чтобы запустить веб-сервер, работающий на localhost.Run the command npm start to start a web server running on localhost.

  4. Повторно загрузите область задач. Для этого закройте ее, а затем выберите в меню Главная пункт Show Taskpane (Показать область задач) для повторного открытия надстройки.Reload the task pane by closing it, and then on the Home menu, select Show Taskpane to reopen the add-in.

  5. Нажмите кнопку Open Dialog (Открыть диалоговое окно) в области задач.Choose the Open Dialog button in the task pane.

  6. Когда диалоговое окно открыто, перетащите его и измените его размер.While the dialog is open, drag it and resize it. Обратите внимание, что вы можете взаимодействовать с листом и нажимать другие кнопки в области задач, но вы не можете запустить второе диалоговое окно на одной и той же странице панели задач.Note that you can interact with the worksheet and press other buttons on the task pane, but you cannot launch a second dialog from the same task pane page.

  7. В диалоговом окне введите имя и нажмите кнопку OK. В области задач отобразится имя, и диалоговое окно закроется.In the dialog, enter a name and choose OK. The name appears on the task pane and the dialog closes.

  8. При желании можно закомментировать строку dialog.close(); в функции processMessage. Повторите шаги этого раздела. Диалоговое окно остается открытым, и вы можете изменить имя. Можно закрыть его вручную, нажав кнопку X в правом верхнему углу.Optionally, comment out the line dialog.close(); in the processMessage function. Then repeat the steps of this section. The dialog stays open and you can change the name. You can close it manually by pressing the X button in the upper right corner.

    Руководство по Excel - Диалоговое окно

Дальнейшие действияNext steps

В этом руководстве показано создание надстройки Excel для области задач, которая взаимодействует с таблицами, диаграммами, листами, диалоговыми окнами в книге Excel.In this tutorial, you've created an Excel task pane add-in that interacts with tables, charts, worksheets, and dialogs in an Excel workbook. Чтобы узнать больше о создании надстроек Excel, перейдите к следующей статье:To learn more about building Excel add-ins, continue to the following article: