Alune 组件

DialogParts

用卡片、路径、统计、后果说明和确认控件组织弹窗正文。RepoRow 的 meta 放置补充说明,DialogPath 可传入组合内容(如 a → b)。

使用方式

弹窗内容组合由宿主传入状态和回调,适合在不同应用和文档中复用。先完成快速开始中的 Provider 与样式配置。

import { DialogCard, DialogPath, RepoRow, DialogStats, DialogStat, DialogLedger, DialogNote, DialogEmpty, DialogProgress, OptionCards, DialogHints, Kbd, CheckCard } from '@alune/ui';

接入要求见快速开始,选择依据见 交互与无障碍规范。

运行示例

运行与复制源码来自同一 TSX 文件。浮层、状态和主题独立于文档;所有回调只更新本地模拟数据。

真实示例 TSX 独立预览 ↗
查看运行源码
源码文件
import { useState } from 'react';
import {
  DialogCard,
  DialogPath,
  RepoRow,
  DialogStats,
  DialogStat,
  DialogLedger,
  DialogNote,
  DialogEmpty,
  DialogProgress,
  OptionCards,
  DialogHints,
  Kbd,
  CheckCard,
} from '@alune/ui';

export default function Example() {
  const [value, setValue] = useState<'safe' | 'fast'>('safe');
  const [checked, setChecked] = useState(false);
  return (
    <div className="example">
      <section className="example-group">
        <h2 className="example-title">仓库与变更摘要</h2>
        <div className="example-stack">
          <DialogCard pad>
            <RepoRow
              name="示例项目"
              path="/example/alune"
              meta={<DialogPath>feature/example → main</DialogPath>}
            />
            <DialogPath path="src/components/Example.tsx" />
            <DialogStats>
              <DialogStat value={3} label="文件" tone="info" />
              <DialogStat value={0} label="失败" off />
            </DialogStats>
          </DialogCard>
          <DialogLedger
            change={[{ icon: 'x', text: '示例草稿' }]}
            keep={[{ icon: 'check', text: '已保存内容' }]}
          />
        </div>
      </section>
      <section className="example-group">
        <h2 className="example-title">说明与进度</h2>
        <div className="example-stack">
          <DialogNote title="说明" tone="warning">
            静态后果说明在确认前始终可见。
          </DialogNote>
          <DialogEmpty>暂无选项</DialogEmpty>
          <DialogProgress value={0.6} label="已完成 60%" />
        </div>
      </section>
      <section className="example-group">
        <h2 className="example-title">选项与确认</h2>
        <div className="example-stack">
          <OptionCards
            label="处理方式"
            value={value}
            onChange={setValue}
            options={[
              { value: 'safe', title: '安全检查', description: '先核对结果' },
              { value: 'fast', title: '快速执行', description: '适用于模拟数据' },
            ]}
          />
          <CheckCard
            checked={checked}
            onChange={setChecked}
            title="我已核对操作范围"
            description="勾选只改变此示例状态"
          />
          <DialogHints>
            <Kbd>Esc</Kbd> 取消
          </DialogHints>
        </div>
      </section>
    </div>
  );
}

API

DialogCard

DialogCard 是通用组合成员,具体属性见关联 Props 表,运行效果见上方示例。

查看 DialogCard 实现 ↗

DialogCardProps

属性 / 方法 类型 默认值 必填 说明
children ReactNode — 是 渲染的子内容。
pad boolean — 否 添加卡片内部间距。
className string — 否 附加 CSS 类名。

查看 DialogCardProps 实现 ↗

DialogPath

DialogPath 是通用组合成员,具体属性见关联 Props 表,运行效果见上方示例。

查看 DialogPath 实现 ↗

DialogPathProps

属性 / 方法 类型 默认值 必填 说明
path string — 否 文件或目录路径,只读取名称,不访问文件系统。
className string — 否 附加 CSS 类名。
children ReactNode — 否 渲染的子内容。

查看 DialogPathProps 实现 ↗

RepoRow

RepoRow 是通用组合成员,具体属性见关联 Props 表,运行效果见上方示例。

查看 RepoRow 实现 ↗

RepoRowProps

