TextArea
文本区域 UI 组件
说明
文本区域 UI 组件允许 App 用户在 App 中输入多行文本。在创建文本区域后，使用 TextArea 对象修改其外观和行为。
创建对象
使用 uitextarea 函数在 App 中创建一个文本区域。
属性
文本
值，指定为字符向量、字符串标量、字符向量元胞数组、字符串数组或一维分类数组。要显示多行文本，请将 Value 指定为数组。数组中的每个元素代表一行文本。
txt = ["Line 1"; "Line 2"; "Line 3"; "Line 4"]; textarea = uitextarea("Value",txt);
如果将此属性指定为分类数组，MATLAB® 将使用数组中的值，而不是完整的类别集。
如果文本区域的宽度不足以容纳文本，MATLAB 将对文本进行换行。
如果有太多行要显示在文本区域，MATLAB 将添加一个滚动条。
示例: ["Joseph Welford"; "Mary Reilly"; "Roberta Silberlicht"]
文本区域中的占位符文本，指定为字符向量或字符串标量。占位符提供简短的提示来说明预期的输入。仅当 Value 属性为 {''} 时，文本才会显示。
示例: 'Enter text'
文本区域中文本的对齐方式，指定为 'left'、'right' 或 'center'。对齐方式影响 App 用户编辑文本区域时的显示方式，还影响 MATLAB 在 App 中显示文本的方式。
文字换行以适合组件宽度，指定为 'on' 或 'off'，或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true，'off' 等效于 false。因此，您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。
当组件的宽度小于要显示的文本的宽度时，使用此属性可防止文本在水平方向上被裁剪。
'on'- 将文本分成若干新行，以便每行都适应组件宽度，并尽可能避免单词断开。'off'- 文本不换行。
字体和颜色
字体颜色，指定为 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" |
|
下表列出了浅色和深色主题中绘图的默认调色板。
| 调色板 | 调色板颜色 |
|---|---|
在 R2025a 之前的版本中: 大多数绘图默认使用这些颜色。 |
|
|
|
您可以使用 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)) 获取十六进制颜色代码。
背景颜色，指定为 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" |
|
下表列出了浅色和深色主题中绘图的默认调色板。
| 调色板 | 调色板颜色 |
|---|---|
在 R2025a 之前的版本中: 大多数绘图默认使用这些颜色。 |
|
|
|
您可以使用 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)) 获取十六进制颜色代码。
交互性
文本区域的可编辑性，指定为 'on' 或 'off'，或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true，'off' 等效于 false。因此，您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。
此属性可与 Enable 属性值结合使用，以确定组件是否响应以及如何响应 App 用户的输入：
要使文本区域可编辑并且关联的回调可触发，请将
Enable属性值和Editable属性值都设置为'on'。
要使文本区域不可编辑，但文本易于阅读，请将
Enable属性值设置为'on'，将Editable属性值设置为'off'。
要使文本区域不可编辑并且使文本灰显，请将这两个属性都设置为
'off'。
文本区域的工作状态，指定为 'on' 或 'off'，或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true，'off' 等效于 false。因此，您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。
此属性可与 Editable 属性值结合使用，以确定组件是否响应以及如何响应 App 用户的输入：
要使文本区域可编辑并且关联的回调可触发，请将
Enable属性值和Editable属性值都设置为'on'。 要使文本区域不可编辑，但文本易于阅读，请将
Enable属性值设置为'on'，将Editable属性值设置为'off'。 要使文本区域不可编辑并且使文本灰显，请将这两个属性都设置为
'off'。
工具提示，指定为字符向量、字符向量元胞数组、字符串数组或一维分类数组。如果使用此属性，则在运行时当用户将指针悬停在组件上时，将显示消息。即使禁用组件，工具提示也会显示。要显示多行文本，请指定字符向量元胞数组或字符串数组。数组中的每个元素变为一行文本。如果将此属性指定为分类数组，MATLAB 将使用数组中的值，而不是完整的类别集。
上下文菜单，指定为使用 uicontextmenu 函数创建的 ContextMenu 对象。使用此属性可在您右键点击组件时显示上下文菜单。
位置
文本区域的内部位置和大小，指定为 [left bottom width height]。位置值相对于父容器。所有测量值都以像素为单位。此属性值等同于 Position 属性值。
此 属性 为只读。
文本区域的外部位置和大小，以 [left bottom width height] 形式返回。位置值相对于父容器。所有测量值都以像素为单位。此属性值等同于 Position 属性值。
布局选项，指定为 GridLayoutOptions 对象。此属性为网格布局容器的子级组件指定选项。如果组件不是网格布局容器的子级（例如，它是图窗或面板的子级），则此属性为空且不起作用。但是，如果组件是网格布局容器的子级，则可以通过在 GridLayoutOptions 对象上设置 Row 和 Column 属性，将组件放置在网格的所需行和列中。
例如，以下代码将一个文本区域放置在其父网格的第三行第二列中。
g = uigridlayout([4 3]); tarea = uitextarea(g); tarea.Layout.Row = 3; tarea.Layout.Column = 2;
要使该文本区域跨多个行或列，请将 Row 或 Column 属性指定为二元素向量。例如，此文本区域跨列 2 到 3：
tarea.Layout.Column = [2 3];
回调
更改值后执行的回调，指定为下列值之一：
函数句柄。
第一个元素是函数句柄的元胞数组。元胞数组中的后续元素是传递到回调函数的参量。
包含有效 MATLAB 表达式的字符向量（不推荐）。MATLAB 在基础工作区计算此表达式。
此回调按照如下方式执行：
当用户在文本区域中键入时，回调会重复执行。
当用户按下 Tab 键或在文本区域外点击时，回调会执行。
如果文本区域值以编程方式发生更改，则回调不会执行。
此回调函数可以访问有关用户与文本区域的交互的特定信息。MATLAB 将 ValueChangingData 对象中的此信息作为第二个参量传递给回调函数。在 App 设计工具中，该参量名为 event。您可以使用圆点表示法查询对象属性。例如，event.Value 是文本区域中触发了回调执行的值。ValueChangingData 对象不可用于指定为字符向量的回调函数。
以下是 ValueChangingData 对象的属性：
| 属性 | 描述 |
|---|---|
Value | 触发了回调执行的值 |
Source | 执行回调的组件 |
EventName | 'ValueChanging' |
TextArea 对象的 Value 属性在用户按下 Tab 键或在文本区域外点击之前不会更新。但是，您可以在用户仍在键入时通过查询 ValueChangingData 对象的 Value 属性来获取文本。
注意
请避免从其自己的 ValueChangingFcn 回调中更新 TextArea 对象的 Value 属性，因为这可能导致意外行为。要更新文本区域值以响应用户输入，请改用 ValueChangedFcn 回调。
有关编写回调的详细信息，请参阅App 设计工具中的回调。
回调执行控件
父级/子级
父容器，指定为 Figure 对象或其子容器之一：Tab、Panel、ButtonGroup 或 GridLayout。如果未指定容器，MATLAB 将调用 uifigure 函数以创建一个新 Figure 对象来充当父容器。
标识符
此 属性 为只读。
图形对象的类型，以 'uitextarea' 形式返回。
示例
在 UI 图窗中创建一个填充的文本区域。
fig = uifigure; txa = uitextarea(fig, ... "Value",["First Name Last Name"; "Address 1"; ... "Address 2"; "City, State"; "Postal Code"]);
请注意，该文本区域包含一个滚动条，以便 App 用户查看邮编。
通过查询 Position 属性的第三个和第四个值来确定文本区域的当前宽度和高度。
size = txa.Position(3:4)
size = 1×2
150 60
增大文本区域的大小，以便在不使用滚动条的情况下显示所有内容。
txa.Position(3:4) = [155 80];
以编程方式滚动到文本区域的底部。
创建一个文本区域。为其指定大小和长文本。
fig = uifigure;
txa = uitextarea(fig);
txa.Position = [100 100 80 80];
txa.Value = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor.";
滚动到文本区域的底部。
scroll(txa,"bottom")
创建一个 App，当 App 用户在文本区域输入文本时，该 App 会启用一个按钮。
在名为 textAreaApp.m 的文件中，编写实现该 App 的函数：
创建一个 UI 图窗和一个网格布局管理器，以对该 App 进行布局。
在网格布局管理器中创建一个标签、文本区域和按钮。
编写一个名为
textEntered的回调函数，它能在文本区域中已存在输入文本时启用一个按钮，并将该函数赋给文本区域的ValueChangedFcn回调属性。有关回调的详细信息，请参阅Create Callbacks for Apps Created Programmatically。
function textAreaApp fig = uifigure; g = uigridlayout(fig,[3 3]); g.RowHeight = {'fit','fit','fit'}; g.ColumnWidth = {'1x','fit','1x'}; lbl = uilabel(g,"Text","Enter Comments:"); lbl.Layout.Row = 1; lbl.Layout.Column = 2; txa = uitextarea(g); txa.Layout.Row = 2; txa.Layout.Column = 2; btn = uibutton(g,"Text","Submit","Enable","off"); btn.Layout.Row = 3; btn.Layout.Column = 2; txa.ValueChangedFcn = @(src,event) textEntered(src,event,btn); end function textEntered(src,event,btn) val = src.Value; btn.Enable = "off"; % Check each element of text area cell array for text for k = 1:length(val) if ~isempty(val{k}) btn.Enable = "on"; break end end end
运行 textAreaApp 函数。在文本区域中输入一些文本，然后在文本区域外点击以启用 Submit 按钮。
