Dialog API

v0.3.11 · Latest stable

Methods

Method	Signature	Description
openModal	(options: SoDialogModalOptions)	Open a modal dialog.
openOffcanvas	(options: Omit<SoDialogOffcanvasOptions, 'kind'>)	Open an offcanvas panel dialog.
confirmModal	(options?: SoDialogConfirmOptions)	Open a confirm dialog and return Promise<boolean>.
promptModal	(options?: SoDialogPromptOptions)	Open a prompt dialog and return `Promise<string
formModal	(options: SoDialogFormOptions)	Open a dynamic form dialog and return submitted values.
SoDialog.open	(options: SoDialogOptions)	Open modal or offcanvas by kind.

openModal

签名

openModal(options: SoDialogModalOptions): SoDialogHandle

参数

参数名	类型	默认值	必填	描述	Since	Deprecated
title	string | HTMLElement	-	是	Dialog 标题；HTMLElement 会原样放入标题区域。	-	-
content	string | Node	-	是	Dialog 主体内容。	-	-
width	number | string	auto	否	面板宽度；数字按 px 处理，字符串接受 CSS 尺寸。	-	-
preset	deploy	-	否	启用可选预设视觉风格。	-	-
closeOnEsc	boolean	true	否	是否允许 Escape 关闭。	-	-
onLayoutStable	SoLayoutStableHook	-	否	布局稳定后触发，用于测量、埋点或提示。	-	-

返回值

返回 SoDialogHandle，可调用 close()、refit()、setFooterButtons() 和 onAction()。

最小示例

import { openModal } from 'sodialog'

openModal({
  title: 'Hello',
  content: '<p>Your dialog is ready.</p>',
})

行为说明

openModal 默认使用原生 showModal()，保留 <dialog> 焦点语义。传入显式 width 或 height 后会优先采用显式尺寸。

边界情况

如果同一个 id 已存在，实例复用行为以当前实现为准；需要销毁时使用返回句柄或 footer action 的 destroy 策略。

相关 API

Open DemoModal 文档Adapter API

Core Options (SoDialogBaseOptions)

Name	Type	Required	Default	Description
title	string | HTMLElement	Yes	-	Dialog title text, or an HTMLElement rendered inside the title region.
content	string | Node	Yes	-	Dialog content.
hideHeader	boolean	No	false	Hide the generated header. Dialog keeps aria-label from title.
hideCloseButton	boolean	No	false	Hide the header close button.
closeButtonLabel	string	No	Close	Accessible label for the close button.
closeButtonText	string	No	×	Visible close button text.
confirmText	string	No	确认	Confirm button text.
cancelText	string	No	取消	Cancel button text.
confirmAction	'hide' | 'destroy'	No	hide	Confirm click close strategy.
closeOnEsc	boolean	No	true	Allow Esc to close the dialog.
closeOnBackdrop	boolean	No	true	Allow backdrop click close.
hideFooter	boolean	No	false	Hide default footer buttons.
footerAlign	'start' | 'center' | 'end' | 'between'	No	end	Footer layout alignment.
footerButtons	SoDialogFooterButton[]	No	built-in confirm/cancel	Custom footer buttons.
traceId	string	No	-	Diagnostic trace identifier.
onLayoutStable	(ctx) => void	No	-	Triggered when layout is stable.
onAction	(ctx) => void	No	-	Triggered on footer actions.
onLifecycle/onBeforeOpen/...	SoLifecycleHook	No	-	Dialog lifecycle hooks.

Modal-only Options (SoDialogModalOptions)

Name	Type	Default	Description
id	string	auto id	Reuse an existing modal instance by id.
position	'center' | 'top' | 'bottom'	center	Modal position.
animation	'slide' | 'fade' | 'zoom'	fade	Modal animation.
width	number | string	auto	Panel width. Numbers are interpreted as pixels; strings accept CSS sizes.
height	number | string	auto	Panel height. Numbers are interpreted as pixels; strings accept CSS sizes.
useModal	boolean	true	Use native showModal() behavior.
draggable	boolean	true	Enable drag interactions. Set false to disable dragging.
dragHandle	SoModalDragHandle | false	header	Drag handle selector target(s). Supports header, title, body, footer, panel, CSS selectors, arrays, or false.
autoFitSize	boolean	true	Auto fit panel to content changes.
scrollMode	'body' | 'viewport' | 'none' | 'hybrid'	auto	Auto-fit scroll strategy.

Providing width or height disables automatic modal sizing so the explicit dimensions take precedence.

Presets

preset: 'deploy' applies the compact confirmation style used by deploy/release dialogs. It is implemented as the sod-preset-deploy class inside the standard stylesheet, so it keeps zero runtime dependencies and can still be overridden with --sod-* CSS variables.

Offcanvas-only Options (SoDialogOffcanvasOptions)

Name	Type	Default	Description
placement	'start' | 'end' | 'top' | 'bottom'	end	Panel placement.
animation	'slide' | 'fade' | 'zoom'	slide	Offcanvas animation.
width	number | string	placement default	Panel width. Numbers are interpreted as pixels; strings accept CSS sizes.
height	number | string	placement default	Panel height. Numbers are interpreted as pixels; strings accept CSS sizes.

Return Handle (SoDialogHandle)

openModal and openOffcanvas return a SoDialogHandle which can be used to close, update, or inspect state.

Field	Type	Description
dialog	HTMLDialogElement	Native dialog element.
close	() => void	Close dialog.
refit	() => void	Trigger layout refit manually.
setFooterButtons	(buttons) => void	Replace footer button set.
updateFooterButton	(id, updates) => boolean	Patch one button by id.
onAction	(listener) => () => void	Subscribe footer actions and return unsubscribe.

Usage Example

import { openModal } from 'sodialog'

const handle = openModal({
  title: 'Delete item',
  content: '<p>Do you want to continue?</p>',
  confirmText: 'Delete',
  cancelText: 'Cancel',
})

handle.close()

Related

• Modal Guide
• Offcanvas Guide
• API Overview