Visio JavaScript API の概要

Visio JavaScript API を使うと、従来 のSharePoint Online で Visio 図面を埋め込むことができます。 (この機能拡張機能は、オンプレミスの SharePoint または SharePoint Framework ページではサポートされていません)。

埋め込まれた Visio ダイアグラムは SharePoint ドキュメント ライブラリに格納され、SharePoint ページに表示されます。 Visio 図面を埋め込むには、その図面を HTML の<iframe> 要素に表示します。 次に、Visio JavaScript API を使用して、埋め込み図をプログラムで操作します。

Visio JavaScript API を使用して、次のことを行えます。

• ページや図形などの Visio 図面の要素を操作する。
• Visio 図面のキャンバスにビジュアル マークアップを作成する。
• 図面の中でのマウス イベントのカスタム ハンドラーを記述する。
• 図形テキスト、図形データ、およびハイパーリンクなどの図面データをソリューションに公開する。

この記事では、Visio on the webで Visio JavaScript API を使用して SharePoint Online のソリューションを構築する方法について説明します。 EmbeddedSession、RequestContext、JavaScript プロキシ オブジェクト、sync()、Visio.run()、load() メソッドなど、API の使用に不可欠な主要な概念について説明します。 コード例により、これらの概念を適用する方法を示します。

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()sync() メソッドが含まれます。 Visio.run()で要求をバッチ処理する利点は、promise が解決されると、実行中に割り当てられた追跡されたページ オブジェクトが自動的に解放されるということです。

run 機能はセッションと RequestContext オブジェクトを取り込み、promise (通常は context.sync() の結果) を返します。 バッチ操作は、 Visio.run()の外部で実行できます。 ただし、このようなシナリオでは、ページ オブジェクト参照を手動で追跡および管理する必要があります。

RequestContext

RequestContext オブジェクトは、Visio アプリケーションへの要求を容易にします。 開発者フレームと Visio Web クライアントは 2 つの異なる iframe で実行されるため、Visio へのアクセスと、開発者フレームからページや図形などの関連オブジェクトにアクセスするには、RequestContext オブジェクト (次の例のコンテキスト) が必要です。

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()sync() メソッドは、Visio 内の JavaScript のプロキシ オブジェクトと実際のオブジェクトの間で状態を同期させます。これは、コンテキストでキューに入れられた指示の実行と、ユーザーのコードで使用するために読み込まれた Office オブジェクトのプロパティを取得することで同期させます。 このメソッドは、同期処理が完了したときに解決される promise を返します。

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 は、selection、expansion、top、skip の各オプションについて説明するオブジェクトを指定します。 詳細については、オブジェクトの読み込みのオプションを参照してください。

例: アクティブ ページですべての図形テキストを印刷する

次の例では、図形の配列オブジェクトから図形テキストの値を印刷する方法を示します。 Visio.run() 機能には、命令のバッチが含まれています。 このバッチの一部として、作業中のドキュメントの図形を参照するプロキシ オブジェクトが作成されます。

これらのすべてのコマンドがキューに登録され、context.sync() が呼び出されたときに実行されます。 sync() メソッドが返す promise は、このメソッドを他の操作とチェーンにするために使用できます。

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 オブジェクトを使用して返されます。 次の表に、考えられるエラー条件の一覧を示します。

作業の開始

このセクションの例を使用して作業を開始できます。 この例では、プログラムを使用して 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 on the webで開きます。 そこから [埋め込み] ダイアログ ボックスを開き、上の例の埋め込み URL を使用します。

編集モードでVisio on the webを使用している場合は、ファイル>Share>Embed を選択して [埋め込み] ダイアログを開きます。 ビュー モードでVisio on the webを使用している場合は、'..' を選択して [埋め込み] ダイアログを開きます。をクリックし、[埋め込み] を選択します。

Visio JavaScript API リファレンス

Visio JavaScript API の詳細については、 Visio JavaScript API リファレンス ドキュメントを参照してください。