uipanel

创建面板容器

全页折叠

语法

p = uipanel

p = uipanel(parent)

p = uipanel(___,Name,Value)

说明

p = uipanel 在当前图窗中创建一个面板并返回 Panel 对象。如果没有可用的图窗，MATLAB^® 将调用 figure 函数创建一个图窗。

p = uipanel(parent) 在指定的父容器中创建一个面板。父容器可以是图窗或图窗的子容器。

示例

p = uipanel(___,Name,Value) 使用一个或多个名称-值参量指定面板属性。可将此选项与上述语法中的任何输入参量组合一起使用。

示例

全部折叠

创建面板

打开实时脚本

在 UI 图窗中创建一个面板。

fig = uifigure;
p = uipanel(fig);

Figure contains an object of type uipanel.

将 UI 组件添加到面板

打开实时脚本

在 UI 图窗中创建一个面板，并在面板中添加一个按钮。

fig = uifigure;
p = uipanel(fig);
btn = uibutton(p);

Figure contains an object of type uipanel.

设置和访问面板属性值

打开实时脚本

在 UI 图窗中创建一个面板，并通过指定属性值来自定义其外观。

fig = uifigure;
p = uipanel(fig, ...
    "Title","Data", ...
    "BackgroundColor","white");

Figure contains an object of type uipanel.

确定面板位置和大小。

s = p.Position

s = 1×4

    20    20   260   221

通过修改面板 Position 属性的第三个和第四个元素来更新面板的宽度和高度。

p.Position(3:4) = [150 380];

Figure contains an object of type uipanel.

创建可滚动面板

在 UI 图窗中创建一个面板。向该面板添加六个 UI 组件。前两个组件不可见，因为它们位于面板的上边框之外。

fig = uifigure;
p = uipanel(fig,"Position",[20 20 196 135]);
ef1 = uieditfield(p,"Text","Position",[11 165 140 22],"Value","First Name");
ef2 = uieditfield(p,"Text","Position",[11 140 140 22],"Value","Last Name");
ef3 = uieditfield(p,"Text","Position",[11 115 140 22],"Value","Address");
dd = uidropdown(p,"Position",[11 90 140 22],"Items",["Male","Female"]);
cb = uicheckbox(p,"Position",[11 65 140 22],"Text","Member");
btn = uibutton(p,"Position",[11 40 140 22],"Text","Send");

UI figure window with a panel with four UI components. Only one edit field is visible.

通过将 Scrollable 属性设置为 "on" 在面板中启用滚动功能。默认情况下，滚动条滚动到面板的顶部。

p.Scrollable = "on";

UI figure window with a scrollable panel. The panel has a scroll bar on its right. The bar is scrolled to the top, and all three edit fields are visible in the panel.

输入参数

全部折叠

`parent` — 父容器
`Figure` 对象 (默认) | `Panel` 对象 | `Tab` 对象 | `ButtonGroup` 对象 | `GridLayout` 对象

父容器，指定为 Figure 对象或其子容器之一：Tab、Panel、ButtonGroup 或 GridLayout。

名称-值参数

全部折叠

以 Name1=Value1,...,NameN=ValueN 的形式指定可选参量对组，其中 Name 是参量名称，Value 是对应的值。名称-值参量必须出现在其他参量之后，但对各个参量对组的顺序没有要求。

示例: uipanel(Title="Options") 指定面板标题为 Options。

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

示例: uipanel("Title","Options") 指定面板标题为 Options。

注意

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

`Title` — 标题
字符向量 | 字符串标量 | 分类数组

标题，指定为字符向量、字符串标量或分类数组。如果将此属性指定为分类数组，MATLAB 将仅显示数组中的第一个元素。

MATLAB 不会将竖线 ('|') 字符解释为换行符，它在标题中显示为竖线。

如果要指定 Unicode^® 字符，则将 Unicode 十进制码传递到 char 函数。例如，['Multiples of ' char(960)] 显示为 Multiples of π。

`BackgroundColor` — 背景色
RGB 三元组 | 十六进制颜色代码 | `'r'` | `'g'` | `'b'` | ...

背景颜色，指定为 RGB 三元组、十六进制颜色代码或下表中列出的颜色选项之一。

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

