Main Content

本页的翻译已过时。点击此处可查看最新英文版本。

uitable

创建表用户界面组件

说明

uit = uitable 在当前图窗中创建表用户界面组件,并返回 Table UI 组件对象。如果没有可用的图窗,MATLAB® 将调用 figure 函数创建一个图窗。

uit = uitable(Name,Value) 使用一个或多个名称-值对组参数指定表 UI 组件的属性值。

示例

uit = uitable(parent) 在指定的父容器中创建表。父容器可以是使用 figureuifigure 函数创建的图窗,也可以是子容器(如面板)。uitable 的属性值略有不同,具体取决于该 App 是使用 figure 还是 uifigure 函数创建的。有关详细信息,请参阅名称-值对组参数

示例

uit = uitable(parent,Name,Value) 指定父容器和一个或多个属性值。

示例

全部折叠

从 R2018a 开始,您可以在表 UI 组件中显示 table 数组数据。(仅当表 UI 组件位于使用 uifigure 函数创建的图窗中时,才支持此类型的数据。App 设计工具使用此类型的图窗来创建 App。)

通过调用 readtable 函数从文件中读取数据来创建表数组 t。从 t 中选择四个变量和 15 个行。

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.

在表 UI 组件中显示并以编程方式更新 table 数组数据。(仅当表 UI 组件位于使用 uifigure 函数创建的图窗中时,才支持此类型的数据。App 设计工具使用此类型的图窗来创建 App。)

通过从文件中读入海啸数据来创建一个表数组,并在表 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 属性,更新第一行中发生海啸的可能性。

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.

创建一个 App,它允许用户对表数据进行排序和编辑,并在数据发生变化时更新数据可视化。(仅当表 UI 组件位于使用 uifigure 函数创建的图窗中时,才支持交互列排序。App 设计工具使用此类型的图窗来创建 App。)

首先,创建一个名为 tsunamisData.m 的程序文件。在该程序文件中:

  • 通过调用 readtable 函数创建一个 table 数组。

  • 创建一个 UI 图窗。

  • 创建一个可排序且可编辑的表 UI 组件以在图窗中显示。将 table 数组存储到该组件的 Data 属性中。

  • 创建一个气泡图来可视化海啸数据,其中气泡的坐标表示海啸的纬度和经度,气泡的大小表示海啸的最大高度。

  • 指定一个 DisplayDataChangedFcn 回调,当 App 用户在表 UI 组件中对列进行排序或编辑单元格时,该回调使用 DisplayData 属性更新气泡图。

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.

首先双击表单元格,然后输入新高度,将第二行中海啸的最大高度编辑为 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 开始,您可以使用 uistyleaddStyle 函数为表 UI 组件的行、列或单元格设置样式。(仅当表 UI 组件位于使用 uifigure 函数创建的图窗中时,才支持样式。App 设计工具使用此类型的图窗来创建 App。)

对表 UI 组件中包含缺失值的单元格设置样式。在本例中,为包含 NaN 值的单元格添加红色背景色样式。

将海啸示例数据作为表数组读入工作区中。然后,创建一个表 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 函数获取包含缺失值的表元素的逻辑数组。找到含有 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 开始,您可以通过编程方式设置和查询选择了哪些表元素,并指定用户是否可以选择单元格、行或列。(仅当表 UI 组件位于使用 uifigure 函数创建的图窗中时,才支持编程选择。App 设计工具使用此类型的图窗来创建 App。)

使用此功能,创建一个 App,当用户在表中选择数据时,该 App 会自动在地图上绘制该数据。首先,创建一个名为 selectTsunamis.m 的程序文件。在该程序文件中:

  • 通过调用 readtable 函数加载海啸数据。

  • 在面板中创建一个具有表 UI 组件和地理气泡图的 UI 图窗。

  • 配置表 UI 组件。将海啸数据存储在 Data 属性中,并让用户通过设置 SelectionTypeMultiSelect 属性来选择多行。

  • 指定一个 SelectionChangedFcn 回调,当 App 用户更改表选择时,该回调会更新气泡图。该函数为每个所选行绘制一个气泡,其中气泡的大小表示最大海啸高度。

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 组件的行、列或单元格。(仅当表 UI 组件位于使用 uifigure 函数创建的图窗中时,才支持编程滚动。App 设计工具使用此类型的图窗来创建 App。)

将样本患者数据以表数组形式读入工作区。然后,创建一个表 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. The table rows are numbered, and the table is scrolled to the top.

滚动到表的第二十五行。

