Main Content

uitable

テーブルのユーザー インターフェイス コンポーネントの作成

説明

uit = uitable は、現在の Figure 内にテーブルのユーザー インターフェイス コンポーネントを作成し、Table UI コンポーネント オブジェクトを返します。利用可能な Figure がない場合は、MATLAB® が関数 figure を呼び出して Figure を作成します。

uit = uitable(Name,Value) は、1 つ以上の名前と値のペアの引数を使用して、テーブル UI コンポーネントのプロパティ値を指定します。

uit = uitable(parent) は、指定された親コンテナー内にテーブルを作成します。親コンテナーには、関数 figure または関数 uifigure で作成された Figure か、パネルなどの子コンテナーを指定できます。uitable のプロパティの値は、関数 figure で作成されたアプリと関数 uifigure で作成されたアプリで多少異なります。詳細については、名前と値のペアの引数を参照してください。

uit = uitable(parent,Name,Value) は、親コンテナーと 1 つ以上のプロパティ値を指定します。

すべて折りたたむ

R2018a 以降、table 配列データをテーブル UI コンポーネント内に表示できます。(この型のデータは、関数 uifigure で作成された Figure 内にテーブル UI コンポーネントがある場合にのみサポートされます。App Designer では、このタイプの Figure がアプリの作成に使用されます)。

ファイルからデータを読み取るために関数 readtable を呼び出すことで、table 配列 t を作成します。4 つの変数と 15 の行を t から選択します。

t = readtable('patients.xls');
vars = {'Age','Systolic','Diastolic','Smoker'};
t = t(1:15,vars);

テーブル UI コンポーネントを作成し、t をデータとして指定します。

fig = uifigure;
uit = uitable(fig,'Data',t);

A table with four columns: "Age", "Systolic", "Diastolic", and "Smoker". The table is populated with data. The data in the "Smoker" column appears as checked or unchecked boxes.

table 配列データをテーブル UI コンポーネントに表示し、プログラムで更新します (この型のデータは、関数 uifigure で作成された Figure 内にテーブル UI コンポーネントがある場合にのみサポートされます。App Designer では、このタイプの Figure がアプリの作成に使用されます)。

津波データをファイルから読み取って table 配列を作成し、データのサブセットをテーブル UI コンポーネントに表示します。

t = readtable('tsunamis.xlsx');
vars = {'Year','MaxHeight','Validity'};
t = t(1:20,vars);
fig = uifigure;
uit = uitable(fig,'Data',t);

A table with three columns of tsunami data: the year of the tsunami, the maximum tsunami height in meters, and the validity of the tsunami (for example, "questionable tsunami" or "definite tsunami").

UI テーブルの Data プロパティを編集して、1 行目の津波の有効性を更新します。

uit.Data.Validity(1) = {'definite tsunami'};

A table with tsunami year, maximum height, and validity. The entry in the first row has a Validity value of "definite tsunami".

MaxHeight 列のデータにアクセスして変更することで、最大の高さのデータをメートルからフィートに変換します。

uit.Data.MaxHeight = uit.Data.MaxHeight*3.281;

A table with tsunami year, max height, and validity. The values in the MaxHeight column are in feet.

ユーザーによるテーブル データの並べ替えと編集を許可し、データ変更時にデータの可視化を更新するアプリを作成します (対話式の列の並べ替えは、関数 uifigure で作成された Figure 内にテーブル UI コンポーネントがある場合にのみサポートされます。App Designer では、このタイプの Figure がアプリの作成に使用されます)。

まず、tsunamisData.m というプログラム ファイルを作成します。プログラム ファイル内で次を行います。

  • 関数 readtable を呼び出して table 配列を作成します。

  • UI figure を作成します。

  • Figure に表示する並べ替えと編集が可能なテーブル UI コンポーネントを作成します。table 配列をコンポーネントの Data プロパティに格納します。

  • バブルの座標が津波の緯度と経度を表し、バブルのサイズが最大の高さを表すバブル チャートを作成して津波データを可視化します。

  • アプリ ユーザーがテーブル UI コンポーネントで列の並べ替えやセルの編集を行ったときに DisplayData プロパティを使用してバブル チャートを更新する、DisplayDataChangedFcn コールバックを指定します。

