Alune 组件

createFeedbackStore

面向适配和测试的独立状态源；应用优先使用 Provider 与 hook。

使用方式

返回 Zustand vanilla store。getState() 读取状态，subscribe(listener) 订阅。下表列出状态与方法；应用优先使用 Provider/hook，避免另建第二个全局队列。 

import { createFeedbackStore } from '@alune/ui';

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

运行示例

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

真实示例 TSX 独立预览 ↗
查看运行源码
源码文件 
import { useEffect, useState } from 'react';
import { createFeedbackStore, feedbackText, Button } from '@alune/ui';

export default function Example() {
  const [store] = useState(createFeedbackStore);
  const [entries, setEntries] = useState(store.getState().entries);
  useEffect(() => store.subscribe((state) => setEntries(state.entries)), [store]);
  return (
    <div className="example">
      <p>
        {feedbackText(
          <span>
            状态示例：<strong>来源去重</strong>
          </span>,
        )}
      </p>
      <div className="example-row">
        <Button
          onClick={() =>
            store.getState().publish({
              id: 'sample',
              scope: 'demo',
              context: '模拟项目',
              revision: '1',
              title: '示例错误',
              type: 'error',
              mode: 'modal',
            })
          }
        >
          发布同一修订
        </Button>
        <Button onClick={() => store.getState().acknowledge('sample')}>标为已读</Button>
        <Button onClick={() => store.getState().rearm('sample')}>允许再次提示</Button>
      </div>
      <pre className="example-code">
        {JSON.stringify(
          entries.map(({ id, queued, title }) => ({ id, queued, title })),
          null,
          2,
        )}
      </pre>
    </div>
  );
}

API

createFeedbackStore

返回 Zustand vanilla store。getState() 读取状态，subscribe(listener) 订阅。下表列出状态与方法；应用优先使用 Provider/hook，避免另建第二个全局队列。

查看 createFeedbackStore 实现 ↗

FeedbackEvent

属性 / 方法 类型 默认值 必填 说明
id string — 是 身份或作用域 ID。
host string — 否 所属弹窗身份，由上下文管理。
content ReactNode — 否 富内容。
actions ReactNode — 否 额外动作节点。
scope string — 是 来源作用域。
context string — 是 反馈上下文说明。
revision string — 是 来源修订，用于去重。
title string — 是 标题或主文案。
description string — 否 辅助说明。
type "error" | "warning" | "info" | "success" — 是 反馈语义类型。
mode "modal" | "notification" | "manual" — 是 反馈意图，控制后续配置动作；自动弹出由 autoOpen 决定。
autoOpen boolean true 否 是否自动弹出详情；false 时仅进入通知与提示中心，动作失败仍会重新提示。
kind "state" | "event" — 否 `state` mirrors an ongoing condition and leaves with its source; `event` is a one-off operation result that stays in the inbox until the user clears it.
actionLabel string — 否 重试或后续动作的名称。
onAction (() => void | Promise<unknown>) — 否 动作回调，支持 Promise；重试成功后自动移除反馈。
busy boolean — 否 受控等待状态。
icon string — 否 图标内容或图标名。
actionIcon string — 否 主动作图标。

查看 FeedbackEvent 实现 ↗

FeedbackEntry

属性 / 方法 类型 默认值 必填 说明
lease number — 是 来源租约，用于拒绝过期释放与回调。
queued boolean — 是 是否仍等待展示。
at number — 是 该修订首次到达的时间戳。
id string — 是 身份或作用域 ID。
host string — 否 所属弹窗身份，由上下文管理。
content ReactNode — 否 富内容。
actions ReactNode — 否 额外动作节点。
scope string — 是 来源作用域。
context string — 是 反馈上下文说明。
revision string — 是 来源修订，用于去重。
title string — 是 标题或主文案。
description string — 否 辅助说明。
type "error" | "warning" | "info" | "success" — 是 反馈语义类型。
mode "modal" | "notification" | "manual" — 是 反馈意图，控制后续配置动作；自动弹出由 autoOpen 决定。
autoOpen boolean true 否 是否自动弹出详情；false 时仅进入通知与提示中心，动作失败仍会重新提示。
kind "state" | "event" — 否 `state` mirrors an ongoing condition and leaves with its source; `event` is a one-off operation result that stays in the inbox until the user clears it.
actionLabel string — 否 重试或后续动作的名称。
onAction (() => void | Promise<unknown>) — 否 动作回调，支持 Promise；重试成功后自动移除反馈。
busy boolean — 否 受控等待状态。
icon string — 否 图标内容或图标名。
actionIcon string — 否 主动作图标。

查看 FeedbackEntry 实现 ↗

FeedbackStore

属性 / 方法 类型 默认值 必填 说明
entries FeedbackEntry[] — 是 当前反馈列表。
read ReadonlySet<string> — 是 Revisions the user has seen; a new revision of the same source is unread again.
markRead (ids?: string[]) => void — 是 参见类型定义及对应实现。
dismiss (id: string) => void — 是 参见类型定义及对应实现。
clearRead () => void — 是 参见类型定义及对应实现。
updatePresentation (id: string, content?: ReactNode, actions?: ReactNode) => void — 是 更新富内容与动作，不重新排队。
publish (event: FeedbackEvent) => number — 是 发布反馈并返回来源租约 number。
release (id: string, lease: number) => void — 是 用 id 与 lease 释放当前来源，过期租约不会覆盖新来源。
acknowledge (id: string) => void — 是 将当前修订标为已读，去重记录跨重新挂载保留。
rearm (id: string) => void — 是 允许指定来源再次提示。
run (id: string) => Promise<void> — 是 执行当前动作，等待时锁定；成功移除，失败保留并支持重试。

查看 FeedbackStore 实现 ↗

交互与使用限制

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

返回 Zustand vanilla store。getState() 读取状态，subscribe(listener) 订阅。下表列出状态与方法；应用优先使用 Provider/hook，避免另建第二个全局队列。

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

查看实现 ↗ 编辑文档 ↗ 设计与验收