Main Content

HTML のプロパティ

HTML UI コンポーネントの外観と動作の制御

R2019b 以降

uihtml を使用して作成した HTML UI コンポーネントを使用して、生の HTML テキスト、組み込み HTML、JavaScript®、または CSS をアプリに表示し、サードパーティ製の JavaScript ライブラリと連動させることができます。HTML プロパティは、HTML UI コンポーネントの外観と動作を制御します。ドット表記を使用して、特定のオブジェクトとプロパティを参照します。

fig = uifigure;
h = uihtml(fig); 
h.Position = [100 100 150 100];
h.HTMLSource = '<p style="font-family:sans-serif">This is <mark>marked</mark> text.</p>';

HTML

すべて展開する

HTML マークアップまたは HTML ファイル。HTML マークアップまたは HTML ファイルへのパスのいずれかを含む文字ベクトルまたは string スカラーとして指定します。HTML マークアップおよび HTML ファイルはすべて、適切な形式でなければなりません。指定された文字ベクトルまたは string スカラーが .html で終わる場合、HTML ファイルへのパスと見なされます。

HTML マークアップを組み込む場合、<html> タグまたは <body> タグを指定する必要はありません。指定したマークアップが、関数 uifigure で作成された MATLAB® Figure により使用される Chromium ブラウザーでサポートされている場合、そのマークアップがレンダリングされます。コードに多くの構造が必要な場合は、代わりに HTML ファイルを使用することを検討してください。

HTMLSource プロパティを HTML ファイルへのパスに設定する場合、HTML ファイルはローカル ファイル システムがアクセスできる場所に配置しなければなりません。JavaScript、CSS、ライブラリ、イメージなどのサポート ファイルを使用している場合は、ローカル ファイル システムがアクセスできる場所にファイルを配置し、HTML ファイル内でそれらを参照して、HTMLSource プロパティを HTML ファイルへのパスに設定します。コンポーネント コードが使用するサポート ファイルは、HTMLSource プロパティに指定した HTML ファイルを含むフォルダー、またはそのフォルダーのサブフォルダーになければなりません。詳細については、制限を参照してください。

例: h = uihtml('HTMLSource','CustomCharts.html') は、HTML ファイルを指定します。

例: h = uihtml('HTMLSource','<p>This is <span style="color:red">red</span> text.</p>') は、マークアップを指定します。

MATLAB データ。任意の MATLAB データ型として指定します。この引数は、HTMLSource の値が JavaScript オブジェクトを定義する HTML ファイルへのパスである場合に使用します。次に、このデータを MATLAB HTML UI コンポーネントと JavaScript オブジェクトの間で同期できます。

MATLAB と、アプリに組み込んでいるサードパーティ製コンテンツの間で Data プロパティ値を同期するには、htmlComponent という JavaScript オブジェクトを MATLAB の HTML UI コンポーネントに接続する関数 setup を HTML ファイル内に作成します。次に、HTMLSource プロパティ値をファイルへのパスに設定します。

Data プロパティ値を変更すると、一方向にのみコールバック イベントがトリガーされます。特に、

  • Data プロパティが MATLAB で設定されると、htmlComponent JavaScript オブジェクトの Data プロパティも更新され、'DataChanged' イベントの JavaScript のイベント リスナーをトリガーします。

  • htmlComponent.Data が JavaScript で設定されると、MATLAB の HTML UI コンポーネントの Data プロパティも更新され、DataChangedFcn コールバックをトリガーします。

入れ子の cell 配列、構造体の配列、MATLAB table 配列データなどのデータがある場合、MATLAB と JavaScript の間でデータがどのように変換されるかに関する情報が必要になることがあります。HTML UI コンポーネントの Data プロパティが MATLAB で設定されると、データは関数 jsonencode を使用して変換され、JavaScript と同期され、JSON.parse() を使用して解析されてから、最後に htmlComponent JavaScript オブジェクトの Data プロパティに設定されます。変換は、JSON.stringify() および関数 jsondecode により、逆方向にも起こります。Data プロパティは、JavaScript と同期される唯一のプロパティです。

