# @aphrody/m3-theme 中文文档

规范地址：https://npmcn.com/package/%40aphrody/m3-theme/

版本：1\.4\.7
npm 元数据更新时间：2026-10-23T03:52:10.883Z
中文译文更新时间：2026-11-07T08:13:56.891Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aphrody/m3-theme
原文对照：https://npmcn.com/package/%40aphrody/m3-theme/?lang=original
项目主页：https://github.com/aphrody-labs/bun-distribution/tree/os/packages/m3-theme#readme
源码仓库：https://github.com/aphrody-labs/bun-distribution

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

- 包体积（解压后）：151 kB，26 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=18\.0\.0
- 首次发布：2026-06-03T22:55:40.314Z
- 最新版本发布：2026-10-23T03:52:10.662Z
- 近 30 天下载量：1991（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

Canonical Materials 3 聚变表: sorders.cs(M3 + shadcn/ui + Tailwind v4别名),尾风.cs(每个M3系统代号为 Tailwind v4 用途)和spaceui.cs(SpaceUI主题重建为M3动态方案,有SpaceUI相容别名).

## 安装

```sh
npm install @aphrody/m3-theme
```

也可以使用：`pnpm add @aphrody/m3-theme`、`yarn add @aphrody/m3-theme`、`bun add @aphrody/m3-theme`

## README

# @aphrody/m3-主题

一个生成的材料 3 样式表( E)`tokens.css`,光和暗),用于映射shadcn/ui和Tailwind v4颜色别名 打开 `--md-sys-color-*` 角色。 。 .

```sh
bun add @aphrody/m3-theme
```

```ts
import "@aphrody/m3-theme/tokens.css"; // Bun bundles the CSS into the page
```

许可证: Apache-2.0(`LICENSE`) (中文(简体) ). 安装指南 : [文件/材料/立方米/INSTALL.md](https://github.com/aphrody-labs/bun-distribution/blob/os/docs/material/m3/INSTALL.md)。 。 。 .

角色是那个 [`@aphrody/material-web`](https://www.npmjs.com/package/@aphrody/material-web) 读取。 导入 工作表一次并样式带有两个词汇;没有应用的手卷颜色值.

## 里面有什么东西 `tokens.css`

-   m3 系统调色板 `--md-sys-color-*` (轻) `:root`暗色通过 `@media (prefers-color-scheme: dark)` **财务报告和审定财务报表** (单位:千美元) `.dark` 强制课 主题);
-   页:1 **阴影/ ui** 别名块( e)`--background`, (中文(简体) ), `--primary`, (中文(简体) ), `--border`, (...) (中文(简体) ) 绘制M3角色图;
-   页:1 **尾风 v4** `@theme inline` 块`--color-background`(中文(简体) ).

因为阴影和尾风的别名是参考 `var(--md-sys-color-*)`,则 暗主题只重新声明M3调色板——会自动跟随别名.

## 使用

```html
<!-- force the dark theme regardless of the OS preference -->
<html class="dark"></html>
```

然后是M3角色的风格(`background: var(--md-sys-color-surface)`)或为: 阴影化名( c)`var(--background)` 编号 : `var(--primary)`) (中文(简体) ).

## 重新生成

```sh
bun run generate                                   # tokens.css, tailwind.css, spaceui.css
M3_SEED=#1a73e8 M3_VARIANT=vibrant bun run generate  # another seed / variant for tokens.css
bun run fixture:mcu                                # refresh the Rust parity fixture
```

床单用Rust(`crates/ui/m3-tokens/src/sheets.rs`),并通过 `m3Css()` 联 合 国 `@aphrody/bun`;此软件包没有颜色表。 锈色科学是一种 准确端口数 `@material/material-color-utilities` (2021 spect) (英语) `test/sheets.test.ts` 财务报告和审定财务报表 `cargo test -p aphrody-m3-tokens` 检查每个角色与它. `tokens.css` 是直指点 m3基线种子计划 `#6750A4`所有49个角色 轻而易举.

## `tailwind.css` 财务报告和审定财务报表 `spaceui.css`

-   **`tailwind.css`**: 每个 M3 系统符作为 Tailwind v4 工具——所有颜色角色 (单位:千美元)`bg-surface-container`, (中文(简体) ), `text-on-surface-variant`固定角色) `success` 编号 : `warning` 角色,作为不透明修改器的状态层(`hover:bg-on-surface/8`,十步形状 比额表(`rounded-extra-large`),打出分级(`text-label-large`, (中文(简体) ), `font-brand|plain|code`, (中文(简体) ), 高地(`shadow-md3-1..5`),放松(`ease-emphasized-decelerate`)和M3断点 (单位:千美元)`medium:`, (中文(简体) ), `expanded:`, (中文(简体) ), `large:`, (中文(简体) ), `extra-large:`) (中文(简体) ).
-   **`spaceui.css`**: 七个空间UI主题(暗地,光线,午夜,鼻音,平板,北地,摩查) 其上游选择器下的M3动态方案,外加SpaceUI兼容设施 (单位:千美元)`bg-app-box`, (中文(简体) ), `text-ink-dull`, (中文(简体) ), `rounded-window`)解决了M3的角色和状态层. 用这个 改为 `tokens.css` 在SpaceUI衍生的应用程序中.

```css
@import "tailwindcss";
@import "@aphrody/m3-tokens/m3-tokens.css";
@import "@aphrody/m3-theme/spaceui.css"; /* or tokens.css */
@import "@aphrody/m3-theme/tailwind.css";
```

