uitextarea

创建文本区域组件

语法

txa = uitextarea

txa = uitextarea(parent)

txa = uitextarea(___,Name,Value)

说明

txa = uitextarea 在新图窗窗口中创建一个文本区域，并返回 TextArea 对象。MATLAB^® 调用 uifigure 函数来创建该图窗。

txa = uitextarea(parent) 在指定的父容器中创建文本区域。父容器可以是使用 uifigure 函数创建的 Figure 对象或其子容器之一。

txa = uitextarea(___,Name,Value) 使用一个或多个名称-值参量指定 TextArea 属性。例如，uitextarea("Value","Comments") 创建一个显示文本 Comments 的文本区域。可将此选项与上述语法中的任何输入参量组合一起使用。

示例

创建文本区域

在 UI 图窗中创建文本区域。

fig = uifigure;
txa = uitextarea(fig);

创建具有占位符文本的文本区域

在 UI 图窗中创建文本区域。指定描述预期输入的占位符文本。占位符文本仅在文本区域为空时显示。

fig = uifigure;
txa = uitextarea(fig,"Placeholder","Enter feedback");

设置和访问文本区域属性

在 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 按钮。

输入参数

parent — 父容器

Figure 对象 (默认) | Tab 对象 | Panel 对象 | ButtonGroup 对象 | GridLayout 对象

父容器，指定为使用 uifigure 函数创建的 Figure 对象或其子容器之一：Tab、Panel、ButtonGroup 或 GridLayout。如果不指定父容器，MATLAB 会调用 uifigure 函数创建新 Figure 对象充当父容器。

名称-值参数

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

示例: uitextarea(Editable="off") 指定 App 用户不能更改文本区域的文本。

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

示例: uitextarea("Editable","off") 指定 App 用户不能更改文本区域的文本。

注意

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

Value — 值

{''} (默认) | 字符向量 | 字符串标量 | 字符向量元胞数组 | 字符串数组 | 一维分类数组

值，指定为字符向量、字符串标量、字符向量元胞数组、字符串数组或一维分类数组。要显示多行文本，请将 Value 指定为数组。数组中的每个元素代表一行文本。

txt = ["Line 1"; "Line 2"; "Line 3"; "Line 4"];
textarea = uitextarea("Value",txt);

如果将此属性指定为分类数组，MATLAB 将使用数组中的值，而不是完整的类别集。

如果文本区域的宽度不足以容纳文本，MATLAB 将对文本进行换行。

如果有太多行要显示在文本区域，MATLAB 将添加一个滚动条。

示例: ["Joseph Welford"; "Mary Reilly"; "Roberta Silberlicht"]

ValueChangedFcn — 更改值后执行的回调

'' (默认) | 函数句柄 | 元胞数组 | 字符向量

更改值后执行的回调，指定为下列值之一：

• 函数句柄。

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

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

当用户更改文本并按 Tab 键或在文本区域外部点击时，将会执行此回调。如果以编程方式更改 Value 属性，将不会执行此回调函数。

此回调函数可以访问有关用户与文本区域的交互的特定信息。MATLAB 将 ValueChangedData 对象中的此信息作为第二个参量传递给回调函数。在 App 设计工具中，该参量名为 event。您可以使用圆点表示法查询对象属性。例如，event.PreviousValue 返回文本区域的上一个值。ValueChangedData 对象不可用于指定为字符向量的回调函数。

下表列出了 ValueChangedData 对象的属性。

属性	值
Value	文本区域在 App 用户最近一次与它交互之后的值
PreviousValue	文本区域在 App 用户最近一次与它交互之前的值
Source	执行回调的组件
EventName	'ValueChanged'

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

ValueChangingFcn — 更改值后执行的回调

'' (默认) | 函数句柄 | 元胞数组 | 字符向量

更改值后执行的回调，指定为下列值之一：

• 函数句柄。

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

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

Position — 文本区域的位置和大小

[100 100 150 60] (默认) | [left bottom width height]

文本区域相对于父级的位置和大小，指定为向量 [left bottom width height]。此表介绍该向量中的每个元素。

元素	描述
left	父容器的内部左边缘与文本区域的外部左边缘之间的距离
bottom	父容器的内部下边缘与文本区域的外部下边缘之间的距离
width	文本区域的左右外部边缘之间的距离
height	文本区域的上下外部边缘之间的距离

所有测量值都以像素为单位。

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

示例: [100 100 100 90]

版本历史记录

在 R2016a 中推出

R2021b: 用户键入时的程序响应

创建一个 ValueChangingFcn 回调以对 App 进行编程，使其在用户在文本区域内键入时作出响应。当用户键入时，该回调函数会重复执行。

R2021a: 指定占位符文本

使用 Placeholder 属性提供一个简短的提示，描述预期的文本区域输入。

有关详细信息，请参阅 TextArea 属性。

R2020b: 切换文本换行

使用 WordWrap 属性来切换文本换行。当 WordWrap 属性为 'on'（默认值）时，UI 组件将文本分成若干新行，以便每行都适应组件水平宽度。当该属性设置为 'off' 时，文本不会换行。

有关详细信息，请参阅 TextArea 属性。

另请参阅

函数

• uifigure | scroll

属性

• TextArea 属性

工具

• App 设计工具