xiaoye-components

Appearance

Dialog 对话框 ​

xy-dialog 是当前组件库里唯一的标准对话框入口。当前文档按增强计划整理，覆盖模板能力、工作台级体验增强，以及已经可用的编程式 DialogService。

迁移提示 ​

  • 后台项目里如果只是想统一 dialog 的背景、边框、阴影和分区节奏，优先使用：
    • panel-class
    • header-class / body-class / footer-class
    • modal-class
    • 对应 --xy-dialog-* 变量
  • 不建议继续在页面层 deep 到 .xy-dialog__header / __body / __footer / __panel。
  • 自定义 header 时，优先继续使用 title 作为可访问名称兜底，或者把 titleId 绑定到真实标题节点；不要为了视觉接管把结构语义一起丢掉。

基础用法 ​

最常见的场景是表单录入或二次确认，并通过 footer 插槽放一组操作按钮。

基础用法模态弹窗

点击按钮打开对话框，支持自定义标题、内容和底部操作。

异步确认与提交中态 ​

删除、归档和发布这类动作通常不会立即结束，对话框关闭时机应该由异步结果决定。

最近一次归档：尚未执行

自定义头部与关闭策略 ​

自定义头部时，推荐继续使用 title 属性，或者把 titleId 透传给实际标题节点，确保屏幕阅读器仍能正确读取对话框标题。

关闭控制与结构裁剪 ​

before-close、show-close 和 lock-scroll 适合更严格的确认场景；不传 title 时则不会渲染默认标题结构。

已开启 beforeClose 拦截

嵌套对话框 ​

嵌套场景下，内层对话框应开启 append-to-body，避免被父层布局和层级影响。

头尾居中 ​

center 只负责头部和底部对齐方式，适合更强调确认动作的居中布局。

垂直居中 ​

align-center 会让对话框在视口里同时水平、垂直居中，此时 top 不再参与布局。

按需销毁 ​

destroy-on-close 适合内容较重、首次打开才需要挂载的场景。

主体已挂载 0 次

拖拽与越界 ​

开启 draggable 后可以拖拽头部，overflow 则允许拖出视口。

可拖拽Draggable

拖动对话框头部可自由调整位置，支持限制在视口内。

限制在视口内

全屏与最大化 ​

工作台级弹层通常需要全屏和最大化切换；fullscreen 和 maximizable 已经可以组合成统一的窗口操作体验。

普通模式

遮罩与穿透 ​

关闭遮罩后可以继续保留 dialog 容器，modal-penetrable 适合做非阻断的浮动工作台。

显示遮罩
拦截背景点击

自定义动画 ​

transition 支持字符串过渡名或 Vue Transition 对象，适合为不同业务氛围定制切入方式。

调整尺寸 ​

工作台级 dialog 常常需要拖拽调整尺寸，并配合最小最大边界一起使用。

最近一次尺寸调整：尚未触发

固定头尾与长内容滚动 ​

sticky-header、sticky-footer 和 body-max-height 更适合长表单、对账明细和批量确认场景。

加载遮罩 ​

loading 和 loading-text 适合 body 内部仍在提交或加载时的过渡态。

Dialog 的默认 loading 视觉已与独立 Loading 对齐，会读取 ConfigProvider.loading 的 text / spinner / svg / svgViewBox / background。如果组件上显式传了 loading-text，局部值仍然优先；delay / minDuration / fullscreen / lock 不会影响 Dialog 自身的既有交互时序。

编程式打开 ​

open() 是通用入口，可承载 message、render 或 component 三类内容来源。

示例已接入真实 `XyDialogService.open()`。

编程式确认 ​

confirm() 更适合删除、发布、归档这类标准确认场景，返回布尔结果即可驱动业务流程。

最近一次 confirm()：尚未调用

编程式输入 ​

prompt() 面向带输入校验的轻量弹框流程，例如命名、备注和二次确认口令。

最近一次 prompt()：尚未调用

何时使用 ​

  • 阻断式录入，例如新建成员、编辑敏感配置。
  • 二次确认，例如删除、停用、归档、发布。
  • 强提示或需要用户显式处理的内容阅读。
  • 需要保留上下文、同时承载较大工作区时，可以把 Dialog 当作中心工作台面板使用。

使用建议

如果内容只是补充说明或轻量交互，不需要阻断主页面时，优先使用 xy-popover。只有在需要强制用户处理当前任务时，再使用 xy-dialog。

无障碍说明 ​

  • 使用默认标题时，会自动建立 aria-labelledby。
  • 自定义 header 或兼容 title 插槽时，推荐继续保留 title 属性，或者把插槽参数里的 titleId 绑定到实际标题元素。
  • 如果自定义头部完全不使用 titleId，组件会回退到 aria-label=title。因此在自定义 header 场景里，最好不要省略 title。
  • open-auto-focus 与 close-auto-focus 分别对应打开后的自动聚焦和关闭后的焦点恢复，可用来补业务日志或埋点。

ConfigProvider 默认项 ​

增强计划里，ConfigProvider 会为 Dialog 提供 DialogGlobalConfig 这组全局默认配置：

ts
type DialogGlobalConfig = ConfigProviderProps["dialog"];
  • ConfigProvider.dialog 只负责高频默认值，不覆盖业务本身的内容结构。
  • 局部 Dialog props 优先级高于全局默认项。
  • DialogService 也应复用同一套默认值，避免模板式和编程式调用出现行为漂移。