RGB 三元组是包含三个元素的行向量，其元素分别指定颜色中红、绿、蓝分量的强度。强度值必须位于 [0,1] 范围内，例如 [0.4 0.6 0.7]。
十六进制颜色代码是字符向量或字符串标量，以井号 (#) 开头，后跟三个或六个十六进制数字，范围可以是 0 到 F。这些值不区分大小写。因此，颜色代码 "#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"`

下表列出了浅色和深色主题中绘图的默认调色板。

调色板调色板颜色

调色板	调色板颜色
`"gem"` - 浅色主题默认值在 R2025a 之前的版本中: 大多数绘图默认使用这些颜色。
`"glow"` - 深色主题默认值

"gem" - 浅色主题默认值

在 R2025a 之前的版本中: 大多数绘图默认使用这些颜色。

Sample of the "gem" color palette

"glow" - 深色主题默认值

Sample of the "glow" color palette

您可以使用 orderedcolors 和 rgb2hex 函数获取这些调色板的 RGB 三元组和十六进制颜色代码。例如，获取 "gem" 调色板的 RGB 三元组并将其转换为十六进制颜色代码。

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

在 R2023b 之前的版本中: 使用 RGB = get(groot,"FactoryAxesColorOrder") 获取 RGB 三元组。

在 R2024a 之前的版本中: 使用 H = compose("#%02X%02X%02X",round(RGB*255)) 获取十六进制颜色代码。

`Position` — 面板的位置和大小，包括边框和标题
`[left bottom width height]`

面板的位置和大小，包括边框和标题，指定为 [left bottom width height] 形式的四元素向量。此表介绍该向量中的每个元素。

元素	描述
`left`	父容器的内部左边缘与面板的外部左边缘之间的距离
`bottom`	父容器的内部下边缘与面板的外部下边缘之间的距离
`width`	面板的左右外部边缘之间的距离
`height`	面板的上下外部边缘之间的距离

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

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

注意

如果网格布局管理器是该面板的父级，则 Position 属性的值不会立即更新。要使用 Position 值相对于面板大小调整面板子级的大小，请使用 SizeChangedFcn 回调。

`Units` — 测量单位
`'pixels'` | `'normalized'` | `'inches'` | `'centimeters'` | `'points'` | `'characters'`

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

单位值	描述
`'pixels'`（基于 `uifigure` 的 App 中的默认值）	在 Windows^® 和 Macintosh 系统上，像素的大小为 1/96 英寸。此大小与系统分辨率无关。在 Linux^® 系统上，一个像素的大小由系统分辨率确定。
`'normalized'`（基于 `figure` 的 App 中的默认值）	这些单位依据父容器进行归一化。容器的左下角映射到 `(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。

提示

如果将面板对象的 Visible 属性设置为 "off"，该对象包含的所有子对象（例如按钮、按钮组或坐标区）以及父面板都将不可见。但是，每个子对象的 Visible 属性值不受影响。

版本历史记录

在 R2006a 之前推出

全部展开

R2025a: 面板标题和边框选项在基于 `figure` 的 App 中已更改

使用 figure 函数创建的 App 中的面板更新了外观。由于此更新，某些标题和边框选项也已更改。

TitlePosition 属性

面板标题只能出现在面板的顶部。因此，以下 TitlePosition 值的行为发生了变化。

值	R2024b 及更早版本	从 R2025a 开始	推荐值
`'leftbottom'`			更新您的代码以使用 `'lefttop'`（而不是 `'leftbottom'`）来反映面板标题位置。
`'centerbottom'`			更新您的代码以使用 `'centertop'`（而不是 `'centerbottom'`）来反映面板标题位置。
`'rightbottom'`			更新您的代码以使用 `'righttop'`（而不是 `'rightbottom'`）来反映面板标题位置。

BorderType 属性

可见的面板边框始终显示为线条。因此，某些 BorderType 值的行为发生了变化。将 BorderType 指定为表中的任一值都会导致警告。此外，BorderType 的默认值已从 'etchedin' 更改为 'line'。

值	R2024b	R2025a	推荐值
`'etchedin'`			更新您的代码以使用 `'line'`（而不是 `'etchedin'`）来反映面板边框类型。
`'etchedout'`			更新您的代码以使用 `'line'`（而不是 `'etchedout'`）来反映面板边框类型。
`'beveledin'`			更新您的代码以使用 `'line'`（而不是 `'beveledin'`）来反映面板边框类型。
`'beveledout'`			更新您的代码以使用 `'line'`（而不是 `'beveledout'`）来反映面板边框类型。

ShadowColor 属性

由于 BorderType 属性的更改，ShadowColor 属性不再起作用，如果设置该属性，系统会发出警告。要指定面板的边框颜色，请改用 BorderColor 属性。

ShadowColor 属性不再出现在对 Panel 对象调用 get 函数时所返回的列表中。

R2025a: 为基于 `figure` 的 App 中的面板设置其他属性

使用 figure 函数创建的 App 中的 Panel 对象包括以下附加属性：

Tooltip
Scrollable
AutoResizeChildren
Layout
Enable

以前，这些属性仅对使用 uifigure 函数创建的 App 中的 Panel 对象可用。

R2023a: 使用 `BorderColor` 属性（而不是 `HighlightColor`）更改面板边框颜色

通过使用 BorderColor 属性，您可以在基于 uifigure 和基于 figure 的 App 中更改面板的边框颜色。

推荐使用 BorderColor 属性而不是 HighlightColor 属性，后者仅在基于 figure 的 App 中受支持。目前没有停止支持 HighlightColor 的计划。

R2022b: 在基于 `uifigure` 的 App 中更改面板边框宽度

在 App 设计工具中使用 uifigure 函数创建的 App 中，使用 BorderWidth 属性更改面板的边框宽度。

R2020b: 关闭和打开交互

要控制面板是否响应用户交互，请使用 Enable 属性。当 Enable 属性设置为 'on' 时，只要面板和其中的 UI 组件处于启用状态，您就可以与它们进行交互。当 Enable 属性设置为 'off' 时，您无法与面板或其内容进行交互。

Enable 属性仅在使用 App 设计工具创建的 App 和基于 uifigure 的 App 中的面板中受支持。

另请参阅

属性

Panel

uipanel

语法

说明

示例

创建面板

将 UI 组件添加到面板

设置和访问面板属性值

创建可滚动面板

输入参数

parent — 父容器 Figure 对象 (默认) | Panel 对象 | Tab 对象 | ButtonGroup 对象 | GridLayout 对象

名称-值参数

Title — 标题 字符向量 | 字符串标量 | 分类数组

BackgroundColor — 背景色 RGB 三元组 | 十六进制颜色代码 | 'r' | 'g' | 'b' | ...

Position — 面板的位置和大小，包括边框和标题 [left bottom width height]

Units — 测量单位 'pixels' | 'normalized' | 'inches' | 'centimeters' | 'points' | 'characters'

提示

版本历史记录

R2025a: 面板标题和边框选项在基于 figure 的 App 中已更改

R2025a: 为基于 figure 的 App 中的面板设置其他属性

R2023a: 使用 BorderColor 属性（而不是 HighlightColor）更改面板边框颜色

R2022b: 在基于 uifigure 的 App 中更改面板边框宽度

R2020b: 关闭和打开交互

另请参阅

属性

`parent` — 父容器
`Figure` 对象 (默认) | `Panel` 对象 | `Tab` 对象 | `ButtonGroup` 对象 | `GridLayout` 对象

`Title` — 标题
字符向量 | 字符串标量 | 分类数组

`BackgroundColor` — 背景色
RGB 三元组 | 十六进制颜色代码 | `'r'` | `'g'` | `'b'` | ...

`Position` — 面板的位置和大小，包括边框和标题
`[left bottom width height]`

`Units` — 测量单位
`'pixels'` | `'normalized'` | `'inches'` | `'centimeters'` | `'points'` | `'characters'`

R2025a: 面板标题和边框选项在基于 `figure` 的 App 中已更改

R2025a: 为基于 `figure` 的 App 中的面板设置其他属性

R2023a: 使用 `BorderColor` 属性（而不是 `HighlightColor`）更改面板边框颜色

R2022b: 在基于 `uifigure` 的 App 中更改面板边框宽度