Main Content

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

Table 属性

控制基于 uifigure 的 App 中表 UI 组件的外观和行为

表 UI 组件在 App 中显示数据的行和列。uitable 函数创建一个表 UI 组件并在显示前为其设置所有必需的属性。通过更改 Table 对象的属性值,您可以对其外观和行为进行某些方面的修改。使用圆点表示法引用特定的对象和属性。

fig = uifigure;
uit = uitable(fig,'Data',[1 2 3; 4 5 6; 7 8 9]);
uit.FontSize = 10;

此处列出的属性对于 App 设计工具中的或使用 uifigure 函数创建的 App 中的表 UI 组件有效。对于在 GUIDE 中使用的或在使用 figure 函数创建的 App 中使用的表 UI 组件,请参阅 Table 属性

全部展开

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

  • 表数组 - 显示 table 数组支持的任意数据类型组合,例如 datetimedurationcategorical

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

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

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

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

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

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

指定表数组

表数组为将表格数据存储为 MATLAB® 变量提供了一种便捷方式。tablereadtablearray2table 函数用于创建表数组。而 uitable 函数用于创建 Table UI 组件(App 的用户界面组件)。

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

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

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

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

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

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

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

此属性为只读

当前显示中的表数据,返回为表、数值数组、逻辑数组、元胞数组、字符串数组或字符向量元胞数组。

如果要根据用户是否对表中的列进行过排序或对单元格进行过编辑来更新可视化效果,请使用此属性。

DisplayData 在表列经过排序或单元格经过编辑时更新。如果用户未对列进行排序,则 DisplayData 的内容与存储在 Data 属性中的值相同。当用户编辑单元格时,DataDisplayData 属性都会更新。

列名称,指定为下列值之一:

  • 'numbered' - 列标题是从 1 开始的有序数字。

  • 字符向量元胞数组或分类数组 - 数组的每个元素都变为列名。如果您指定 1×n 元胞数组,MATLAB 将存储该值并以 n×1 元胞数组形式返回该值。如果您指定 m×n 数组,MATLAB 将数组重构为列向量。通过在列名称中包含一个竖线 (|) 来指定多行列名称。例如,值 'Telephone|Number' 生成一个在单词“Telephone”和“Number”之间有一个换行符的列标题。

  • 空元胞数组 ({}) - 表没有任何列标题。

  • 空矩阵 ([]) - 表没有任何列标题。

如果 Data 属性数组中的列数与 ColumnName 数组中的元素数不匹配,则生成表中的列数是这两个值中的较大者。

如果将 Data 属性指定为表数组,则默认列名称与表数组的 VariableNames 属性匹配。更改 Table UI 组件的 ColumnName 属性将更新 UI,但不会更新表数组中的变量名称。

示例: uit = uitable(uifigure,'ColumnName',{'Name';'Number'},'Data',{'Bob',5})

示例: uit = uitable(uifigure,'ColumnName',{'Name';[]},'Data',{'Bob',5})

表列的宽度,指定为 'auto''fit''1x',或指定为由字符向量、字符串和数值组成的 1×n 元胞数组。

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

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

  • 均匀宽度 - 指定值 '1x' 可使所有列的宽度相同,平均分配可用空间。

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

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

  • 加权可变宽度 - 指定包含字符向量或字符串的元胞数组,这些字符向量或字符串由一个数字与 'x' 串联而成(例如,'2x''3x' 等)。每列的 x 因子相对于其他列按比例设置该列的宽度,同时考虑 uitable 中的剩余空间。

示例: 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 中也将是可编辑的。

对列进行排序的能力,指定为:

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

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

  • 逻辑标量 - 整个表可排序 (true) 或不可排序 (false)。

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

示例: uit = uitable(uifigure,'Data',rand(5),'ColumnSortable',true);

如果 Data 属性包含元胞数组数据或具有元胞数组列的表数组数据,则只有具有一致数据类型的数值/字符数组列或字符向量元胞数组列才能在运行的 App 中排序。即使 ColumnSortable 属性为 true,具有一致的逻辑数据类型或不一致数据类型的元胞数组列也无法在运行的 App 中排序。

单元格显示格式,指定为空元胞数组或 1×n 字符向量元胞数组。

