Обзор API JavaScript для Visio

С помощью API JavaScript для Visio вы можете встраивать схемы Visio в классические страницы SharePoint в SharePoint Online. (Эта функция расширения не поддерживается на локальных страницах SharePoint или SharePoint Framework.)

Важно!

Прежде чем вкладывать ресурсы на создание внедренной схемы Visio, учтите, что классические страницы SharePoint удаляются. Вы по-прежнему можете создавать их до 1 марта 2027 года и редактировать до 1 октября 2028 года. После этой даты классические страницы SharePoint станут доступны только для чтения, и все динамические аспекты внедренной схемы перестанут работать.

Внедренная схема Visio хранится в библиотеке документов SharePoint и отображается на странице SharePoint. Чтобы внедрить документ Visio, отобразите его в элементе <iframe> HTML. Затем используйте API JavaScript Visio для программной работы с внедренной схемой.

API JavaScript для Visio позволяет следующее:

• работать с элементами документа Visio как со страницами и фигурами;
• создавать визуальную разметку на холсте документа Visio;
• создавать специальные обработчики событий мыши для документа;
• предоставлять своему решению данные документа, такие как текст фигуры, данные фигуры и гиперссылки.

В этой статье описывается, как использовать API JavaScript Visio с Visio в Интернете для создания решений для SharePoint Online. В ней представлены ключевые понятия, которые являются фундаментальными для использования API, такие как EmbeddedSessionобъекты RequestContext, , и JavaScript прокси-объекты, а также sync()методы , Visio.run()и load() . В приведенных ниже примерах кода показано применение этих элементов.

EmbeddedSession

Объект EmbeddedSession инициализирует взаимодействие между фреймом разработчика и фреймом Visio в браузере.

const session = new OfficeExtension.EmbeddedSession(url, { id: "embed-iframe",container: document.getElementById("iframeHost") });
session.init().then(function () {
    window.console.log("Session successfully initialized");
});

Visio.run(session, function(context) { batch })

Метод Visio.run() выполняет пакетный сценарий, совершающий действия с объектной моделью Visio. Пакетные команды включают определения локальных прокси-объектов JavaScript и методов sync(), синхронизирующих состояние объектов Visio и локальных объектов, а также разрешение обещания. Преимущество пакетных запросов заключается в Visio.run() том, что при разрешении обещания все отслеживаемые объекты страницы, которые были выделены во время выполнения, автоматически освобождаются.

Функция run использует объект session и RequestContext и возвращает обещание (как правило, просто результат выполнения метода context.sync()). Пакетную операцию можно выполнить за пределами Visio.run(). Однако в таком сценарии любые ссылки на объекты страницы необходимо отслеживать вручную и управлять.

RequestContext

Объект RequestContext обеспечивает отправку запросов приложению Visio. Поскольку фрейм разработчика и веб-клиент Visio работают в двух разных фреймах iframe, объект RequestContext (контекст в следующем примере) необходим для получения доступа к Visio и связанным объектам, таким как страницы и фигуры, из фрейма разработчика.

function hideToolbars() {
    Visio.run(session, function(context){
        const app = context.document.application;
        app.showToolbars = false;
        return context.sync().then(function () {
            window.console.log("Toolbars Hidden");
        });
    }).catch(function(error)
    {
        window.console.log("Error: " + error);
    });
};

Прокси-объекты

Объекты JavaScript для Visio, объявленные и использованные во встроенном сеансе, — это прокси-объекты для реальных объектов в документе Visio. Все действия, выполняемые над прокси-объектами, не реализуются в Visio, и состояние документа Visio не реализуется в прокси-объектах до тех пор, пока состояние документа не будет синхронизировано. Состояние документа синхронизируется при выполнении context.sync().

Например, локальный объект JavaScript getActivePage объявлен в качестве ссылки на выбранную страницу. Это можно использовать для постановки в очередь настройки его свойств и вызова методов. Действия над такими объектами не реализуются до тех пор, пока метод не будет запущен.sync()

const activePage = context.document.getActivePage();

sync()

Метод sync() синхронизирует состояние прокси-объектов JavaScript и реальных объектов в Visio путем выполнения поставленных в очередь инструкций над контекстом и получения свойств загруженных объектов Office для их использования в коде. Этот метод возвращает обещание, которое выполняется после завершения синхронизации.

load()

Метод load() используется для заполнения прокси-объектов, созданных на уровне JavaScript. При попытке получения объекта, такого как документ, сначала на уровне JavaScript создается локальный прокси-объект. Такой объект можно использовать для постановки в очередь установки его свойств и вызова методов. Но для чтения свойств или связей объекта сначала необходимо вызвать методы load() и sync(). Метод load() использует свойства и связи, которые необходимо загрузить при вызове метода sync().

Ниже представлен синтаксис метода load().

object.load(string: properties); //or object.load(array: properties); //or object.load({loadOption});

1. properties — это список имен свойств, которые требуется загрузить, разделенных запятыми, или массив имен. Дополнительные сведения см. в описаниях методов .load() под каждым объектом.