function tsunamisData
    % Create table array
    t = readtable('tsunamis.xlsx');
    vars = {'Latitude','Longitude','MaxHeight'};
    t = t(1:20,vars);

    % Create UI figure
    fig = uifigure;
    fig.Position(3:4) = [722 360];

    % Create table UI component
    uit = uitable(fig);
    uit.Data = t;
    uit.ColumnSortable = true;
    uit.ColumnEditable = [false false true];
    uit.Position(3) = 290;
    uit.DisplayDataChangedFcn = @updatePlot;

    % Create bubble chart
    ax = uiaxes(fig);
    ax.Position(1) = 315;
    ax.XLabel.String = 'Longitude';
    ax.YLabel.String = 'Latitude';
    x = t.Longitude;
    y = t.Latitude;
    sz = t.MaxHeight;
    bubblechart(ax,x,y,sz)

        % Update the bubble chart when table data changes
        function updatePlot(src,event)
            t = uit.DisplayData;
            x = t.Longitude;
            y = t.Latitude;
            sz = t.MaxHeight;
            bubblechart(ax,x,y,sz)
        end

end

An app with a table displaying the Latitude, Longitude, and MaxHeight data for a number of tsunamis, and a bubble chart of the table data. The bubble chart plots the location of the tsunamis with Longitude on the x-axis, Latitude on the y-axis, and bubble size given by MaxHeight.

並べ替え可能な列は、マウスのカーソルを合わせるとヘッダーに矢印が表示されます。テーブルを津波の最大の高さで並べ替えます。

The MaxHeight column of the tsunami data table is sorted in ascending order. The user's mouse cursor is on the MaxHeight column header, where an arrow pointing up is displayed next to the header text.

テーブルのセルをダブルクリックしてから新しい高さを入力することで、2 行目の津波の最大の高さを編集して 30 メートルにします。これに応答してバブル チャートがどのように更新されるかに注目してください。

The cell in the second row and the MaxHeight column is selected, and the number 1 has been replaced with the number 30. The bubble chart bubble sizes have changed to reflect the new MaxHeight data.

R2019b 以降、関数 uistyle および関数 addStyle を使用して、テーブル UI コンポーネントの行、列、またはセルにスタイルを追加できます (スタイルは、関数 uifigure を使用して作成された Figure 内にテーブル UI コンポーネントがある場合にのみサポートされます。App Designer では、このタイプの Figure がアプリの作成に使用されます)。

テーブル UI コンポーネント内の欠損値を含むセルのスタイルを設定します。この場合は、NaN 値をもつセルに赤の背景色スタイルを追加します。

津波のサンプル データを table 配列としてワークスペースに読み取ります。次に、データを表示するテーブル UI コンポーネントを作成します。

tdata = readtable('tsunamis.xlsx');
vars = {'Year','Month','Day','Hour', ...
        'MaxHeight','Cause','EarthquakeMagnitude'};
tdata = tdata(1:100,vars);

fig = uifigure('Position',[500 500 760 360]);
uit = uitable(fig);
uit.Position = [20 20 720 320];
uit.Data = tdata;
uit.RowName = 'numbered';

関数 ismissing を使用して、欠損値を含むテーブル要素の logical 配列を取得します。NaN 値をもつ要素の行と列の添字を見つけます。最後に、赤の背景色スタイルを作成し、テーブル UI コンポーネントの NaN 値をもつセルに追加します。

styleIndices = ismissing(tdata);
[row,col] = find(styleIndices);

s = uistyle('BackgroundColor',[1 0.6 0.6]);
addStyle(uit,s,'cell',[row,col]);

Table with earthquake data. The cells with NaN are highlighted in red.

R2021b 以降では、選択されているテーブル要素をプログラムで設定してクエリでき、ユーザーがセル、行または列を選択できるかどうかを指定できます (プログラムによる選択は、関数 uifigure を使用して作成された Figure 内にテーブル UI コンポーネントがある場合にのみサポートされます。App Designer では、このタイプの Figure がアプリの作成に使用されます)。

