Использование API JavaScript служб Excel для работы с внедренными книгами Excel

  • Статья

Дата последнего изменения: 21 октября 2013 г.

Применимо к: SharePoint Server 2010

В этой статье
Работа с внедренным документом
Изучение кода внедрения JavaScript OneDrive
Использование API JavaScript служб Excel

Внедренная книга Microsoft Excel — это книга, которая хранится в Microsoft OneDrive, но отображается на веб-странице узла. Один из способов внедрения книги — ее отображение в элементе HTML <iframe>. Кроме того, книгу Excel, которая хранится в OneDrive, можно внедрять с помощью ECMAScript (JavaScript, JScript) и элемента HTML <div>. Преимуществом внедрения книги в элементе <div> перед ее внедрением в элементе <iframe>, в частности, является то, что такой книгой можно управлять программным образом, чтобы создавать специализированные приложения и гибридные веб-приложения.

ПримечаниеПримечание

Дополнительные сведения о внедрении книги в веб-страницу с помощью элемента HTML <iframe> см. в статье Внедрение книги Excel в веб-страницу

В этой статье показано, как можно использовать интерфейсы API ECMAScript (JavaScript, JScript)Excel (JavaScript) для программной работы с внедренной книгой Excel, которая хранится в OneDrive.

Работа с внедренным документом

Чтобы можно было программно работать с внедренной книгой, необходимо выполнить два действия: сохранить книгу Excel в OneDrive и вставить код ECMAScript (JavaScript, JScript) в веб-страницу, чтобы программно внедрить эту книгу.

Сохранение книги в OneDrive

До внедрения книги в веб-страницу необходимо сделать ее общедоступной. Общий доступ к книге должен быть открыт в OneDrive. Дополнительные сведения о предоставлении общего доступа к книге, которая хранится в OneDrive, см. в статье Предоставление общего доступа к файлам и папкам и изменение разрешений.

Создание фрагмента кода внедрения JavaScript

Чтобы отображать книгу и программно работать с ней на веб-странице узла, необходимо создать и вставить код внедрения в HTML этой веб-страницы. Код внедрения задает элемент <div>, включает ссылку на библиотеку служб ExcelECMAScript (JavaScript, JScript), указывает книгу (или схему, именованный объект, диапазон) для внедрения в элемент <div>, задает разные параметры отображения и взаимодействия книги, а затем внедряет ее.

Хотя и можно написать собственный код для внедрения книги, самый простой способ создания кода внедрения книги ECMAScript (JavaScript, JScript) заключается в использовании диалогового окна Embed (Внедрить), которое можно вызвать из меню Excel Web App Share (Общий доступ). Пользовательский интерфейс диалогового окна Embed позволяет установить параметры внедрения книги и автоматически создать HTML и код ECMAScript (JavaScript, JScript) для внедрения этой книги с параметрами, задающими ее отображение и возможности взаимодействия. Дополнительные сведения об использовании диалогового окна внедрения для автоматического создания кода внедрения см. в статье Создание гибридного веб-приложения. Добавление Excel в веб-приложение.

Диалоговое окно внедрения SkyDrive

В следующем разделе рассматривается код внедрения JavaScript OneDrive.

Изучение кода внедрения JavaScript OneDrive

В этом разделе рассматриваются основные элементы кода JavaScript, которые используются для внедрения книги и программной работы с ней. В следующем примере кода показаны все основные элементы необходимого кода внедрения. Приведенный здесь код создан с помощью диалогового окна Embed (Внедрить), упомянутого в предыдущем разделе.

<div id="myExcelDiv" style="width: 402px; height: 346px"></div>
<script type="text/javascript" src="http://r.office.microsoft.com/r/rlidExcelWLJS?v=1&kip=1"></script>
<script type="text/javascript">
/*
 * This code uses the Microsoft Office Excel JavaScript object model to programmatically insert the
 * Excel Web App into a div with id=myExcelDiv. The full API is documented at
 * https://msdn.microsoft.com/en-us/library/hh315812.aspx. There you can find out how to get
 * values programmatically from your Excel file and how to use the rest of the object model. 
 */

// Use this file token to reference Book1.xlsx in the Excel APIs
var fileToken = "SD206C5E037684EDE5!1119/2336345675664780773/";

// Run the Excel load handler on page load
if (window.attachEvent) {
window.attachEvent("onload", loadEwaOnPageLoad);
} else {
window.addEventListener("DOMContentLoaded", loadEwaOnPageLoad, false);
}

