ICEN UI
ICEN UI 对话框
Docs ⌘K
Core · 稳定

对话框

让当前任务保持专注。支持多种尺寸、贴边面板、焦点约束和轻柔的进出场。

Preview
浮层 modal
html
<div class="demo-row">  <button class="icen-btn" data-icen-modal-open="demo-modal-sm">小号对话框</button>  <button class="icen-btn" data-icen-modal-open="demo-modal-md">默认对话框</button>  <button class="icen-btn" data-icen-modal-open="demo-modal-lg">大号对话框</button>  <button class="icen-btn" data-icen-modal-open="demo-sheet-right">右侧 Sheet</button></div><div class="icen-modal-backdrop" data-icen-modal="demo-modal-sm" hidden>  <div class="icen-modal icen-modal--sm">    <div class="icen-modal-header">      <div>        <h3 class="icen-modal-title">移到回收站？</h3>        <p class="icen-modal-description">文档仍可在回收站中恢复。</p>      </div>      <button class="icen-modal-close" data-icen-modal-close aria-label="关闭"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" focusable="false" class="icen-symbol" aria-hidden="true"><path d="M6 6l8 8M14 6l-8 8"></path></svg></button>    </div>    <div class="icen-modal-body">      <p>将「设计规范.md」移到回收站，不会影响已分享的副本。</p>    </div>    <div class="icen-modal-footer">      <button class="icen-btn icen-btn-sm" data-icen-modal-close>取消</button>      <button class="icen-btn icen-btn-sm icen-btn-primary" data-icen-modal-close data-demo-modal-action="已移到回收站（演示）">移到回收站</button>    </div>  </div></div><div class="icen-modal-backdrop" data-icen-modal="demo-modal-md" hidden>  <div class="icen-modal">    <div class="icen-modal-header">      <div>        <h3 class="icen-modal-title">保存工作区</h3>        <p class="icen-modal-description">为下次打开保留当前布局。</p>      </div>      <button class="icen-modal-close" data-icen-modal-close aria-label="关闭"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" focusable="false" class="icen-symbol" aria-hidden="true"><path d="M6 6l8 8M14 6l-8 8"></path></svg></button>    </div>    <div class="icen-modal-body">      <label class="icen-form-label" for="modal-workspace-name">工作区名称</label><div class="icen-input-wrap"><input class="icen-input" id="modal-workspace-name" value="设计工作区" autofocus required maxlength="40" /></div>      <p>保留已打开的文档、侧栏布局与当前外观设置。</p>    </div>    <div class="icen-modal-footer">      <button class="icen-btn icen-btn-sm" data-icen-modal-close>取消</button>      <button class="icen-btn icen-btn-sm icen-btn-primary" data-icen-modal-close data-demo-modal-action="工作区已保存（演示）">保存</button>    </div>  </div></div><div class="icen-modal-backdrop" data-icen-modal="demo-modal-lg" hidden>  <div class="icen-modal icen-modal--lg">    <div class="icen-modal-header">      <div>        <h3 class="icen-modal-title">发布前预览</h3>        <p class="icen-modal-description">检查内容，确认后再继续。</p>      </div>      <button class="icen-modal-close" data-icen-modal-close aria-label="关闭"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" focusable="false" class="icen-symbol" aria-hidden="true"><path d="M6 6l8 8M14 6l-8 8"></path></svg></button>    </div>    <div class="icen-modal-body">      <p>现代设计规范：让材质、排版和交互保持一致。</p>      <p>从按钮和菜单到完整的工作区，以清楚的层级承载内容，让操作自然出现。</p>    </div>    <div class="icen-modal-footer">      <button class="icen-btn icen-btn-sm" data-icen-modal-close>关闭</button>    </div>  </div></div><div class="icen-modal-backdrop" data-icen-modal="demo-sheet-right" hidden>  <div class="icen-modal icen-modal--sheet-right">    <div class="icen-modal-header">      <div>        <h3 class="icen-modal-title">文档详情</h3>        <p class="icen-modal-description">设计规范 · 今天更新</p>      </div>      <button class="icen-modal-close" data-icen-modal-close aria-label="关闭"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" focusable="false" class="icen-symbol" aria-hidden="true"><path d="M6 6l8 8M14 6l-8 8"></path></svg></button>    </div>    <div class="icen-modal-body">      <p>所有者：设计团队</p>      <p>可见范围：仅工作区成员</p>    </div>    <div class="icen-modal-footer">      <button class="icen-btn icen-btn-sm" data-icen-modal-close>关闭</button>    </div>  </div></div>

特性

接口

初始化
initModal()（kit 一行入口可直接命名导入）
导出
openModalcloseModal
事件
icen:modal-closeicen:modal-open detail 契约见 IcenEventMap
类型
dist/behaviors/modal.d.mts（随 npm 包发布，含全部 JSDoc 约束）

安装

bun add @icen.ai/ui

一行引入该组件（CSS 与 behavior 自动带上，无需关心内部 CSS 文件名）：

js
import '@icen.ai/ui/kit/modal';

也可以用脚手架直接打印引入行：

bash
bunx --bun @icen.ai/ui add modal

Astro 项目注意：kit 入口里的 CSS import 在页面 <script> 里会被 Astro 的 client bundle 摇掉——请改在布局 frontmatter 里引 CSS（import '@icen.ai/ui/components/modal.css';），JS 行为仍可走 kit。Vite SPA / webpack 项目无此问题。

用法

js
import { initModal, openModal, closeModal } from '@icen.ai/ui/kit/modal';import '@icen.ai/ui/kit/input'; // 本页输入型示例const dispose = initModal(); // 页面卸载时 dispose()，恢复门户与滚动锁openModal('confirm');   // 编程打开（可传 { initialFocus } 控制初始焦点）closeModal('confirm');  // 编程关闭；开合均派 icen:modal-open / icen:modal-close