Data 属性包含 table 数组时,请不要设置此属性。有关详细信息,请参阅通过 App 设计工具创建的 App 中的表数组数据类型

此属性设置数值数组、逻辑数组、元胞数组、字符串数组和字符向量元胞数组数据类型的显示格式。元胞数组的元素对应于 Data 属性数组中的列。如果您不希望指定特定列的显示格式,请为该列指定 []。如果不指定列的格式,则 MATLAB 根据单元格中数据的类型确定默认显示方式。

元胞数组的元素必须是下表中描述的值之一。

单元格格式值

说明

'char'

显示左对齐值。如果 Data 属性数组中的元素是逻辑值,则 truefalse 显示在表中。

要编辑单元格,用户可键入文本以替换现有值。

'logical'

显示居中对齐的复选框。最初,当对应的 Data 值计算为 true 时选中一个复选框。Data 属性数组中的对应值的类型必须为 logical 以确保数据正确显示在表中。

要编辑单元格,用户可选中或清除复选框。然后,MATLAB 将相应的 Data 值设置为 truefalseColumnEditable 属性值必须为 true,才能允许用户选中或清除复选框。

'numeric'

显示与数值数据的命令行窗口显示等效的右对齐值。如果 Data 属性数组中的元素是逻辑值,则 10 显示在表中。如果 Data 属性数组中的元素既非数值也非逻辑值,则 NaN 显示在表中。

要编辑单元格,用户可以输入任何文本。

如果用户输入表示常量(如 pi)的文本,您可以对 CellEditCallback 函数进行编码以将该值转换为等同的数值。在此情况下,MATLAB 先尝试将用户输入的文本转换为数值,并将其存储在 Data 属性中。随后将执行 CellEditCallback 函数。有关示例,请参阅 CellEditCallback 说明。

n 字符向量元胞数组,如 {'one','two','three'}

在可编辑列中显示弹出式菜单。无论 ColumnEditable 属性设置为 true 还是 false,该值都显示为左对齐。

要编辑元胞,用户可从弹出式菜单中选择一个项目,或输入文本以创建一个新项目。MATLAB 会将对应的 Data 属性数组值设置为选定的菜单项。ColumnEditable 属性值必须为 true,才能允许用户选择弹出式菜单中的项目。

format 函数接受的格式名称,例如:'short''long'

使用指定格式显示 Data 属性值。值显示为右对齐。

弹出式菜单 ColumnFormat 和各种数据类型的效果

如果 ColumnFormat 值定义弹出式菜单,则初始 Data 值不必是该菜单中的选项之一。初始 Data 值将一直显示,直到用户进行不同的选择。

例如,假设给定列的 Data 属性值对于所有行都是 'Choose',并且 ColumnFormat 值指定具有选项 'group 1''group 2' 的弹出式菜单。当 MATLAB 创建表时,这些表单元格会显示 'Choose',直到用户选择弹出式菜单中的某个项为止:

fig = uifigure;
myData = {'Andrew' 31 'Male' 'Choose'; ...
    'Bob' 41 'Male' 'Choose';  ...
    'Anne' 20 'Female' 'Choose';};
uit = uitable('Parent', fig, ...
    'Position', [100 150 380 100], ...
    'ColumnFormat',({[] [] [] {'group 1' 'group 2'}}), ...
    'ColumnEditable',true, ...
    'Data',myData);

可编辑列的日期显示

此表介绍各种数据类型如何显示特定 ColumnFormat 值。

 ColumnFormat
'numeric''char''logical'
数据数组值的数据类型任意数值类型表按原样显示数字。MATLAB 将值转换为文本并使其在表中左对齐显示。如果 MATLAB 不能转换该值,则显示 NaN不推荐。MATLAB 可能在用户编辑单元格时返回警告,除非您定义 CellEditCallback 函数。
char表按右对齐显示值,就像数字一样。表按原样显示值。不推荐。MATLAB 可能在用户编辑单元格时返回警告,除非您定义 CellEditCallback 函数。
logical表以数字形式显示逻辑值。MATLAB 可能在用户编辑单元格时返回警告,除非您定义 CellEditCallback 函数。表显示左对齐的 'true''false' 形式的逻辑值。除非您定义了 CellEditCallback 函数,否则 MATLAB 可能在您编辑单元格时返回警告。表显示复选框形式的逻辑值。

