Visio JavaScript API 概述

可以使用 Visio JavaScript API 在 SharePoint Online 的经典 SharePoint 页面中嵌入 Visio 图表。 (本地 SharePoint 或 SharePoint 框架 pages 不支持此扩展性功能。)

嵌入的 Visio 关系图存储在 SharePoint 文档库中，并显示在 SharePoint 页面上。 若要嵌入 Visio 图表，请在 HTML <iframe> 元素中显示它。 然后使用 Visio JavaScript API 以编程方式处理嵌入式关系图。

可以使用 Visio JavaScript API 执行以下操作：

• 与页面、形状等 Visio 图表元素进行交互。
• 在 Visio 图表画布上创建视觉标记。
• 为绘图中的鼠标事件编写自定义处理程序。
• 向解决方案公开图表数据，如形状文本、形状数据和超链接。

本文介绍如何将 Visio JavaScript API 与 Visio web 版 配合使用来生成 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 代理对象、在本地和 Visio 对象之间同步状态的 sync() 方法以及承诺实现。 中 Visio.run() 批处理请求的优点是，在承诺得到解决时，会自动释放在执行期间分配的任何跟踪页对象。

run 函数获取会话和 RequestContext 对象，并返回一个承诺（通常就是 context.sync() 的结果）。 可以在 外部 Visio.run()运行批处理作。 但是，在这种情况下，需要手动跟踪和管理任何页面对象引用。

RequestContext

RequestContext 对象可方便对 Visio 应用程序提出请求。 由于开发人员框架和 Visio Web 客户端在两个不同的 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);
    });
};

代理对象

在嵌入会话中声明和使用的 Visio JavaScript 对象是 Visio 文档中真实对象的代理对象。 在 Visio 中不会实现对代理对象执行的所有作，在同步文档状态之前，不会在代理对象中实现 Visio 文档的状态。 运行 context.sync() 时将同步文档状态。

例如，本地 JavaScript 对象 getActivePage 声明为引用选定页面。 可以使用此来排队设置其属性并调用方法。 在运行 方法之前， sync() 不会实现对此类对象的作。

const activePage = context.document.getActivePage();

sync()

sync() 方法通过执行在上下文中排队的指令以及检索用于你代码中的已加载 Office 对象的属性，在 JavaScript 代理对象和 Visio 中的真实对象之间同步状态。 此方法返回一个将在同步完成时实现的承诺。

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));
    }
});

错误消息

使用包含代码和消息的错误对象返回错误。 下表提供了可能的错误条件列表。

开始使用

可以从本部分中的示例入手。 此示例展示了如何在 Visio 图表中以编程方式显示选定形状的形状文本。 首先，在 SharePoint Online 中创建一个经典页面，或编辑现有页面。 在页面上添加脚本编辑器 Web 部件，并复制粘贴以下代码。

<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>

完成此操作之后，只需使用你想要使用的 Visio 图表的 URL。 将 Visio 关系图上传到 SharePoint Online 并在Visio web 版中打开它。 在这里打开嵌入对话框，然后使用以上示例中的嵌入 URL。

如果在编辑模式下使用Visio web 版，请通过选择“文件共享>>嵌入”打开“嵌入”对话框。 如果在“视图”模式下使用Visio web 版，请通过选择“...”打开“嵌入”对话框，然后嵌入。

Visio JavaScript API 参考

有关 Visio JavaScript API 的详细信息，请参阅 Visio JavaScript API 参考文档。