# @14ch/svelte-ui 中文文档

规范地址：https://npmcn.com/package/%4014ch/svelte-ui/

版本：0\.0\.83
npm 元数据更新时间：2026-11-04T12:43:31.087Z
中文译文更新时间：2026-11-06T20:49:23.999Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%4014ch/svelte-ui
原文对照：https://npmcn.com/package/%4014ch/svelte-ui/?lang=original
项目主页：https://github.com/iyodatakashi/svelte-ui#readme
源码仓库：https://github.com/iyodatakashi/svelte-ui

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

- 包体积（解压后）：863 kB，156 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：sass ^1\.89\.2，svelte ^5\.0\.0
- 首次发布：2025-10-13T09:23:19.326Z
- 最新版本发布：2026-11-04T12:43:30.913Z
- 近 30 天下载量：2366（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：83（近 12 个月 81 个）

## 中文简介

拥有 TypeScript 支持的现代 Svelte UI 组件库

## 安装

```sh
npm install @14ch/svelte-ui
```

也可以使用：`pnpm add @14ch/svelte-ui`、`yarn add @14ch/svelte-ui`、`bun add @14ch/svelte-ui`

## README

# Svelte 用户界面

一个Svelte组件库,拥有TypeScript支持和材质设计启发的造型.

> **QQ 预览发布**: 此库在预览中 。 API在稳定1.0放出前可能会有变化.

## 特征

-   设计灵感组件
-   ARIA 支持和键盘导航
-   移动设备触控优化
-   暗模式和高对比模式支持
-   包含类型脚本定义
-   可树动的ES模块
-   由 Svelte 5 个 API 创建

## 安装

```bash
npm install @14ch/svelte-ui
# or
pnpm install @14ch/svelte-ui
# or
yarn add @14ch/svelte-ui
```

## 设置

### 1\. 导入样式

组件从 `--svelte-ui-*` CSS变量,所以设计符号必须被加载.

对于一个应用,导入一切(建议):

```javascript
// Icon fonts + design tokens + app-wide base rules
import '@14ch/svelte-ui/styles';
```

对于将svelte-ui组件嵌入到其他应用程序的软件包,只导入组件需要的东西,所以不会漏入主机页面:

```javascript
// Design tokens only: CSS variables on :where(:root) and the dark/high-contrast switches.
// No external requests, no rules on elements.
import '@14ch/svelte-ui/styles/tokens';

// Material Symbols fonts (loaded from Google Fonts).
// Needed only when components render an icon: Icon, IconButton, Fab, the `icon` props,
// and built-in icons such as clear buttons, popup arrows, pickers and PopupMenu check marks.
import '@14ch/svelte-ui/styles/icons';
```

部件与 `styles/tokens` 独自一人,如满地 `styles`。完全导入还对整个页面适用这些基本规则: `box-sizing: border-box` 每个元素的重置 `button`, (中文(简体) ), `color: inherit` 页:1 `dialog`, (中文(简体) ), `font-weight: normal` 页:1 `label`,自动填充背景修正 `input`,则 `.sr-only` 课.

可选额外( Sass 源; 您的建设需要) `sass`:

```javascript
import '@14ch/svelte-ui/styles/optional/fonts.scss'; // Roboto, Noto Sans JP, YakuHanJP
import '@14ch/svelte-ui/styles/optional/reset.scss'; // CSS reset
```

### 2\. 基本用途

```svelte
<script>
    import { Button, Input, Dialog } from '@14ch/svelte-ui';

    let dialogRef;
    let inputValue = $state('');
</script>

<Input bind:value={inputValue} placeholder="Enter your name" />

<Button onclick={() => dialogRef.open()}>Open Dialog</Button>

<Dialog bind:this={dialogRef} title="Greeting">
    <p>Hello {inputValue}!</p>
    <p>Welcome to Svelte UI Component Library.</p>
    {#snippet footer()}
        <Button onclick={() => dialogRef.close()}>Close</Button>
    {/snippet}
</Dialog>
```

## 可用组件

### 窗体组件

