前端组件与工具开发文档

import { Button } from "@buildingai/ui/components/ui/button";

<Button type="submit" variant="outline" size="sm" loading={isSubmitting}>
    保存
</Button>;

import {
    Empty,
    EmptyContent,
    EmptyDescription,
    EmptyMedia,
    EmptyTitle,
} from "@buildingai/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 "@buildingai/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 "@buildingai/ui/components/ui/status-badge";

<StatusBadge active={record.isEnabled} />;
<StatusBadge active={false} inactiveText="已下架" inactiveVariant="muted" />;

import { TimeText } from "@buildingai/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 "@buildingai/ui/components/icon-picker";
import { LucideIcon } from "@buildingai/ui/components/lucide-icon";

<IconPicker value={icon} onChange={setIcon} placeholder="选择菜单图标" />;
<LucideIcon name="settings" className="size-4" />;

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

import { ImageUpload } from "@buildingai/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 "@buildingai/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 "@buildingai/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 "@buildingai/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 "@buildingai/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 "@buildingai/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 "@buildingai/ui/components/auth/auth-guard";

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

import { PermissionGuard } from "@buildingai/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 "@buildingai/ui/components/auth/root-only";

<RootOnly fallback={null}>
    <Button variant="destructive">系统维护</Button>
</RootOnly>

<RootOnly reverse>
    <span>普通用户可见</span>
</RootOnly>

import { ThemeProvider, useTheme } from "@buildingai/ui/components/theme-provider";
import { ThemeToggle } from "@buildingai/ui/components/theme-toggle";

<ThemeProvider
    defaultTheme="system"
    storageKey="buildingai-theme"
    defaultThemeColor="indigo"
    themeColorStorageKey="buildingai-theme-color"
>
    <App />
</ThemeProvider>;

import { CopyButton } from "@buildingai/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 "@buildingai/ui/components/ai-elements/message";

<Message from="assistant">
    <MessageContent>你好，我可以帮你分析这个任务。</MessageContent>
</Message>;

import {
    Tool,
    ToolContent,
    ToolHeader,
    ToolInput,
    ToolOutput,
} from "@buildingai/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 "@buildingai/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 "@buildingai/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 "@buildingai/ui/hooks/use-alert-dialog";

<AlertDialogProvider>
    <App />
</AlertDialogProvider>;

import { useAlertDialog } from "@buildingai/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 "@buildingai/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 "@buildingai/ui/hooks/use-upload-file";

const { uploadFile, isUploading, progress, uploadedFile } = useUploadFile({
    onUploadComplete: (file) => console.log(file.url),
});

await uploadFile(file);

import { useCopy, useDocumentHead } from "@buildingai/hooks";

function Page() {
    useDocumentHead({ title: "文章管理" });
    const { copy, isCopying } = useCopy();

    return (
        <Button disabled={isCopying} onClick={() => copy("hello")}>
            复制
        </Button>
    );
}

import { createHttpClient, createStandardApiParser } from "@buildingai/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 "@buildingai/services";

import { createPluginHttpClients } from "@buildingai/services";

const { apiHttpClient, consoleHttpClient } = createPluginHttpClients();

export { apiHttpClient, consoleHttpClient };

import type {
    MutationOptionsUtil,
    PaginatedQueryOptionsUtil,
    PaginatedResponse,
    QueryOptionsUtil,
} from "@buildingai/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 "@buildingai/stores";

export const useDemoStore = createStore(createDemoSlice, {
    persist: {
        name: "demo",
        partialize: (state) => ({ demo: state.demo }),
    },
});

import { useAuthStore } from "@buildingai/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 "@buildingai/stores";

const storage = getLocalStorage();
const cached = safeJsonParse<string[]>(storage.getItem("selected_ids")) ?? [];
storage.setItem("selected_ids", safeJsonStringify(cached));

import { defineRouteOption } from "@buildingai/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 "@buildingai/web-core/vite/extension";
import packageJson from "./package.json";

export default defineExtensionViteConfig(packageJson, {
    server: { port: 5174 },
});