TextField 文本输入

通用布局能力：RenderTextBox、RenderPasswordField 和 RenderSearchBox 实例统一支持 width、height、min/max、margin 和槽位对齐；fieldHeight 只表示输入主体高度，不再代表组件总高度。详见组件通用布局属性。

DirectSurface UI 的单行文本输入公共类名是 RenderTextBox。本页同时说明基于它封装的 RenderPasswordField 和 RenderSearchBox。

RenderTextBox 适合表单字段、查询条件、简短文本编辑、带前后缀的单行输入。它通过框架统一的 InputComposer 承接键盘、粘贴和中文 IME 输入，使用共享的输入焦点、选区、光标和剪贴板机制。

API 总览

主类：

• RenderTextBox
• RenderPasswordField
• RenderSearchBox

相关 public type：

• FormFieldStatus
• IconName

导入：

import {  RenderPasswordField,  RenderSearchBox,  RenderTextBox,  type FormFieldStatus,  type IconName,} from 'ds-ui'

RenderTextBox、RenderPasswordField 和 RenderSearchBox 的构造参数是公开 options 对象，但当前没有单独导出的 options 类型。业务代码直接按本文的参数表传入对象。

何时使用

• 单行文本输入，例如姓名、编码、关键字、备注短文本。
• 查询条件输入。
• 带前缀、后缀、清除按钮或尾部图标的输入框。
• 密码输入，使用 RenderPasswordField。
• 搜索输入，使用 RenderSearchBox。

不适合：

• 多行文本，使用 TextArea。
• 几十万行源码、JSON、日志，使用 PlainTextEditor。
• 数字输入，使用 NumberInput。
• 日期时间输入，使用 DatePicker。
• 下拉选择，使用 Dropdown 或相关 selector 组件。

最小示例

import { RenderTextBox } from 'ds-ui' const patientFormState = {  patientName: '',} const patientNameField = new RenderTextBox({  value: patientFormState.patientName,  placeholder: '输入姓名',  onChange: value => {    patientFormState.patientName = value  },})

组件关系

RenderFieldPresenter 字段壳

RenderFieldPresenter 不是输入控件，而是输入控件外层的字段语义壳。它把 label、必填标记、编辑器、单位、meta 文本和校验反馈排在稳定的字段行中；实际值、输入事件和提交逻辑仍由 child 维护。

RenderTextBox 构造参数

new RenderTextBox(options) 的 options：

const emailField = new RenderTextBox({  value: '',  placeholder: 'name',  prefixText: '@',  suffixText: '.hospital.local',  clearable: true,  maxLength: 40,  status: 'default',  helperText: '',  onChange: value => {    state.emailName = value  },})

RenderTextBox 属性

placeholder、onChange、onSubmit、password 是公开字段，不是 setter。运行时直接改这些字段时，框架不会自动知道视觉发生变化；如果改的是会影响绘制的字段，业务应重新触发一次布局或重绘，或者优先在构造阶段确定。

RenderTextBox 方法

const resettableField = new RenderTextBox({  value: 'old',}) resettableField.reset('new')

输入和键盘行为

如果设置了 onKeyDown，焦点系统会先调用它。返回 true 时会调用 preventDefault() / stopImmediatePropagation()，输入框自己的 Enter 提交、Escape 失焦等默认处理不会继续执行。典型用途是搜索框结果列表的 ArrowUp / ArrowDown / Enter 导航。普通提交仍优先使用 onSubmit；页面级快捷键优先放在父级 render object 的 handleUnhandledKeyDownFromDescendant / handleUnhandledEnterFromDescendant 中。

清除按钮和尾部图标

清除按钮显示条件：

• clearable === true
• value.length > 0
• 非 disabled
• 非 readonly

点击清除按钮会：

• 获得焦点。
• 把 value 设为空字符串。
• 光标定位到 0。
• 触发 onChange('')。

尾部图标由 trailingIcon 和 onTrailingIconClick 控制。点击尾部图标时组件会先获得焦点，再触发回调。RenderPasswordField 和 RenderSearchBox 都是基于尾部图标实现自己的行为。

const trailingIconField = new RenderTextBox({  value: 'keyword',  trailingIcon: 'search',  clearable: true,  onTrailingIconClick: () => {    service.search(state.keyword)  },  onChange: value => {    state.keyword = value  },})

只读和禁用

如果字段需要提交表单但当前不可修改，优先使用 readonly；如果字段不应参与交互，使用 disabled。

Placeholder 和状态颜色

placeholder 使用弱于真实值的颜色，避免和真实值混淆。状态色通过 status 控制：

helperText 可以和状态配合显示错误或提示。设置 helperText 会增加组件高度，布局容器需要给它足够空间。

const validatedField = new RenderTextBox({  value: '',  placeholder: '输入病历号',  status: 'error',  helperText: '病历号不能为空',})

RenderPasswordField

RenderPasswordField 是 RenderTextBox 的密码封装。它默认隐藏密码，尾部显示眼睛图标，点击后在隐藏和显示之间切换。