サポートするデータ型の詳細については、関数 jsonencode を参照してください。使用しているデータ型を関数 jsonencode がサポートしていない場合は、num2str などのデータ型変換関数を使用して、サポートされている型にデータを変換します。次に、それを Data プロパティ値として設定します。

データ同期を可能にする HTML ファイルの作成方法と、htmlComponent JavaScript オブジェクトのプロパティの詳細については、アプリ内の HTML コンテンツの作成を参照してください。

対話機能

すべて展開する

可視性の状態。'on' または 'off'、もしくは数値または logical 1 (true) または 0 (false) として指定します。'on' の値は true と等価であり、'off'false と等価です。したがって、このプロパティの値を logical 値として使用できます。値は matlab.lang.OnOffSwitchState 型の on/off logical 値として格納されます。

  • 'on' — オブジェクトを表示します。

  • 'off' — オブジェクトを削除せずに非表示にします。非表示の UI コンポーネントのプロパティには引き続きアクセスできます。

アプリの起動を高速化するには、起動時に表示する必要のないすべての UI コンポーネントの Visible プロパティを 'off' に設定します。

ツールヒント。文字ベクトル、文字ベクトルの cell 配列、string 配列、または 1 次元の categorical 配列として指定します。このプロパティを使用して、実行時にユーザーがポインターをコンポーネントに合わせるとメッセージが表示されるようにします。コンポーネントが無効になっている場合でも、ツールヒントは表示されます。複数行のテキストを表示するには、文字ベクトルの cell 配列または string 配列を指定します。配列の各要素は、テキストの各行になります。このプロパティを categorical 配列として指定した場合、MATLAB はカテゴリの完全なセットではなく、配列内の値を使用します。

コンテキスト メニュー。関数 uicontextmenu を使用して作成された ContextMenu オブジェクトとして指定します。

メモ

このプロパティは、HTML UI コンポーネントの HTMLSource プロパティが設定されている場合は無効になります。代わりに、ユーザーがコンポーネントを右クリックしたときにコンテキスト メニューを表示するには、イベントを検出し、必要な場所にコンテキスト メニューをプログラムで開くコードを記述します。

例: HTML UI コンポーネントのコンテキスト メニューを開く

cmexample.html という名前の HTML ファイルを作成します。ファイルで次を行います。

  • コンポーネントの外観を構成する <div> 要素を作成します。

  • 関数 setup を記述して、htmlComponent JavaScript オブジェクトを MATLAB の HTML UI コンポーネントに接続します。

  • JavaScript オブジェクトで contextmenu イベント (右クリックなど) をリッスンし、リスナー コールバック関数を作成するイベント リスナーを関数 setup に追加します。contextmenu イベントが発生すると、リスナー コールバックが htmlComponent オブジェクトの Data プロパティを設定し、イベントをトリガーしたアクションおよびイベントがトリガーされた位置を格納します。このデータは、関連する MATLAB HTML UI コンポーネントから使用できるようになります。

<!DOCTYPE html> 
<html> 
<body> 

<div id="contextMenuTarget" style="background-color:gray;width:200px;height:200px;">
    Right-click on this component to open a context menu.
</div>

<script type="text/javascript">
    function setup(htmlComponent) {
        document.getElementById("contextMenuTarget").addEventListener("contextmenu", function(event) {
            htmlComponent.Data = {Action:"showContextMenu", PosData:[event.clientX, event.clientY]};
        });
    }
</script>

</body> 
</html>

MATLAB スクリプトで、UI Figure 内に HTML UI コンポーネントおよびコンテキスト メニュー オブジェクトを作成します。HTML UI コンポーネントの HTMLSource プロパティとして cmexample.html ファイルを指定します。次に、コンテキスト メニューを入力として受け取り、HTML UI コンポーネントの Data プロパティが変更されるたびに実行されるコールバック関数 openContextMenu を定義します。このコールバック関数で、コールバック実行をトリガーしたイベントがコンテキスト メニュー イベントであったかどうかを確認します。そうであった場合は、イベントの位置を取得し、それを使用して Figure 内の適切な場所にコンテキスト メニューを開きます。

