Main Content

本页翻译不是最新的。点击此处可查看最新英文版本。

uitable

创建表用户界面组件

全页折叠

语法

uit = uitable
uit = uitable(parent)
uit = uitable(___,Name,Value)

说明

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

uit = uitable(parent) 在指定的父容器中创建一个表。父容器可以是使用 figure 或 uifigure 函数创建的图窗，也可以是子容器（如面板）。

uit = uitable(___,Name,Value) 使用一个或多个名称-值参量指定表属性。可将此选项与上述语法中的任何输入参量组合一起使用。表 UI 组件的属性值略有不同，具体取决于该 App 是使用 figure 还是 uifigure 函数创建的。

示例

示例

全部折叠

打开实时脚本

创建一个显示 10×3 随机整数数组的表 UI 组件。

fig = uifigure;
uit = uitable(fig,"Data",randi(100,10,3));

打开实时脚本

通过从文件中读取数据创建一个具有不同数据类型的表数组 t。从 t 中选择四个变量的前 15 行。

t = readtable("patients.xls");
vars = ["Age","Systolic","Diastolic","Smoker"];
t = t(1:15,vars);

创建一个表 UI 组件来显示表格数据。数据在组件中的显示方式由数据类型确定。例如，逻辑数据显示为复选框。有关详细信息，请参阅在 App 中格式化表格数据。

fig = uifigure;
uit = uitable(fig,"Data",t,"Position",[20 20 350 300]);

打开实时脚本

在表 UI 组件中显示并以编程方式更新数据。

通过从文件中读入海啸数据来创建一个表数组，并在表 UI 组件中显示部分数据。

t = readtable("tsunamis.xlsx");
vars = ["Year","MaxHeight","Validity"];
t = t(1:20,vars);
fig = uifigure;
uit = uitable(fig,"Data",t);

通过编辑表 UI 组件的 Data 属性，更新第一行中发生海啸的可能性。

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

通过访问和修改 MaxHeight 变量中的数据，将最大高度数据从米转换为英尺。

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

打开实时脚本

创建一个 App，它允许用户对表数据进行排序和编辑，并在数据发生变化时更新数据可视化。

在名为 tableDataApp.m 的文件中，编写实现该 App 的函数：

  • 创建一个包含海啸数据的 table 数组。

  • 用网格布局管理器创建一个 UI 图窗。

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

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

  • 当 App 用户通过编写 DisplayDataChangedFcn 回调在表 UI 组件中对列进行排序或编辑单元格时，会更新气泡图。有关回调的详细信息，请参阅Create Callbacks for Apps Created Programmatically。

function tableDataApp
% 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];
gl = uigridlayout(fig,[1 2]);

% Create table UI component
uit = uitable(gl);
uit.Data = t;
uit.ColumnSortable = true;
uit.ColumnEditable = [false false true];

% Create bubble chart
ax = geoaxes(gl);
lat = t.Latitude;
long = t.Longitude;
sz = t.MaxHeight;
bubblechart(ax,lat,long,sz)

% Specify table callback
uit.DisplayDataChangedFcn = @(src,event) updatePlot(src,ax);
end


function updatePlot(src,ax)
t = src.DisplayData;
lat = t.Latitude;
long = t.Longitude;
sz = t.MaxHeight;
bubblechart(ax,lat,long,sz)
end

运行 App。

tableDataApp

当您指向可排序的列时，该列会在标题中显示箭头。按海啸的最大高度对表进行排序。

tableDataApp that has a table UI component with tsunami data next to a geographic bubble chart of the tsunamis in the table. The MaxHeight column of the tsunami data table is sorted in ascending order. The mouse cursor is on the MaxHeight column header, where an arrow pointing up is displayed next to the header text.

通过双击表单元格然后输入新高度，将第二行中海啸的最大高度编辑为 30 米。气泡图会相应更新。

tableDataApp showing a selected cell in the MaxHeight column of the second row of the table, where the number 1 has been replaced with the number 30. The bubble chart bubble sizes have changed to reflect the new MaxHeight data.

使用 uistyle 和 addStyle 函数为表 UI 组件的行、列或单元格设置样式。仅当表 UI 组件位于使用 uifigure 函数创建的图窗中时，才支持样式。