属性 / 方法 类型 默认值 必填 说明
name ReactNode — 是 展示名称。
path ReactNode — 否 文件或目录路径,只读取名称,不访问文件系统。
meta ReactNode — 否 参见类型定义及对应实现。
icon "warning" | "info" | "x" | "arrow-right" | "arrow-up-right" | "check" | "caret" | "trash" | "lock" | "key" | "server" | "folder" | "folder-open" | "branch" | "merge" | "pr" | "archive" | "cloud-up" | "cloud-down" | "globe" | "user" | "mail" | "terminal" | "laptop" | "search" | "bell" | "copy" | "eye" | "eye-off" | "link" | "sparkle" | "sliders" | "columns" | "download" | "moon" | "sun" | "wave" | "file" | "file-plus" | "refresh" | "plus" | "pencil" | "swap" | "shield" | "plug" | "tree" | "commit" | "chat" | "dots" | "clock" | "undo" 'folder' 否 图标内容或图标名。
children ReactNode — 否 渲染的子内容。

查看 RepoRowProps 实现 ↗

DialogStats

DialogStats 是通用组合成员,具体属性见关联 Props 表,运行效果见上方示例。

查看 DialogStats 实现 ↗

DialogStatsProps

属性 / 方法 类型 默认值 必填 说明
children ReactNode — 是 渲染的子内容。

查看 DialogStatsProps 实现 ↗

DialogStat

DialogStat 是通用组合成员,具体属性见关联 Props 表,运行效果见上方示例。

查看 DialogStat 实现 ↗

DialogStatProps

属性 / 方法 类型 默认值 必填 说明
value ReactNode — 是 受控值。
label ReactNode — 是 可访问名称或展示文案。
tone Tone — 否 语义色调。
off boolean — 否 弱化统计项。

查看 DialogStatProps 实现 ↗

DialogLedger

DialogLedger 是通用组合成员,具体属性见关联 Props 表,运行效果见上方示例。

查看 DialogLedger 实现 ↗

DialogLedgerProps

属性 / 方法 类型 默认值 必填 说明
change LedgerItem[] — 是 将改变的内容列表。
keep LedgerItem[] — 是 保留的内容列表。
changeTitle ReactNode '将放弃' 否 改变内容的列标题。
keepTitle ReactNode '将保留' 否 保留内容的列标题。

查看 DialogLedgerProps 实现 ↗

DialogNote

不传 role 时是确认前的静态后果说明;role=alert/status 时进入反馈。icon 与 quiet 是旧兼容属性,当前不改变静态说明外观。

查看 DialogNote 实现 ↗

DialogNoteProps

属性 / 方法 类型 默认值 必填 说明
tone Tone 'info' 否 语义色调。
icon "warning" | "info" | "x" | "arrow-right" | "arrow-up-right" | "check" | "caret" | "trash" | "lock" | "key" | "server" | "folder" | "folder-open" | "branch" | "merge" | "pr" | "archive" | "cloud-up" | "cloud-down" | "globe" | "user" | "mail" | "terminal" | "laptop" | "search" | "bell" | "copy" | "eye" | "eye-off" | "link" | "sparkle" | "sliders" | "columns" | "download" | "moon" | "sun" | "wave" | "file" | "file-plus" | "refresh" | "plus" | "pencil" | "swap" | "shield" | "plug" | "tree" | "commit" | "chat" | "dots" | "clock" | "undo" — 否 旧兼容属性,当前静态说明不绘制图标。
title ReactNode — 否 标题或主文案。
children ReactNode — 否 渲染的子内容。
action ReactNode — 否 操作节点。
quiet boolean — 否 旧兼容属性,当前不会改变行为。
role "alert" | "status" — 否 alert/status 时转入反馈;不传时保留静态说明。

查看 DialogNoteProps 实现 ↗

DialogEmpty

DialogEmpty 是通用组合成员,具体属性见关联 Props 表,运行效果见上方示例。

查看 DialogEmpty 实现 ↗

DialogEmptyProps

属性 / 方法 类型 默认值 必填 说明
children ReactNode — 是 渲染的子内容。

查看 DialogEmptyProps 实现 ↗

DialogProgress

value 是 0~1 的有限比例,并被限制在这个范围;不传或传入非有限数时显示持续等待。label 为辅助进度文字。

查看 DialogProgress 实现 ↗

DialogProgressProps

属性 / 方法 类型 默认值 必填 说明
value number — 否 0~1 的进度比例,有限数值会限制在范围内;不传时显示持续等待。
label ReactNode — 否 可访问名称或展示文案。

