Main Content

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.";

Text area in a UI figure window. The text area is vertically scrollable.

滚动到文本区域的底部。

scroll(txa,"bottom")

Text area in a UI figure window. The text area is scrolled to the 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 按钮。

Label, text area, and button in a UI figure window. At the top is a label with text "Enter Comments:". Below is a text area with text "Great app!". At the bottom is a Submit button.

输入参数

全部折叠

父容器，指定为使用 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 指定为数组。数组中的每个元素代表一行文本。

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

Text area with four lines of text labeled Line 1 through Line 4

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

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

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

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

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

  • 函数句柄。

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

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

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

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

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

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

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

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

  • 函数句柄。

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

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

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

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

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

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

示例: [100 100 100 90]

版本历史记录

在 R2016a 中推出

全部展开

另请参阅

函数

属性

工具