构造参数：

属性和方法：

const passwordField = new RenderPasswordField({  value: '',  placeholder: '输入密码',  clearable: true,  onChange: value => {    state.password = value  },  onRevealChange: revealed => {    state.passwordRevealed = revealed  },})

RenderSearchBox

RenderSearchBox 是搜索场景的单行输入。它默认 placeholder 为 搜索...，默认 clearable: true，尾部图标固定为 search。

构造参数：

属性和方法：

RenderSearchBox 覆盖了基础提交行为：按 Enter 会触发搜索，但不会自动失焦。这样连续按 Enter 可以执行“下一处搜索”等业务逻辑，除非用户主动点击其他可聚焦组件或按 Tab 移动焦点。

const orderSearchBox = new RenderSearchBox({  value: '',  placeholder: '搜索订单号或姓名',  onChange: value => {    state.orderQuery = value  },  onSearch: value => {    service.search(value)  },}) orderSearchBox.search()

如果搜索框需要驱动外部结果列表，可以用 onKeyDown 拦截方向键和 Enter：

const menuSearchBox = new RenderSearchBox({  value: '',  placeholder: '搜索菜单',  onChange: value => {    state.query = value    state.activeIndex = 0  },  onKeyDown: event => {    if (event.key === 'ArrowDown') {      if (state.results.length === 0) return true      state.activeIndex = Math.min(state.activeIndex + 1, state.results.length - 1)      return true    }    if (event.key === 'ArrowUp') {      if (state.results.length === 0) return true      state.activeIndex = Math.max(state.activeIndex - 1, 0)      return true    }    if (event.key === 'Enter') {      const result = state.results[state.activeIndex]      if (result) openResult(result)      return true    }    return false  },})

搜索下一处模式

对于 MarkdownViewer、PlainTextEditor、GridView 列搜索这类“同一个关键词连续跳转”的场景，推荐：

• onChange 更新关键字并重置当前结果。
• onSearch 执行下一处。
• Enter 不失焦，由 RenderSearchBox 默认行为保证。

const contentMarkdownViewer = new RenderMarkdownViewer({  markdown: '# 文档\n\n正文',}) const contentSearchBox = new RenderSearchBox({  value: '',  placeholder: '搜索当前文档',  onChange: value => {    state.contentQuery = value    contentMarkdownViewer.searchQuery = value  },  onSearch: () => {    const results = contentMarkdownViewer.getSearchResults()    if (results.length === 0) return    contentMarkdownViewer.scrollToSearchResult(results[0]!.id)  },})

布局和尺寸

• 默认宽度：父约束为无限宽时使用 200。
• 默认高度：来自主题 TextInputStyleTokens.height。
• helperText 会让整体高度增加 helperGap + helperLineHeight。
• fieldHeight 只控制输入框主体高度，不直接控制 helperText 高度；height 是所有组件一致的总高度约束。
• prefix、suffix、clear button、trailing icon 会占用输入行内空间，值文本会在剩余区域横向滚动。

在表单布局中，推荐用 FormPanel、GridPanel 或字段包装组件控制 label 和列宽，不要靠给 TextBox 写固定坐标。

生命周期

dispose() 会：

• 释放正在等待或已捕获的指针手势。
• 结束当前输入 session。
• dispose 内部输入控制器。
• 从 FocusManager 注销。
• 调用父类 dispose()。

页面关闭、弹窗关闭、tab 销毁时，应随页面一起释放输入组件，避免共享输入器或焦点管理器继续持有引用。

常见问题

为什么 SearchBox 按 Enter 后不失焦？

搜索通常需要连续按 Enter 跳转下一处。只有用户显式点击其他组件或按 Tab 移动焦点时，才应该丢失焦点。基础 RenderTextBox 仍保持 Enter 后失焦的表单提交行为。

为什么粘贴会把换行变成空格？

这是单行输入框。粘贴多行文本时，组件会把 \r\n、\r、\n 归一化为空格，并替换当前选区。

为什么大文本不能直接放 TextBox？

TextBox 是单行输入，聚焦后需要同步共享 textarea、测量光标和滚动位置。大文本会影响浏览器 textarea 和测量成本。大文本、JSON、日志应使用 PlainTextEditor。

readonly 和 disabled 应该怎么选？

需要用户能复制或查看完整内容时用 readonly。完全不可交互、不可聚焦时用 disabled。

为什么修改 placeholder 后没有立刻刷新？

placeholder 是公开字段，不是 setter。构造后动态修改时，业务需要让页面触发重绘；常规表单中更推荐在构造阶段传入固定 placeholder。

相关组件

• TextArea：多行文本输入。
• PlainTextEditor：大文本、代码、JSON、日志。
• NumberInput：数字输入。
• DatePicker：日期时间输入。
• Dropdown：单选下拉。
• GridView：查询结果表格。
• MarkdownViewer：文档搜索和阅读。