SpaceUI 表格镜像 `crates/ui/m3-tokens/src/spaceui.rs`· ; `bun test` 失败 漂流,或沉沦的时候。 绘图和规则: `docs/architecture/ui/design/SPACEUI-M3-FUSION.md`。 。 。 .

## 运行时间主题

颜色只来自 Rust 主人 `crates/ui/m3-tokens`。页面的编译表 (单位:千美元)`m3:theme.css` 从 `@aphrody/m3` 插头, `tokens.css`,一个品牌表) 携带建设时间 主题。 此软件包中没有任何内容获得颜色或写作 `--md-sys-color-*` 角色内置,所以 锈 `@media (prefers-contrast: more)` 块保持它们的效果.

不同的种子,变种或对比物是Rust `scheme` 工作表( e)`m3Css({ sheet: "scheme", ... })` 联 合 国 `@aphrody/bun`,或应用服务器路由响应),安装为一体 `<style>` 元素 及其对比-1双子 `@media (prefers-contrast: more)`。没有工作表来源 更改失败,但有明显的错误.

### 1\. 香草联合材料/TS: `applyDynamicFusionTheme`

```ts
import { applyDynamicFusionTheme, type M3SchemeSheet } from "@aphrody/m3-theme";

const sheet: M3SchemeSheet = async request =>
  (
    await fetch(
      `/api/m3/scheme.css?${new URLSearchParams(Object.entries(request).map(([k, v]) => [k, String(v)]))}`,
    )
  ).text();

await applyDynamicFusionTheme("#6750A4", {
  dark: false,
  contrastLevel: 0,
  variant: "tonalSpot",
  sheet,
});
```

选项 : `dark` (默认:目标) `.dark` 类别或 `prefers-color-scheme`, (中文(简体) ), `target` (默认) `<html>`; 将另一个元素的范围通过 `data-m3-scheme`, (中文(简体) ), `contrastLevel` 内 `[-1, 1]`, (中文(简体) ), `variant` 财务报告和审定财务报表 `sheet`。 。 。 . `applyM3Mode(dark, target)` 只设置模式类 `color-scheme`· ; `clearM3Scheme(target)` 返回编译的主题。 无效的输入或不是 Rust 的工作表 `scheme` 工作表拒绝并保留已安装的主题不变.

### 2\. 反应: `M3ThemeProvider` 打开 `useM3Theme`

这个 `default*` 道具描述所编译的主题. 虽然主题等于它们,但只提供者 设置模式. `setSeedColor`, (中文(简体) ), `setVariant` 财务报告和审定财务报表 `setContrastLevel` 无时抛出 `sheet` 道具为 给定; 失败的工作表源被曝光为 `schemeError`。 。 。 .

```tsx
import { M3ThemeProvider, useM3Theme } from "@aphrody/m3-theme/react";

function App() {
  return (
    <M3ThemeProvider
      defaultSeedColor="#6750a4"
      defaultThemeMode="system"
      sheet={sheet}
    >
      <YourMainAppLayout />
    </M3ThemeProvider>
  );
}
```

### 3\. Tauri 2.0一体化: `useM3TauriThemeSync` 打开 `M3TauriTitlebar`

对于编译为 Tauri 2.0 桌面外壳的React 应用程序,此软件包提供无缝零依赖性集成帮助器来管理本地窗口样式:

-   **`useM3TauriThemeSync`**:一个自定义的回放钩,可以自动将M3主题模式(光/暗)同步回Tauri本地窗口上下文,允许本地上下文菜单和对话框与应用程序外观相匹配.
-   **`M3TauriTitlebar`**:一个被高磨,材料设计3自定义的标题栏组件. 它处理窗口拖曳( I)`data-tauri-drag-region`),最大化/恢复状态,以及没有外部库要求的窗口动作(最小化,最大化,关闭),当应用程序运行在普通的网页浏览器中时自动隐藏.

```tsx
import { M3ThemeProvider } from "@aphrody/m3-theme/react";
import { M3TauriTitlebar, useM3TauriThemeSync } from "@aphrody/m3-theme/tauri";

function MainAppLayout() {
  // Syncs M3 theme mode back to Tauri window
  useM3TauriThemeSync();

  return (
    <div className="flex flex-col h-screen">
      {/* Renders a custom M3 borderless titlebar for the desktop app */}
      <M3TauriTitlebar title="My Material App" logo={<AppLogo />} />
      <div className="flex-1 overflow-auto">{/* Your content */}</div>
    </div>
  );
}
```

## 与 `@aphrody/m3-tokens`

红箱 `aphrody-m3-tokens` 拥有词条角色定义并生成 床单. `@aphrody/m3-tokens` 提供网页显示的动态颜色 API、CSS和 断点投影. `m3-theme` 添加阴影和尾风的化名, 所以 Lit Web 组件和反应公用设施决心发挥同样的M3作用。 保持运行时间网络输出 ;不保留第二个调色板表.

## 常见问题

### @aphrody/m3-theme 是什么？

Canonical Materials 3 聚变表: sorders\.cs\(M3 \+ shadcn/ui \+ Tailwind v4别名\),尾风\.cs\(每个M3系统代号为 Tailwind v4 用途\)和spaceui\.cs\(SpaceUI主题重建为M3动态方案,有SpaceUI相容别名\)\.

### 如何安装 @aphrody/m3-theme？

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

### @aphrody/m3-theme 支持 TypeScript 吗？

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

### @aphrody/m3-theme 支持 ESM 还是 CommonJS？

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

### @aphrody/m3-theme 可以商用吗？

@aphrody/m3-theme 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aphrody/m3-theme 的下载量有多少？

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

### @aphrody/m3-theme 还在维护吗？

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