Prompt 输入对话框

通用布局能力：RenderPromptModal 继承 RenderBox 的尺寸、min/max、margin 和槽位对齐属性；作为 modal 打开时，viewport 居中和默认面板尺寸仍由 Prompt 规则控制。详见组件通用布局属性。

RenderPromptModal 是单行输入型模态对话框。它在 Modal 的阻断式遮罩和按钮区基础上内置一个 RenderTextBox，适合快速收集一段简短文本。

Prompt 不是通用表单容器：当前只支持一个单行输入框，没有内置校验、错误提示、多字段布局或富文本输入。复杂表单应使用 Drawer、RenderWindow，或业务自定义 popup。

API 总览

import {  AppOverlayService,  RenderPromptModal,} from 'ds-ui'

最小装配顺序有两种：业务流程优先调用 AppOverlayService.prompt(options)；需要精确控制实例时创建 RenderPromptModal，并在 onClose 或页面释放时 dispose()。

何时使用

使用 Prompt：

• 重命名。
• 输入简短备注、原因或命令参数。
• 需要用户立即输入一段短文本，并明确确认/取消。

不要使用：

• 多字段表单，使用 Drawer 或页面级表单。
• 长文本输入，使用 TextArea 或专门编辑器。
• 需要复杂校验和错误展示的流程，使用自定义对话框。
• 只需要确认/取消而不输入文本，使用 Modal。

最小示例

const prompt = new RenderPromptModal({  title: '重命名',  content: '请输入新名称',  value: currentName,  placeholder: '名称',  onClose: (key, value) => {    if (key === 'ok') rename(value)  },}) prompt.show()

直接使用 RenderPromptModal 时，关闭后需要由调用方释放，或在 onClose 中 dispose()。

AppOverlayService 示例

业务页面更常用 AppOverlayService.prompt()，它返回 Promise<string | null> 并自动释放 modal：

const overlayService = new AppOverlayService() overlayService.prompt({  title: '重命名',  content: '请输入新的演示名称',  initialValue: currentName,  placeholder: '名称',}).then(value => {  if (value !== null) rename(value)})

返回语义：

空字符串 '' 是合法输入值，不等同于取消。业务判断应使用 value !== null，不要直接用 truthy 判断。

构造参数

默认按钮：

[  { label: '取消', key: 'cancel' },  { label: '确认', key: 'ok', primary: true },]

AppPromptDialogOptions

AppOverlayService.prompt() 使用的选项：

prompt() 会先 closeModal()，因此会关闭当前 active Modal/Prompt，然后打开新的 prompt。

属性和方法

value 会随着输入框 onChange 更新。hide() 时会再次读取输入框当前值并传给 onClose。

键盘和鼠标行为

当前实现没有按钮级禁用，也没有内置校验失败阻止关闭的机制。业务需要校验时，应在 Promise 返回后处理，或实现自定义输入对话框。

绘制和布局

Prompt 使用 Modal 的视觉 token：

1. 全屏遮罩。
2. 居中面板阴影、背景和边框。
3. 标题栏和分隔线。
4. content 说明文本。
5. 单行输入框。
6. 底部按钮。

默认面板尺寸是 420 x 220。输入框位置由标题栏高度、modal padding 和 deriveTextInputStyle(theme).height 计算。每次 paint 前会同步 viewport 尺寸和输入框布局，因此窗口尺寸变化后仍保持居中。

App Context

和 Modal 一样，Prompt 可以提供局部 App Context：

const reasonKey = createAppContextKey<string>('prompt.reason')const promptContext = new AppContextRegistry(undefined, [  [reasonKey, '默认原因'],]) const prompt = new RenderPromptModal({  title: '填写原因',  content: '请输入原因',  value: promptContext.require(reasonKey),  appContext: promptContext,  disposeAppContextOnDispose: true,}) prompt.show()

通过 AppOverlayService.prompt() 时，可使用 source、context、contextValues 和 disposeContextOnClose 管理局部上下文生命周期。

生命周期

直接使用时：

let prompt!: RenderPromptModal prompt = new RenderPromptModal({  title: '重命名',  content: '请输入新名称',  onClose: () => {    prompt.dispose()  },}) prompt.show()

AppOverlayService.prompt() 已经在内部处理关闭后的 dispose()，业务只需要处理 Promise 结果。

注意：

• hide() 只关闭并触发回调，不自动 dispose。
• dispose() 会先 close()，然后释放动画和子输入框。
• disposeAppContextOnDispose 为 true 时会释放局部上下文。
• 打开新的 prompt 前，AppOverlayService.prompt() 会关闭当前 active modal。

性能边界

• Prompt 是短生命周期组件，绘制成本低。
• 输入变化只更新内部单行输入框和 overlay 重绘，不应承载复杂页面。
• 长文本不会自动变成多行，输入框仍是单行 TextBox。
• 不要用 Prompt 实现复杂表单校验流程。

常见问题

为什么点击遮罩不关闭？

Prompt 继承阻断式对话框语义，遮罩点击只消费事件，不关闭。取消应通过取消按钮、Escape 或程序调用。

为什么没有校验？

当前实现没有内置校验、错误提示或禁用确认按钮能力。需要复杂校验时应使用自定义 popup 或页面级表单。

为什么空字符串会进入 then 分支？

AppOverlayService.prompt() 的确认结果是 string，取消结果是 null。空字符串是合法确认值。判断时使用 value !== null。

Enter 是否总是确认？

是。Prompt 的 onKeyDown 和内部输入框 submit 都会以 ok 关闭。

能放多个输入框吗？

不能。当前只内置一个 RenderTextBox。多字段场景应使用 Drawer、窗口或自定义 popup。

相关文档

• Modal 模态框
• Popup 浮层系统
• Drawer 抽屉
• TextField / TextBox
• App Context