Visio JavaScript API の概要

[アーティクル]
04/07/2023

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

埋め込んだ Visio 図面は、SharePoint ドキュメントライブラリに保存され、SharePoint ページに表示されます。 Visio 図面を埋め込むには、その図面を HTML の<iframe> 要素に表示します。そうすると、Visio JavaScript API を使用して、プログラムで埋め込み済みの図面を使った作業ができるようになります。

SharePoint ページの Iframe 上にある Visio の図とスクリプトエディター Web パーツ。

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

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

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

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

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

properties は、読み込まれるプロパティ名の一覧で、コンマ区切りの文字列または名前の配列として指定されます。詳細については、各オブジェクトの下の .load() メソッドを参照してください。
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 オブジェクトを使用して返されます。次の表は、発生する可能性があるエラー状態の一覧を示しています。

error.code	error.message
InvalidArgument	引数が無効であるか、存在しません。または形式が正しくありません。
GeneralException	要求の処理中に内部エラーが発生しました。
NotImplemented	要求された機能は実装されていません。
UnsupportedOperation	試行中の操作はサポートされていません。
AccessDenied	要求された操作を実行できません。
ItemNotFound	要求されたリソースは存在しません。

作業の開始

このセクションの例を使用して作業を開始できます。この例では、プログラムを使用して 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 ファイル URL をコピーします。

編集モードで Visio on the web を使用している場合は、[ファイル]>[共有]>[埋め込み] を選択して [埋め込み] ダイアログを開きます。表示モードで Visio on the web を使用している場合は、[...]、[埋め込み] の順に選択して [埋め込み] ダイアログを開きます。

Visio JavaScript API リファレンス

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

次の方法で共有

Visio JavaScript API の概要

EmbeddedSession

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

RequestContext

プロキシオブジェクト

sync()

load()

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

エラーメッセージ

作業の開始

Visio JavaScript API リファレンス

その他のリソース

次の方法で共有

Visio JavaScript API の概要

EmbeddedSession

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

RequestContext

プロキシ オブジェクト

sync()

load()

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

エラー メッセージ

作業の開始

Visio JavaScript API リファレンス

その他のリソース

プロキシオブジェクト

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

エラーメッセージ