UI SDK 模块总览
完整查看 @downcity/ui 的导出模块、组件分组和可用变体
UI SDK 模块总览
本页用于完整列出 @downcity/ui 的公开模块，方便在开发时快速确认可复用能力，而不必去翻源码。
快捷键
快捷键模块提供跨平台的按键匹配、注册和 React Provider。Mod 在 macOS 上表示 Command，在 Windows/Linux 上表示 Ctrl。
import { ShortcutProvider, use_register_shortcuts } from "@downcity/ui";
function AppShortcuts() {
use_register_shortcuts(() => [{
id: "editor.bold",
title: "加粗",
keys: ["Mod+B"],
scope: "editor",
run: () => { document.execCommand("bold"); return true; },
}], []);
return null;
}支持 Mod+B、Mod+L、Mod+I、Mod+, 等组合键。快捷键动作由宿主应用注册，UI SDK 不预设业务行为。
工具与类型
cn
- 用途：合并 Tailwind 类名，并自动处理冲突类
- 适合场景：在组件封装或条件样式分支中安全组合
className
DowncityButtonVariant
- 可选值：
default、outline、secondary、ghost、destructive、link
DowncityButtonSize
- 可选值：
default、xs、sm、lg、icon、icon-xs、icon-sm、icon-lg
DowncityCardSize
- 可选值：
default、sm
DowncityDropdownMenuItemVariant
- 可选值：
default、destructive
DowncityContextMenuItemVariant
- 可选值：
default、destructive
DowncityItemVariant、DowncityItemSize
- Item 变体：
default、outline、muted - Item 尺寸：
default、sm
DowncitySpinnerSize
- 可选值：
sm、default、lg
DowncityToasterTheme
- 可选值：
light、dark、system
样式模块
@downcity/ui/source.css
- 作用：声明 Tailwind 扫描来源
- 特点：不注入主题样式
@downcity/ui/styles.css
- 作用：注入 Downcity UI 设计令牌与基础层
- 特点：不负责源码扫描声明
动作与状态模块
Button
- 导出：
Button、buttonVariants - 用途：主操作、次操作、图标按钮
ButtonGroup
- 导出：
ButtonGroup - 导出类型：
DowncityButtonGroupProps、DowncityButtonGroupOrientation - 用途：组合相关按钮并合并相邻边界
Badge
- 导出：
Badge、badgeVariants - 用途：状态标签、分类标签、轻量统计
Toggle
- 导出：
Toggle、toggleVariants - 用途：单个状态开关
ToggleGroup
- 导出：
ToggleGroup、ToggleGroupItem - 用途：按钮组切换
Spinner
- 导出：
Spinner - 用途：按钮、列表项和异步区域的加载反馈
Kbd
- 导出：
Kbd、KbdGroup - 用途：展示快捷键和键位组合
CodeBlock
- 导出：
CodeBlock - 导出类型：
DowncityCodeBlockProps - 用途：展示普通源码或构建期高亮后的代码，并提供复制操作
Typography
- 导出：
H1–H6、Paragraph、Lead、Small、Muted、Strong、Emphasis、InlineCode、Blockquote、UnorderedList、OrderedList、ListItem、TaskListItem、DefinitionList、DefinitionTerm、DefinitionDescription、FootnoteReference、Footnotes、FootnoteItem、Anchor、Hr、Annotation - 导出类型：
DowncityAnnotationProps、DowncityAnnotationTone与 Typography 属性类型 - 用途：渲染标题、正文、引用、列表、链接、行内代码和语义注释
表单模块
Input
- 导出：
Input - 用途：单行输入、搜索框、短配置
Textarea
- 导出：
Textarea - 导出类型：
TextareaProps - 用途：Prompt、长说明、多行配置
Checkbox
- 导出：
Checkbox - 用途：多选配置、权限勾选
Label
- 导出：
Label - 用途：字段标题、表单命名
Select
- 导出：
Select、SelectTrigger、SelectValue、SelectContent、SelectGroup、SelectLabel、SelectItem、SelectSeparator - 用途：单值选择与分组选项
Slider
- 导出：
Slider - 用途：单值或范围数值选择
Switch
- 导出：
Switch - 用途：切换单个布尔配置
容器与展示模块
ChatPanel
- 导出：
ChatPanel、ChatHistory、ChatMessage、ChatComposer、session_message_to_chat_message - 导出类型：
DowncityChatPanelProps、DowncityChatMessage、DowncityChatThread、DowncityChatStatus、DowncityChatSubmitInput - 用途：提供与运行时无关的 Agent 对话界面，包括标题栏、会话历史、消息列表、空状态、流式状态、停止生成和输入框。
- 特点：组件是受控的，不读取 Agent、Session、Electron 或网络状态；宿主通过 props 传入数据，并通过回调接管发送、停止、新建、切换和归档。
import { ChatPanel } from "@downcity/ui";
import "@downcity/ui/styles.css";
<ChatPanel
thread={{ id: "session-1", title: "项目助手" }}
messages={messages}
status={is_streaming ? "streaming" : "ready"}
on_submit={({ text }) => send_message(text)}
on_stop={() => stop_generation()}
render_message={({ message }) => render_markdown(message.content)}
/>session_message_to_chat_message 可直接把 Session SDK canonical message 转成 Chat 展示消息。Chat UI 内置 Duobox 风格的消息、工具活动、Interaction、Changed Files、历史列表和输入区；Session 生命周期与响应操作由宿主负责。
Card
- 导出：
CardCardHeaderCardTitleCardDescriptionCardActionCardContentCardFooter
Separator
- 导出：
Separator - 支持方向：
horizontal、vertical
Skeleton
- 导出：
Skeleton - 用途：加载占位
Tabs
- 导出：
TabsTabsListTabsTriggerTabsContenttabsListVariants
Settings
- 导出：
SettingsContainer、SettingSection、SettingGroup、SettingItem、InfoRow - 用途：组合紧凑设置页和信息详情分组
Item
- 导出：
Item、ItemMedia、ItemContent、ItemTitle、ItemDescription、ItemActions、ItemGroup、item_variants - 用途：组合资源列表、搜索结果和设置入口
Empty
- 导出：
Empty、EmptyHeader、EmptyMedia、EmptyTitle、EmptyDescription、EmptyContent - 用途：首次使用、无数据和无筛选结果状态
Workboard
- 导出：
Workboard - 导出类型：
DowncityWorkboardPropsDowncityWorkboardBoardSnapshotDowncityWorkboardAgentItemDowncityWorkboardActivityItem
- 用途：展示多个 agents 的像素化 game world，支持固定 40 x 24 tile 大地图画布、普通视图完整比例、全屏 cover 铺满、Smallville 风格小镇 atlas、开放式状态建筑、平铺式室内子地图、portal rail、键盘地图控制、sprite 巡游、quest path、墙面公告板、蓝图桌、codex log 和聚焦查看
buildWorkboardGameMapConfig
- 导出：
buildWorkboardGameMapConfig - 导出类型：
DowncityWorkboardGameMapConfigDowncityWorkboardGameZoneDowncityWorkboardGameActorDowncityWorkboardGameRouteDowncityWorkboardGamePointOfInterestDowncityWorkboardGameAreaLabelDowncityWorkboardGameAtlasPropsDowncityWorkboardGameRoomPropsDowncityWorkboardGameInspectorPropsDowncityWorkboardGameHudProps
- 用途：把
workboard的公开快照映射成完整的游戏地图配置，方便在自定义 host 中复用 zones、actors、routes、city、station、道具和标签
浮层与反馈模块
Dialog
- 导出：
DialogDialogTriggerDialogPortalDialogCloseDialogOverlayDialogContentDialogHeaderDialogFooterDialogTitleDialogDescription
Sheet
- 导出：
SheetSheetTriggerSheetCloseSheetPortalSheetOverlaySheetContentSheetHeaderSheetFooterSheetTitleSheetDescription
DropdownMenu
- 导出：
DropdownMenuDropdownMenuTriggerDropdownMenuPortalDropdownMenuContentDropdownMenuGroupDropdownMenuLabelDropdownMenuItemDropdownMenuCheckboxItemDropdownMenuRadioGroupDropdownMenuRadioItemDropdownMenuSeparatorDropdownMenuShortcutDropdownMenuSubDropdownMenuSubTriggerDropdownMenuSubContent
ContextMenu
- 导出：
ContextMenu、ContextMenuTrigger、ContextMenuContent、ContextMenuGroup、ContextMenuLabel、ContextMenuItem、ContextMenuCheckboxItem、ContextMenuRadioGroup、ContextMenuRadioItem、ContextMenuSeparator、ContextMenuShortcut、ContextMenuSub、ContextMenuSubTrigger、ContextMenuSubContent - 用途：为目标区域提供右键操作菜单
Command
- 导出：
Command、CommandInput、CommandList、CommandEmpty、CommandGroup、CommandItem、CommandSeparator、CommandShortcut - 用途：命令面板、资源搜索和快速跳转
Popover
- 导出：
PopoverPopoverTriggerPopoverContent
Tooltip
- 导出：
TooltipTooltipTriggerTooltipContentTooltipProvider
Toaster
- 导出：
Toaster - 基于：
sonner