将海啸示例数据作为表数组读入工作区中。然后，创建一个表 UI 组件来显示数据。

tdata = readtable("tsunamis.xlsx");
vars = ["Year","Month","Day","Hour", ...
    "Cause","EarthquakeMagnitude"];
tdata = tdata(1:20,vars);

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

使用 ismissing 函数获取包含缺失值的表元素的逻辑数组。找到含有 NaN 值的元素的行和列下标。最后，创建一个红色背景色样式并将它添加到表中包含 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.

打开实时脚本

创建一个 App，当 App 用户选择表中的数据时，该 App 会在地图上绘制该数据。

在名为 selectTsunamis.m 的文件中，编写实现该 App 的函数：

  • 加载海啸数据。

  • 在网格布局管理器中创建一个具有表 UI 组件和地理气泡图的 UI 图窗。

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

  • 指定一个 SelectionChangedFcn 回调，当 App 用户更改表选择时，该回调会更新气泡图。plotTsunami 回调函数为每个所选行绘制一个气泡，其中气泡的大小表示最大海啸高度。有关回调的详细信息，请参阅Create Callbacks for Apps Created Programmatically。

function selectTsunamis
% Load data
t = readtable("tsunamis.xlsx");
vars = ["Latitude","Longitude","MaxHeight"];
t = t(1:20,vars);

% Create UI components
fig = uifigure("Position",[100 100 800 350]);
gl = uigridlayout(fig,[1 2]);
gl.ColumnWidth = {'1x','2x'};
tbl = uitable(gl);
gb = geobubble(gl,[],[]);

% Configure table
tbl.Data = t;
tbl.SelectionType = "row";
tbl.Multiselect = "on";
tbl.SelectionChangedFcn = @(src,event) plotTsunami(src,event,gb);  
end

% Plot tsunami data for each selected row
function plotTsunami(src,event,gb)
rows = event.Selection;
data = src.Data(rows,:);
gb.LatitudeData = data.Latitude;
gb.LongitudeData = data.Longitude;
gb.SizeData = data.MaxHeight;
end

运行 App。

selectTsunamis

通过在点击时按住 Ctrl 键选择多个表行。该图会随所选海啸数据而更新。

自 R2021a 起

使用 scroll 函数以编程方式滚动到表 UI 组件的行、列或单元格。仅当表 UI 组件位于使用 uifigure 函数创建的图窗中时，才支持编程滚动。

将样本患者数据以表数组形式读入工作区。然后，创建一个表 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.

输入参数

全部折叠

父容器，指定为使用 figure 或 uifigure 函数创建的图窗，或图窗中的子容器，如面板、选项卡、按钮组或网格布局管理器。

名称-值参数

将可选的参量对组指定为 Name1=Value1,...,NameN=ValueN，其中 Name 是参量名称，Value 是对应的值。名称-值参量必须出现在其他参量之后，但参量对组的顺序无关紧要。

示例: uitable(Data=[1 2 3; 4 5 6]) 使用指定的数据创建一个表 UI 组件。

在 R2021a 之前，使用逗号分隔每个名称和值，并用引号将 Name 引起来。

示例: uitable("Data",[1 2 3; 4 5 6]) 使用指定的数据创建一个表 UI 组件。

注意

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

表数据，指定为以下类型的数组之一：

  • 表数组（仅限基于 uifigure 的 App）- 显示 table 数组支持的任意数据类型组合，例如 datetime、duration 和 categorical。

  • 数值数组 - 显示数值，例如 double 或 single。

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

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

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

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

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

指定表数组

在 App 设计工具中和使用 uifigure 函数创建的 App 中，您可以将 Data 属性指定为表数组。表数组为将表格数据存储为 MATLAB 变量提供了一种便捷方式。table、readtable 和 array2table 函数用于创建表数组。而 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 中格式化表格数据。

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

使用 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 表中的剩余空间。

如果用户在运行的 App 中以交互方式调整表列的大小，即使您稍后更新 ColumnWidth 属性，调整后的列宽仍会保留。

示例: 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])

编辑列单元格的功能，指定为：

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

  • 1×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 英寸。
'characters'

这些单位基于图形根对象的默认 uicontrol 字体：

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

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

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

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

版本历史记录

在 R2008a 中推出

全部展开

另请参阅

函数

属性

主题