前端组件与工具开发文档

import { Button } from "@chatbuddy-ai/ui/components/ui/button"; <Button type="submit" variant="outline" size="sm" loading={isSubmitting}> 提交
</Button>;

import { Empty, EmptyContent, EmptyDescription, EmptyMedia, EmptyTitle,
} from "@chatbuddy-ai/ui/components/ui/empty"; <Empty> <EmptyMedia variant="icon"> <Search className="size-5" /> </EmptyMedia> <EmptyContent> <EmptyTitle>暂无数据</EmptyTitle> <EmptyDescription>调整筛选条件后再试。</EmptyDescription> </EmptyContent>
</Empty>;

import { Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel,
} from "@chatbuddy-ai/ui/components/ui/field"; <FieldGroup> <Field> <FieldLabel htmlFor="title">标题</FieldLabel> <Input id="title" value={title} onChange={(e) => setTitle(e.target.value)} /> <FieldDescription>展示在列表和详情页。</FieldDescription> {error ? <FieldError>{error}</FieldError> : null} </Field> <Field orientation="horizontal"> <Switch checked={enabled} onCheckedChange={setEnabled} /> <FieldContent> <FieldLabel>启用</FieldLabel> <FieldDescription>停用后用户侧不可见。</FieldDescription> </FieldContent> </Field>
</FieldGroup>;

import { StatusBadge } from "@chatbuddy-ai/ui/components/ui/status-badge"; <StatusBadge active={record.isEnabled} />;
<StatusBadge active={false} inactiveText="已下架" inactiveVariant="muted" />;

import { TimeText } from "@chatbuddy-ai/ui/components/ui/time-text"; <TimeText value={item.createdAt} />;
<TimeText value={item.createdAt} variant="date" />;
<TimeText value={item.updatedAt} variant="relative" />;
<TimeText value={item.createdAt} format="YYYY年MM月DD日 HH:mm" />;

import { IconPicker } from "@chatbuddy-ai/ui/components/icon-picker";
import { LucideIcon } from "@chatbuddy-ai/ui/components/lucide-icon"; <IconPicker value={icon} onChange={setIcon} placeholder="选择菜单图标" />;
<LucideIcon name="settings" className="size-4" />;

import { ImageUpload } from "@chatbuddy-ai/ui/components/ui/image-upload";

import { ImageUpload } from "@chatbuddy-ai/ui/components/ui/image-upload"; <ImageUpload value={form.cover} size="xl" onChange={(url, result) => { setForm((prev) => ({ ...prev, cover: url ?? "" })); console.log(result?.id); }} onUploadStart={ => setUploading(true)} onUploadError={(error) => toast.error(error.message)}
/>;

import { Upload, UploadDropzone, UploadFileList, UploadRoot, UploadTrigger, useUpload,
} from "@chatbuddy-ai/ui/components/upload";

type UploadStatus = "idle" | "uploading" | "success" | "error"; interface UploadFile { id: string; file: File; status: UploadStatus; progress: number; result?: UploadFileResult; error?: string;
}

<Upload multiple maxFiles={5} maxSize={20 * 1024 * 1024} accept=".pdf,.docx,.txt" params={{ description: "知识库文档", extensionId }} onUploadStart={(files) => console.log(files.length)} onUploadProgress={(file) => console.log(file.progress)} onUploadSuccess={(file, result) => console.log(file.file.name, result.url)} onUploadError={(file, error) => toast.error(`${file.file.name}: ${error.message}`)} onUploadComplete={(files) => console.log(files)}
/>

<UploadRoot multiple accept="image/*" maxFiles={3}> <UploadTrigger>选择图片</UploadTrigger> <UploadDropzone className="rounded-md border border-dashed p-8" activeClassName="border-primary bg-primary/5" > {({ isDragOver, isUploading }) => isUploading ? "上传中..." : isDragOver ? "松开上传" : "拖拽文件到这里" } </UploadDropzone> <UploadFileList className="space-y-2" />
</UploadRoot>

const { files, upload, isUploading, removeFile, clearFiles, getRootProps, getInputProps } = useUpload({ multiple: true, onUploadComplete: (items) => console.log(items), }); return ( <div {...getRootProps}> <input {...getInputProps} /> {files.map((file) => ( <button key={file.id} onClick={ => removeFile(file.id)}> {file.file.name} </button> ))} </div>
);

import { invalidateStorageConfigCache, uploadFile, uploadFileAuto, uploadFiles, uploadFilesAuto, uploadInitFile,
} from "@chatbuddy-ai/services/shared";

const result = await uploadFileAuto( file, { description: "头像" }, { onUploadProgress: (event) => { const percent = event.total ? Math.round((event.loaded / event.total) * 100) : 0; setProgress(percent); }, },
);