2. loadOption указывает объект, который описывает параметры выбора, расширения, вершины и пропуска. Дополнительные сведения см. в разделе параметры загрузки объекта.

Пример. Печать текста всех фигур на активной странице

Приведенный ниже пример показывает, как распечатать значение текста фигуры из объекта фигур массива. Функция Visio.run() содержит пакет инструкций. В рамках этого пакета создается прокси-объект, который ссылается на фигуры в активном документе.

Все эти команды ставятся в очередь и выполняются при вызове метода context.sync(). Метод sync() возвращает обещание, с помощью которого его можно связать с другими операциями.

Visio.run(session, function (context) {
    const page = context.document.getActivePage();
    const shapes = page.shapes;
    shapes.load();
    return context.sync().then(function () {
        for(let i=0; i<shapes.items.length;i++) {
            let shape = shapes.items[i];
            window.console.log("Shape Text: " + shape.text );
        }
    });
}).catch(function(error) {
    window.console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        window.console.log ("Debug info: " + JSON.stringify(error.debugInfo));
    }
});

Сообщения об ошибках

Ошибки возвращаются с помощью объекта ошибки, состоящего из кода и сообщения. В следующей таблице приведен список возможных условий ошибки.

error.code	error.message
InvalidArgument	Аргумент недопустим, отсутствует или имеет неправильный формат.
GeneralException	При обработке запроса возникла внутренняя ошибка.
NotImplemented	Запрашиваемая функция не реализована.
UnsupportedOperation	Выполняемая операция не поддерживается.
AccessDenied	Вы не можете выполнить запрашиваемую операцию.
ItemNotFound	Запрашиваемый ресурс не существует.

Начало работы

Для начала просмотрите пример в этом разделе. В этом примере показано, как программно отобразить текст выбранной фигуры в документе Visio. Сперва создайте классическую страницу в SharePoint Online или отредактируйте существующую страницу. Добавьте веб-часть редактора скриптов на страницу и скопируйте и вставьте следующий код.

<script src='https://appsforoffice.microsoft.com/embedded/1.0/visio-web-embedded.js' type='text/javascript'></script>

Enter Visio File Url:<br/>
<script language="javascript">
document.write("<input type='text' id='fileUrl' size='120'/>");
document.write("<input type='button' value='InitEmbeddedFrame' onclick='initEmbeddedFrame()' />");
document.write("<br />");
document.write("<input type='button' value='SelectedShapeText' onclick='getSelectedShapeText()' />");
document.write("<textarea id='ResultOutput' style='width:350px;height:60px'> </textarea>");
document.write("<div id='iframeHost' />");

let session; // Global variable to store the session and pass it afterwards in Visio.run()
let textArea;
// Loads the Visio application and Initializes communication between developer frame and Visio online frame
function initEmbeddedFrame() {
    textArea = document.getElementById('ResultOutput');
    let url = document.getElementById('fileUrl').value;
    if (!url) {
        window.alert("File URL should not be empty");
    }
    // APIs are enabled for EmbedView action only.
    url = url.replace("action=view","action=embedview");
    url = url.replace("action=interactivepreview","action=embedview");
    url = url.replace("action=default","action=embedview");
    url = url.replace("action=edit","action=embedview");
  
    session = new OfficeExtension.EmbeddedSession(url, { id: "embed-iframe",container: document.getElementById("iframeHost") });
    return session.init().then(function () {
        // Initialization is successful
        textArea.value  = "Initialization is successful";
    });
}

// Code for getting selected Shape Text using the shapes collection object
function getSelectedShapeText() {
    Visio.run(session, function (context) {
        const page = context.document.getActivePage();
        const shapes = page.shapes;
        shapes.load();
        return context.sync().then(function () {
            textArea.value = "Please select a Shape in the Diagram";
            for(let i=0; i<shapes.items.length;i++) {
                let shape = shapes.items[i];
                if ( shape.select == true) {
                    textArea.value = shape.text;
                    return;
                }
            }
        });
    }).catch(function(error) {
        textArea.value = "Error: ";
        if (error instanceof OfficeExtension.Error) {
            textArea.value += "Debug info: " + JSON.stringify(error.debugInfo);
        }
    });
}
</script>

После этого вам нужен только URL-адрес документа Visio, с которым вы хотите работать. Загрузите схему Visio в SharePoint Online и откройте ее в Visio в Интернете. Оттуда откройте диалоговое окно внедрения и используйте URL-адрес внедрения в приведенном выше примере.

Если вы используете Visio в Интернете в режиме правки, откройте диалоговое окно "Внедрить", выбрав>"Внедрить файловый ресурс>". Если вы используете Visio в Интернете в режиме просмотра, откройте диалоговое окно внедрения, выбрав «...» а затем "Внедрить".

Справочник по API JavaScript для Visio

Подробные сведения об API JavaScript в Visio см. в справочной документации по API JavaScript в Visio.