-   `Button` - 各种按钮样式和状态
-   `Input` - 有验证支持的文本输入
-   `Textarea` - 多行文字输入
-   `Checkbox` - 带有自定义样式的复选框
-   `CheckboxGroup` - 多个复选框选择组
-   `Radio` - 无线电按钮组
-   `RadioGroup` - 无线电按钮组包装器
-   `Select` - 下拉选择
-   `Combobox` - 可搜索的下降
-   `Slider` - 范围滑动器输入
-   `Switch` - 切换开关
-   `ColorPicker` - 颜色选择输入
-   `Datepicker` - 带有日历的日期选择
-   `FileUploader` - 拖放文件上传( D)
-   `ImageUploader` - 有预览的图像上传

### 布局导航( N)

-   `Tab` 编号 : `TabItem` - 标签导航
-   `Pagination` - 页面导航

### 模块

-   `Dialog` - 模块对话框
-   `ConfirmDialog` - 确认对话框
-   `Drawer` - 边抽屉

### 弹出菜单( M)

-   `Popup` - 填充内容
-   `PopupMenu` 编号 : `PopupMenuButton` - 上下文菜单

### 通知和反馈

-   `Snackbar` 编号 : `SnackbarItem` - 敬酒通知
-   `LoadingSpinner` - 装入指标

### 斯凯勒通装入器

-   `Skeleton` - 用预设模式加载占位符

### 图标按钮( B)

-   `Icon` - 材料符号图标
-   `IconButton` - 基于图标的按钮
-   `Fab` - 浮动动作按钮

## 构成部分实例

### 按钮变量

```svelte
<script>
    import { Button } from '@14ch/svelte-ui';
</script>

<!-- Different variants -->
<Button variant="filled">Filled Button</Button>
<Button variant="outlined">Outlined Button</Button>
<Button variant="text">Text Button</Button>

<!-- With icons -->
<Button icon="add">Add Item</Button>

<!-- Different sizes -->
<Button size="small">Small</Button>
<Button size="medium">Medium</Button>
<Button size="large">Large</Button>

<!-- States -->
<Button disabled>Disabled</Button>
<Button loading>Loading...</Button>
```

### 表格验证

```svelte
<script>
    import { Input, Checkbox, Button } from '@14ch/svelte-ui';

    let email = $state('');
    let password = $state('');
    let agreed = $state(false);

    const handleSubmit = () => {
        if (!email || !password || !agreed) {
            alert('Please fill all fields');
            return;
        }
        // Handle form submission
    };
</script>

<Input bind:value={email} type="email" placeholder="Email" required />

<Input bind:value={password} type="password" placeholder="Password" required />

<Checkbox bind:value={agreed}>I agree to the terms and conditions</Checkbox>

<Button onclick={handleSubmit} disabled={!agreed}>Sign Up</Button>
```

### 复选框和无线电组

```svelte
<script>
    import { CheckboxGroup, RadioGroup } from '@14ch/svelte-ui';

    const options = [
        { label: 'Option 1', value: 'opt1' },
        { label: 'Option 2', value: 'opt2' },
        { label: 'Option 3', value: 'opt3' }
    ];

    let selectedCheckboxes = $state([]);
    let selectedRadio = $state(null);
</script>

<CheckboxGroup bind:value={selectedCheckboxes} {options} direction="vertical" gap="16px" />

<RadioGroup bind:value={selectedRadio} {options} direction="horizontal" gap="24px" />
```

### 斯凯勒通装入器

```svelte
<script>
    import { Skeleton, SkeletonBox, SkeletonText, SkeletonAvatar } from '@14ch/svelte-ui';
</script>

<!-- Using preset patterns -->
<Skeleton patterns={[{ type: 'article-list' }]} repeat={3} />
<Skeleton patterns={[{ type: 'product-list' }]} repeat={4} />

<!-- Using individual components for custom layouts -->
<div>
    <SkeletonAvatar showName={true} />
    <SkeletonBox width="100%" height="200px" />
    <SkeletonText lines={3} />
</div>
```

### 带有确认的对话框

