CardService

CardService 是 AutumnBox 宿主中 Card（首页卡片）的注册表。所有通过 defineCard() 或 context.registerCard() 注册的卡片都由它统一管理。插件可以通过它查询已注册的 Card 列表、判断某张 Card 属于哪个插件，以及在运行时动态注册和注销 Card。

获取方式

import { useService, useServiceState } from '@autumnbox/sdk/hooks';
import { CardService } from '@autumnbox/sdk/hooks';

// React 组件中
const cardService = useService(CardService);

// pluginMain 或非 React 环境中
const cardService = context.getService(CardService);

API 一览

方法 / 属性	签名	说明
cards	readonly cards: IReadonlyState<readonly AutumnCard[]>	响应式的已注册 Card 列表
register	register({ card, pluginPackageName }): void	注册一张 Card
unregister	unregister(cardId: string): void	按 ID 注销一张 Card
unregisterByPluginPackageName	unregisterByPluginPackageName(pluginPackageName: string): void	注销某个插件的所有 Card
getCard	getCard(id: string): AutumnCard \| undefined	按 ID 查找 Card
getPluginPackageName	getPluginPackageName(cardId: string): string \| undefined	查询 Card 所属插件

订阅 Card 列表

cards 是一个响应式的 IReadonlyState，当有新 Card 注册或注销时自动通知订阅者。配合 useServiceState 使用时，列表变化会自动触发 React 重渲染：

import { useService, useServiceState } from '@autumnbox/sdk/hooks';
import { CardService } from '@autumnbox/sdk/hooks';

const CardCounter: React.FC = () => {
  const cardService = useService(CardService);
  const [cards] = useServiceState(cardService.cards);

  return <span>当前已注册 {cards.length} 张卡片</span>;
};

查询 Card

按 ID 查找

const cardService = useService(CardService);

const batteryCard = cardService.getCard('battery');
if (batteryCard) {
  console.log('找到卡片:', batteryCard.id);
}

查看 Card 归属

const pluginName = cardService.getPluginPackageName('battery');
// → 'autumnbox.main-plugin'

列出某插件的所有 Card

CardService 没有直接的按插件过滤方法，但可以结合 cards 列表和 getPluginPackageName 实现：

const cardService = useService(CardService);
const [cards] = useServiceState(cardService.cards);

const mainPluginCards = cards.filter(
  (card) => cardService.getPluginPackageName(card.id) === 'autumnbox.main-plugin',
);
console.log('main-plugin 注册了', mainPluginCards.length, '张 Card');

动态注册与注销

大多数情况下，Card 通过 defineCard() + __entry__.ts 自动注册。但如果需要在运行时动态控制 Card 的显示，可以手动调用注册和注销方法。

在 pluginMain 中注册

import type { PluginContext, AutumnCard } from '@autumnbox/sdk';
import { CardService } from '@autumnbox/sdk/hooks';
import { MyStatusCard } from './cards/MyStatusCard';

export function pluginMain(context: PluginContext): () => void {
  const cardService = context.getService(CardService);

  const card: AutumnCard = {
    id: 'my-status',
    name: 'card.name.my_status',
    component: MyStatusCard,
  };

  cardService.register({
    card,
    pluginPackageName: context.pluginPackageName,
  });

  // 插件卸载时注销
  return () => {
    cardService.unregister('my-status');
  };
}

批量注销

当插件被卸载时，宿主会自动调用 unregisterByPluginPackageName 清理该插件注册的所有 Card。插件自身通常不需要调用此方法，但它在构建插件管理工具时很有用：

// 移除某个插件的所有 Card
cardService.unregisterByPluginPackageName('autumnbox.old-plugin');

下一步

• AppService -- App 注册表，结构与 CardService 类似
• OverlayService -- 全局浮层组件管理
• 应用层服务总览 -- 所有应用层 Service 速查
• Card 开发基础 -- 如何定义和开发 Card