# @hone-ui/sx 中文文档

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

版本：0\.2\.0
npm 元数据更新时间：2026-11-01T05:08:17.467Z
中文译文更新时间：2026-11-01T08:58:22.403Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40hone-ui/sx
原文对照：https://npmcn.com/package/%40hone-ui/sx/?lang=original
源码仓库：https://github.com/Visalan-H/ui-library

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

- 包体积（解压后）：127 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：@hone-ui/react ^0\.2\.0，@hone-ui/editor ^0\.2\.0
- 首次发布：2026-10-22T15:56:43.507Z
- 最新版本发布：2026-11-01T05:08:17.309Z
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

构建插件，编译成静态的CSS。

## 安装

```sh
npm install @hone-ui/sx
```

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

## README

# @hone-ui / sx

的构建插件 `sx` prop转换为静态CSS，因此浏览器中不会运行任何样式代码。

```tsx
<Box sx={{ p: 2, color: 'primary.main', '&:hover': { opacity: 0.8 } }} />
```

变成一个由生成的样式表支持的类：

```css
.hn-sx-k3J9aQ2x {
  padding: calc(2 * var(--hn-spacing));
  color: var(--hn-palette-primary-main);
}
.hn-sx-k3J9aQ2x:hover {
  opacity: 0.8;
}
```

## 设置

轻快地:

```ts
// vite.config.ts
import react from '@vitejs/plugin-react';
import sx from '@hone-ui/sx/vite';
import { defineConfig } from 'vite';

// List sx() before react(), and keep react() so Fast Refresh works.
export default defineConfig({
  plugins: [sx(), react()],
});
```

删除Vite模板 `src/index.css` 和 `App.css`，或者把它们放在较早的一层。他们的 非分层规则覆盖库。

Next.js，使用turbpack或webpack：

```ts
// next.config.ts
import { withSx } from '@hone-ui/sx/next';

// Pass your existing config object, such as create-next-app's, instead of {}.
// optimizePackageImports keeps `next build --webpack` from shipping every component.
export default withSx({
  experimental: { optimizePackageImports: ['@hone-ui/react'] },
});
```

进口 `app/globals.css` 在查看CSS之前 `app/layout.tsx`，并将其重置 `@layer reset, hone-ui;`。非分层CSS打败了库和 `sx`.

Rollup， esbuild和webpack的使用 `@hone-ui/sx/rollup`， `@hone-ui/sx/esbuild` 和 `@hone-ui/sx/webpack` 和维特一样。

## 选项

| 选项 | 默认的 | 目的 |
| --- | --- | --- |
| `breakpoints` | `{ values: { xs: 0, sm: 600, md: 900, lg: 1200, xl: 1536 } }` | 形状中的断点名称和宽度 `createTheme` 需要(`values`， `unit`）. 与主题共享一个对象。 |
| `palette` | `{}` | 你的主题 `palette` 对象。每个对象值键，例如 `neutral: { main }`，是调色板键。与主题共享一个对象。 |
| `paletteKeys` | `[]` | 额外的调色板键，例如 `['brand']`,所以 `'brand.500'` 解析为主题变量。 `main`， `light`， `dark` 和 `contrastText` 任何没有它的钥匙都可以工作。合并了 `palette`. |
| `spacing` | 无 | 主题的间距数组，例如 `[0, 4, 8, 16]`,所以 `p: 3` 编译, `16px`. |
| `importSources` | `['@hone-ui/react']` | 其组件为 `sx`。总是编译来自本地路径和同一文件的组件。 |
| `include` | `/\.[jt]sx$/` | 要转换的文件。 |
| `cacheDir` | `'node_modules/.cache/hone-ui-sx'` | 生成的CSS文件的位置。 |
| `editor` | `true` | 在dev中，用 `data-hn-source` 用于可视化编辑器。生产忽略了它。 |

## 什么编译

静态值、主题值、断点对象和数组、嵌套选择器、 `@media`， `@container` 和 `@supports` 块都编译成CSS。在运行时更改的值，例如 `width: size`，编译为该组件设置的CSS变量。条件项，如 `sx={[base, active && { color: 'red' }]}`，每个组合编译为一个类，最多三个 条件。的成员 `const` 样式对象在同一个文件中，例如 `sx={styles.root}`， 编译。

插件编译 `sx` 关于组件 `@hone-ui/react`，从您自己的文件中的组件， 在诸如 `memo(Box)`。另一个库的组件，甚至包装在 `styled(...)` 或者 `memo(...)`，保持它的 `sx` 都没动。

主题的功能，如 `sx={(theme) => ({ zIndex: theme.zIndex.drawer + 1 })}`，需要 主题在运行时。插件不处理它，不发出警告，组件调用它 当前主题。在数组中，第一个函数之前的项编译。函数和它之后的每一项 保持内联，这样以后的条目仍然会覆盖它。函数结果变成内联样式，因此它不能保存选择器或媒体查询。 插件不能区分服务器组件，所以它不会检查函数的位置；写 函数 `sx` 在一个 `'use client'`.

当无法编译文件时，插件会用文件和行发出警告 `sx` getter和方法； 扩展它不能读取，一个运行时 `typography` 值，或三个以上的条件。这些道具 退回到内联样式，它不能容纳选择器或媒体查询。

## 匹配主题

媒体查询和间距数组不能读取CSS变量，所以插件需要主题值 生活在它们外面。传递相同的值 `createTheme` 使用:

```ts
sx({
  breakpoints, // the object you pass to createTheme
  palette, // the palette you pass to createTheme; its object keys count as palette keys
  spacing: [0, 4, 8, 16, 32],
  paletteKeys: ['brand'],
});
```

一个数字 `spacing` 什么都不需要：因子相乘 `--hn-spacing`,这 `ThemeProvider` 集。 函数尺度不能传递给插件。把它写成一个数组。

## 常见问题

### @hone-ui/sx 是什么？

构建插件，编译成静态的CSS。

### 如何安装 @hone-ui/sx？

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

### @hone-ui/sx 支持 TypeScript 吗？

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

### @hone-ui/sx 支持 ESM 还是 CommonJS？

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

### @hone-ui/sx 可以商用吗？

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

### @hone-ui/sx 还在维护吗？

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