# @frontile/theme 中文文档

规范地址：https://npmcn.com/package/%40frontile/theme/

版本：0\.18\.9
npm 元数据更新时间：2026-11-13T20:05:30.523Z
中文译文更新时间：2026-11-15T15:06:00.592Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.9 MB，140 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：10\.\* \|\| \>= 12
- 运行依赖：10 个
- peer 依赖：tailwindcss \*，ember-source \>= 4\.12\.0，@babel/runtime \>= 7
- 首次发布：2024-01-10T01:20:10.504Z
- 最新版本发布：2026-11-13T20:05:30.336Z
- 近 30 天下载量：4912（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：78（近 12 个月 35 个）

## 中文简介

Ember Octane apps 组件库:主题

## 安装

```sh
npm install @frontile/theme
```

也可以使用：`pnpm add @frontile/theme`、`yarn add @frontile/theme`、`bun add @frontile/theme`

## README

## @ frontile/ 主题

Ember Octane apps 组件库:主题

## 兼容性

-   Ember.js v3.16 或以上 (中文(简体) )
-   Ember CLI v2.13 或以上 (单位:千美元)
-   节点.js v10 或以上

## 安装

```sh
ember install @frontile/theme
```

### 样式

#### 尾风 CSS v3

```js
// tailwind.config.js

const { frontile, safelist } = require('@frontile/theme/plugin');

module.exports = {
  content: [
    './app/**/*.{html,js,ts,hbs,gts,gjs}',
    './node_modules/@frontile/theme/dist/**/*.js',
  ],
  safelist: [
    ...safelist,
  ],
  darkMode: "class",
  theme: {
    extend: {},
  },
  plugins: [frontile()],
  // ...
};
```

#### 尾风 CSS v4

##### 使用默认主题

对于默认主题,请将此添加到您的 `app/styles/app.css`数字 :

```css
@import "tailwindcss" source("../../");
@plugin "@frontile/theme/plugin/default";
@source '../../node_modules/@frontile';
```

##### 自定义前置主题

要自定义前置主题, 请在您命名的项目根创建文件 `frontile.js` 内容如下:

```js
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({ /* your config */ });
```

那就更新你的 `app/styles/app.css` 来使用自定义配置 :

```css
@import "tailwindcss" source("../../");
@plugin "./../../frontile.js";
@source '../../node_modules/@frontile';
```

### 颜色配置

您可以自定义前沿颜色的两种方式:

#### 备选案文1: Via 插件配置(建议)

配置您的颜色 `frontile.js` 文档。 这种方法会自动生成最佳文本对比的"上"颜色:

```js
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({
  themes: {
    light: {
      colors: {
        primary: {
          subtle: '#3b82f6',
          DEFAULT: '#2563eb',
          strong: '#1d4ed8',
        }
      }
    },
    dark: {
      colors: {
        primary: {
          subtle: '#60a5fa',
          DEFAULT: '#3b82f6',
          strong: '#2563eb',
        }
      }
    }
  }
});
```

使用任何颜色格式(hex, rgb, hsl, oklch等). 插件会自动生成"上"的颜色来进行最优的文本对比.

**CSS 可变引用 :** 您也可以引用配置中的其他 CSS 变量 :

```js
module.exports = frontile({
  themes: {
    light: {
      colors: {
        primary: {
          subtle: 'var(--color-surface-solid-6)',
        }
      }
    }
  }
});
```

**说明:** 在使用 CSS 变量引用时,自动"上"颜色生成被跳过,因为实际颜色值在构建时不为人所知. 需要时需要手动定义相应的"上"颜色.

### 自定义颜色

主题系统自动生成"上色"变体(如, `on-primary`, (中文(简体) ), `on-success`)用于语义颜色,以确保最佳文本对比. 这些颜色被作为语义背景上的文字/前色.

默认情况下,在彩色上使用WCAG对比指针来计算,并且会是纯白色或纯黑色. 然而,您可以覆盖这些自动生成的颜色,以符合您的品牌或设计要求:

```js
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({
  themes: {
    light: {
      colors: {
        // Define background colors as usual
        primary: {
          subtle: '#3b82f6',
          soft: '#2563eb',
          strong: '#1e3a8a',
          DEFAULT: '#1e40af'
        },
        // Override on-colors to use custom values
        'on-primary': {
          subtle: '#ffffff',      // Pure white
          soft: '#e0f2ff',        // Light blue tint instead of pure white
          strong: '#bfdbfe',      // Lighter blue
          DEFAULT: '#ffffff'      // Pure white
        }
      }
    }
  }
});
```

**支持部分覆盖** - 你没有定义的任何变体仍将是自动生成的:

```js
module.exports = frontile({
  themes: {
    light: {
      colors: {
        primary: {
          subtle: '#3b82f6',
          DEFAULT: '#1e40af',
          strong: '#1e3a8a',
        },
        'on-primary': {
          DEFAULT: '#e0f2ff',  // Only override the DEFAULT level, others auto-generate
        }
      }
    }
  }
});
```

您可以为任意语义色彩类别覆盖颜色 :

-   `on-neutral`, (中文(简体) ), `on-primary`, (中文(简体) ), `on-secondary`, (中文(简体) ), `on-tertiary`, (中文(简体) ), `on-success`, (中文(简体) ), `on-warning`, (中文(简体) ), `on-danger`
-   `on-surface-modal`

#### 备选案文2:通过CSS变量

在您的 CSS 中直接覆盖颜色 :

```css
@import "tailwindcss" source("../../");
@plugin "@frontile/theme/plugin/default";
@source '../../node_modules/@frontile';

@theme {
  /* Override primary colors */
  --color-primary-subtle: #3b82f6;
  --color-primary: #2563eb;
  --color-primary-strong: #1d4ed8;

  /* Manually define "on-" colors for text contrast */
  --color-on-primary-subtle: #ffffff;
  --color-on-primary: #ffffff;
  --color-on-primary-strong: #ffffff;
}
```

**说明:** 在通过 CSS 定义颜色时,必须手动定义相应的"上"颜色. 插件无法自动生成它们,因为CSS变量值在构建时无法访问.

## 文档

访问 [前卫. dev](https://frontile.dev/) 读取文件 并看到现场演示.

## 许可证

本项目根据以下规定获得许可证: [MIT 许可证](https://npmcn.com/package/%40frontile/theme/LICENSE.md)。 。 。 .

## 常见问题

### @frontile/theme 是什么？

Ember Octane apps 组件库:主题

### 如何安装 @frontile/theme？

在项目目录运行 npm install @frontile/theme，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：tailwindcss（\*）、ember-source（\>= 4\.12\.0）、@babel/runtime（\>= 7）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @frontile/theme 支持 TypeScript 吗？

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

### @frontile/theme 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @frontile/theme 需要什么版本的 Node\.js？

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

### @frontile/theme 可以商用吗？

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

### @frontile/theme 的下载量有多少？

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

### @frontile/theme 还在维护吗？

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