Alune 组件

Feedback

状态栏通知中心、同来源修订去重、重试、队列和卸载清理。

使用方式

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

import { FeedbackProvider, FeedbackStatusButton, FeedbackNotice, FeedbackScope, FeedbackAlert, useFeedbackMessage, feedbackText } from '@alune/ui';

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

运行示例

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

真实示例 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 已组合一个反馈状态源和中心,不需要再次嵌套。弹窗内失败属于原表单,队列、去重和卸载清理沿用已合入行为。

查看 FeedbackProvider 实现 ↗

FeedbackProviderProps

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

查看 FeedbackProviderProps 实现 ↗

FeedbackStatusButton

在同一个 Provider 的状态栏内放置一个通知与提示入口,展示数量和未读状态。onUpdates?: () => void 由宿主提供,用于打开更新设置。

查看 FeedbackStatusButton 实现 ↗

FeedbackNotice

source、scope、context 组成身份,eventKey 或内容修订决定是否重新提示。autoOpen=false 时仅进入通知中心;title 清空与 resetOnClear 控制再次提示。在有效作用域内发布,卸载时释放当前来源租约。

查看 FeedbackNotice 实现 ↗

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 否 参见类型定义及对应实现。

查看 FeedbackNoticeProps 实现 ↗

FeedbackScope

active 与父作用域共同决定是否有效。切换到失效作用域会释放来源,不执行过期回调;id 应稳定且能区分不同宿主内容。

查看 FeedbackScope 实现 ↗

FeedbackScopeProps

属性 / 方法 类型 默认值 必填 说明
id string — 是 身份或作用域 ID。
label string — 是 可访问名称或展示文案。
active boolean true 否 与上层作用域共同控制来源有效性;停用后释放来源及过期动作。
children ReactNode — 是 渲染的子内容。

查看 FeedbackScopeProps 实现 ↗

FeedbackAlert

兼容富 React 内容,使用 feedbackText 建立稳定文本身份。当前通过反馈中心展示,组件自身不绘制内联 Alert。

查看 FeedbackAlert 实现 ↗

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 — 否 修订标识,同一身份与修订不重复提示。

查看 FeedbackAlertProps 实现 ↗

useFeedbackMessage

返回 error / warning / info / success 四个方法,接收 title: string。方法由当前作用域拥有,StrictMode 或卸载后不留下过期动作。不要用于高频操作的常规成功提示。

查看 useFeedbackMessage 实现 ↗

FeedbackMessageApi

属性 / 方法 类型 默认值 必填 说明
error (title: string) => void — 是 发布错误,弹窗内错误归属当前表单。
warning (title: string) => void — 是 发布警告,保留作用域与卸载清理。
info (title: string) => void — 是 发布说明。
success (title: string) => void — 是 发布成功;高频常规操作应保持克制。

查看 FeedbackMessageApi 实现 ↗

feedbackText

将 ReactNode 中的文字与数字递归归一为字符串,忽略无文字的节点,用于稳定身份;不序列化 React 内部对象。

查看 feedbackText 实现 ↗

交互与使用限制

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

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

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