# @cawalch/porchlight 中文文档
规范地址：https://npmcn.com/package/%40cawalch/porchlight/
版本：0\.13\.1
npm 元数据更新时间：2026-10-31T16:20:14.732Z
中文译文更新时间：2026-10-31T19:17:38.824Z
软件包许可：MIT
本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40cawalch/porchlight
原文对照：https://npmcn.com/package/%40cawalch/porchlight/?lang=original
项目主页：https://cawalch.github.io/porchlight
源码仓库：https://github.com/cawalch/porchlight
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：2.3 MB，185 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-06-24T15:48:33.639Z
- 最新版本发布：2026-10-31T16:20:14.415Z
- 已发布版本数：17（近 12 个月 17 个）
## 中文简介
一个无依赖的原生css框架，用于构建可访问的、可主题化的web应用程序。
## 安装
```sh
npm install @cawalch/porchlight
```
也可以使用：`pnpm add @cawalch/porchlight`、`yarn add @cawalch/porchlight`、`bun add @cawalch/porchlight`
## README
# @cawalch / porchlight
Porchlight是一个无依赖的原生css框架， 主题web应用程序。看词根 [自述](https://github.com/cawalch/porchlight#readme) 和 这个 [文档网站](https://cawalch.github.io/porchlight) 以获得完整的指导。
在服务器模板、html片段和Alpine组件中使用稳定类。 看到 [集成指南](https://cawalch.github.io/porchlight/guides/integrations) 用于那些工作流和可选的CSS模块定制。
## 安装
```sh
pnpm add @cawalch/porchlight
# or
bun add @cawalch/porchlight
# or
npm install @cawalch/porchlight
```
## 完整的包
主要导出是一个预构建的样式表。通过解析包导入 你的应用绑定器，并加载一次生成的CSS条目。浏览器无法解析 这些裸包名称直接；使用下面的静态HTML而不使用捆绑器。
```css
@layer porchlight, app;
@import "@cawalch/porchlight";
@layer app {
/* your product styles */
}
```
## 较小的包
如果你的应用只使用了几个组件，那就从 `core.css`，然后导入 你需要的东西。
```css
@layer porchlight, app;
@import "@cawalch/porchlight/core.css";
@import "@cawalch/porchlight/layout.css";
@import "@cawalch/porchlight/components/button.css";
@import "@cawalch/porchlight/components/field.css";
@import "@cawalch/porchlight/components/card.css";
@import "@cawalch/porchlight/utilities.css";
```
`core.css` 包括层顺序，重置，令牌，主题和基本样式。 组件文件依赖于这些令牌，所以加载 `core.css` 第一。 对于拆分按钮，也要加载 `button.css` 之前 `split-button.css`;它的两个 片段使用按钮组件。 `porchlight copy --components split-button` 包括 `button.css` 自动，而CSS `@import` 保持明确的。
如果你想要整个实用框架而不需要实验增强 语法、使用 `compat.css`． 它包括核心、布局、所有组件和 公用事业，但遗漏 `enhancements.css`.
```css
@layer porchlight, app;
@import "@cawalch/porchlight/compat.css";
```
## 公共CSS API
Porchlight公共钩子使用 `pl-` 命名空间，以避免冲突 应用CSS和其他框架：
- 组件: `.pl-c-button`， `.pl-c-card__title`
- 布局原语: `.pl-l-stack`， `.pl-l-cluster`
- 公用事业: `.pl-u-sr-only`， `.pl-u-flow`
- 组件和实例令牌： `--pl-c-card-padding`， `--pl-l-stack-gap`
- Framework-wide属性: `data-pl-theme`， `data-pl-density`
组件本地属性，例如 `data-tone`， `data-selected`，以及ARIA 当作用域在Porchlight组件类下时，状态保持不带前缀。
## 静态HTML和CLI工具
对于服务器渲染的应用程序、快速原型或直接复制资产的管道，Porchlight包括命令行界面（CLI）：
```sh
# Scaffold a starter HTML file
npx --no-install porchlight init
# Scaffold with a custom output path, local stylesheet, and title
npx --no-install porchlight init --out public/index.html --local --title "My App"
# Inspect design tokens in the terminal
npx --no-install porchlight tokens
npx --no-install porchlight tokens radius
npx --no-install porchlight tokens --group Fonts
# Output matching tokens as JSON
npx --no-install porchlight tokens --group Colors --json
# Copy static CSS files for non-bundler pipelines
npx --no-install porchlight copy --out public/porchlight --compat
```
```html
```
这些url假定您的服务器公开 `public/` 在 `/`;根据你的 资产挂载或部署基础路径。
对于较小的静态切片，请命名您使用的组件（并可选择请求最小化输出）：
```sh
npx --no-install porchlight copy --out public/porchlight --components button,field --layout --utilities --min
```
```html
```
在 `app.css`，在重写之前声明你的层顺序：
```css
@layer porchlight, app;
@layer app {
/* app overrides */
}
```
生成的 `dist/porchlight.manifest.json` 列出每个打包的CSS文件， 组件名称，以及脚本的推荐复制顺序。
## 轻快地
Vite解析CSS导入包。从您的应用程序或导入一个CSS条目 链接到Vite的HTML入口；裸包导入不是浏览器url。
```css
@layer porchlight, app;
@import "@cawalch/porchlight/core.css";
@import "@cawalch/porchlight/components/button.css";
@import "@cawalch/porchlight/components/data-table.css";
@import "@cawalch/porchlight/utilities.css";
```
如果方便的话，你也可以从JS/TS条目中导入CSS：
```ts
import "@cawalch/porchlight/core.css";
import "@cawalch/porchlight/components/button.css";
import "./app.css";
```
对于生产版本，设置一个与您支持的浏览器匹配的CSS目标。 文档构建使用 `build.cssTarget: "chrome149"` 为了保留本土色彩 功能。这是Chromium的目标，而不是跨浏览器支持的保证。 完整的包也与Vite 8.2.1的默认目标在一个小的 亮/暗消费类灯具。更改目标后重新检查渲染输出 或缩小镜;看到 [Vite的CSS目标选项](https://vite.dev/config/build-options#build-csstarget).
## 面包和其他静态管道
Bun可以安装Porchlight并运行它的复制助手。使用Bun作为包 manager与发送CSS是分开的 `bun build`.
验证与 **Bun 1.4.2和Porchlight 0.13.1**：
| 路径 | 结果 |
| --- | --- |
| `bun add @cawalch/porchlight` | 安装软件包和本地命令行 |
| 包 `compat.css` 或者 `core.css` +选定组件 | 构建;发出非致命 `@property` 警告 |
| 绑定默认的导出或 `enhancements.css` | 失败在 `@container scroll-state(...)` |
| 复制预构建的CSS并直接提供服务 | 保留完整的CSS，无需解析器转换 |
对于Bun的CSS打包器，放入这个 `app.css`，然后跑 `bun build ./app.css --outdir ./dist`：
```css
@layer porchlight, app;
@import "@cawalch/porchlight/compat.css";
```
在页面中加载发出的样式表；单独的CSS构建不会附加它 到DOM。基本的按钮/卡片颜色以浅色和深色为主题； 这不是对每个组件或未来的Bun版本的保证。
要获得完整的bundle，可以显式地运行已安装的CLI和Bun的运行时：
```sh
bunx --bun --no-install porchlight copy --out public/porchlight --full
```
```html
```
将该目录作为静态文件提供。将复制的CSS返回给Bun's HTML/CSS打包器重新引入了解析器的限制。 `--bun` 避免了CLI的 节点工作; `--no-install` 使用本地安装包。 看到 [Bun的CSS捆绑器](https://bun.com/docs/bundler/css) 和 [Bunx运行时选择](https://bun.com/docs/pm/bunx#shebangs).
## 令牌
Porchlight为编辑器自动完成提供生成的令牌元数据， 验证和自定义工具。
```ts
import tokenDoc, { tokenGroups } from "@cawalch/porchlight/tokens";
console.log(tokenDoc.tokens["--pl-color-accent"].value);
console.log(tokenGroups.map((group) => group.name));
```
JSON也可用：
```ts
import tokens from "@cawalch/porchlight/tokens.json" with { type: "json" };
```
## 出口
| 导入路径 | 目录 |
| --- | --- |
| `@cawalch/porchlight` | 完整的预构建CSS包（缩小） |
| `@cawalch/porchlight/min.css` | 最小化的完整包别名 |
| `@cawalch/porchlight/porchlight.css` | 完整的未缩小的CSS包 |
| `@cawalch/porchlight/unminified.css` | 完全未缩小的CSS包别名 |
| `@cawalch/porchlight/compat.css` | 没有增强层的Bundle |
| `@cawalch/porchlight/compat.min.css` | 缩小的压缩包 |
| `@cawalch/porchlight/core.css` | 图层顺序，重置，标记，主题，基础 |
| `@cawalch/porchlight/core.min.css` | 缩小的核心样式表 |
| `@cawalch/porchlight/layout.css` | 布局原语 |
| `@cawalch/porchlight/layout.min.css` | 最小化布局原语 |
| `@cawalch/porchlight/components.css` | 所有51个组件CSS文件 |
| `@cawalch/porchlight/components.min.css` | 最小化所有组件包 |
| `@cawalch/porchlight/components/*.css` | 单个组件CSS文件 |
| `@cawalch/porchlight/components/*.min.css` | 单个最小化组件CSS文件 |
| `@cawalch/porchlight/utilities.css` | 实用程序类 |
| `@cawalch/porchlight/utilities.min.css` | 迷你实用程序类 |
| `@cawalch/porchlight/enhancements.css` | 渐进增强层 |
| `@cawalch/porchlight/enhancements.min.css` | 缩小增强层 |
| `@cawalch/porchlight/tokens` | 类型化令牌元数据模块 |
| `@cawalch/porchlight/tokens.json` | 令牌元数据JSON |
| `@cawalch/porchlight/manifest.json` | Static-copy清单 |
| `@cawalch/porchlight/src/*` | 原料泄漏口 |
有关记录所有51个组件（主选择器、模块化导入路径、最小化包、依赖项和描述）的离线参考，请参见 [`COMPONENTS.md`](https://npmcn.com/package/%40cawalch/porchlight/COMPONENTS.md).
## 层序
Porchlight包含了每条规则 `@layer porchlight.*`． 声明你的应用程序层 在Porchlight之后，产品CSS赢得了无特异性的战斗。
不要通过 `layer(...)` 这些进口。Porchlight已经自我分层了。
## 浏览器支持
铬是主要的测试目标；Firefox和WebKit烟雾有限 报道。 `@scope` 需要Firefox 146或更高版本，而不是Firefox 135。Porchlight使用 现代CSS包括 `@layer`， `@scope`， `@property`OKLCH, `light-dark()`， `color-mix()`， `:has()`，容器查询，弹出窗口API， 以及锚的定位。看到 [浏览器支持指南](https://cawalch.github.io/porchlight/guides/browser-support) 对于完整的特征矩阵。
## 常见问题
### @cawalch/porchlight 是什么？
一个无依赖的原生css框架，用于构建可访问的、可主题化的web应用程序。
### 如何安装 @cawalch/porchlight？
在项目目录运行 npm install @cawalch/porchlight，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 porchlight，可以用 npx porchlight 直接运行。
### @cawalch/porchlight 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @cawalch/porchlight 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @cawalch/porchlight 可以商用吗？
@cawalch/porchlight 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @cawalch/porchlight 还在维护吗？
最新版本 0\.13\.1 发布于 2026/11/01（2 天前）；至今共发布 17 个版本，其中过去 12 个月发布了 17 个；首次发布于 2026/06/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。