# @placeholderco/placeholder-ui 中文文档

规范地址：https://npmcn.com/package/%40placeholderco/placeholder-ui/

版本：3\.2\.3
npm 元数据更新时间：2026-11-02T04:42:07.740Z
中文译文更新时间：2026-11-02T04:55:01.057Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1 MB，441 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：36 个
- peer 依赖：svelte ^5\.0\.0，@sveltejs/kit ^2\.26\.0 \|\| ^3\.0\.0
- 首次发布：2026-02-07T01:18:41.764Z
- 最新版本发布：2026-11-02T04:42:07.366Z
- 已发布版本数：52（近 12 个月 52 个）

## 中文简介

一个现代的、可定制的Svelte 5 UI组件库，具有全面的主题支持。用单个配置对象重新命名它。

## 安装

```sh
npm install @placeholderco/placeholder-ui
```

也可以使用：`pnpm add @placeholderco/placeholder-ui`、`yarn add @placeholderco/placeholder-ui`、`bun add @placeholderco/placeholder-ui`

## README

# PlaceholderUI

使用单个配置对象重新命名的Svelte 5组件库。 表单、覆盖、布局、数据显示、TipTap富文本编辑器和 CodeMirror代码编辑器，所有样式都通过一组 `--ui-*` CSS的令牌。

-   在每个组件上添加5个runes、TypeScript和类型化的道具
-   带有持续性的浅色/深色/系统主题
-   中性默认调色板；在一个电话中交换您自己的颜色，字体和徽标
-   150+图标导出为原始SVG字符串

## 安装

```bash
pnpm add @placeholderco/placeholder-ui
```

同行的依赖: `svelte ^5`.

## 快速启动

把你的应用包裹起来 `AppShell` （它加载基本样式表），然后使用组件：

```svelte
<script lang="ts">
    import { AppShell, Navbar, Button } from '@placeholderco/placeholder-ui';
</script>

<AppShell>
    <Navbar appNav={{ href: '/', text: 'My App' }} />
    <Button variant="primary">Save</Button>
</AppShell>
```

或跳过 `AppShell` 然后自己导入标记样式表：

```ts
import '@placeholderco/placeholder-ui/app.css';
```

## 品牌

所有与颜色和字体相关的内容都解析为 `--ui-*` 自定义属性 有两种方法可以给图书馆打上品牌。

### 1\. 配置对象（推荐）

```ts
// src/routes/+layout.svelte (or any startup code)
import { applyTheme } from '@placeholderco/placeholder-ui';
import logo from '$lib/logo.svg?raw';

applyTheme({
    colors: {
        primary: '#1e3a5f', // dark brand colour: solid buttons, headings
        accent: '#93c5fd', // light brand colour: highlights, dark-mode accent
        tertiary: '#a5f3fc' // supporting color: links use its readable text color
    },
    fontFamily: "'Inter', system-ui, sans-serif",
    logo // raw SVG, rendered by <Logo />
});
```

每个品牌的颜色都有独立的 `*HoverColor` 和 `*PressedColor` 设置: `primaryHoverColor`， `accentHoverColor`， `tertiaryHoverColor`， `primaryPressedColor`， `accentPressedColor` 和 `tertiaryPressedColor`. 它们由坚实、轮廓和微妙的控制共享；微妙的变体使用 半透明的悬停填充在适当的地方。

这三种颜色都有两个相同的文本角色：

| 设置 | 用于 |
| --- | --- |
| `primaryTextColor`， `accentTextColor`， `tertiaryTextColor` | 在页面/纸张表面的彩色文本和轮廓边界。 |
| `primaryContrastColor`， `accentContrastColor`， `tertiaryContrastColor` | 文字和图标上的匹配实体填充，包括悬停和按下填充。 |

例如, `primaryTextColor` 样式化静止时的主要轮廓按钮，而 `primaryContrastColor` 为填充的主按钮上的标签设置样式。 `focusColor`， `link` 和 `linkHover` 控制键盘焦点环和链接 独立。更改悬停颜色不会更改其他角色。

所有角色覆盖都是可选的。默认情况下，主悬停使用重音文本 颜色，重音悬停使用三级悬停，三级悬停使用重音。主要按 从它的底色变暗。Primary文本默认为Primary；口音和 三级文本颜色比它们的基色变暗。重音和三级 按下的颜色由三级调亮（或省略三级调时的重音）。 主对比度默认为白色；重音和三级对比度默认为主要对比度。

对于现有配置，请替换 `primaryDark` 与 `primaryPressedColor`， `accentDark` 与 `accentTextColor`, `tertiaryDark` 与 `tertiaryTextColor`. 取代 `tertiaryLight` 与 `accentPressedColor` 和 `tertiaryPressedColor` 来保持两组受压状态。分别设置悬停的颜色 定制的交互。重命名 `primaryContrast` 和 `accentContrast` 来 `primaryContrastColor` 和 `accentContrastColor`． 它们的CSS令牌也获得 `-color` 后缀。CSS重写使用相应的串大小写名称， 如 `--ui-primary-hover-color` 和 `--ui-tertiary-text-color`.

### 明暗值

配置中的所有内容都是亮模式值，也适用于暗模式。 当暗模式处于活动状态时，添加一个 `dark` 用相同的块 形状。只有你的名字被覆盖；色度是根据每种颜色得出的。