DialogService 用法 ​

当前可直接使用的导出如下：

ts
import {
  XyDialogService,
  type DialogServiceHandle,
  type DialogServiceOpenOptions,
  type DialogServiceResult
} from "xiaoye-components";

通用 open ​

ts
const handle = XyDialogService.open({
  title: "批量发布确认",
  message: "当前操作会同步 12 个菜单入口。",
  dialogProps: {
    width: 560,
    closeOnClickModal: false
  }
});

const result = await handle.result;

confirm / alert / prompt ​

ts
const confirmed = await XyDialogService.confirm({
  title: "删除成员",
  message: "删除后不可恢复，是否继续？"
});

await XyDialogService.alert({
  title: "发布完成",
  message: "所有变更已同步到生产环境。"
});

const promptResult = await XyDialogService.prompt({
  title: "输入发布口令",
  inputPlaceholder: "请输入口令",
  inputValidator(value) {
    if (!value.trim()) {
      return "口令不能为空";
    }
  }
});

结果约定 ​

ts
const result: DialogServiceResult = await handle.result;

Dialog Service Handle ​

字段说明类型
id当前 service 弹框实例标识DialogServiceHandle["id"]
close主动关闭当前弹框DialogServiceHandle["close"]
update更新当前弹框配置DialogServiceHandle["update"]
result关闭后的结果 PromiseDialogServiceHandle["result"]

Dialog Service Result ​

字段说明类型
action最终关闭动作DialogServiceResult["action"]
valueprompt 场景下的输入值DialogServiceResult["value"]
  • alert() 适合单按钮提示。
  • confirm() 返回布尔值，适合标准确认流程。
  • prompt() 返回 { confirmed, value }，适合轻量输入。

API ​

Dialog Attributes ​

属性说明类型默认值
model-value是否打开对话框booleanfalse
title对话框标题string''
append-to-body是否 teleport 到 bodybooleanfalse
append-toteleport 挂载目标string | HTMLElement'body'
before-close关闭前拦截函数，仅拦截内建关闭入口，并透出关闭原因DialogBeforeCloseFnundefined
destroy-on-close关闭后是否销毁内容booleanfalse
close-on-click-modal点击遮罩是否关闭booleantrue
close-on-press-escape按下 Escape 是否关闭booleantrue
lock-scroll打开时是否锁定 body 滚动booleantrue
modal是否显示遮罩层booleantrue
modal-class遮罩容器自定义类名string''
panel-class面板容器自定义类名string''
modal-penetrable无遮罩时是否允许穿透点击背景booleanfalse
open-delay打开延迟，单位毫秒number0
close-delay关闭延迟，单位毫秒number0
top非垂直居中时的顶部偏移string'15vh'
width对话框宽度string | number'50%'
z-index自定义层级numberundefined
center是否让头部和底部内容居中booleanfalse
align-center是否让对话框在视口中垂直居中booleanfalse
close-icon自定义关闭图标，增强计划里支持 string | Componentstring | Component'mdi:close'
draggable是否允许通过头部拖拽对话框booleanfalse
overflow拖拽时是否允许超出视口booleanfalse
fullscreen是否全屏显示booleanfalse
maximizable是否显示最大化/还原按钮booleanfalse
resizable是否允许通过右下角手柄调整尺寸booleanfalse
min-width调整尺寸时的最小宽度string | numberundefined
max-width调整尺寸时的最大宽度string | numberundefined
min-height调整尺寸时的最小高度string | numberundefined
max-height调整尺寸时的最大高度string | numberundefined
sticky-header是否固定头部booleanfalse
sticky-footer是否固定底部booleanfalse
body-max-heightbody 区域最大高度string | numberundefined
loading是否显示 body 内部加载遮罩booleanfalse
loading-text加载文案string''
header-class头部区域自定义类名string''
body-class主体区域自定义类名string''
footer-class底部区域自定义类名string''
show-close是否显示右上角关闭按钮booleantrue
header-aria-level默认标题的 aria-levelstring'2'
transition自定义过渡配置，支持过渡名或 Vue Transition 对象string | TransitionProps'xy-dialog-fade'

Dialog Events ​

事件说明参数
update:model-value对话框开关状态变化时触发DialogModelValueChangeHandler
update:fullscreen最大化/还原切换时触发DialogFullscreenChangeHandler
open打开时触发—
opened进入完成后触发—
close关闭时触发—
closed离开完成后触发—
open-auto-focus打开后完成自动聚焦时触发—
close-auto-focus关闭后恢复焦点时触发—
maximize切换到全屏/最大化时触发—
restore从全屏/最大化恢复时触发—
resize-start开始调整尺寸时触发DialogResizeHandler
resize调整尺寸过程中触发DialogResizeHandler
resize-end结束调整尺寸时触发DialogResizeHandler

Dialog Slots ​

插槽说明
default对话框主体内容
header自定义头部内容，透出 close、titleId、titleClass
footer自定义底部操作区
title与 header 兼容的旧式标题插槽，建议仅在迁移期使用

Dialog Exposes ​

名称说明类型
visible当前可见状态DialogInstance["visible"]
dialogContentRef内容层实例，可继续访问拖拽和尺寸控制方法DialogInstance["dialogContentRef"]
resetPosition重置拖拽位移DialogInstance["resetPosition"]
handleClose触发内建关闭流程，可显式指定关闭原因DialogInstance["handleClose"]