# @nine-thirty-five/material-symbols-react 中文文档

规范地址：https://npmcn.com/package/%40nine-thirty-five/material-symbols-react/

版本：2\.5\.2
npm 元数据更新时间：2026-11-02T00:19:43.333Z
中文译文更新时间：2026-11-02T00:33:57.160Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40nine-thirty-five/material-symbols-react
原文对照：https://npmcn.com/package/%40nine-thirty-five/material-symbols-react/?lang=original
项目主页：https://github.com/nine-thirty-five/material-symbols-react#readme
源码仓库：https://github.com/nine-thirty-five/material-symbols-react

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

- 包体积（解压后）：105 MB，109 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- peer 依赖：react \>=18
- 首次发布：2024-01-09T11:26:22.553Z
- 最新版本发布：2026-11-02T00:19:42.960Z
- 已发布版本数：73（近 12 个月 28 个）

## 中文简介

灵活的，可摇树的React包谷歌的材料符号-每一个风格，重量和填充。

## 安装

```sh
npm install @nine-thirty-five/material-symbols-react
```

也可以使用：`pnpm add @nine-thirty-five/material-symbols-react`、`yarn add @nine-thirty-five/material-symbols-react`、`bun add @nine-thirty-five/material-symbols-react`

## README

# 物质符号的反应