function loadEwaOnPageLoad() {
var props = {
uiOptions: {
showGridlines: false,
showRowColumnHeaders: false,
showParametersTaskPane: false
},
interactivityOptions: {
allowTypingAndFormulaEntry: false,
allowParameterModification: false,
allowSorting: false,
allowFiltering: false,
allowPivotTableInteractivity: false
}
};

Ewa.EwaControl.loadEwaAsync(fileToken, "myExcelDiv", props, onEwaLoaded);
}

function onEwaLoaded(result) {
/*
 * Add code here to interact with the embedded Excel web app.
 * For more information, see https://msdn.microsoft.com/en-us/library/hh315812.aspx.
 */
}
</script>

Определение элемента <div> для внедренной книги

В первой строке кода внедрения задается элемент <div>, в котором будет размещаться внедренная книга.

<divid="myExcelDiv" style="width: 402px; height: 346px"></div>

Атрибут id задает идентификатор для элемента <div>. Атрибут id используется позднее в коде ECMAScript (JavaScript, JScript) для указания места внедрения книги.

Элемент <div> также содержит атрибут style, который задает размеры элемента <div>.

Включение ссылки на библиотеку объектных моделей JavaScript служб Excel

Чтобы программно работать с внедренной книгой, необходимо иметь ссылку на интерфейс API ECMAScript (JavaScript, JScript) служб Excel. Код внедрения в примере вставляет элемент <script>, который указывает на интерфейс API ECMAScript (JavaScript, JScript)Excel, размещенный в OneDrive.

<script type="text/javascript" src="http://r.office.microsoft.com/r/rlidExcelWLJS? v=1&kip=1"></script>

Атрибут src элемента <script> задает расположение библиотеки в OneDrive. При работе с внедренными книгами, которые хранятся в OneDrive, атрибут src всегда должен указывать на расположение библиотеки API ECMAScript (JavaScript, JScript) служб ExcelOneDrive.

URI для атрибута src содержит два параметра querystring: v (указывает на версию) и kip (указывает на сохранение протокола входящего трафика).

Параметр v указывает версию API ECMAScript (JavaScript, JScript) служб Excel. В настоящее время доступна только версия 1.

Параметр kip указывает, что перенаправление должно сохранять используемый протокол (HTTP или HTTPS).

Указание книги Microsoft Excel для внедрения

Код внедрения, приведенный выше в этой статье, включает в себя элемент скрипта, содержащий ECMAScript (JavaScript, JScript), который выполняет основную работу по внедрению и настройке книги. Первая строка кода ECMAScript (JavaScript, JScript) инициализирует переменную с идентификатором для книги, хранящейся в общедоступной папке OneDrive.

<script type="text/javascript">
// Use this file token to reference Book1.xlsx in the Excel APIs
var fileToken = "SD206C5E037684EDE5!1119/2336345675664780773/";

В этом примере кода в fileToken хранится строковое значение, которое задает книгу с именем Book1.xlsx, хранящуюся в OneDrive.

Важное примечаниеВажно!

Чтобы получить уникальный маркер файла для книги, которую требуется внедрить, используйте маркер файла, предоставленный в коде диалогового окна Embed (Внедрить).

Установка параметров отображения и взаимодействия для внедренной книги

Можно указать, как должна отображаться внедренная книга, и как пользователи могут с ней взаимодействовать, когда она отображается. Параметры, имеющиеся в API, соответствуют многим параметрам, которые можно установить в пользовательском интерфейсе диалогового окна внедрения.

В следующем примере кода параметры отображения и взаимодействия устанавливаются в функции loadEwaOnPageLoad.

function loadEwaOnPageLoad() {
var props = {
uiOptions: {
showGridlines: false,
showRowColumnHeaders: false,
showParametersTaskPane: false
},
interactivityOptions: {
allowTypingAndFormulaEntry: false,
allowParameterModification: false,
allowSorting: false,
allowFiltering: false,
allowPivotTableInteractivity: false
}
};

Ewa.EwaControl.loadEwaAsync(fileToken, "myExcelDiv", props, onEwaLoaded);
}

Функция loadEwaonPageLoad вызывается событием страницы onLoad.

// Run the Excel load handler on page load
if (window.attachEvent) {
    window.attachEvent("onload", loadEwaOnPageLoad);
} 
else {
    window.addEventListener("DOMContentLoaded", loadEwaOnPageLoad, false);
}
function loadEwaOnPageLoad() {
    …
}
ПримечаниеПримечание

Блок if…else предоставляет два теста, чтобы можно было увидеть, какой метод присоединения событий распознается браузером. Это следствие того факта, что современные браузеры поддерживают либо метод attachEvent, либо метод addEventListener. Включение обоих методов гарантирует, что код ECMAScript (JavaScript, JScript) будет работать в большинстве современных браузеров.