この機能を使用して、ユーザーがテーブル内のデータを選択するとそのデータをマップ上に自動的にプロットするアプリを作成します。まず、selectTsunamis.m というプログラム ファイルを作成します。プログラム ファイル内で次を行います。

  • 関数 readtable を呼び出して津波データを読み込みます。

  • パネル内にテーブル UI コンポーネントと地理バブル チャートがある UI figure を作成します。

  • テーブル UI コンポーネントを構成します。津波データを Data プロパティに格納し、SelectionType プロパティと MultiSelect プロパティを設定することによってユーザーが複数の行を選択できるようにします。

  • アプリ ユーザーがテーブル選択を変更したときにバブル チャートを更新する、SelectionChangedFcn コールバックを指定します。この関数は、バブルのサイズが津波の最大の高さを表す各選択行のバブルをプロットします。

function selectTsunamis
% Load data
T = readtable('tsunamis.xlsx');
vars = {'Latitude','Longitude','MaxHeight'};
T = T(1:20,vars);

% Create UI components
fig = uifigure('Position',[500 500 700 350]);
tbl = uitable(fig,'Position',[20 20 250 300]);
pnl = uipanel(fig,'Position',[285 20 400 300]);
geobubble(pnl,[],[]);

% Configure table
tbl.Data = T;
tbl.SelectionType = 'row';
tbl.Multiselect = 'on';
tbl.SelectionChangedFcn = @plotTsunami;

  % Plot tsunami data for each selected row
  function plotTsunami(src,event)
    rows = event.Selection;
    data = src.Data(rows,:);
    lat = data.Latitude;
    long = data.Longitude;
    ht = data.MaxHeight;
    geobubble(pnl,lat,long,ht);
  end
end

関数 selectTsunamis を実行し、Ctrl キーを押したまま複数のテーブル行をクリックして選択します。プロットが津波データで更新されます。

Figure window with a table and a geographic bubble chart. Multiple table rows are selected.

R2021a 以降、関数 scroll を使用して、テーブル UI コンポーネントの行、列、またはセルにプログラムでスクロールできます (プログラムによるスクロールは、関数 uifigure を使用して作成された Figure 内にテーブル UI コンポーネントがある場合にのみサポートされます。App Designer では、このタイプの Figure がアプリの作成に使用されます)。

サンプルの患者データを table 配列としてワークスペースに読み取ります。次に、データを表示するテーブル UI コンポーネントを作成します。

tdata = readtable('patients.xls');
vars = {'Age','Systolic','Diastolic','Smoker'};
tdata = tdata(1:40,vars);

fig = uifigure;
uit = uitable(fig,'Data',tdata);
uit.RowName = 'numbered';

Table with patient data in a UI figure window. The table rows are numbered, and the table is scrolled to the top.

テーブルの 25 行目にスクロールします。

scroll(uit,'row',25)

Table with patient data in a UI figure window. The table is scrolled so that row 25 is at the top of the visible data.

ランダムな整数からなる 3 行 10 列の配列を表示するテーブル UI コンポーネントを作成します。Data プロパティが表示対象の値を指定し、Position プロパティが Figure 内のテーブルの位置とサイズを指定します。

f = figure;
uit = uitable(f,'Data',randi(100,10,3),'Position',[20 20 262 204]);

Table with ten rows and three columns of numerical data.

テーブル UI コンポーネントには、異なるデータ型を複数列にわたって混在させて格納することができます。

空の Table UI コンポーネントを作成します。

f = figure;
uit = uitable(f);

Data プロパティの設定により、異なるデータ型が混在して含まれる cell 配列としてデータを格納します。その後、Position プロパティを設定して、データに合わせて位置とサイズを調整します。

d = {'Male',52,true;'Male',40,true;'Female',25,false};
uit.Data = d;
uit.Position = [20 20 258 78];

Table with three rows and three columns. The first column contains text, the second column contains numerical data, and the third column contains check boxes. The check boxes in the first and second rows are selected.