```ts
applyTheme({
    colors: { primary: '#1e293b', accent: '#fbbf24', tertiary: '#7dd3fc' },
    logo,
    dark: {
        colors: { accent: '#fde68a', link: '#fde68a' },
        fontFamily: "'Inter', system-ui, sans-serif", // optional
        logo: darkLogo // optional
    }
});
```

`applyTheme` 注入一个 `<style>` 元素 `:root` 规则和a `:root.dark` 规则，因此值与现有值切换 `.dark` 类。

为了避免默认调色板在第一次绘制时闪烁，请呈现相同的配置 作为服务器端的CSS：

```ts
import { themeToCss } from '@placeholderco/placeholder-ui';
const css = themeToCss(myTheme); // ":root { ... }\n:root.dark { ... }"
```

然后把它放在 `<style>` 标签 `app.html` 或者你的根布局头。

### 2\. 纯CSS

覆盖在库之后加载的任何样式表中的标记：

```css
:root {
    --ui-primary-rgb: 30 58 95;
    --ui-primary-rgbc: 30, 58, 95;
    --ui-primary: rgb(var(--ui-primary-rgb));
    --ui-primary-hover-color: #1d4ed8;
    --ui-primary-pressed-color: #12253d;
    --ui-primary-text-color: #1e3a5f;
    --ui-primary-contrast-color: #ffffff;
    --ui-accent-rgb: 147 197 253;
    --ui-accent-rgbc: 147, 197, 253;
    --ui-accent: rgb(var(--ui-accent-rgb));
    --ui-accent-hover-color: #a5f3fc;
    --ui-accent-pressed-color: #cffafe;
    --ui-accent-text-color: #1d4ed8;
    --ui-accent-contrast-color: #1e3a5f;
    --ui-tertiary: #a5f3fc;
    --ui-tertiary-hover-color: #93c5fd;
    --ui-tertiary-pressed-color: #cffafe;
    --ui-tertiary-text-color: #0e7490;
    --ui-tertiary-contrast-color: #1e3a5f;
    --ui-focus-color: #1d4ed8;
    --ui-font-family: 'Inter', system-ui, sans-serif;
}
```

完整的令牌列表以及对每个角色的注释位于顶部 [src / lib / app.css](https://npmcn.com/package/%40placeholderco/placeholder-ui/src/lib/app.css).

### 色的角色

在选择颜色时保持这些关系，因为成分会假设它们：

| 令牌 | 角色 |
| --- | --- |
| `--ui-primary` | 默认为暗。实心按钮和活动背景。 |
| `--ui-accent` | 光。悬停，高亮，重音在黑暗模式。 |
| `--ui-tertiary` | 光。支持填充;它的文本颜色用于链接 |

### 字体

库从不捆绑一个字体。集 `--ui-font-family` (或 `fontFamily` 在 配置)并自己加载字体 `@font-face` 或者一个 `<link>`.

### 标志

`<Logo />` 渲染，按优先顺序：它 `svg` 道具、商标注册 通过 `applyTheme({ logo })` / `setLogo()`，或通用占位符。使用 `fill="currentColor"` 在您的SVG中，使其遵循主题，或注册一个单独的 深色图案logo `dark.logo` / `setLogo(light, dark)`.

## 变体

按钮，徽章，动作图标，下拉菜单，手风琴和进度条共享颜色 以令牌命名的变体： `primary`， `accent`， `tertiary`,再加上 `-outline` 和 `-subtle` 形式和中性词 `secondary`， `white`， `danger` 和 `auto-*` 变体。

使用额外的彩色按钮 `tertiary`， `tertiary-outline` 和 `tertiary-subtle`，通过配置 `colors.tertiary` 和现有的 `--ui-tertiary*` 令牌。这个 `secondary`， `secondary-subtle` 和 `secondary-selected` 变体保留其原有的中性风格；现有的 应用程序不需要重命名它们。现有的三级颜色和按钮样式 都被保留了下来，为家庭增加了轮廓支持。

## 主题（浅色/深色）

```ts
import { themeState, setTheme } from '@placeholderco/placeholder-ui';

setTheme('dark'); // 'light' | 'dark' | 'system'
themeState.isDarkMode; // reactive boolean
```

这个 `.light` / `.dark` 类应用于 `<html>`． 在您自己的组件中使用 `:global(.dark) .my-class { ... }` 或者表面符号(`--page-bg`， `--paper-body-bg`， `--text-color`， `--border-color`,……)。

## 开发

```bash
pnpm install
pnpm run dev      # showcase app at http://localhost:5173
pnpm run check    # svelte-check
pnpm run build    # library + showcase
pnpm run format
```

`src/lib` 是出版图书馆； `src/routes` 是橱窗。每一个 组件下有一个演示页面 `src/routes/components/<name>`.

## 许可证

[麻省理工学院](https://npmcn.com/package/%40placeholderco/placeholder-ui/LICENSE)

## 常见问题

### @placeholderco/placeholder-ui 是什么？

一个现代的、可定制的Svelte 5 UI组件库，具有全面的主题支持。用单个配置对象重新命名它。

### 如何安装 @placeholderco/placeholder-ui？

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

### @placeholderco/placeholder-ui 支持 TypeScript 吗？

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

### @placeholderco/placeholder-ui 支持 ESM 还是 CommonJS？

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

### @placeholderco/placeholder-ui 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @placeholderco/placeholder-ui 可以商用吗？

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

### @placeholderco/placeholder-ui 还在维护吗？

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