查看 DialogProgressProps 实现 ↗

OptionCards

受控单选卡片,保持 options 的 value 类型与 onChange 一致。方向键跳过禁用选项;组 label 必须说明选择的用途。

查看 OptionCards 实现 ↗

OptionCardsProps

属性 / 方法 类型 默认值 必填 说明
value T — 是 受控值。
options OptionCard<T>[] — 是 选项及其标题、说明、图标和可用状态。
onChange (value: T) => void — 是 值变化回调,参数与 value/checked 的类型一致。
label string — 是 可访问名称或展示文案。
columns number — 否 选项列数。
disabled boolean — 否 禁用操作。

查看 OptionCardsProps 实现 ↗

DialogHints

DialogHints 是通用组合成员,具体属性见关联 Props 表,运行效果见上方示例。

查看 DialogHints 实现 ↗

DialogHintsProps

属性 / 方法 类型 默认值 必填 说明
tone "warn" — 否 语义色调。
children ReactNode — 是 渲染的子内容。

查看 DialogHintsProps 实现 ↗

Kbd

Kbd 是通用组合成员,具体属性见关联 Props 表,运行效果见上方示例。

查看 Kbd 实现 ↗

KbdProps

属性 / 方法 类型 默认值 必填 说明
children ReactNode — 是 渲染的子内容。

查看 KbdProps 实现 ↗

CheckCard

受控勾选卡片,onChange 接收 boolean。title 描述需要核对的内容;真正的提交门槛由宿主或 AluneModal acknowledge 管理。

查看 CheckCard 实现 ↗

CheckCardProps

属性 / 方法 类型 默认值 必填 说明
checked boolean — 是 受控勾选状态。
onChange (checked: boolean) => void — 是 值变化回调,参数与 value/checked 的类型一致。
title ReactNode — 是 标题或主文案。
description ReactNode — 否 辅助说明。
tone "danger" — 否 语义色调。
plain boolean — 否 减少确认卡片外观。
disabled boolean — 否 禁用操作。
className string — 否 附加 CSS 类名。

查看 CheckCardProps 实现 ↗

LedgerItem

属性 / 方法 类型 默认值 必填 说明
icon "warning" | "info" | "x" | "arrow-right" | "arrow-up-right" | "check" | "caret" | "trash" | "lock" | "key" | "server" | "folder" | "folder-open" | "branch" | "merge" | "pr" | "archive" | "cloud-up" | "cloud-down" | "globe" | "user" | "mail" | "terminal" | "laptop" | "search" | "bell" | "copy" | "eye" | "eye-off" | "link" | "sparkle" | "sliders" | "columns" | "download" | "moon" | "sun" | "wave" | "file" | "file-plus" | "refresh" | "plus" | "pencil" | "swap" | "shield" | "plug" | "tree" | "commit" | "chat" | "dots" | "clock" | "undo" — 是 图标内容或图标名。
text ReactNode — 是 参见类型定义及对应实现。

查看 LedgerItem 实现 ↗

OptionCard

属性 / 方法 类型 默认值 必填 说明
value T — 是 受控值。
title ReactNode — 是 标题或主文案。
description ReactNode — 否 辅助说明。
icon "warning" | "info" | "x" | "arrow-right" | "arrow-up-right" | "check" | "caret" | "trash" | "lock" | "key" | "server" | "folder" | "folder-open" | "branch" | "merge" | "pr" | "archive" | "cloud-up" | "cloud-down" | "globe" | "user" | "mail" | "terminal" | "laptop" | "search" | "bell" | "copy" | "eye" | "eye-off" | "link" | "sparkle" | "sliders" | "columns" | "download" | "moon" | "sun" | "wave" | "file" | "file-plus" | "refresh" | "plus" | "pencil" | "swap" | "shield" | "plug" | "tree" | "commit" | "chat" | "dots" | "clock" | "undo" — 否 图标内容或图标名。
disabled boolean — 否 禁用操作。

查看 OptionCard 实现 ↗

交互与使用限制

为每个操作提供可访问名称,为输入关联 label;使用语义化组件和清晰焦点。不要只靠颜色传达状态,禁用与等待时避免重复执行。

宿主负责状态、业务操作、错误处理与真实内容。组件不读取业务 store、路由或 Electron。示例中的反馈和等待均为本地模拟。

键盘、焦点、风险确认与通知策略的完整约定见交互规范。