scroll(uit,'row',25)

Table with patient data. The table is scrolled so that row 25 is the top of the visible data.

创建一个显示 10×3 随机整数数组的表 UI 组件。Data 属性指定要显示的值,Position 属性指定图窗内表的位置和大小。

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 属性以填充数据,构成一个包含不同类型的混合数据的元胞数组。然后设置 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 属性以将列标题更改为描述性名称。将 ColumnEditable 属性设置为 true,以便用户能够在 UI 中编辑数据。当用户在 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.

输入参数

全部折叠

父容器,指定为使用 figureuifigure 函数创建的图窗或子容器:

  • 面板、选项卡和按钮组可以是任一类型的图窗中的容器。

  • 网格布局是只能位于使用 uifigure 函数创建的图窗中的容器。

名称-值参数

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

指定可选的、以逗号分隔的 Name,Value 对组参数。Name 为参数名称,Value 为对应的值。Name 必须放在单引号 (' ') 中。您可以指定多个名称-值对组参数,如 Name1,Value1,...,NameN,ValueN

注意

此处所列的属性只是可用属性中的一部分。有关完整列表,请参阅 Table 属性

表数据,指定为以下类型的数组之一:

  • 表数组(仅限基于 uifigure 的 App)- 显示 table 数组支持的任意数据类型组合,例如 datetimedurationcategorical

  • 数值数组 - 显示数值,例如 doublesingle

  • 逻辑数组 - 显示复选框。true 值对应于选中复选框,而 false 值显示不选中复选框。

  • 元胞数组 - 显示数值、逻辑值或字符数组值的任意组合。

  • 字符串数组 - 显示字符和文本。

  • 字符向量元胞数组 - 显示字符和文本。

要避免用户在可编辑单元格中输入无效数据时显示警告或 NaN 值,可以编写一个 CellEditCallback 函数,将该数据转换为正确的类型。当用户编辑单元格时,Data 属性会更新。

指定表数组

在 App 设计工具中和使用 uifigure 函数创建的 App 中,您可以将 Data 属性指定为表数组。表数组为将表格数据存储为 MATLAB 变量提供了一种便捷方式。tablereadtablearray2table 函数用于创建表数组。而 uitable 函数用于创建 Table UI 组件(App 的用户界面组件)。

当您以表数组的形式指定 Table UI 组件的 Data 属性时,MATLAB 会自动基于表数组中的值设置 Table UI 组件的格式:

  • 默认情况下,App 中显示的列名称与表数组中的 VariableNames 属性匹配。更改 Table UI 组件的 ColumnName 属性会更新 UI,但不会更新表数组中的变量名称。

  • 默认情况下,App 中显示的行名称与表数组中的 RowName 属性匹配。更改 Table UI 组件的 RowName 属性会更新 UI,但不会更新表数组中的行名称。

  • 每个表数组变量的数据类型控制着 App 中相应列的格式。如果您尝试设置 ColumnFormat 属性,MATLAB 将返回警告。

有关显示表数组数据的详细信息,请参阅通过 App 设计工具创建的 App 中的表数组数据类型

指定数值数组、逻辑数组、元胞数组、字符串数组或字符向量元胞数组

使用 ColumnFormat 属性指定数据的格式,数据可以是数值数组、逻辑数组、元胞数组、字符串数组或字符向量元胞数组。如果编辑了数据并导致数据的数据类型与 ColumnFormat 属性不匹配,MATLAB 会转换数据或显示警告。有关详细信息,请参阅 ColumnFormat 属性说明中的可编辑列的日期显示

表列的宽度,指定为 'auto' 或指定为由字符向量、字符串和数值组成的 1×n 元胞数组。在基于 uifigure 的 App 中,您还可以将列宽指定为 '1x''fit'

  • 自动宽度 - 指定 'auto' 可让 MATLAB 使用多个因子自动计算列宽,其中一个因子是 ColumnName 属性值。

  • 根据内容调整宽度(仅限基于 uifigure 的 App)- 指定值 'fit' 可将列配置为严格调整宽度来适应列名称和数据。此设置允许比 'auto' 更窄的列。

  • 均匀宽度(仅限基于 uifigure 的 App)- 指定值 '1x' 可使所有列的宽度相同,平均分配可用空间。

  • 固定宽度 - 指定以像素为单位定义列宽的数值元胞数组。

  • 组合 - 可以在元胞数组中组合固定和可变列宽。元胞数组中的每一列对应于表中的一列。如果您指定的元胞数组中的值少于列数,则没有指定值的列将保留默认值 'auto'。如果数组中的值多于列数,MATLAB 会忽略多余的值。

  • 加权可变宽度(仅限基于 uifigure 的 App)- 指定包含字符向量或字符串的元胞数组,这些字符向量或字符串由一个数字与 'x' 串联而成(例如,'2x''3x' 等)。每列的 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])