fig = uifigure;

h = uihtml(fig,"HTMLSource","cmexample.html");
h.Position = [100 100 200 200];

cm = uicontextmenu(fig);
m1 = uimenu(cm,"Text","Option 1");
m2 = uimenu(cm,"Text","Option 2");
h.ContextMenu = cm;

h.DataChangedFcn = {@openContextMenu,cm};

function openContextMenu(src,event,cm)
    switch src.Data.Action
        case "showContextMenu"
            p = getpixelposition(src,true);
            xClick = src.Data.PosData(1);
            yClick = src.Data.PosData(2);
            xOpen = p(1)+xClick;
            yOpen = p(2)+p(4)-yClick;
            open(cm,xOpen,yOpen);
    end
end

スクリプトを実行し、HTML UI コンポーネントを右クリックしてコンテキスト メニューを開きます。

HTML UI component inside a UI figure window. The HTML UI component contains text that says: "Right-click on this component to open a context menu." There is a context menu open on the component.

位置

すべて展開する

親コンテナーを基準とした HTML UI コンポーネントの位置とサイズ。[left bottom width height] の形式の 4 要素ベクトルとして指定します。次の表で、ベクトルの各要素について説明します。

要素説明
left親コンテナーの内側左端から HTML UI コンポーネントの外側左端までの距離
bottom親コンテナーの内側下端から HTML UI コンポーネントの外側下端までの距離
widthHTML UI コンポーネントの外側の左端から右端までの距離
heightHTML UI コンポーネントの外側の上端から下端までの距離

Position の値の基準は、親コンテナーの "描画可能領域" です。描画可能領域は、コンテナーの境界線の内側にある領域で、メニュー バーやタイトルなどの装飾が占める領域は含まれません。

すべての測定単位はピクセルです。

HTML UI コンポーネントの内側の位置とサイズ。[left bottom width height] の形式の 4 要素ベクトルとして指定します。すべての測定単位はピクセルです。このプロパティ値は、Position プロパティと同一です。

この プロパティ は読み取り専用です。

HTML UI コンポーネントの外側の位置とサイズ。[left bottom width height] の形式の 4 要素ベクトルとして返されます。すべての測定単位はピクセルです。このプロパティ値は、Position プロパティと同一です。

レイアウト オプション。GridLayoutOptions オブジェクトとして指定します。このプロパティは、グリッド レイアウト コンテナーの子であるコンポーネントのオプションを指定します。コンポーネントがグリッド レイアウト コンテナーの子ではない場合 (たとえば、Figure またはパネルの子である場合) は、このプロパティは空で、効果はありません。しかし、コンポーネントがグリッド レイアウト コンテナーの子である場合は、GridLayoutOptions オブジェクトの Row プロパティおよび Column プロパティを設定して、グリッドの対象とする行と列にコンポーネントを配置することができます。

たとえば、以下のコードは、HTML UI コンポーネントをその親グリッドの 3 行目の 2 列目に配置します。

g = uigridlayout([4 3]);
h = uihtml(g);
h.HTMLSource = '<body style="background-color:powderblue;"><p>Hello World!</p></body>';
h.Layout.Row = 3;
h.Layout.Column = 2;

HTML UI コンポーネントが連続する行または列にまたがるようにするには、Row プロパティまたは Column プロパティを 2 要素ベクトルとして指定します。たとえば、次の HTML UI コンポーネントは 2 列目から 3 列目にまたがります。

h.Layout.Column = [2 3];

コールバック

すべて展開する

データが変化したときのコールバック。次の値のいずれかとして指定します。

  • 関数ハンドル。

  • 最初の要素が関数ハンドルである cell 配列。cell 配列内のその後の要素はコールバック関数に渡される引数です。

  • 有効な MATLAB 式を含む文字ベクトル (非推奨)。MATLAB は、この式をベース ワークスペースで評価します。