import { InfiniteScroll } from "@chatbuddy-ai/ui/components/infinite-scroll"; <InfiniteScroll loading={query.isFetchingNextPage} hasMore={hasNextPage} threshold={120} onLoadMore={ => fetchNextPage}
> {items.map((item) => ( <Item key={item.id} item={item} /> ))}
</InfiniteScroll>;

import { InfiniteScrollTop } from "@chatbuddy-ai/ui/components/infinite-scroll-top"; <InfiniteScrollTop hasMore={hasMoreMessages} isLoadingMore={isLoadingMoreMessages} onLoadMore={loadMoreMessages} prependKey={oldestMessageId} topThreshold={32}
> {messages.map((message) => ( <MessageItem key={message.id} message={message} /> ))}
</InfiniteScrollTop>;

import { Editor, EditorContainer, EditorKit, markdownToValue, Plate, serializeEditorToMarkdown, usePlateEditor,
} from "@chatbuddy-ai/ui/components/editor";

const editor = usePlateEditor({ plugins: EditorKit, id: "article-content", value: markdownToValue(initialMarkdown),
}); <Plate editor={editor} onValueChange={ => { const markdown = serializeEditorToMarkdown(editor); setContent(markdown); }}
> <EditorContainer className="min-h-80 rounded-lg border"> <Editor variant="default" /> </EditorContainer>
</Plate>;

import AuthGuard from "@chatbuddy-ai/ui/components/auth/auth-guard";

{ element: <AuthGuard />, children: [{ path: "/console", element: <ConsoleLayout /> }],
}

import { PermissionGuard } from "@chatbuddy-ai/ui/components/auth/permission-guard";

<PermissionGuard permissions="role:create"> <Button>创建角色</Button>
</PermissionGuard> <PermissionGuard permissions={["role:update", "role:delete"]} any blockOnly> <Button variant="destructive">批量操作</Button>
</PermissionGuard>

import { RootOnly } from "@chatbuddy-ai/ui/components/auth/root-only"; <RootOnly fallback={null}> <Button variant="destructive">系统维护</Button>
</RootOnly> <RootOnly reverse> <span>普通用户可见</span>
</RootOnly>

import { ThemeProvider, useTheme } from "@chatbuddy-ai/ui/components/theme-provider";
import { ThemeToggle } from "@chatbuddy-ai/ui/components/theme-toggle"; <ThemeProvider defaultTheme="system" storageKey="chatbuddy-ai-theme" defaultThemeColor="indigo" themeColorStorageKey="chatbuddy-ai-theme-color"
> <App />
</ThemeProvider>;

import { CopyButton } from "@chatbuddy-ai/ui/components/copy-button"; <CopyButton value={code} timeout={1500} onCopy={ => toast.success("已复制")} onCopyError={(error) => toast.error(error.message)}
/>;

<FileFormatIcon format="pdf" className="size-5" />
<LucideIcon name="settings" className="size-4" />
<IconPicker value={icon} onChange={setIcon} />

import { Message, MessageContent } from "@chatbuddy-ai/ui/components/ai-elements/message"; <Message from="assistant"> <MessageContent>你好，我可以帮你分析这个任务。</MessageContent>
</Message>;

import { Tool, ToolContent, ToolHeader, ToolInput, ToolOutput,
} from "@chatbuddy-ai/ui/components/ai-elements/tool"; <Tool defaultOpen> <ToolHeader type="tool-weather" state="output-available" toolName="weather" /> <ToolContent> <ToolInput input={{ city: "Shanghai" }} /> <ToolOutput output={{ temperature: 22 }} /> </ToolContent>
</Tool>;

import { CodeBlock, CodeBlockActions, CodeBlockCopyButton, CodeBlockHeader, CodeBlockTitle,
} from "@chatbuddy-ai/ui/components/ai-elements/code-block"; <CodeBlock code={source} language="tsx" showLineNumbers> <CodeBlockHeader> <CodeBlockTitle>example.tsx</CodeBlockTitle> <CodeBlockActions> <CodeBlockCopyButton /> </CodeBlockActions> </CodeBlockHeader>
</CodeBlock>;

import { AssistantProvider, Chat, useAssistant } from "@/components/ask-assistant-ui";
import type { AiProvider } from "@chatbuddy-ai/services/web";

function AssistantChat({ providers }: { providers: AiProvider[] }) { const assistant = useAssistant({ providers, enableThinking: true, suggestions: [ { title: "帮我总结", prompt: "总结当前内容" }, { title: "生成计划", prompt: "给我一个执行计划" }, ], }); return ( <AssistantProvider {...assistant}> <Chat title="AI 助手" /> </AssistantProvider> );
}

import { SettingsDialogProvider, useSettingsDialog } from "@/components/settings-dialog";