编辑列单元格的功能,指定为:

  • 空逻辑数组 ([]) - 没有可编辑的列。

  • n 逻辑数组 - 该数组指定哪些列是可编辑的。n 的值等于表中的列数。数组中的每个值对应于一个表列。数组中的值 true 将使该列中的单元格可编辑。值 false 将使该列中的单元格不可编辑。如果数组中的值多于列数,MATLAB 会忽略多余的值。如果数组中的值少于列数,则没有指定值的列不可编辑。

  • 逻辑标量 - 整个表可编辑或不可编辑。

当用户编辑单元格时,Data 属性会更新。

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

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

要使用户能够与包含复选框或弹出式菜单的表列中的控件进行交互,请将 ColumnEditable 属性设置为 true

如果 Data 属性是一个表数组,则任何多列变量或包含不可编辑数据类型的变量,如 duration,在运行的 App 中都不可编辑,即使 ColumnEditable 属性是 true 也是如此。对于元胞数组中包含的混合数据类型的表数组变量,只要这些数据类型是可编辑的,则表数组变量在运行的 App 中也将是可编辑的。

单元格编辑回调函数,指定为下列值之一:

  • 函数句柄。

  • 第一个元素是函数句柄的元胞数组。元胞数组中的后续元素是传递到回调函数的参数。

  • 包含有效 MATLAB 表达式的字符向量(不推荐)。MATLAB 在基础工作区计算此表达式。

使用此回调函数可在 App 用户更改表单元格的内容时执行计算或验证输入。

此回调函数可以访问有关用户与单元格的交互的特定信息(例如单元格索引)。MATLAB 将 CellEditData 对象中的此信息作为第二个参数传递给回调函数。在 App 设计工具中,该参数名为 event。您可以使用圆点表示法查询对象属性。例如,event.Indices 返回所选单元格的索引。CellEditData 对象不可用于指定为字符向量的回调函数。

下表说明了 CellEditData 对象的属性。

属性

说明

Indices

这是一个 1×2 数组,包含用户在运行的 App 中编辑的单元格的行和列索引。对列进行排序时,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 设计工具中编写回调

表的位置和大小,指定为 [left bottom width height] 形式的四元素向量。此表介绍该向量中的每个元素。

元素说明
left父容器的内部左边缘与表的外部左边缘之间的距离
bottom父容器的内部下边缘与表的外部下边缘之间的距离
width表的左右外部边缘之间的距离
height表的上下外部边缘之间的距离

所有测量值都采用 Units 属性指定的单位。

Position 值相对于父容器的可绘制区域。可绘制区域是指容器边框内的区域,不包括装饰元素(如菜单栏或标题)所占的区域。

测量单位,指定为下表中的值之一。

单位值说明
'pixels'(默认值)

以像素为单位的距离不依赖 Windows®Macintosh 系统上的系统分辨率:

  • 在 Windows 系统上,一个像素是 1/96 英寸。

  • Macintosh 系统上,一个像素是 1/72 英寸。

在 Linux® 系统上,一个像素的大小由系统分辨率确定。

'normalized'

这些单位依据父容器进行归一化。容器的左下角映射到 (0,0),右上角映射到 (1,1)

'inches'英寸。
'centimeters'厘米。
'points'磅。1 磅等于 1/72 英寸。

推荐值为 'pixels',因为大多数 MATLAB App 构建功能以像素为单位测量距离。您可以创建一个表,该表根据父容器的大小重新缩放,方法是将使用 uigridlayout 函数创建的一个网格布局管理器作为该表的父级。有关详细信息,请参阅Lay Out Apps Programmatically

基于 figure 的 App

对于在使用 figure 函数创建的 App 中的表,Units 的默认值为 'normalized'

此外,您可以将 Units 指定为 'characters'。字符单元基于图形根对象的默认 uicontrol 字体:

  • 字符宽度 = 字母 x 的宽度。

  • 字符高度 = 两个文本行的基线之间的距离。

要访问默认的 uicontrol 字体,请使用 get(groot,'defaultuicontrolFontName')set(groot,'defaultuicontrolFontName')

版本历史记录

在 R2008a 中推出