ColumnName プロパティを設定して、列見出しを説明的な名前に変更します。ユーザーが UI 内のデータを編集できるように、ColumnEditable プロパティを true に設定します。ユーザーが UI 内の値を変更すると、Data プロパティはその変更を反映して更新されます。

uit.ColumnName = {'Gender','Age','Authorized'};
uit.ColumnEditable = true;

Table with three rows and three columns. Each column has a column name above the data.

入力引数

すべて折りたたむ

親コンテナー。関数 figure または関数 uifigure で作成された Figure か、子コンテナーとして指定します。

  • パネル、タブ、およびボタン グループは、いずれのタイプの Figure でもコンテナーとすることができる。

  • グリッド レイアウトは、関数 uifigure で作成された Figure 内でのみコンテナーとすることができる。

名前と値の引数

例: uitable(fig,'Data',[1 2 3; 4 5 6])

オプションの Name,Value の引数ペアをコンマ区切りで指定します。Name は引数名で、Value は対応する値です。Name は一重引用符 (' ') で囲まなければなりません。Name1,Value1,...,NameN,ValueN のように、複数の名前と値のペアの引数を指定できます。

メモ

以下にリストするプロパティは、利用できるプロパティの一部です。完全なリストについては、Table のプロパティ を参照してください。

テーブル データ。次のいずれかのタイプの配列として指定します。

  • table 配列 (uifigure ベースのアプリのみ) — datetimedurationcategorical などの table 配列でサポートするデータ型の組み合わせを表示します。

  • 数値配列 — doublesingle などの数値を表示します。

  • logical 配列 — チェック ボックスを表示します。true 値はオンのボックスを示し、false 値はオフのボックスを示します。

  • cell 配列 — 数値配列値、logical 配列値または文字配列値の任意の組み合わせを表示します。

  • string 配列 — 文字とテキストを表示します。

  • 文字ベクトルの cell 配列 — 文字およびテキストを表示します。

ユーザーが編集可能なセルに無効なデータを入力したときに警告または NaN 値が表示されないようにするには、関数 CellEditCallback を記述してデータを適切な型に変換します。ユーザーがセルを編集すると、Data プロパティが更新されます。

table 配列の指定

App Designer 内および関数 uifigure を使用して作成されたアプリ内では、Data プロパティを table 配列として指定できます。table 配列を使用すると、テーブル データを変数 MATLAB として簡単に格納できます。table 配列を作成するのは、関数 table、関数 readtable、および関数 array2table です。一方、関数 uitable は、Table UI コンポーネント (アプリのユーザー インターフェイス コンポーネント) を作成します。

Table UI コンポーネントの Data プロパティを table 配列として指定すると、MATLAB では、次のように table 配列の値に基づいて Table UI コンポーネントの形式が自動的に設定されます。

  • 既定では、アプリに表示される列名は、table 配列の VariableNames プロパティと一致します。Table UI コンポーネントの ColumnName プロパティを変更すると UI が更新されますが、table 配列の変数名は更新されません。

  • 既定では、アプリに表示される行名は、table 配列の RowName プロパティと一致します。Table UI コンポーネントの RowName プロパティを変更すると UI が更新されますが、table 配列の行名は更新されません。

  • 各 table 配列変数のデータ型は、アプリ内の対応する列の形式を制御します。ColumnFormat プロパティを設定しようとすると、MATLAB は警告を返します。

table 配列データの表示の詳細については、App Designer アプリの table 配列データ型を参照してください。

数値配列、logical 配列、cell 配列、string 配列、または文字ベクトルの cell 配列の指定

ColumnFormat プロパティを使用して、数値配列、logical 配列、cell 配列、string 配列、または文字ベクトルの cell 配列であるデータの形式を指定します。データを編集した結果、データのデータ型と ColumnFormat プロパティの値で不一致が生じた場合、MATLAB はデータを変換するか、警告を表示します。詳細については、編集可能な列のデータ表示ColumnFormat プロパティの説明を参照してください。