行名称,指定为下列值之一:

  • 'numbered' - 行标题是从 1 开始的有序数字。

  • 字符向量元胞数组或分类数组 - 数组的每个元素都变为行名。行名限制为单行文本。如果您指定 1×n 元胞数组,MATLAB 将存储该值并以 n×1 元胞数组形式返回该值。如果您指定 m×n 数组,MATLAB 将数组重构为列向量。

  • 空元胞数组 ({}) - 表没有任何行标题。

  • 空矩阵 ([]) - 表没有任何行标题。

如果 Data 属性数组中的行数与 RowName 数组中的元素数不匹配,则生成的表中的行数反映 Data 属性中的行数。

如果将 Data 属性指定为表数组,则默认行名称与表数组的 RowNames 属性匹配。更改表 UI 组件的 RowName 属性将更新 UI,但不会更新表数组中的行名称。

示例: uit = uitable(uifigure,'RowName',{'Name';'Number'},'Data',{'Bob';5})

示例: uit = uitable(uifigure,'RowName',{'Name';[]},'Data',{'Bob';5})

此属性为只读

所添加样式的配置,以 n×3 表数组形式返回。表数组的每一行对应于当前应用于表 UI 组件的一个样式。对连续添加的样式赋予 n+1 的样式顺序号。TargetTargetIndex 列指定样式所添加到的表 UI 组件部分。Style 列指定样式类名。

如果要使用 removeStyle 函数从表 UI 组件中删除样式,请使用此属性。例如,在此示例中,将三个样式添加到了一个表 UI 组件中。

s1 = uistyle('BackgroundColor','yellow');
s2 = uistyle('BackgroundColor','red');
s3 = uistyle('FontColor','b','FontWeight','bold');

fig = uifigure;
fig.Position = [100 100 520 220];
uit = uitable(fig);
uit.Data = rand(5);
uit.Position = [20 30 480 135];

addStyle(uit,s1,'row',[1 2 4 5]);
addStyle(uit,s2,'cell',[2 1; 4 2; 1 3; 1 5])
addStyle(uit,s3,'column',2);

当您查询 uit.StyleConfigurations 时,将返回一个 3×3 表数组。行样式首先添加到表 UI 组件中,因此它具有样式顺序号 1。行样式的 TargetIndex{1×4 double} 表示添加该样式时指定了四行。类似地,第二个样式添加到了表中的四个单元格中。第三个样式添加到了第二列。

uit.StyleConfigurations
ans =

  3×3 table

         Target    TargetIndex                Style           
         ______    ____________    ___________________________

    1    row       {1×4 double}    [1×1 matlab.ui.style.Style]
    2    cell      {4×2 double}    [1×1 matlab.ui.style.Style]
    3    column    {[       2]}    [1×1 matlab.ui.style.Style]

通过指定样式顺序号 2 删除添加到表中的第二个样式。请注意表 UI 组件是如何更新的。

removeStyle(uit,2)

字体

全部展开

字体名称,指定为系统支持的一种字体名称。默认字体取决于具体操作系统和区域设置。

如果指定的字体不可用,MATLAB 将使用运行 App 的系统上的可用字体中的最佳匹配项。

字体大小,指定为正数。测量单位为像素。默认字体大小取决于具体操作系统和区域设置。

示例: 14

字体粗细,指定为下列值之一:

  • 'normal' - 特定字体定义的默认粗细

  • 'bold' - 字符轮廓比 'normal'

并非所有字体都有加粗字体。对于非加粗字体,指定 'bold' 会得到普通字体。

字体角度,指定为 'normal''italic'。并非所有字体都有倾斜字体角度。对于无斜体字体,指定 'italic' 后会使用常规字体角度。

字体大小单位,指定为 'pixels'

交互性

全部展开

可见性状态,指定为 'on''off',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true'off' 等效于 false。因此,您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

  • 'on' - 显示对象。

  • 'off' - 隐藏对象而不删除它。您仍然可以访问不可见 UI 组件的属性。

