Alune 组件
Feedback
状态栏通知中心、同来源修订去重、重试、队列和卸载清理。
使用方式
作用域与反馈由宿主传入状态和回调,适合在不同应用和文档中复用。先完成快速开始中的 Provider 与样式配置。
import { FeedbackProvider, FeedbackStatusButton, FeedbackNotice, FeedbackScope, FeedbackAlert, useFeedbackMessage, feedbackText } from '@alune/ui'; 运行示例
运行与复制源码来自同一 TSX 文件。浮层、状态和主题独立于文档;所有回调只更新本地模拟数据。
正在加载示例…
查看运行源码
import { useState } from 'react';
import {
Button,
FeedbackScope,
FeedbackNotice,
FeedbackStatusButton,
FeedbackAlert,
useFeedbackMessage,
Switch,
Space,
} from '@alune/ui';
export default function Example() {
const [active, setActive] = useState(true);
return (
<div className="example">
<label className="example-row">
<Switch aria-label="启用反馈作用域" checked={active} onChange={setActive} /> 启用作用域
</label>
<FeedbackScope id="example" label="示例项目" active={active}>
<FeedbackActions />
</FeedbackScope>
<div className="example-footer">
<FeedbackStatusButton />
</div>
</div>
);
}
function FeedbackActions() {
const [revision, setRevision] = useState(0);
const [failure, setFailure] = useState(false);
const [rich, setRich] = useState(false);
const [notice, setNotice] = useState(0);
const message = useFeedbackMessage();
return (
<div className="example-stack">
<Space wrap size="middle">
<Button
onClick={() => {
setFailure(true);
setRevision((n) => n + 1);
}}
>
产生可重试错误
</Button>
<Button onClick={() => message.warning('示例状态需要核对')}>发送警告</Button>
<Button
onClick={() => {
message.error('第一条示例错误');
message.info('第二条说明');
}}
>
并发队列
</Button>
<Button onClick={() => setRich((v) => !v)}>切换富文本反馈</Button>
<Button onClick={() => setNotice((n) => n + 1)}>发送仅入中心的通知</Button>
</Space>
<FeedbackNotice
source="background"
title={notice ? '后台检查已完成' : null}
type="info"
autoOpen={false}
eventKey={notice}
/>
<FeedbackNotice
source="load"
title={failure ? '示例加载失败' : null}
description="同一来源、同一修订只提示一次。重试后移除。"
eventKey={revision}
type="error"
actionLabel="重试"
onAction={async () => {
await new Promise((resolve) => setTimeout(resolve, 400));
setFailure(false);
}}
/>
{rich && (
<FeedbackAlert
source="rich"
title="使用限制"
description={
<span>
此示例使用<strong>本地模拟数据</strong>。
</span>
}
/>
)}
</div>
);
}
API
FeedbackProvider
AluneUIProvider 已组合一个反馈状态源和中心,不需要再次嵌套。弹窗内失败属于原表单,队列、去重和卸载清理沿用已合入行为。
FeedbackProviderProps
| 属性 / 方法 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
children | ReactNode | — | 是 | 渲染的子内容。 |
FeedbackStatusButton
在同一个 Provider 的状态栏内放置一个通知与提示入口,展示数量和未读状态。onUpdates?: () => void 由宿主提供,用于打开更新设置。
FeedbackNotice
source、scope、context 组成身份,eventKey 或内容修订决定是否重新提示。autoOpen=false 时仅进入通知中心;title 清空与 resetOnClear 控制再次提示。在有效作用域内发布,卸载时释放当前来源租约。
FeedbackNoticeProps
| 属性 / 方法 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
source | string | — | 是 | 来源标识;与 scope 和 context 一起确定去重身份。 |
content | ReactNode | — | 否 | 富内容。 |
actions | ReactNode | — | 否 | 额外动作节点。 |
title | string | null | — | 否 | 标题或主文案。 |
description | string | — | 否 | 辅助说明。 |
type | "error" | "warning" | "info" | "success" | 'error' | 否 | 反馈语义类型。 |
mode | "modal" | "notification" | "manual" | 'modal' | 否 | 反馈意图,控制后续配置动作;自动弹出由 autoOpen 决定。 |
autoOpen | boolean | true | 否 | 是否自动弹出详情;false 时仅进入通知与提示中心,动作失败仍会重新提示。 |
eventKey | string | number | object | — | 否 | 修订标识,同一身份与修订不重复提示。 |
context | string | — | 否 | 反馈上下文说明。 |
actionLabel | string | — | 否 | 重试或后续动作的名称。 |
onAction | (() => void | Promise<unknown>) | — | 否 | 动作回调,支持 Promise;重试成功后自动移除反馈。 |
busy | boolean | — | 否 | 受控等待状态。 |
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" | — | 否 | 图标内容或图标名。 |
actionIcon | "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" | — | 否 | 主动作图标。 |
resetOnClear | boolean | mode === 'modal' | 否 | title 清空时是否允许同来源再次提示。 |
read | boolean | false | 否 | 参见类型定义及对应实现。 |
FeedbackScope
active 与父作用域共同决定是否有效。切换到失效作用域会释放来源,不执行过期回调;id 应稳定且能区分不同宿主内容。
FeedbackScopeProps
| 属性 / 方法 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
id | string | — | 是 | 身份或作用域 ID。 |
label | string | — | 是 | 可访问名称或展示文案。 |
active | boolean | true | 否 | 与上层作用域共同控制来源有效性;停用后释放来源及过期动作。 |
children | ReactNode | — | 是 | 渲染的子内容。 |
FeedbackAlert
兼容富 React 内容,使用 feedbackText 建立稳定文本身份。当前通过反馈中心展示,组件自身不绘制内联 Alert。
FeedbackAlertProps
| 属性 / 方法 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
source | string | — | 是 | 来源标识;与 scope 和 context 一起确定去重身份。 |
title | ReactNode | — | 否 | 标题或主文案。 |
message | ReactNode | — | 否 | title 的兼容替代。 |
description | ReactNode | — | 否 | 辅助说明。 |
type | "error" | "warning" | "info" | "success" | 'info' | 否 | 反馈语义类型。 |
action | ReactNode | — | 否 | 操作节点。 |
context | string | — | 否 | 反馈上下文说明。 |
eventKey | string | number | object | — | 否 | 修订标识,同一身份与修订不重复提示。 |
useFeedbackMessage
返回 error / warning / info / success 四个方法,接收 title: string。方法由当前作用域拥有,StrictMode 或卸载后不留下过期动作。不要用于高频操作的常规成功提示。
FeedbackMessageApi
| 属性 / 方法 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
error | (title: string) => void | — | 是 | 发布错误,弹窗内错误归属当前表单。 |
warning | (title: string) => void | — | 是 | 发布警告,保留作用域与卸载清理。 |
info | (title: string) => void | — | 是 | 发布说明。 |
success | (title: string) => void | — | 是 | 发布成功;高频常规操作应保持克制。 |
feedbackText
将 ReactNode 中的文字与数字递归归一为字符串,忽略无文字的节点,用于稳定身份;不序列化 React 内部对象。
交互与使用限制
为每个操作提供可访问名称,为输入关联 label;使用语义化组件和清晰焦点。不要只靠颜色传达状态,禁用与等待时避免重复执行。
宿主负责状态、业务操作、错误处理与真实内容。组件不读取业务 store、路由或 Electron。示例中的反馈和等待均为本地模拟。
键盘、焦点、风险确认与通知策略的完整约定见交互规范。