# @classic-homes/theme-svelte 中文文档

规范地址：https://npmcn.com/package/%40classic-homes/theme-svelte/

版本：1\.44\.0
npm 元数据更新时间：2026-11-05T19:57:10.489Z
中文译文更新时间：2026-11-09T23:50:47.383Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40classic-homes/theme-svelte
原文对照：https://npmcn.com/package/%40classic-homes/theme-svelte/?lang=original
项目主页：https://github.com/Classic-Homes/classic-theme#readme
源码仓库：https://github.com/Classic-Homes/classic-theme

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.5 MB，383 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：9 个
- peer 依赖：hls\.js ^1\.4\.0，svelte ^5\.31\.0，@classic-homes/notifications \*
- 首次发布：2026-01-08T18:28:45.249Z
- 最新版本发布：2026-11-05T19:57:10.269Z
- 近 30 天下载量：5863（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：129（近 12 个月 129 个）

## 中文简介

经典主题系统的 Svelte 组件

## 安装

```sh
npm install @classic-homes/theme-svelte
```

也可以使用：`pnpm add @classic-homes/theme-svelte`、`yarn add @classic-homes/theme-svelte`、`bun add @classic-homes/theme-svelte`

## README

# @ classic-homes/ 主题闪光

经典主题设计系统的Svelte 5组件. 建造在 [位素用户界面](https://bits-ui.com/) 原始和风格与Tailwind CSS.

## 安装

```bash
npm install @classic-homes/theme-svelte @classic-homes/theme-tokens
```

## 设置

### 1\. 配置尾风CSS

将经典主题添加到您的预设中 `tailwind.config.js`数字 :

```js
import preset from '@classic-homes/theme-tailwind-preset';

export default {
  presets: [preset],
  content: [
    './src/**/*.{html,js,svelte,ts}',
    './node_modules/@classic-homes/theme-svelte/**/*.{html,js,svelte,ts}',
  ],
};
```

### 2\. 进口设计托肯斯

在您的应用程序的 root CSS 文件中导入 CSS 令牌 :

```css
@import '@classic-homes/theme-tokens/css';
```

或者在您的根布局中 :

```svelte
<script>
  import '@classic-homes/theme-tokens/css';
</script>
```

## 使用量

```svelte
<script>
  import { Button, Card, CardHeader, CardTitle, CardContent } from '@classic-homes/theme-svelte';
</script>

<Card>
  <CardHeader>
    <CardTitle>Welcome</CardTitle>
  </CardHeader>
  <CardContent>
    <Button variant="default">Click me</Button>
  </CardContent>
</Card>
```

## 构成部分

### 核心用户界面

-   `Button` - 有变体的按钮(默认、次要、破坏性、轮廓、幽灵、链接)
-   `Input` - 文本输入字段
-   `Textarea` - 多行文字输入
-   `Label` - 表格标签
-   `Checkbox` - 复选框输入
-   `Switch` - 切换开关
-   `Select` - 选择下拉
-   `FormField` - 合并标签+输入+错误处理

### 版式

-   `AppShell` - 有跳过链接和土司容器的应用程序包装器
-   `DashboardLayout` - 仪表板的侧边栏和页眉布局
-   `PublicLayout` - 公共页面页眉+页脚布局
-   `FormPageLayout` - 居中格式页面布局
-   `Sidebar` - 导航边栏
-   `Header` - 页眉
-   `Footer` - 页脚

### 反馈

-   `Alert` - 警报信息(默认、破坏性、成功、警告、信息)
-   `AlertDialog` - 确认对话框
-   `Dialog` - 模块对话框
-   `Toast` - 敬酒通知
-   `ToastContainer` - 吐司通知容器
-   `Spinner` - 装入旋转器
-   `Skeleton` - 装入骨架

### 数据显示

-   `Card` - 有页眉、内容和页脚的纸箱
-   `Badge` - 身份证
-   `DataTable` - 可排序的数据表
-   `Tabs` - 标签导航
-   `Tooltip` - 自动工具提示
-   `DropdownMenu` - 下放菜单
-   `Avatar` - 用户形象

### 媒体

-   `AspectRatio` - 限制内容达到固定宽度与高度比率
-   `Image` - 用懒惰的加载、占位符和出错倒计时图像
-   `Video` - 有主题控件的视频播放器,完整的键盘支持,以及 HLS/Cloudflare Stream 回放
-   `Audio` - 用主题控件压缩音频播放器
-   `MediaEmbed` - Lazy YouTube、Vimeo、Cloudflare Stream和Matterport 3D巡回演唱会都装入了在点击前一无所有的东西
-   `MediaGrid` - 媒体缩略图响应画廊
-   `MediaCarousel` - 有点、缩略图和可选自动播放功能的可刷媒体幻灯片
-   `Lightbox` - 有缩放、平板和键盘导航的全屏幕媒体取景器

#### 适应流和云花流

`Video` 播放 HLS 播放列表,包括 Cloudflare Stream,其控件与自托管文件相同. Safari 本地播放 HLS; 其他浏览器需要 [hls.js (英语)](https://github.com/video-dev/hls.js),一个 **可选同伴依赖**数字 :

```bash
npm install hls.js
```

```ts
// once, at app startup
import { setHlsLoader } from '@classic-homes/theme-svelte';

setHlsLoader(() => import('hls.js').then((m) => m.default));
```

导入存在于您的代码中而不是这个软件包中,所以从未玩过一流的消费者不会被迫安装hls.js来构建.

```svelte
<script lang="ts">
  import { Video, cloudflareStream } from '@classic-homes/theme-svelte';

  const tour = cloudflareStream('a1b2c3d4e5f6', {
    customerCode: 'abc123',
    title: 'Product tour',
  });
</script>

<Video item={tour} />
```

`cloudflareStream()` 从 Stream 的 URL 计划中获取 HLS 播放列表和海报, 没有 API 调用 。 传递一个签名的回放信使,代替视频代号用于私人视频. 对于Cloudflare自己的玩家,请使用 `MediaEmbed` 与 `provider="cloudflare"`。 。 。 .

### 标记

-   `LogoMain` - 主要标志部分
-   `LoadingLogo` - 动画加载标志

### 通知部分(备选)

通知UI组件通过单独的切入点提供. 这使得 `@classic-homes/notifications` 依赖可选 - 只有使用这些组件时您才会需要它 .

```bash
# Install the notifications package if using notification components
npm install @classic-homes/notifications
```

```svelte
<script>
  // Import notification components from the /notifications subpath
  import {
    NotificationList,
    NotificationItem,
    NotificationBadge,
    NotificationDialog,
    NotificationFilters,
    NotificationBulkActions,
  } from '@classic-homes/theme-svelte/notifications';

  // Import types and utilities from the notifications package
  import type { Notification } from '@classic-homes/notifications/core';
</script>
```

可用的通知组件 :

-   `NotificationBadge` - 未读数徽章
-   `NotificationItem` - 单一通知卡
-   `NotificationList` - 空状态的通知清单
-   `NotificationDialog` - 通知的详细对话框
-   `NotificationFilters` - 过滤标签(全部/已读/未读)
-   `NotificationBulkActions` - 散装动作工具栏

## 处理错误

### 概览

此库中的组件不包括内置出错边界,以赋予您对出错处理的全部控制. 我们建议在您的应用程序的根层执行错误处理 .

### 建议:错误边界组件

创建一个错误边界组件来优雅地捕获和处理错误 :

```svelte
<!-- src/lib/ErrorBoundary.svelte -->
<script lang="ts">
  import type { Snippet } from 'svelte';
  import { Button, Alert, AlertDescription } from '@classic-homes/theme-svelte';

  interface Props {
    children: Snippet;
    fallback?: Snippet<[Error, () => void]>;
  }

  let { children, fallback }: Props = $props();
  let error = $state<Error | null>(null);

  function reset() {
    error = null;
  }

  $effect(() => {
    const handleError = (e: ErrorEvent) => {
      e.preventDefault();
      error = e.error || new Error(e.message);
    };

    const handleUnhandledRejection = (e: PromiseRejectionEvent) => {
      e.preventDefault();
      error = e.reason instanceof Error ? e.reason : new Error(String(e.reason));
    };

    window.addEventListener('error', handleError);
    window.addEventListener('unhandledrejection', handleUnhandledRejection);

    return () => {
      window.removeEventListener('error', handleError);
      window.removeEventListener('unhandledrejection', handleUnhandledRejection);
    };
  });
</script>

{#if error}
  {#if fallback}
    {@render fallback(error, reset)}
  {:else}
    <div class="flex min-h-screen items-center justify-center p-4">
      <div class="w-full max-w-md space-y-4">
        <Alert variant="destructive">
          <AlertDescription>
            <strong>Something went wrong</strong>
            <p class="mt-2 text-sm">{error.message}</p>
          </AlertDescription>
        </Alert>
        <Button onclick={reset} variant="outline" class="w-full">Try again</Button>
      </div>
    </div>
  {/if}
{:else}
  {@render children()}
{/if}
```

### 使用 Appshell

包起来 `AppShell` 使用错误边界 :

```svelte
<!-- src/routes/+layout.svelte -->
<script>
  import { AppShell } from '@classic-homes/theme-svelte';
  import ErrorBoundary from '$lib/ErrorBoundary.svelte';
</script>

<ErrorBoundary>
  <AppShell>
    <slot />
  </AppShell>
</ErrorBoundary>
```

### 自定义后退 UI

您可以提供自定义后退 UI :

```svelte
<ErrorBoundary>
  {#snippet fallback(error, reset)}
    <div class="error-page">
      <h1>Oops!</h1>
      <p>{error.message}</p>
      <button onclick={reset}>Reload</button>
    </div>
  {/snippet}

  <AppShell>
    <slot />
  </AppShell>
</ErrorBoundary>
```

## 标签

图书馆包括一个管理通知的土司店:

```svelte
<script>
  import { toastStore, Button } from '@classic-homes/theme-svelte';

  function showSuccess() {
    toastStore.success('Operation completed successfully!');
  }

  function showError() {
    toastStore.error('Something went wrong', { title: 'Error' });
  }
</script>

<Button onclick={showSuccess}>Show Success</Button>
<Button onclick={showError} variant="destructive">Show Error</Button>
```

土司方法:

-   `toastStore.success(message, options?)` - 绿色成功祝酒词
-   `toastStore.error(message, options?)` - 红色出错道具(默认为持久)
-   `toastStore.warning(message, options?)` - 黄警告吐司
-   `toastStore.info(message, options?)` - 蓝信息吐司
-   `toastStore.add(toast)` - 加自定义的土司
-   `toastStore.remove(id)` - 用身份证去除吐司
-   `toastStore.clear()` - 把吐司都拿开

## 边栏状态

对于可折叠侧边栏的布局,请使用侧边栏商店:

```svelte
<script>
  import { sidebarStore } from '@classic-homes/theme-svelte';

  function toggleSidebar() {
    sidebarStore.toggle();
  }
</script>

<button onclick={toggleSidebar}>
  {sidebarStore.isOpen ? 'Close' : 'Open'} Sidebar
</button>
```

## 类型脚本支持

所有组件全部输入。 视需要导入类型:

```typescript
import type {
  NavItem,
  NavSection,
  User,
  Tab,
  FileMetadata,
  DataTableColumn,
  SelectOption,
} from '@classic-homes/theme-svelte';
```

## Svelte 5 运行

所有组件都使用Svelte 5 runes语法:

-   `$props()` 组件道具
-   `$state()` 反应状态
-   `$derived()` 计算值
-   `$effect()` 副作用
-   `$bindable()` 双向绑定

## 无障碍

构件的构建考虑到无障碍性:

-   ARIA 属性
-   键盘导航支持
-   重点管理
-   方便屏幕阅读器
-   在 AppShell 中跳过链接

## 许可证

麻省理工学院

## 常见问题

### @classic-homes/theme-svelte 是什么？

经典主题系统的 Svelte 组件

### 如何安装 @classic-homes/theme-svelte？

在项目目录运行 npm install @classic-homes/theme-svelte，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：svelte（^5\.31\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @classic-homes/theme-svelte 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @classic-homes/theme-svelte 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @classic-homes/theme-svelte 可以商用吗？

@classic-homes/theme-svelte 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @classic-homes/theme-svelte 的下载量有多少？

根据 npm 官方下载统计，@classic-homes/theme-svelte 在 2026/10/10 – 2026/11/08 这 30 天内被下载 5,863 次，日均约 195 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @classic-homes/theme-svelte 还在维护吗？

最新版本 1\.44\.0 发布于 2026/11/06（4 天前）；至今共发布 129 个版本，其中过去 12 个月发布了 129 个；首次发布于 2026/01/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。