# @aphrody/m3-primitives 中文文档

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

版本：1\.4\.7
npm 元数据更新时间：2026-10-23T03:53:52.189Z
中文译文更新时间：2026-11-07T07:16:53.898Z
软件包许可：Apache-2\.0 AND MIT

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

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

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

- 包体积（解压后）：884 kB，114 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：9 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0，tailwindcss \>=4\.1\.0
- 首次发布：2026-09-25T02:03:50.273Z
- 最新版本发布：2026-10-23T03:53:51.988Z
- 近 30 天下载量：2017（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

材料设计 3 反应原始: SpaceUI (@spacedrive/primitives) 组件被重建在相片设计系统的M3角色上,形状,型号,状态层和运动上.

## 安装

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

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

## README

# @aphrody/m3 - 小学

材质设计 3 反应原始人(按钮,字段,菜单,对话框,卡片,土司) 在 Base UI上,从 SpaceUI 重建 `@spacedrive/primitives`。 。 。 .

```sh
bun add @aphrody/m3-primitives @aphrody/m3-theme @aphrody/m3-tokens react react-dom tailwindcss
```

```tsx
import {
  Button,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
  Input,
} from "@aphrody/m3-primitives";

export function Welcome() {
  return (
    <Card variant="elevated">
      <CardHeader>
        <CardTitle>Welcome</CardTitle>
      </CardHeader>
      <CardContent>
        <Input placeholder="Your name" icon="person" />
        <Button variant="filled">Get started</Button>
      </CardContent>
    </Card>
  );
}
```

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