要使您的 App 更快地启动,请将不需要在启动时出现的所有 UI 组件的 Visible 属性设置为 'off'

表的工作状态,指定为 'on''off'Enable 属性控制 UI 组件是否响应按钮点击。有两个可能的值:

  • 'on' - UI 组件处于工作状态。

  • 'off' - UI 组件未处于工作状态,并且呈灰显。

Enable 属性的值和按钮点击的类型共同确定 UI 的响应方式。

启用值响应左键点击响应右键点击
'on'

执行 CellSelectionCallback 函数(仅适用于表单元格,不适用于标题单元格)。Indices 属性在 MATLAB 传递给回调函数的回调数据对象中更新。

  1. 执行图窗的 WindowButtonDownFcn 回调。

  2. 执行 ButtonDownFcn 回调。

'off'

  1. 执行图窗的 WindowButtonDownFcn 回调。

  2. 执行 ButtonDownFcn 回调。

  1. 执行图窗的 WindowButtonDownFcn 回调。

  2. 执行 ButtonDownFcn 回调。

工具提示,指定为字符向量、字符向量元胞数组、字符串数组或一维分类数组。如果使用此属性,则在运行时当用户将指针悬停在组件上时,将显示消息。即使禁用组件,工具提示也会显示。要显示多行文本,请指定字符向量元胞数组或字符串数组。数组中的每个元素变为一行文本。如果将此属性指定为分类数组,MATLAB 将使用数组中的值,而不是完整的类别集。

上下文菜单,指定为使用 uicontextmenu 函数创建的 ContextMenu 对象。使用此属性可在您右键点击组件时显示上下文菜单。

颜色和样式

全部展开

单元格文本颜色,指定为 RGB 三元组、十六进制颜色代码或下表中列出的颜色选项之一。当您使用 ForegroundColor 属性设置单元格文本颜色时,它将应用于表 UI 组件中的所有单元格。