テーブル列の幅。'auto'、または 1n 列の文字ベクトル、string、および数値の cell 配列として指定します。uifigure ベースのアプリでは、列幅を '1x' または 'fit' として追加で指定できます。

  • 自動設定幅 — 'auto' を指定して、MATLAB が複数の要素を使用して自動的に列の幅を計算するようにします。その 1 つは ColumnName プロパティ値です。

  • 幅を内容に合わせる (uifigure ベースのアプリのみ) — 'fit' の値を指定して、列の幅を列名とデータに合わせるように厳密に調整するよう列を設定します。この設定では 'auto' よりも狭い幅の列が許容されます。

  • 一様な幅 (uifigure ベースのアプリのみ) — '1x' の値を指定して、使用できるスペースを等分してすべての列が同じ幅になるようにします。

  • 固定幅 — 列の幅をピクセル単位で定義する数値の cell 配列を指定します。

  • 組み合わせ — cell 配列内で固定と可変の列幅を組み合わせることができます。cell 配列内の各要素はテーブル内の列に対応します。指定した cell 配列の値が列数よりも少ない場合、値が指定されていない列は既定値の 'auto' のままになります。配列の値が列数よりも多い場合、MATLAB は余分な値を無視します。

  • 重み付けされた可変幅 (uifigure ベースのアプリのみ) — 'x' に連結された数字から成る文字ベクトルまたは string ('2x''3x' など) をもつ cell 配列を指定します。それぞれの列の x 係数がその列の幅を、他の列に対する比率として設定します (UI テーブルの残りのスペースを考慮します)。

例: uit = uitable(uifigure,'ColumnWidth','auto','Data',[1 2 3;4 5 6])

例: uit = uitable(uifigure,'ColumnWidth','fit','Data',[1 2 3;4 5 6])

例: uit = uitable(uifigure,'ColumnWidth',{64,60,40},'Data',[1 2 3;4 5 6])

例: uit = uitable(uifigure,'ColumnWidth',{'2x','1x','1x'},'Data',[1 2 3;4 5 6])

例: uit = uitable(uifigure,'ColumnWidth',{64,"auto",40},'Data',[1 2 3;4 5 6])

例: uit = uitable(uifigure,'ColumnWidth',{'fit','1x','3x'},'Data',[1 2 3;4 5 6])

列セルを編集する機能。以下として指定します。

  • 空の logical 配列 ([]) — 列は編集できません。

  • 1 行 n 列の logical 配列 — この配列は編集可能な列を指定します。n の値はテーブル内の列の数と等しくなります。配列内の各値はテーブルの列に対応します。配列の値が true の場合、その列のセルが編集可能になります。値が false の場合、その列内のセルが編集不可になります。配列の値が列数よりも多い場合、MATLAB は余った値を無視します。配列の値が列数よりも少ない場合、値が指定されていない列は編集不可になります。

  • logical スカラー — テーブル全体が編集可能または編集不可のいずれかになります。

ユーザーがセルを編集すると、Data プロパティが更新されます。

例: uit = uitable(uifigure,'Data',rand(10,3),'ColumnEditable',[false true true])

例: uit = uitable(uifigure,'Data',rand(10,3),'ColumnEditable',false)

チェック ボックスやポップアップ メニューを含むテーブルの列でユーザーがコントロールを操作できるようにするには、ColumnEditable プロパティを true に設定します。

Data プロパティが table 配列である場合、duration など複数列の変数または編集不可のデータ型を含む変数は、ColumnEditable プロパティが true であっても、実行中のアプリで編集できません。cell 配列内に混在するデータ型を含む table 配列変数は、データ型が編集可能であれば実行中のアプリで編集できます。

セル編集コールバック関数。次の値のいずれかとして指定します。

  • 関数ハンドル。

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

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

このコールバック関数を使用して、アプリ ユーザーがテーブル セルのコンテンツを変更したときの計算や入力の検証を実行できます。

このコールバック関数は、ユーザーのセルの操作に関する特定の情報 (セルのインデックスなど) にアクセスできます。MATLAB は、この情報を CellEditData オブジェクトに格納して、2 番目の引数としてコールバック関数に渡します。App Designer では、引数は event と呼ばれます。ドット表記を使用して、オブジェクトのプロパティをクエリできます。たとえば、event.Indices は選択されたセルのインデックスを返します。CellEditData オブジェクトは、文字ベクトルとして指定されているコールバック関数では使用できません。

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