function Root { return <SettingsDialogProvider>{children}</SettingsDialogProvider>;
}

function ProfileButton { const settings = useSettingsDialog; return <Button onClick={ => settings.open("profile")}>个人配置</Button>;
}

import { ManageTagsDialog, TagCreate, TagSelect } from "@/components/tags";

<TagSelect value={tagIds} onChange={setTagIds} type="app" tagsSource="console" showManage />

import { AlertDialogProvider } from "@chatbuddy-ai/ui/hooks/use-alert-dialog"; <AlertDialogProvider> <App />
</AlertDialogProvider>;

import { useAlertDialog } from "@chatbuddy-ai/ui/hooks/use-alert-dialog"; const { confirm } = useAlertDialog; async function handleDelete { await confirm({ title: "确认移除？", description: "移除后不可恢复", confirmText: "移除", confirmVariant: "destructive", }); await deleteMutation.mutateAsync(id);
}

import { usePagination } from "@chatbuddy-ai/ui/hooks/use-pagination"; const pagination = usePagination({ total: data?.total ?? 0, pageSize, page, siblingCount: 1, onPageChange: setPage,
}); return <pagination.PaginationComponent className="mt-4" />;

import { useUploadFile } from "@chatbuddy-ai/ui/hooks/use-upload-file"; const { uploadFile, isUploading, progress, uploadedFile } = useUploadFile({ onUploadComplete: (file) => console.log(file.url),
}); await uploadFile(file);

import { useCopy, useDocumentHead } from "@chatbuddy-ai/hooks"; function Page { useDocumentHead({ title: "文章管理" }); const { copy, isCopying } = useCopy; return ( <Button disabled={isCopying} onClick={ => copy("hello")}> 复制 </Button> );
}

import { createHttpClient, createStandardApiParser } from "@chatbuddy-ai/http";

const http = createHttpClient({ baseURL: import.meta.env.VITE_PRODUCTION_APP_BASE_URL, pathPrefix: "/api", parseResponse: createStandardApiParser, hooks: { getAccessToken: => token, onError: (error) => toast.error(error.message), },
}); const detail = await http.get<UserInfo>("/user/info");
const list = await http.get<PaginatedResponse<User>>("/user", { query: { page: 1, pageSize: 15 },
});

import { apiHttpClient, consoleHttpClient, createPluginHttpClients } from "@chatbuddy-ai/services";

import { createPluginHttpClients } from "@chatbuddy-ai/services"; const { apiHttpClient, consoleHttpClient } = createPluginHttpClients; export { apiHttpClient, consoleHttpClient };

import type { MutationOptionsUtil, PaginatedQueryOptionsUtil, PaginatedResponse, QueryOptionsUtil,
} from "@chatbuddy-ai/web-types";
import { useMutation, useQuery } from "@tanstack/react-query"; import { consoleHttpClient } from "../base"; export function useArticleListQuery( params?: QueryArticleParams, options?: PaginatedQueryOptionsUtil<Article>,
) { return useQuery({ queryKey: ["articles", "list", params], queryFn: => consoleHttpClient.get<PaginatedResponse<Article>>("/article", { params }), ...options, });
} export function useCreateArticleMutation( options?: MutationOptionsUtil<Partial<Article>, CreateArticleParams>,
) { return useMutation({ mutationFn: (data) => consoleHttpClient.post<Partial<Article>>("/article", data), ...options, });
}

import { createStore } from "@chatbuddy-ai/stores"; export const useDemoStore = createStore(createDemoSlice, { persist: { name: "demo", partialize: (state) => ({ demo: state.demo }), },
});

import { useAuthStore } from "@chatbuddy-ai/stores"; const token = useAuthStore((s) => s.auth.token);
const userInfo = useAuthStore((s) => s.auth.userInfo);
const logout = useAuthStore((s) => s.authActions.logout);

import { getLocalStorage, safeJsonParse, safeJsonStringify } from "@chatbuddy-ai/stores"; const storage = getLocalStorage;
const cached = safeJsonParse<string[]>(storage.getItem("selected_ids")) ?? [];
storage.setItem("selected_ids", safeJsonStringify(cached));

import { defineRouteOption } from "@chatbuddy-ai/web-core";
import packageJson from "./../../package.json"; export const routeOption = defineRouteOption({ base: `extension/${packageJson.name}`, identifier: packageJson.name, routes: [{ index: true, element: <IndexPage /> }], consoleMenus: [{ title: "文章管理", path: "/", icon: "file-text" }], consoleRoutes: [{ index: true, element: <ArticleListPage /> }],
});

import { defineExtensionViteConfig } from "@chatbuddy-ai/web-core/vite/extension";
import packageJson from "./package.json"; export default defineExtensionViteConfig(packageJson, { server: { port: 5174 },
});