RGB 三元组和十六进制颜色代码对于指定自定义颜色非常有用。

  • RGB 三元组是包含三个元素的行向量,其元素分别指定颜色中红、绿、蓝分量的强度。强度值必须位于 [0,1] 范围内,例如 [0.4 0.6 0.7]

  • 十六进制颜色代码是字符向量或字符串标量,以井号 (#) 开头,后跟三个或六个十六进制数字,范围可以是 0F。这些值不区分大小写。因此,颜色代码 '#FF8800''#ff8800''#F80''#f80' 是等效的。

此外,还可以按名称指定一些常见的颜色。下表列出了命名颜色选项、等效 RGB 三元组和十六进制颜色代码。

颜色名称短名称RGB 三元组十六进制颜色代码外观
'red''r'[1 0 0]'#FF0000'

'green''g'[0 1 0]'#00FF00'

'blue''b'[0 0 1]'#0000FF'

'cyan' 'c'[0 1 1]'#00FFFF'

'magenta''m'[1 0 1]'#FF00FF'

'yellow''y'[1 1 0]'#FFFF00'

'black''k'[0 0 0]'#000000'

'white''w'[1 1 1]'#FFFFFF'

以下是 MATLAB 在许多类型的绘图中使用的默认颜色的 RGB 三元组和十六进制颜色代码。

RGB 三元组十六进制颜色代码外观
[0 0.4470 0.7410]'#0072BD'

[0.8500 0.3250 0.0980]'#D95319'

[0.9290 0.6940 0.1250]'#EDB120'

[0.4940 0.1840 0.5560]'#7E2F8E'

[0.4660 0.6740 0.1880]'#77AC30'

[0.3010 0.7450 0.9330]'#4DBEEE'

[0.6350 0.0780 0.1840]'#A2142F'

表背景色,指定为 RGB 三元组或由 RGB 三元组组成的 m×3 矩阵。RGB 三元组是行向量,用于指定颜色的红、绿和蓝分量的强度。强度必须处于范围 [0,1] 中。颜色名称无效。

当您希望表中各行按某种重复模式使用 m 种不同颜色进行着色时,请指定 m×3 矩阵。矩阵的每一行都必须是一个 RGB 三元组。当 RowStriping 属性为 'on' 时,MATLAB 使用矩阵的行。除非两个 RowStriping 均为 'on'BackgroundColorm×3 矩阵,否则不会对表背景隔行着色。

示例: uit = uitable(uifigure,'Data',rand(10,3),'BackgroundColor',[0.85 0.85 1])

示例: uit = uitable(uifigure,'Data',rand(10,3),'BackgroundColor',[1 1 1 ;0.85 0.85 1])

下表列出了某些颜色的 RGB 三元组。

颜色RGB 三元组
黄色[1 1 0]
品红色[1 0 1]
青蓝色[0 1 1]
红色[1 0 0]
绿色[0 1 0]
蓝色[0 0 1]
白色[1 1 1]
黑色[0 0 0]

隔行着色,指定为 'on''off',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true'off' 等效于 false。因此,您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

此属性控制表行的着色模式。当 RowStriping 值设置为 'on' 时,BackgroundColor 矩阵指定行的颜色以某种重复模式显示。如果 BackgroundColor 矩阵只有一行,则所有表行的着色都相同。

RowStriping 设为 'off' 时,BackgroundColor 矩阵中的第一个颜色定义表中所有行的着色。

位置

全部展开

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

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

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

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

表的位置和大小,指定为 [left bottom width height] 形式的四元素向量。所有测量值都采用 Units 属性指定的单位。

此属性值等同于 PositionOuterPosition 属性值。

表的位置和大小,指定为 [left bottom width height] 形式的四元素向量。所有测量值都采用 Units 属性指定的单位。

此属性值等同于 PositionInnerPosition 属性值。

测量单位,指定为 'pixels'。MATLAB 从父对象的左下角测量所有单位。

布局选项,指定为 GridLayoutOptions 对象。此属性为网格布局容器的子级组件指定选项。如果组件不是网格布局容器的子级(例如,它是图窗或面板的子级),则此属性为空且不起作用。但是,如果组件是网格布局容器的子级,则可以通过在 GridLayoutOptions 对象上设置 RowColumn 属性,将组件放置在网格的所需行和列中。

例如,以下代码将一个表 UI 组件放置在其父网格的第三行和第二列中。

g = uigridlayout([4 3]);
uit = uitable(g,'Data',rand(10,3));
uit.Layout.Row = 3;
uit.Layout.Column = 2;

要使该表跨多个行或列,请将 RowColumn 属性指定为二元素向量。例如,以下表跨列 23

uit.Layout.Column = [2 3];

回调

全部展开

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

  • 函数句柄。

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

  • 包含有效 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 设计工具中编写回调

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

  • 函数句柄。

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

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

当用户选择单元格时,此回调函数执行。通过点击或使用箭头键导航到单个数据单元格(非行标题或列标题),可以选择该数据单元格。可以使用下表中所述的任何操作选择多个单元格。选择多个单元格时,请根据它们是连续的还是不连续的来使用不同操作。

连续选择选项
点击并拖动一个单元格。
点击一个单元格,然后按住 Shift 键并点击另一个单元格,即可选择两者之间的所有单元格。
点击一个单元格,然后按住 Shift 键并按箭头键即可添加连续单元格。
点击一个行标题或列标题以选择整行或整列。
点击一个单元格,然后按 Ctrl+space,即可选择该列中的所有单元格(无论所有单元格是否都在视图中)。
点击一个单元格,然后按 Shift+space,即可选择该行中的所有单元格(无论所有单元格是否都在视图中)。
选择一行或一列。然后,按住 Shift 键并点击另一个行标题或列标题,即可选择两者之间的所有行或列。
点击一个单元格,然后按 Shift+PgUp 键或 Shift+PgDn 键,即可选择该单元格上方或下方的所有可见单元格。
Ctrl+A 键可选择表中的所有单元格。

不连续选择选项
点击并拖动以选择一组连续的单元格(或选择单个单元格)。然后,按住 Ctrl 键并点击另一单元格以将焦点置于该单元格,随后按住 Shift 键并点击焦点所在单元格以选取该单元格,或者在按住 Shift 键并点击该单元格后拖动光标以选择从其开始的一组单元格。(按 Shift 键 + 箭头键也可选择多个单元格。)
按住 Ctrl 键并点击行标题或列标题可选择整行或整列。然后重复此操作可选择另一个不相邻的行或列。

当通过按住 Ctrl 键并点击某单元格使其具有焦点时,该单元格轮廓会变为蓝色 ()。当通过点击或按住 Shift 键并点击以选择某个单元格时,该单元格填充颜色将更改为蓝色 ()。

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

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

属性

说明

Indices

这是一个 n×2 数组,包含用户在运行的 App 中选择的单元格的行索引和列索引。对于表数组中的多列变量,列索引引用整个列。对列进行排序时,Indices 会返回排序前单元格的原始 1×2 数组 - DisplayIndices 会返回所选单元格在排序后的表中的新显示位置。

DisplayIndices

这是一个 n×2 数组,包含所选单元格在排序后的表中的显示位置所对应的行和列索引。如果用户不对表进行排序,则 DisplayIndices 的内容与 Indices 属性的内容相同。

Source

执行回调的组件。

EventName

'CellSelection'

有关编写回调的详细信息,请参阅在 App 设计工具中编写回调

在显示数据更改时执行的回调,指定为下列值之一:

  • 函数句柄。

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

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

当用户编辑单元格或对表的列进行排序而导致 DisplayData 更改时,会执行此回调。

如果您要了解导致 DisplayData 发生更改的用户交互信息,请使用此回调。如果您需要有关编辑过的单元格的特定信息,请创建 CellEditCallback

此回调函数可以访问有关列是否经过排序或单元格是否经过编辑的特定信息。MATLAB 将 DisplayDataChangedData 对象中的此信息作为第二个参数传递给回调函数。在 App 设计工具中,该参数名为 event。您可以使用圆点表示法查询对象属性。例如,event.InteractionColumn 返回 Data 中进行过交互的列的索引。DisplayDataChangedData 对象不可用于指定为字符向量的回调函数。

属性说明
DisplayRowName排序后所显示的表中 RowName 属性值的元胞数组。DisplayRowName 将始终是原始 RowName 属性的一种排列。
DisplayColumnName排序后所显示的表中 ColumnName 属性值的元胞数组。DisplayColumnName 将始终是原始 ColumnName 属性的一种排列。
Interaction'sort''edit'
InteractionColumnData 中已修改列的索引。
InteractionDisplayColumnDisplayData 中已修改列的索引。
InteractionVariable表数组数据的修改列的 VariableNames 属性。如果 Data 包含表数组以外的数据类型,则 InteractionVariable 返回空字符数组。
Source执行回调的组件。
EventName

'DisplayDataChanged'

有关将回调指定为函数句柄、元胞数组或字符向量的详细信息,请参阅在 App 设计工具中编写回调

按下鼠标按键回调函数,指定为下列值之一:

  • 函数句柄。

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

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

有关将回调属性值指定为函数句柄、元胞数组或字符向量的详细信息,请参阅如何指定回调属性值

ButtonDownFcn 回调是当用户在 UI 组件上点击鼠标按键时执行的函数。回调在以下情形下执行:

  • 用户右键点击表,并且 Enable 属性设置为 'on'

  • 用户右键点击或左键点击表,并且 Enable 属性设置为 'off'

按键回调函数,指定为下列值之一:

  • 函数句柄。

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

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

有关将回调属性值指定为函数句柄、元胞数组或字符向量的详细信息,请参阅如何指定回调属性值

Table 对象获得焦点并且用户按下键时执行该回调函数。如果您没有为该属性定义函数,则MATLAB 向父图窗传递按键操作。重复按键操作会保留 Table 对象的焦点,并在每次发生按键操作时执行该函数。如果用户几乎在同一时间按下多个键,MATLAB 将检测最后一个按键的按键操作。

如果将该属性指定为函数句柄(或包含函数句柄的元胞数组),则 MATLAB 会将包含回调数据的对象作为第二个参数传递给回调函数。该对象包含下表中介绍的属性。您可以使用圆点表示法访问回调函数内的这些属性。

属性

说明

示例:

a

=

Shift

Shift-a

Character作为按下一个或多个键的结果显示的字符。字符可能为空或无法打印。'a''=''''A'
Modifier包含按下的一个或多个修改键(例如 CtrlAltShift)名称的元胞数组。{1x0 cell}{1x0 cell}{'shift'}{'shift'}
Key按下的键,通过键上的(小写字母)标签或文本说明标识。'a''equal''shift''a'
Source当用户按下该键时获取焦点的对象。Table 对象Table 对象Table 对象Table 对象
EventName导致回调函数执行的操作。'KeyPress''KeyPress''KeyPress''KeyPress'

按修改键会以下列方式影响回调数据:

  • 修改键可影响 Character 属性,但不会更改 Key 属性。

  • 特定键以及使用 Ctrl 修饰的键会在 Character 属性中放置无法打印的字符。

  • CtrlAltShift 以及其他几个键不会生成 Character 属性数据。

您还可以查询图窗的 CurrentCharacter 属性以确定用户按下的字符。

释放键回调函数,指定为下列值之一:

  • 函数句柄。

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

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

有关将回调属性值指定为函数句柄、元胞数组或字符向量的详细信息,请参阅如何指定回调属性值

Table 对象获得焦点并且用户释放键时执行该回调函数。

如果将该属性指定为函数句柄(或包含函数句柄的元胞数组),则 MATLAB 会将包含回调数据的对象作为第二个参数传递给回调函数。该对象包含下表中介绍的属性。您可以使用圆点表示法访问回调函数内的这些属性。

属性

说明

示例:

a

=

Shift

Shift-a

Character

已释放的键的字符解释。

'a''=''''A'
Modifier

当前修改键(例如,'control')或空元胞数组(如果没有修改键)。

{1x0 cell}{1x0 cell}{1x0 cell}{1x0 cell}
Key

释放的键的名称,通过键上的小写字母标签或文本说明标识。

'a''equal''shift''a'
Source当用户按下该键时获取焦点的对象。Table 对象Table 对象Table 对象Table 对象
EventName导致回调函数执行的操作。'ase''ase''ase''ase'

按修改键会以下列方式影响回调数据:

  • 修改键可影响 Character 属性,但不会更改 Key 属性。

  • 特定键以及使用 Ctrl 修饰的键会在 Character 属性中放置无法打印的字符。

  • CtrlAltShift 以及其他几个键不会生成 Character 属性数据。

您还可以查询图窗的 CurrentCharacter 属性以确定用户按下的字符。

对象创建函数,指定为下列值之一:

  • 函数句柄。

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

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

有关将回调指定为函数句柄、元胞数组或字符向量的详细信息,请参阅在 App 设计工具中编写回调

此属性指定要在 MATLAB 创建对象时执行的回调函数。MATLAB 将在执行 CreateFcn 回调之前初始化所有属性值。如果不指定 CreateFcn 属性,则 MATLAB 执行默认的创建函数。

对现有组件设置 CreateFcn 属性没有任何作用。

如果将此属性指定为函数句柄或元胞数组,则可以使用回调函数的第一个参数访问正在创建的对象。否则,使用 gcbo 函数访问该对象。

对象删除函数,指定为下列值之一:

  • 函数句柄。

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

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

有关将回调指定为函数句柄、元胞数组或字符向量的详细信息,请参阅在 App 设计工具中编写回调

此属性指定在 MATLAB 删除对象时要执行的回调函数。MATLAB 在销毁对象的属性之前执行 DeleteFcn 回调。如果不指定 DeleteFcn 属性,则 MATLAB 执行默认的删除函数。

如果将此属性指定为函数句柄或元胞数组,则可以使用回调函数的第一个参数访问要删除的对象。否则,使用 gcbo 函数访问该对象。

回调执行控件

全部展开

回调中断,指定为 'on''off',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true'off' 等效于 false。因此,您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

此属性确定是否可以中断运行中回调。有以下两种回调状态要考虑:

  • 运行中回调是当前正在执行的回调。

  • 中断回调是试图中断运行中回调的回调。

每当 MATLAB 调用回调时,回调都会试图中断正在运行的回调(如果存在)。运行中回调所属对象的 Interruptible 属性决定着是否允许中断。

  • 'on' 允许其他回调中断对象的回调。中断发生在 MATLAB 处理队列的下一个位置,例如当存在 drawnowfigureuifiguregetframewaitforpause 命令时。

    • 如果运行中回调包含以上命令之一,则 MATLAB 将在该时刻停止执行回调并执行中断回调。当中断回调完成时,MATLAB 将恢复执行运行中回调。

    • 如果运行中回调不包含以上命令之一,则 MATLAB 执行完当前回调,不会出现任何中断。

  • 'off' 阻止所有中断尝试。由中断回调所属的对象的 BusyAction 属性决定是放弃该中断回调还是将其放入队列中。

注意

回调的中断和执行在以下情况下会有不同的表现:

  • 如果中断回调是 DeleteFcnCloseRequestFcnSizeChangedFcn 回调,则无论是否存在 Interruptible 属性值都会发生中断。

  • 如果运行中回调当前正在执行 waitfor 函数,则无论是否存在 Interruptible 属性值都会发生中断。

  • Timer 对象根据排定时间执行,而不管 Interruptible 属性值如何。

发生中断时,MATLAB 不保存属性状态或显示内容。例如,gcagcf 命令返回的对象可能会在另一个回调执行时发生改变。

回调排队,指定为 'queue''cancel'BusyAction 属性决定 MATLAB 如何处理中断回调的执行。有以下两种回调状态要考虑:

  • 运行中回调是当前正在执行的回调。

  • 中断回调是试图中断运行中回调的回调。

无论何时 MATLAB 调用回调,该回调都会试图中断运行中回调。运行中回调所属对象的 Interruptible 属性决定着是否允许中断。如果不允许中断,则中断回调所属对象的属性 BusyAction 将决定是放弃该回调还是将回调放入队列中。以下是 BusyAction 属性的可能值:

  • 'queue' - 将中断回调放入队列中,以便在运行中回调执行完毕后进行处理。

  • 'cancel' - 不执行中断回调。

此属性为只读

删除状态,以 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值形式返回。

DeleteFcn 回调开始执行时,MATLAB 会将 BeingDeleted 属性设置为 'on'BeingDeleted 属性将一直保持 'on' 设置状态,直到组件对象不再存在为止。

在查询或修改对象之前,请先检查其 BeingDeleted 属性的值,以确认它不是待删除项。

父级/子级

全部展开

父容器,指定为使用 uifigure 函数创建的 Figure 对象或其子容器之一:TabPanelButtonGroupGridLayout。如果未指定容器,MATLAB 将调用 uifigure 函数以创建一个新 Figure 对象来充当父容器。

表的子级,以空数组形式返回。表对象没有子级,因此设置此属性没有任何作用。

对象句柄的可见性,指定为 'on''callback''off'

此属性控制对象在其父级的子级列表中的可见性。当对象未显示在其父级的子级列表中时,通过搜索对象层次结构或查询属性来获取对象的函数不会返回该对象。这些函数包括 getfindobjclfclose。对象即使在不可见时也有效。如果可以访问某个对象,则可以设置和获取其属性,并将其传递给针对对象进行运算的任意函数。

HandleVisibility 值说明
'on'对象始终可见。
'callback'对象对于回调或回调调用的函数可见,但对于命令行调用的函数不可见。此选项阻止通过命令行访问对象,但允许回调函数访问它。
'off'对象始终不可见。该选项用于防止另一函数无意中对 UI 进行更改。将 HandleVisibility 设置为 'off' 可在执行该函数时暂时隐藏对象。

标识符

全部展开

此属性为只读

图形对象的类型,以 'uitable' 形式返回。

对象标识符,指定为字符向量或字符串标量。您可以指定唯一的 Tag 值作为对象的标识符。如果需要访问您代码中其他位置的对象,可以使用 findobj 函数基于 Tag 值搜索对象。

用户数据,指定为任何 MATLAB 数组。例如,您可以指定标量、向量、矩阵、元胞数组、字符数组、表或结构体。使用此属性存储对象上的任意数据。

如果您在 App 设计工具中工作,请在该 App 中创建公共或私有属性以共享数据,而不是使用 UserData 属性。有关详细信息,请参阅在用 App 设计工具创建的 App 内共享数据

在 R2016b 中推出