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 文件。浮层、状态和主题独立于文档;所有回调只更新本地模拟数据。
正在加载示例…
查看运行源码
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 表,运行效果见上方示例。
DialogCardProps
| 属性 / 方法 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
children | ReactNode | — | 是 | 渲染的子内容。 |
pad | boolean | — | 否 | 添加卡片内部间距。 |
className | string | — | 否 | 附加 CSS 类名。 |
DialogPath
DialogPath 是通用组合成员,具体属性见关联 Props 表,运行效果见上方示例。
DialogPathProps
| 属性 / 方法 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
path | string | — | 否 | 文件或目录路径,只读取名称,不访问文件系统。 |
className | string | — | 否 | 附加 CSS 类名。 |
children | ReactNode | — | 否 | 渲染的子内容。 |
RepoRow
RepoRow 是通用组合成员,具体属性见关联 Props 表,运行效果见上方示例。
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 | — | 否 | 渲染的子内容。 |
DialogStats
DialogStats 是通用组合成员,具体属性见关联 Props 表,运行效果见上方示例。
DialogStatsProps
| 属性 / 方法 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
children | ReactNode | — | 是 | 渲染的子内容。 |
DialogStat
DialogStat 是通用组合成员,具体属性见关联 Props 表,运行效果见上方示例。
DialogStatProps
| 属性 / 方法 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
value | ReactNode | — | 是 | 受控值。 |
label | ReactNode | — | 是 | 可访问名称或展示文案。 |
tone | Tone | — | 否 | 语义色调。 |
off | boolean | — | 否 | 弱化统计项。 |
DialogLedger
DialogLedger 是通用组合成员,具体属性见关联 Props 表,运行效果见上方示例。
DialogLedgerProps
| 属性 / 方法 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
change | LedgerItem[] | — | 是 | 将改变的内容列表。 |
keep | LedgerItem[] | — | 是 | 保留的内容列表。 |
changeTitle | ReactNode | '将放弃' | 否 | 改变内容的列标题。 |
keepTitle | ReactNode | '将保留' | 否 | 保留内容的列标题。 |
DialogNote
不传 role 时是确认前的静态后果说明;role=alert/status 时进入反馈。icon 与 quiet 是旧兼容属性,当前不改变静态说明外观。
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 时转入反馈;不传时保留静态说明。 |
DialogEmpty
DialogEmpty 是通用组合成员,具体属性见关联 Props 表,运行效果见上方示例。
DialogEmptyProps
| 属性 / 方法 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
children | ReactNode | — | 是 | 渲染的子内容。 |
DialogProgress
value 是 0~1 的有限比例,并被限制在这个范围;不传或传入非有限数时显示持续等待。label 为辅助进度文字。
DialogProgressProps
| 属性 / 方法 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
value | number | — | 否 | 0~1 的进度比例,有限数值会限制在范围内;不传时显示持续等待。 |
label | ReactNode | — | 否 | 可访问名称或展示文案。 |
OptionCards
受控单选卡片,保持 options 的 value 类型与 onChange 一致。方向键跳过禁用选项;组 label 必须说明选择的用途。
OptionCardsProps
| 属性 / 方法 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
value | T | — | 是 | 受控值。 |
options | OptionCard<T>[] | — | 是 | 选项及其标题、说明、图标和可用状态。 |
onChange | (value: T) => void | — | 是 | 值变化回调,参数与 value/checked 的类型一致。 |
label | string | — | 是 | 可访问名称或展示文案。 |
columns | number | — | 否 | 选项列数。 |
disabled | boolean | — | 否 | 禁用操作。 |
DialogHints
DialogHints 是通用组合成员,具体属性见关联 Props 表,运行效果见上方示例。
DialogHintsProps
| 属性 / 方法 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
tone | "warn" | — | 否 | 语义色调。 |
children | ReactNode | — | 是 | 渲染的子内容。 |
Kbd
Kbd 是通用组合成员,具体属性见关联 Props 表,运行效果见上方示例。
KbdProps
| 属性 / 方法 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
children | ReactNode | — | 是 | 渲染的子内容。 |
CheckCard
受控勾选卡片,onChange 接收 boolean。title 描述需要核对的内容;真正的提交门槛由宿主或 AluneModal acknowledge 管理。
CheckCardProps
| 属性 / 方法 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
checked | boolean | — | 是 | 受控勾选状态。 |
onChange | (checked: boolean) => void | — | 是 | 值变化回调,参数与 value/checked 的类型一致。 |
title | ReactNode | — | 是 | 标题或主文案。 |
description | ReactNode | — | 否 | 辅助说明。 |
tone | "danger" | — | 否 | 语义色调。 |
plain | boolean | — | 否 | 减少确认卡片外观。 |
disabled | boolean | — | 否 | 禁用操作。 |
className | string | — | 否 | 附加 CSS 类名。 |
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 | — | 是 | 参见类型定义及对应实现。 |
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 | — | 否 | 禁用操作。 |
交互与使用限制
为每个操作提供可访问名称,为输入关联 label;使用语义化组件和清晰焦点。不要只靠颜色传达状态,禁用与等待时避免重复执行。
宿主负责状态、业务操作、错误处理与真实内容。组件不读取业务 store、路由或 Electron。示例中的反馈和等待均为本地模拟。
键盘、焦点、风险确认与通知策略的完整约定见交互规范。