htmlComponent JavaScript オブジェクトの Data プロパティ値が変化すると、MATLAB の HTML UI コンポーネントの Data プロパティが更新され、このコールバックが実行されます。

このコールバック関数は JavaScript オブジェクト内のデータの変化に関する特定の情報にアクセスできます。MATLAB は、コールバック関数の 2 番目の引数として DataChangedData オブジェクト内にこの情報を渡します。App Designer では、引数は event と呼ばれます。ドット表記を使用して、DataChangedData オブジェクトのプロパティをクエリできます。たとえば、event.PreviousData は、Data の最終更新または最終変更が行われる前の値を返します。DataChangedData オブジェクトは、文字ベクトルとして指定されているコールバック関数では使用できません。

次の表に、DataChangedData オブジェクトのプロパティを示します。

プロパティ説明
Data直前の DataChanged イベントの結果として得られた最新のデータ
PreviousData直前の DataChanged イベントの前のデータ
Source

コールバックを実行する MATLAB の HTML UI コンポーネント

EventName'DataChanged'

コールバックの記述の詳細については、App Designer のコールバックを参照してください。

R2023a 以降

HTML ソースからイベントを受信したときのコールバック。次の値のいずれかとして指定します。

  • 関数ハンドル。

  • 最初の要素が関数ハンドルである cell 配列。cell 配列内のその後の要素はコールバック関数に渡される引数です。

  • 有効な MATLAB 式を含む string スカラーまたは文字ベクトル (非推奨)。MATLAB は、この式をベース ワークスペースで評価します。

このコールバックは、JavaScript の htmlComponent オブジェクトで関数 sendEventToMATLAB を呼び出して JavaScript から MATLAB にイベントが送信されると実行されます。このコールバックを使用して、ボタン HTML 要素のクリックなど、ユーザー操作や HTML コンポーネントの変化に応答する MATLAB コードを記述します。詳細については、アプリ内の HTML コンテンツの作成を参照してください。

このコールバック関数は、JavaScript オブジェクトから送信されたイベントに関する特定の情報にアクセスできます。MATLAB は、その情報を HTMLEventReceivedData オブジェクトに格納して、2 番目の引数としてコールバック関数に渡します。App Designer では、引数は event と呼ばれます。ドット表記を使用して、HTMLEventReceivedData オブジェクトのプロパティをクエリします。たとえば、event.HTMLEventName は、JavaScript オブジェクトで指定されたイベントの名前を返します。HTMLEventReceivedData オブジェクトは、string スカラーまたは文字ベクトルとして指定されているコールバック関数では使用できません。

次の表に、HTMLEventReceivedData オブジェクトのプロパティを示します。

プロパティ説明
HTMLEventNameJavaScript コードで呼び出される関数 sendEventToMATLAB によって指定されたイベントの名前
HTMLEventDataJavaScript コードで呼び出される関数 sendEventToMATLAB によって指定されたイベント データ
Source

コールバックを実行する MATLAB の HTML UI コンポーネント

EventName'HTMLEventReceived'

コールバックの記述の詳細については、プログラムで作成したアプリ用のコールバックの作成を参照してください。

オブジェクト作成関数。次の値のいずれかとして指定します。

  • 関数ハンドル。

  • 最初の要素が関数ハンドルである cell 配列。cell 配列内のその後の要素はコールバック関数に渡される引数です。

  • 有効な MATLAB 式を含む文字ベクトル (非推奨)。MATLAB は、この式をベース ワークスペースで評価します。

コールバックを関数ハンドル、cell 配列、または文字ベクトルとして指定する方法の詳細については、App Designer のコールバックを参照してください。

このプロパティは、MATLAB がオブジェクトを作成するときに実行されるコールバック関数を指定します。MATLAB は CreateFcn コールバックを実行する前に、すべてのプロパティ値を初期化します。CreateFcn プロパティを指定しない場合、MATLAB は既定の作成関数を実行します。

既存のコンポーネントに CreateFcn プロパティを設定しても効果はありません。

