对话框 · Dialog

展示模态内容，并在打开和关闭时管理焦点。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

• 对话框 · 综合展示 1：首先体验这个示例，再查看代码理解组件的组合方式。
• 对话框 · 综合展示 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 对话框 · 交互示例 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 对话框 · 交互示例 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 对话框 · 交互示例 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 对话框 · 交互示例 6：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 对话框 · 基础用法 7：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 对话框 · 交互示例 8：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 对话框 · 交互示例 9：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

Dialog

Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped.

使用建议

• Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond.
• Include a clear title in the header so users immediately understand what the dialog is asking.
• Use purpose="form" for dialogs with inputs so the user can't accidentally lose data by clicking the backdrop.
• Keep dialogs focused on a single task; if the content grows beyond what fits, consider a full page instead.
• 避免：Use a dialog for simple messages that could be shown inline or as a toast notification.
• 避免：Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.
• 避免：Use the fullscreen variant for simple confirmations; it is meant for complex content like editors or long forms.

主题 API

{
  "container": true,
  "targets": [
    {
      "className": "astryx-dialog",
      "visualProps": [
        "variant"
      ]
    },
    {
      "className": "astryx-dialog-header"
    },
    {
      "className": "astryx-dialog-header-start-content"
    },
    {
      "className": "astryx-dialog-header-title-block"
    },
    {
      "className": "astryx-dialog-header-end-content"
    },
    {
      "className": "astryx-dialog-header-close-icon"
    }
  ],
  "vars": [
    {
      "name": "--_dialog-radius",
      "description": "Border radius of the dialog",
      "default": "var(--radius-container)",
      "private": true
    }
  ],
  "derived": [
    {
      "property": "borderRadius",
      "vars": [
        "--_dialog-radius"
      ]
    },
    {
      "property": "padding",
      "expand": "container"
    }
  ]
}

DialogHeader

useImperativeDialog

组件结构

• Header: Title, optional subtitle, and close button. The title receives focus on open and labels the dialog via aria-labelledby.
• Body: The main content area: text, forms, lists, or any layout.
• Footer: Action buttons like Save/Cancel or Accept/Decline, aligned to the end.
• Backdrop: Semi-transparent overlay behind the dialog that blocks page interaction.

Dialog Header

使用 DialogHeader 为对话框提供带标签的标题区和可选的关闭控件。

Basic

import {DialogHeader} from '@astryxdesign/core/Dialog';

<DialogHeader title="Delete file?" subtitle="This action cannot be undone." />;

With close button

import {useState} from 'react';
import {DialogHeader} from '@astryxdesign/core/Dialog';

function Header() {
  const [, setIsOpen] = useState(true);

  // Passing onOpenChange renders a close button that calls it with false.
  return <DialogHeader title="Settings" onOpenChange={setIsOpen} />;
}

With a link in the subtitle

import {DialogHeader} from '@astryxdesign/core/Dialog';
import {Link} from '@astryxdesign/core/Link';

<DialogHeader
  title="Share conversation"
  subtitle={
    <>
      Anyone with the link can view it. Review the{' '}
      <Link href="#sharing-policy">sharing policy</Link> first.
    </>
  }
/>;

With start and end content

import {DialogHeader} from '@astryxdesign/core/Dialog';
import {Icon} from '@astryxdesign/core/Icon';
import {Badge} from '@astryxdesign/core/Badge';

<DialogHeader
  title="Notifications"
  startContent={<Icon icon="chevronLeft" size="sm" />}
  endContent={<Badge label="3" />}
/>;

主题 API

{
  "targets": [
    {
      "className": "astryx-dialog-header"
    },
    {
      "className": "astryx-dialog-header-start-content"
    },
    {
      "className": "astryx-dialog-header-title-block"
    },
    {
      "className": "astryx-dialog-header-end-content"
    },
    {
      "className": "astryx-dialog-header-close-icon"
    }
  ]
}

组件结构

• Header row: 排列标题区、可选的首尾内容和关闭控件。
• Start content: 包装可选的首部内容。
• Title block: 组合标题和可选副标题。
• End content: 组合可选尾部内容和可选关闭控件。
• Close icon: 关闭按钮内的关闭图标。

useImperativeDialog

Hook for showing a dialog without managing open state. Call dialog.show(content, options) to open and dialog.hide() to close. Render dialog.element in your JSX tree.