プロパティ

説明

Indices

これは、実行中のアプリでユーザーが編集したセルの行および列のインデックスを含む 1 行 2 列の配列です。列が並べ替えられている場合、Indices は並べ替え前の元の 1 行 2 列のセルの配列を返し、DisplayIndices は並べ替え後のテーブルにおける編集されたセルの新しい表示位置を返します。

DisplayIndices

これは並べ替え後のテーブルにおける編集されたセルの表示位置に対応する行および列のインデックスを含む 1 行 2 列の配列です。ユーザーが列を並べ替えていない場合、DisplayIndices の内容は Indices プロパティと同じになります。

PreviousData

これは前のセル データです。既定の設定は、空行列 [] です。

EditData

これはユーザーが入力した値です。

NewData

これは、MATLAB がプロパティ配列 Data に書き込んだ値です。

MATLAB がユーザー入力データでエラーを検出した場合、NewData プロパティは空です。

Error

これは、MATLAB がユーザー入力データでエラーを検出した場合に返されるエラー メッセージです。

MATLAB が Data プロパティに値を正常に書き込んだ場合、Error プロパティは空です。

Error プロパティが空でない場合、CellEditCallback はメッセージを表示するか、問題の修正を試行することができます。

Source

コールバックを実行するコンポーネント。

EventName

'CellEdit'.

ユーザーがテーブルのセルを編集すると、MATLAB は以下の手順を実行します。

  1. 新しい値をテーブルの Data プロパティに保存しようとします。

  2. 関数 CellEditCallback (存在する場合) を呼び出します。

値が結果としてエラーになり、関数 CellEditCallback が存在しない場合、セル データは以前の値に戻され、エラーは表示されません。

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

テーブルの位置とサイズ。[left bottom width height] の形式の 4 要素ベクトルとして指定します。次の表で、ベクトルの各要素について説明します。

要素説明
left親コンテナーの内側左端からテーブルの外側左端までの距離
bottom親コンテナーの内側下端からテーブルの外側下端までの距離
widthテーブルの外側の右端と左端の間の距離
heightテーブルの外側の上端と下端の間の距離

すべての測定値は、Units プロパティで指定した単位で表されます。

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

測定の単位。次の表のいずれかの値として指定します。

単位の値説明
'pixels' (既定)

Windows® および Macintosh システムでのピクセル単位の距離は、システムの解像度に依存しません。

  • Windows システムの 1 ピクセルは 1/96 インチです。

  • Macintosh システムの 1 ピクセルは 1/72 インチです。

Linux® システムでは、ピクセルのサイズは使用しているシステムの解像度によって決まります。

'normalized'

これらの単位は親コンテナーを基準として正規化されます。コンテナーの左下隅が (0,0) で、右上隅が (1,1) になります。

'inches'インチ。
'centimeters'センチメートル。
'points'ポイント。1 ポイントは 1/72 インチです。

MATLAB のほとんどのアプリ作成機能では距離をピクセル単位で測定するため、推奨値は 'pixels' です。親コンテナーのサイズに基づいて再スケーリングされるテーブルを作成するには、関数 uigridlayout を使用して作成されたグリッド レイアウト マネージャーをテーブルの親にします。詳細については、Lay Out Apps Programmaticallyを参照してください。

figure ベースのアプリ

関数 figure を使用して作成されたアプリ内のテーブルの場合、Units の既定値は 'normalized' です。

また、Units として 'characters' を指定できます。文字単位は、グラフィックス ルート オブジェクトの既定の uicontrol フォントを基にしています。

  • 文字の幅 = 文字 x の幅。

  • 文字の高さ = 2 行のテキストのベースライン間の距離。

既定の uicontrol フォントにアクセスするには、get(groot,'defaultuicontrolFontName') または set(groot,'defaultuicontrolFontName') を使用します。

バージョン履歴

R2008a で導入

すべて展開する