このプロパティを関数ハンドルまたは cell 配列として指定した場合、コールバック関数の最初の引数を使用して、作成中のオブジェクトにアクセスできます。それ以外の場合は、関数 gcbo を使用してオブジェクトにアクセスします。

オブジェクト削除関数。次の値のいずれかとして指定します。

  • 関数ハンドル。

  • 最初の要素が関数ハンドルである cell 配列。cell 配列内のその後の要素はコールバック関数に渡される引数です。

  • 有効な MATLAB 式を含む文字ベクトル (非推奨)。MATLAB は、この式をベース ワークスペースで評価します。

コールバックを関数ハンドル、cell 配列、または文字ベクトルとして指定する方法の詳細については、App Designer のコールバックを参照してください。

このプロパティは、MATLAB がオブジェクトを削除するときに実行されるコールバック関数を指定します。MATLAB は、オブジェクトのプロパティを破棄する前に DeleteFcn コールバックを実行します。DeleteFcn プロパティを指定しない場合、MATLAB は既定の削除関数を実行します。

このプロパティを関数ハンドルまたは cell 配列として指定した場合、コールバック関数の最初の引数を使用して、削除されるオブジェクトにアクセスできます。それ以外の場合は、関数 gcbo を使用してオブジェクトにアクセスします。

コールバック実行制御

すべて展開する

コールバックの割り込み。'on' または 'off'、もしくは数値または logical 1 (true) または 0 (false) として指定します。'on' の値は true と等価であり、'off'false と等価です。したがって、このプロパティの値を logical 値として使用できます。値は matlab.lang.OnOffSwitchState 型の on/off logical 値として格納されます。

このプロパティは実行中のコールバックが割り込み可能かどうかを決定します。次の 2 つのコールバックの状態について考慮する必要があります。

  • "実行中" コールバックは、現在実行しているコールバックです。

  • "割り込み" コールバックは、実行中のコールバックに割り込もうとするコールバックです。

MATLAB は、コールバック キューを処理するコマンドを実行するたびにコールバックの割り込み動作を判別します。これらのコマンドには、drawnowfigureuifiguregetframewaitforpause があります。

実行中コールバックにこれらのコマンドが含まれていない場合、割り込みは発生しません。MATLAB は、実行中コールバックの実行を先に終了させ、その後に割り込みコールバックを実行します。

実行中コールバックにこれらのいずれかのコマンドが含まれている場合、実行中コールバックを所有するオブジェクトの Interruptible プロパティに応じて割り込みが発生するかどうかが決まります。

  • Interruptible の値が 'off' の場合、割り込みは発生しません。代わりに、割り込みコールバックを所有するオブジェクトの BusyAction プロパティに応じて、割り込みコールバックが破棄されるかコールバック キューに追加されるかが決まります。

  • Interruptible の値が 'on' の場合、割り込みが発生します。MATLAB は、コールバック キューの次回処理時に、実行中コールバックの実行を停止し、割り込みコールバックを実行します。割り込みコールバックが完了した後、MATLAB は実行中だったコールバックの実行を再開します。

メモ

コールバックの割り込みと実行は、以下の状況では動作が異なります。

  • 割り込みコールバックが DeleteFcnCloseRequestFcn または SizeChangedFcn コールバックの場合、Interruptible プロパティの値にかかわらず割り込みが発生します。

  • 実行中のコールバックが関数 waitfor を現在実行している場合、Interruptible プロパティの値にかかわらず割り込みが発生します。

  • 割り込みコールバックが Timer オブジェクトで所有されている場合、Interruptible プロパティの値にかかわらずスケジュールに従ってコールバックが実行されます。

メモ

MATLAB は、割り込みが発生したときにプロパティの状態や表示を保存しません。たとえば、gca コマンドや gcf コマンドから返されたオブジェクトは、別のコールバックを実行するときに変更されている可能性があります。

コールバック キューイング。'queue' または 'cancel' として指定します。BusyAction プロパティは MATLAB による割り込みコールバックの実行の処理方法を決定します。次の 2 つのコールバックの状態について考慮する必要があります。

  • "実行中" コールバックは、現在実行しているコールバックです。

  • "割り込み" コールバックは、実行中のコールバックに割り込もうとするコールバックです。

