TextInput 是一个底层项，用于显示文本并允许输入文本。 你可能不应该直接使用它，而应该使用 或 组件。

当不属于布局时，其宽度和高度默认为父元素的 100%。

当光标位于可见区域之外时，TextInput 不会自动滚动。 确保这一点是封闭控件的责任，它可以使用 cursor-position-changed 回调来实现。

示例

export component Example inherits Window {    width: 270px;    height: 40px;    Rectangle {        clip: true;
        TextInput {            text: "Edit me";            width: max(parent.width, self.preferred-width);            vertical-alignment: center;
            private property <length> margin: 1rem;            cursor-position-changed(cursor-position) => {                if cursor-position.x + self.x < margin {                    self.x = - cursor-position.x + margin;                } else if cursor-position.x + self.x > parent.width - margin - self.text-cursor-width {                    self.x = parent.width - cursor-position.x - margin - self.text-cursor-width;                }            }        }    }}

属性

color

brush 默认：depends on the style

文本的颜色。

font-family

string 默认：""

用于渲染文本的字体系列的名称。

font-size

length 默认：0px

文本的字体大小。

font-weight

int 默认：0

字体的粗细。值范围从 100（最细）到 900（最粗）。400 是常规粗细。

font-italic

bool 默认：false

字体外观是否应以斜体绘制。

font-metrics

struct FontMetrics (out) 默认：a struct with all default values

按元素使用的字体像素大小缩放的字体设计度量。

FontMetrics

用于保存指定像素大小的字体度量的结构。

• ascent (length)：基线到字体中最高字形顶部的距离。
• descent (length)：基线到字体中最高字形底部的距离。通常为负值。
• x_height (length)：基线到字体中最高字形水平中点的距离；如果字体未指定则为零。
• cap_height (length)：基线到字体中常规大写字形顶部的距离；如果字体未指定则为零。

has-focus

bool (out) 默认：false

当 TextInput 获得焦点时，它将此属性设置为 true。只有在这种情况下它才会接收 KeyEvent。

horizontal-alignment

enum TextHorizontalAlignment 默认：the first enum value

文本的水平对齐方式。

TextHorizontalAlignment

此枚举描述 Text 或 StyledText 元素沿水平轴的不同对齐方式。

• start：文本将与包含框的起始边缘对齐。这可能是左或右，取决于文本的方向。
• end：文本将与包含框的结束边缘对齐。这可能是左或右，取决于文本的方向。
• left：文本将与包含框的左边缘对齐。
• center：文本将在包含框内水平居中。
• right：文本将与包含框的右边缘对齐。

input-type

enum InputType 默认：text

使用此属性来配置 TextInput 以编辑特殊输入，例如密码字段。

InputType

此枚举用于定义输入字段的类型。

• text：默认值。这将正常渲染所有字符。
• password：这将使用默认为 ”*“ 的字符渲染所有字符。
• number：这将仅接受并渲染数字字符（0-9）。
• decimal：如果字符是小数的有效部分，这将会接受并渲染它们。

letter-spacing

length 默认：0

字符间距允许更改字形之间的间距。正值增加间距，负值减小距离。

page-height

length 默认：0px

用于计算用户按下 Page Up 或 Page Down 时滚动量的页面高度。

read-only

bool 默认：false

当设置为 true 时，通过键盘和鼠标的文本编辑被禁用，但仍然可以选择文本并以编程方式编辑文本。

selection-background-color

color 默认：a transparent color

选区的背景颜色。

selection-foreground-color

color 默认：a transparent color

选区的前景颜色。

single-line

bool 默认：true

当设置为 true 时，无论文本中是否有换行分隔符，文本始终渲染为单行。

text-cursor-width

length 默认：provided at run-time by the selected widget style

文本光标的宽度。

text

string (in-out) 默认：""

由用户渲染和编辑的文本。

vertical-alignment

enum TextVerticalAlignment 默认：the first enum value

文本的垂直对齐方式。

TextVerticalAlignment

此枚举描述 Text 或 StyledText 元素沿垂直轴的不同对齐方式。

• top：文本将与包含框的顶部对齐。
• center：文本将在包含框内垂直居中。
• bottom：文本将与包含框的底部对齐。

wrap

enum TextWrap 默认：no-wrap

文本输入的换行方式。仅在 single-line 为 false 时才有意义。

TextWrap

此枚举描述当文本过宽无法放入 Text 或 StyledText 元素的宽度时如何换行。

• no-wrap：文本不会换行，而是会溢出。
• word-wrap：文本将尽可能在单词边界处换行，对于很长的单词则在任意位置换行。
• char-wrap：文本将在任意字符处换行。目前仅由 Qt 和 Software 渲染器支持。

函数

focus()

调用此函数以使文本输入获得焦点并接收将来的键盘事件。

clear-focus()

如果此 TextInput 当前具有焦点，调用此函数以移除键盘焦点。另请参见 焦点处理。

set-selection-offsets(start: int, end: int)

选择两个 UTF-8 偏移量之间的文本。

select-all()

选择所有文本。

clear-selection()

清除选择。

copy()

将所选文本复制到剪贴板。

cut()

将所选文本复制到剪贴板并将其从可编辑区域中移除。

paste()

在光标位置粘贴剪贴板的文本内容。

回调

accepted()

当按下 Enter 键时调用。

cursor-position-changed(position: Point)

光标已移动到由 Point 参数描述的新的 (x, y) 位置。

edited()

当文本因用户修改而发生更改时调用。

key-pressed(event: KeyEvent) -> EventResult

当按键被按下时调用，参数是一个 KeyEvent 结构。使用此回调在 TextInput 之前处理按键。返回 accept 表示你已处理该事件，或返回 reject 让 TextInput 处理它。

key-released(event: KeyEvent) -> EventResult

当按键被释放时调用，参数是一个 KeyEvent 结构。使用此回调在 TextInput 之前处理按键。返回 accept 表示你已处理该事件，或返回 reject 让 TextInput 处理它。

可访问性

默认情况下，TextInput 元素具有以下可访问性属性：

• accessible-role: text-input;
• accessible-value: text;
• accessible-enabled: enabled;
• accessible-read-only: read-only;