使用 [b谷歌的物质符号](https://fonts.google.com/icons?icon.set=Material+Symbols) in React - **各种款式，重量和填充**，完全可树摇，零运行时依赖。

生活例子: [九百三十- five.github.io / material-symbols-react](https://nine-thirty-five.github.io/material-symbols-react)

[![NPM version](https://img.shields.io/npm/v/@nine-thirty-five/material-symbols-react)](https://www.npmjs.com/package/@nine-thirty-five/material-symbols-react) [![Downloads](https://img.shields.io/npm/dm/@nine-thirty-five/material-symbols-react)](https://www.npmjs.com/package/@nine-thirty-five/material-symbols-react) ![npm-typescript](https://img.shields.io/npm/types/@nine-thirty-five/material-symbols-react) [![GitHub License](https://img.shields.io/badge/license-Apache--2.0-green)](https://npmcn.com/package/%40nine-thirty-five/material-symbols-react/LICENSE)

-   [安装](https://npmcn.com/package/%40nine-thirty-five/material-symbols-react/#readme-installation)
-   [使用](https://npmcn.com/package/%40nine-thirty-five/material-symbols-react/#readme-usage)
    -   [进口](https://npmcn.com/package/%40nine-thirty-five/material-symbols-react/#readme-importing)
    -   [权重](https://npmcn.com/package/%40nine-thirty-five/material-symbols-react/#readme-weights)
    -   [道具](https://npmcn.com/package/%40nine-thirty-five/material-symbols-react/#readme-props)
-   [摇树&束大小](https://npmcn.com/package/%40nine-thirty-five/material-symbols-react/#readme-tree-shaking--bundle-size)
-   [查找图标（用于代理和工具）](https://npmcn.com/package/%40nine-thirty-five/material-symbols-react/#readme-finding-icons-for-agents--tooling)
-   [ESM只](https://npmcn.com/package/%40nine-thirty-five/material-symbols-react/#readme-esm-only)
-   [从v1迁移](https://npmcn.com/package/%40nine-thirty-five/material-symbols-react/#readme-migrating-from-v1)
-   [它是如何工作的](https://npmcn.com/package/%40nine-thirty-five/material-symbols-react/#readme-how-it-works)
-   [许可证](https://npmcn.com/package/%40nine-thirty-five/material-symbols-react/#readme-license)

## 安装

```sh
npm install @nine-thirty-five/material-symbols-react
# or: yarn add … / pnpm add …
```

**需要React 18或19** (同行)的依赖。

## 使用

物质符号有三种 **风格** （`outlined`， `rounded`， `sharp`), 7 **权重** （`100`–`700`)，二 **填满** （划线/填写）。每个组合都有自己的导入路径，所以 您的捆绑器只发送您使用的确切图标。

### 进口

```tsx
// Default weight (400)
import { Search } from '@nine-thirty-five/material-symbols-react/outlined';
import { Home } from '@nine-thirty-five/material-symbols-react/outlined/filled';

// Specific weight
import { Star } from '@nine-thirty-five/material-symbols-react/rounded/300';
import { Favorite } from '@nine-thirty-five/material-symbols-react/rounded/700/filled';

// Sharp style
import { Delete } from '@nine-thirty-five/material-symbols-react/sharp/500';
```

```tsx
function Toolbar() {
  return (
    <>
      <Search />
      <Star size={32} />
      <Favorite color="crimson" />
    </>
  );
}
```

### 权重

导入路径遵循该模式 `…/{style}[/{weight}][/filled]`：

| 路径 | 风格 | 重量 | 填满 |
| --- | --- | --- | --- |
| `…/outlined` | 概述了 | 400 | 0 |
| `…/outlined/filled` | 概述了 | 400 | 1 |
| `…/outlined/300` | 概述了 | 300 | 0 |
| `…/rounded/700/filled` | 圆形的 | 700 | 1 |
| `…/sharp/100` | 锋利的 | 100 | 0 |

风格: `outlined`， `rounded`， `sharp`． 重量: `100`， `200`， `300`， `400`， `500`， `600`， `700` (裸路径默认为 `400`）. 附加 `/filled` 对于填充的变体。

### 道具

每个图标接受所有SVG道具(`SVGProps<SVGSVGElement>`)，再加上方便 `size` 道具:

```tsx
<Search size={32} />                 {/* sets width and height */}
<Search />                            {/* defaults to 1em — scales with font-size */}
<Search color="red" />                {/* icons use fill="currentColor" */}
<Search className="icon" />
<Search style={{ verticalAlign: 'middle' }} />
<Search onClick={…} aria-label="Search" />
```

-   **`size`** - - - - - - `number | string`． 设置两个 `width` 和 `height`． 默认为 `"1em"`，所以图标 与周围环境成比例 `font-size`。通过 `width`/`height` 显式地覆盖。
-   **颜色** -图标渲染 `fill="currentColor"`所以他们继承了 `color` 从CSS。
-   **`title`** -可访问的标签，呈现为SVG `<title>` 与 `role="img"`.

### 可访问性

图标 **默认是装饰性的**：他们用 `aria-hidden="true"` 屏幕阅读器跳过 他们。为了使一个图标有意义，给它一个标签- via `title`， `aria-label`，或者 `aria-labelledby` -然后切换到 `role="img"` 以标签作为其可访问的名称：

```tsx
<Delete />                    {/* decorative: aria-hidden="true" */}
<Delete title="Delete item" /> {/* semantic: role="img" + <title> */}
<Delete aria-label="Delete item" />
```

## 摇树&束大小

每个图标是一个单行模块(`base("<path>")`)在单个共享组件上，标记为 `/*#__PURE__*/` 在一个 `"sideEffects": false` 包中。只在一个重量下导入一个图标 这条路径，不是集合的其他部分，也不是其他权重。适用于Vite， Next.js, webpack， esbuild、Parcel和Rollup。

## 查找图标（用于代理和工具）

每个安装都附带一个可搜索的目录 **`…/manifest.json`** （`node_modules/@nine-thirty-five/material-symbols-react/dist/manifest.json`）. 每一个 条目有图标 `name`，是出口的。 `component`， `categories`，而且富有 `tags` （同义词）-因此工具或编码代理可以将自然语言请求解析为 组件 **离线**，没有API调用；

```jsonc
{
  "importPattern": "import { <component> } from '@nine-thirty-five/material-symbols-react/<style>[/<weight>][/filled]'",
  "styles": ["outlined", "rounded", "sharp"],
  "weights": [100, 200, 300, 400, 500, 600, 700],
  "defaultWeight": 400,
  "icons": [
    {
      "name": "add",
      "component": "Add",
      "categories": ["…"],
      "tags": ["add", "create", "new", "plus", "+"],
    },
  ],
}
```

例如，满足 _“给按钮添加一个创建图标”_:匹配 `create` 反对 `tags`,选 `Add`，并导入：

```tsx
import { Add } from '@nine-thirty-five/material-symbols-react/outlined';

<button>
  <Add /> Create
</button>;
```

目录也是可以直接导入的：

```ts
import manifest from '@nine-thirty-five/material-symbols-react/manifest.json' with { type: 'json' };
```

### 从命令行搜索

该包在同一个目录上附带了一个小的无依赖的CLI：

```bash
npx @nine-thirty-five/material-symbols-react find trash
```

```text
Delete            delete  [UI actions]
DeleteForever     delete_forever  [UI actions]
…

import { Delete } from '@nine-thirty-five/material-symbols-react/outlined';
```

选项: `--limit/-n <N>` (默认10), `--json` 用于机器可读输出。

## ESM只

这个包裹运送 **仅限ES模块**． 它适用于所有现代的捆绑器和ESM Node。在 节点≥22，CommonJS代码即可 `require()` 这直接归功于 `require(esm)`;在旧节点上或 下 `node16`/`nodenext` 从CJS中解析TypeScript，使用动态 `import()`.

## 从v1迁移

V2增加了重量轴和一些符合人体工程学的变化：

-   **现有的进口产品仍在运行。** `…/outlined` 和 `…/outlined/filled` 仍然决心减肥 400，和以前一样。
-   **默认大小从 `24` 来 `1em`.** 图标现在可以缩放 `font-size`． 修复旧的 固定尺寸，pass `size={24}` (或一组 `width`/`height`）。
-   **新 `size` 道具** 和新的权重入口点(`/100`–`/700`）。
-   **纠正了14个图标名称** (一个v1 bug掉了一个裸 `0`),如。 `SpeedFivex → SpeedZeroFivex`.
-   **ESM-only** (v1也是有效的ESM；破碎的CJS `main` 字段已被删除)。

### 自动升级（codemod）

运行捆绑的 [codemod](https://npmcn.com/package/%40nine-thirty-five/material-symbols-react/codemods/README.md) 为您应用大小和重命名更改：

```sh
npx jscodeshift -t node_modules/@nine-thirty-five/material-symbols-react/codemods/v1-to-v2.cjs \
  --parser tsx src/
```

它增加了 `size={24}` 对依赖旧默认值的图标进行修改，并将其重命名为14个 组件。通过 `--size=skip` 接受新事物 `1em` 违约。

## 它是如何工作的

图标是从谷歌的官方工件生成的-图标列表来自 [材料符号元数据API](https://fonts.google.com/metadata/icons) 和svg `fonts.gstatic.com` CDN。生成器提取每条路径，用SVGO对其进行优化，并发出 `dist` 直接树。没有网页抓取，没有无头浏览器。看到 [CONTRIBUTING.md](https://npmcn.com/package/%40nine-thirty-five/material-symbols-react/CONTRIBUTING.md).

## 许可证

材料设计图标是由 [谷歌](https://github.com/google/material-design-icons#license).

> 我们提供了这些图标，以便您在Apache下将其合并到您的产品中 许可证版本2.0。请随意在您的 产品。我们希望在应用的about屏幕中出现归属，但这不是必需的。

## 常见问题

### @nine-thirty-five/material-symbols-react 是什么？

灵活的，可摇树的React包谷歌的材料符号-每一个风格，重量和填充。

### 如何安装 @nine-thirty-five/material-symbols-react？

在项目目录运行 npm install @nine-thirty-five/material-symbols-react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 material-symbols-react，可以用 npx material-symbols-react 直接运行。

### @nine-thirty-five/material-symbols-react 支持 TypeScript 吗？

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

### @nine-thirty-five/material-symbols-react 支持 ESM 还是 CommonJS？

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

### @nine-thirty-five/material-symbols-react 需要什么版本的 Node\.js？

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

### @nine-thirty-five/material-symbols-react 可以商用吗？

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

### @nine-thirty-five/material-symbols-react 还在维护吗？

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