BusyAction プロパティによってコールバック キューイングの動作が決まるのは、次の両方の条件を満たす場合のみです。

  • 実行中コールバックに drawnowfigureuifiguregetframewaitforpause などのコールバック キューを処理するコマンドが含まれている。

  • 実行中コールバックを所有するオブジェクトの Interruptible プロパティの値が 'off' である。

これらの条件に当てはまる場合、割り込みコールバックを所有するオブジェクトの BusyAction プロパティに応じて MATLAB による割り込みコールバックの処理方法が決まります。BusyAction プロパティは次の値を取ることができます。

  • 'queue' — 割り込みコールバックをキューに入れ、実行中のコールバックが終了した後に処理されるようにします。

  • 'cancel' — 割り込みコールバックを実行しません。

この プロパティ は読み取り専用です。

削除状態。matlab.lang.OnOffSwitchState 型の on/off logical 値として返されます。

MATLAB は、DeleteFcn コールバックが実行を開始すると、BeingDeleted プロパティを 'on' に設定します。コンポーネント オブジェクトが存在しなくなるまで BeingDeleted プロパティは 'on' に設定されたままです。

クエリや変更の前にオブジェクトが削除されようとしていないか確認するために BeingDeleted プロパティの値をチェックします。

親/子

すべて展開する

親コンテナー。関数 uifigure を使用して作成された Figure オブジェクト、またはその子コンテナー (TabPanelButtonGroup または GridLayout) のいずれかとして指定します。コンテナーが指定されていない場合、MATLAB は関数 uifigure を呼び出し、親コンテナーとして使用される新しい Figure オブジェクトを作成します。

オブジェクト ハンドルの可視性。'on''callback' または 'off' として指定します。

このプロパティは、オブジェクトの親がもつ子のリストにおけるそのオブジェクトの可視性を制御します。オブジェクトがその親オブジェクトのリストで、子として可視できない場合、オブジェクト階層の検索またはプロパティのクエリによってオブジェクトを取得する関数は、そのオブジェクトを返しません。これらの関数には、getfindobjclf および close が含まれます。オブジェクトは参照できない場合も有効です。オブジェクトにアクセスできる場合は、そのプロパティを設定および取得して、それをオブジェクトに作用する任意の関数に渡すことができます。

HandleVisibility の値説明
'on' オブジェクトは常に参照できます。
'callback'オブジェクトはコールバック内から、あるいはコールバックにより呼び出される関数から参照できます。しかし、コマンド ラインから呼び出される関数からは参照できません。このオプションを使用すると、コマンド ラインからのオブジェクトへのアクセスがブロックされますが、コールバック関数からのアクセスは許可されます。
'off'オブジェクトは常に参照できません。このオプションは、他の関数による UI の意図しない変更を防止するために役立ちます。HandleVisibility'off' に設定すると、その関数の実行中にオブジェクトが一時的に非表示になります。

識別子

すべて展開する

この プロパティ は読み取り専用です。

グラフィックス オブジェクトのタイプ。'uihtml' として返されます。

オブジェクト識別子。文字ベクトルまたは string スカラーとして指定します。オブジェクトの識別子として機能する一意の Tag 値を指定できます。コードの他の部分からオブジェクトにアクセスする必要がある場合、関数 findobj を使用して Tag 値に基づいてオブジェクトを検索できます。

ユーザー データ。任意の MATLAB 配列として指定します。たとえば、スカラー、ベクトル、行列、cell 配列、文字配列、table、または構造体を指定できます。このプロパティを使用して、任意のデータをオブジェクトに保存します。

App Designer を使用している場合は、UserData プロパティを使用する代わりに、アプリでパブリック プロパティまたはプライベート プロパティを作成してデータを共有します。詳細については、App Designer アプリ内でのデータの共有を参照してください。

バージョン履歴

R2019b で導入

すべて展開する