SpaceUI设定(MIT, (c) Spacedrive)在M3系统上被重建:颜色角色和状态层,10步形状尺度, 排版尺、焦点环、高地、材料符号和 `@aphrody/m3-motion`。 。 。 . [基础UI](https://base-ui.com/) (单位:千美元)`@base-ui/react`)是无头层:它拥有行为,键盘交互,焦点 管理和无障碍,并驱动 M3 通过其 `data-starting-style` 编号 : `data-ending-style` 属性。 每个上游出口和道具仍然起作用;Radix时代道具(`asChild`, (中文(简体) ), `checked="indeterminate"`, (中文(简体) ), `delayDuration`, (中文(简体) ), `forceMount`, (中文(简体) ), `onSelect`, 数组滑动器值)被映射到 Base UI,以及 基础UI道具也被接受.

每个组件的组合规则、符号映射和材料Web当量: [空间-M3-未来.md](https://github.com/aphrody-labs/bun-distribution/blob/os/docs/material/m3/architecture/design/SPACEUI-M3-FUSION.md)。 。 。 . 端点 : `react` 财务报告和审定财务报表 `react-dom` 18或19岁, `tailwindcss` 4.1+ (英语).

## 样式

这些部件采用M3 Tailwind公用事业(`bg-surface-container`, (中文(简体) ), `text-on-surface-variant`, (中文(简体) ), `rounded-full`, (中文(简体) ), `text-label-large`, (中文(简体) ), `hover:bg-on-surface/8`),所以应用程序 用 Tailwind v4 编译它们 :

```css
@import "tailwindcss";
@import "@aphrody/m3-tokens/m3-tokens.css"; /* shape, typescale, elevation, motion, state */
@import "@aphrody/m3-theme/spaceui.css"; /* SpaceUI themes as M3 schemes — or tokens.css */
@import "@aphrody/m3-theme/tailwind.css"; /* M3 utilities */
@source "../node_modules/@aphrody/m3-primitives/dist";
```

图标使用材料符号字体:导入 `@aphrody/m3-fonts/fonts-symbols.css`,或,与 `@aphrody/material-web` 已安装, 注册一次 :

```ts
import { ensureMaterialSymbols } from "@aphrody/material-web/icon/material-symbols.js";
ensureMaterialSymbols();
```

## 使用量

```tsx
import {
  Button,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
  Icon,
  Input,
} from "@aphrody/m3-primitives";

export function Welcome() {
  return (
    <Card variant="elevated">
      <CardHeader>
        <CardTitle>Welcome</CardTitle>
      </CardHeader>
      <CardContent className="space-y-4">
        <Input placeholder="Your name" icon="person" />
        <Button variant="filled">
          <Icon name="arrow_forward" size={18} /> Get started
        </Button>
      </CardContent>
    </Card>
  );
}
```

## 构成部分

| 组 | 构成部分 | M3 解剖学 |
| --- | --- | --- |
| 行动 | `Button` (单位:千美元)`filled`, (中文(简体) ), `tonal`, (中文(简体) ), `outlined`, (中文(简体) ), `text`, (中文(简体) ), `elevated` + SpaceUI 的变体,), `CircleButton`, (中文(简体) ), `CircleButtonGroup`, (中文(简体) ), `ShinyButton`, (中文(简体) ), `ShinyToggle`, (中文(简体) ), `FilterButton`, (中文(简体) ), `SelectPill`, (中文(简体) ), `SelectTriggerButton` | 常用按钮、图标按钮、 连接组、 过滤芯片 |
| 选择 | `CheckBox`, (中文(简体) ), `RadixCheckbox`, (中文(简体) ), `Switch`, (中文(简体) ), `Slider`, (中文(简体) ), `RadioGroupRoot/Item`, (中文(简体) ), `ToggleGroup`, (中文(简体) ), `OptionList` | 复选框、开关、滑动器、收音机、分块按钮 |
| 文本输入 | `Input`, (中文(简体) ), `SearchInput`, (中文(简体) ), `PasswordInput`, (中文(简体) ), `TextArea`, (中文(简体) ), `Label`, (中文(简体) ), `SearchBar`, (中文(简体) ), `NumberStepper`, (中文(简体) ), `Select` | 已大纲/ 已填充文本字段、 搜索栏、 已曝光的下拉菜单 |
| 导航 | `TabsRoot/List/Trigger/Content`, (中文(简体) ), `TabBar`, (中文(简体) ), `SpaceItem` | 主标签, 导航绘图项目 |
| 菜单和封面 | `Dialog` (+ 数) `dialogManager`, (中文(简体) ), `useDialog`, (中文(简体) ), `Popover`, (中文(简体) ), `Tooltip`, (中文(简体) ), `Kbd`, (中文(简体) ), `DropdownMenu`, (中文(简体) ), `ContextMenu`, (中文(简体) ), `Dropdown` | 基本对话框、菜单、普通工具提示 |
| 反馈 | `toast`, (中文(简体) ), `Toaster`, (中文(简体) ), `Loader`, (中文(简体) ), `ProgressBar`, (中文(简体) ), `CircularProgress`, (中文(简体) ), `Banner`, (中文(简体) ), `InfoBanner`, (中文(简体) ), `Badge` | Snackbar、进度指示器、横幅、徽章和辅助芯片 |
| 封装 | `Card` (单位:千美元)`elevated`, (中文(简体) ), `filled`, (中文(简体) ), `outlined`, (中文(简体) ), `Divider`, (中文(简体) ), `Collapsible`, (中文(简体) ), `Resizable`, (中文(简体) ), `LayoutCard`, (中文(简体) ), `GridLayout` | 纸牌、分牌、扩展面板 |
| 类型 | `CategoryHeading`, (中文(简体) ), `ScreenHeading`, (中文(简体) ), `Shortcut` | 标题小, 标题小, 密钥芯片 |
| 表单 | `Form`, (中文(简体) ), `ErrorMessage`, (中文(简体) ), `errorStyles`, (中文(简体) ), `z` | 支持文本出错 |
| 帮助者 | `Icon`, (中文(简体) ), `renderIcon`, (中文(简体) ), `IconSource`, (中文(简体) ), `PHOSPHOR_TO_SYMBOL`, (中文(简体) ), `m3StateLayer`, (中文(简体) ), `m3FocusRing`, (中文(简体) ), `tw`,表面类名称,关键符号 |  |

大小:默认值( E)`md`/unset)为M3基线高;尺寸较小为M3密度阶.

## 来自 `@spacedrive/primitives`

重命名导入 。 Phosphor 图标道具仍在编译(它们接受 `IconSource`: a 材料 符号名称、元素或组件。 明显差异: M3高地(输入默认为56高地, 图标按钮到40),丸形按钮, `secondary-container` 选择, 材料符号glyphs, `Select` 在它的下方打开, `Collapsible` 绘制一个 `expand_more` 指标(`indicator={false}` 页:1.

## 发展

```sh
bun run typecheck
bun test          # happy-dom preloaded by bunfig.toml
bun run build     # Bun.build + declarations
```

## 常见问题

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

材料设计 3 反应原始: SpaceUI \(@spacedrive/primitives\) 组件被重建在相片设计系统的M3角色上,形状,型号,状态层和运动上\.

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

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

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

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

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

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

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

@aphrody/m3-primitives 使用 Apache-2\.0 AND MIT 许可。声明的许可为 Apache-2\.0 AND MIT，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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