В функции loadEwaonPageLoad код задает объект props, который содержит два объекта в качестве свойств: uiOptions и interactivityOptions. Объект uiOptions содержит свойства, которые влияют на отображение внедренной книги (например, следует ли показывать заголовки строк и столбцов), а объект interactivityOptions содержит свойства, которые влияют на возможности взаимодействия пользователей с этой книгой (такие как ввод текста или формул).

Внедрение книги

Последнее, что делает код внедрения из предыдущего примера, — это внедрение книги в элемент <div>, созданный ранее. Это выполняется с использованием вызова асинхронного метода Ewa.EwaControl.loadEwaAsync.

Ewa.EwaControl.loadEwaAsync(fileToken, "myExcelDiv", props, onEwaLoaded);

Сигнатура метода loadEwaAsync показана в следующем примере кода.

loadEwaAsync(fileID, divID, embedOptions, callback, userContext)

Метод loadEwaAsync задает следующие параметры:

  • fileID — значение string, содержащее маркер файла для книги;

  • divID — значение string, содержащее идентификатор для элемента <div>, в котором отображается книга;

  • embedOptions — объект, задающий параметры отображения и взаимодействия внедренной книги;

  • callback — обратный вызов, который вызывается после завершения работы метода loadEwaAsync;

  • userContext — объект, который позволяет вызывающей стороне передавать состояние с помощью асинхронного вызова.

Использование API JavaScript служб Excel

Показанный выше код внедрения загружает книгу и делает API ECMAScript (JavaScript, JScript) служб Excel доступным в коде внедрения. Затем можно использовать этот API для продолжения работы с внедренной книгой, чтобы создавать собственные приложения.

Пример

В следующем примере кода показывается, как можно программно работать с внедренной книгой Excel с помощью API ECMAScript (JavaScript, JScript) служб Excel.

<div id="myExcelDiv" style="width: 402px; height: 346px"></div>
<script type="text/javascript" src="http://r.office.microsoft.com/r/rlidExcelWLJS?v=1&kip=1"></script>
<script type="text/javascript">
    /*
    * This code uses the Microsoft Office Excel JavaScript object model to programmatically insert the
    * Excel Web App into a div with id=myExcelDiv. The full API is documented at
    * https://msdn.microsoft.com/en-us/library/hh315812.aspx. There you can find out how to programmatically get
    * values from your Excel file and how to use the rest of the object model. 
    */

    // Use this file token to reference Book1.xlsx in the Excel APIs
    var fileToken = "SD310A16DD64ED7E41!112/3533661997762444865/";
    var ewa = null;

    // Run the Excel load handler on page load.
    if (window.attachEvent)
    {
        window.attachEvent("onload", loadEwaOnPageLoad);
    } else
    {
        window.addEventListener("DOMContentLoaded", loadEwaOnPageLoad, false);
    }

    function loadEwaOnPageLoad()
    {
        var props = {
            uiOptions: {
                showGridlines: false,
                showRowColumnHeaders: false,
                showParametersTaskPane: false
            },
            interactivityOptions: {
                allowTypingAndFormulaEntry: false,
                allowParameterModification: false,
                allowSorting: false,
                allowFiltering: false,
                allowPivotTableInteractivity: false
            }
        };
        // Embed workbook using loadEwaAsync
        Ewa.EwaControl.loadEwaAsync(fileToken, "myExcelDiv", props, onEwaLoaded);
    }

    function onEwaLoaded(asyncResult)
    { 
        if (asyncResult.getSucceeded())
        {
            // Use the AsyncResult.getEwaControl() method to get a reference to the EwaControl object
            ewa = asyncResult.getEwaControl();
            ewa.add_activeCellChanged(cellChanged);
        }
        else
        {
            alert("Async operation failed!");
        }
        // ...
    }

    // Handle the active cell changed event.
    function cellChanged(rangeArgs)
    {
        // Use the RangeEventArgs object to get information about the range.
        var sheetName = rangeArgs.getRange().getSheet().getName();
        var col = rangeArgs.getRange().getColumn();
        var row = rangeArgs.getRange().getRow();
        var value = rangeArgs.getFormattedValues();
        alert("The active cell is located at row " + (row + 1) + " and column " + (col + 1) + " with value '" + value + "'.");
        // ...
    }
</script>

Дополнительные сведения об API ECMAScript (JavaScript, JScript) служб Excel см. в документации по пространству имен Ewa в пакете SDK SharePoint.

См. также

Концепции

Общие сведения о сценариях ECMAScript в службах Excel