```svelte
<script>
    import { Button, ConfirmDialog } from '@14ch/svelte-ui';

    let confirmDialogRef;

    const handleDelete = () => {
        confirmDialogRef.open();
    };

    const onConfirm = () => {
        // Delete logic here
        console.log('Item deleted');
        confirmDialogRef.close();
    };
</script>

<Button variant="outlined" onclick={handleDelete}>Delete Item</Button>

<ConfirmDialog
    bind:this={confirmDialogRef}
    title="Confirm Delete"
    message="Are you sure you want to delete this item? This action cannot be undone."
    onconfirm={onConfirm}
    oncancel={() => confirmDialogRef.close()}
/>
```

## 黑暗主题

通过设置应用暗模式 `data-theme` 属性 :

```svelte
<script>
    import { Button } from '@14ch/svelte-ui';
    import { onMount } from 'svelte';

    let theme = $state('light');

    const toggleTheme = () => {
        theme = theme === 'light' ? 'dark' : 'light';
        document.body.setAttribute('data-theme', theme);
    };

    onMount(() => {
        document.body.setAttribute('data-theme', theme);
    });
</script>

<Button onclick={toggleTheme}>Toggle Theme</Button>
```

您也可以对特定区域应用暗模式 :

```svelte
<div data-theme="dark">
    <!-- This section and its children will use dark mode -->
    <Button>Dark Mode Button</Button>
</div>
```

## 自定义

### CSS 自定义属性

库使用 CSS 自定义属性来方便主题:

```css
:root {
    --svelte-ui-primary-color: #1976d2;
    --svelte-ui-surface-color: #ffffff;
    --svelte-ui-text-color: #1f1f1f;
    --svelte-ui-border-radius: 8px;
    /* ... and many more */
}
```

### 自定义暗模式颜色

您可以通过压倒性的 CSS 变量自定义暗模式颜色 :

```css
[data-theme='dark'] {
    --svelte-ui-primary-color: #90caf9;
    --svelte-ui-surface-color: #121212;
    --svelte-ui-text-color: #ffffff;
    /* ... customize other colors as needed */
}
```

## 类型脚本支持

所有组件都带有完整的类型脚本定义:

```typescript
import type { MenuItem } from '@14ch/svelte-ui';

const menuItems: MenuItem[] = [
    { title: 'Home', href: '/' },
    { title: 'About', href: '/about' },
    { title: 'Contact', href: '/contact' }
];
```

## 无障碍

该图书馆的建设考虑到了无障碍性:

-   ARIA 属性
-   键盘导航支持
-   屏幕阅读器通知
-   重点管理
-   高对比度模式支持

## 浏览器支持

-   克罗梅/第88号+
-   Firefox 78+ (英语)
-   萨法里14+

## 许可证

麻省理工学院的执照 - 看 [自由主义](https://npmcn.com/package/%4014ch/svelte-ui/LICENSE) 详细文件.

## 更改日志

### 页:1

-   改进 Tab 项目徘徊行为:用指示栏不透明变化替换背景颜色
-   Tab 项目现在显示选中的文本颜色和指示栏, 以获取更好的视觉反馈
-   中断更改:已替换 `variant` 道具为 `inline` 在 Combobox、 Datepicker 和选择组件中的道具

### 页:1

-   使用按钮、 Fab、 Tab 项目、 复选框和 Radio 组件改进文本垂直对齐 `text-box-trim`
-   文本标签现在在其容器内显示的视线更集中

### 页:1

(前出释注

### 页:1

-   初步释放
-   40+ 组件 (按钮, 输入, 对话框, Skeleton 加载器等)
-   复选框组和无线电组
-   带有预设模式的 Skeleton 组件
-   设计灵感造型
-   类型脚本支持
-   ARIA 键盘导航、屏幕阅读器支持
-   高对比度模式支持
-   Svelte 5 函数 API

## 常见问题

### @14ch/svelte-ui 是什么？

拥有 TypeScript 支持的现代 Svelte UI 组件库

### 如何安装 @14ch/svelte-ui？

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

### @14ch/svelte-ui 支持 TypeScript 吗？

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

### @14ch/svelte-ui 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @14ch/svelte-ui 可以商用吗？

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

### @14ch/svelte-ui 的下载量有多少？

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

### @14ch/svelte-ui 还在维护吗？

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