# @bradleyhodges/sfsymbols-react 中文文档

规范地址：https://npmcn.com/package/%40bradleyhodges/sfsymbols-react/

版本：8\.1\.3
npm 元数据更新时间：2026-09-08T03:45:48.090Z
中文译文更新时间：2026-11-08T13:29:26.626Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：53.8 kB，48 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2025-09-23T01:43:05.353Z
- 最新版本发布：2026-09-08T03:45:47.888Z
- 近 30 天下载量：3190（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 5 个）

## 中文简介

用于在 React 应用程序中使用来自 @bradleyhodges/ sfsymbols 包的图标的组件和公用设备.

## 安装

```sh
npm install @bradleyhodges/sfsymbols-react
```

也可以使用：`pnpm add @bradleyhodges/sfsymbols-react`、`yarn add @bradleyhodges/sfsymbols-react`、`bun add @bradleyhodges/sfsymbols-react`

## README

# @bradleyhodges/sfsymbols-反应

### 使用 Apple 的 SF 符号图标的配套软件包 [@bradleyhodges/ sfsymbols (英语)](https://github.com/bradleyhodges/sfsymbols) 在 React/Next.js 中输入.

 ![NPM Downloads by package author](https://img.shields.io/npm-stat/dm/bradleyhodges)[![npmjs package](https://img.shields.io/badge/npmjs-package-red?logo=npm) ](https://www.npmjs.com/package/@bradleyhodges/sfsymbols-react)[![GitHub repo](https://img.shields.io/badge/github-repo-blue?logo=github)](https://github.com/bradleyhodges/sfsymbols-react)  
 [![Version: 8.1.3](https://img.shields.io/badge/version-8.1.3-blue.svg)](https://github.com/bradleyhodges/sfsymbols/releases)![Platforms: Next.js – React.js – React Nav](https://img.shields.io/badge/Platforms-Next.js%20|%20React.js%20|%20React%20Native-FF69B4.svg) [![License: MIT](https://img.shields.io/badge/license-MIT-lightgrey.svg)](https://github.com/bradleyhodges/sfsymbols-react/blob/stable/LICENSE)

SF符号是一个由超过7000个符号组成的库,设计上与旧金山无缝地融合,是苹果平台的系统字体.

[可用图标](https://npmcn.com/package/%40bradleyhodges/sfsymbols-react/#readme-available-icons) 二. 支助 [开始](https://npmcn.com/package/%40bradleyhodges/sfsymbols-react/#readme--getting-started) 二. 支助 [安装](https://npmcn.com/package/%40bradleyhodges/sfsymbols-react/#readme-install-the-packages) 二. 支助 [使用量](https://npmcn.com/package/%40bradleyhodges/sfsymbols-react/#readme-usage) 二. 支助 [业绩优化](https://npmcn.com/package/%40bradleyhodges/sfsymbols-react/#readme-optimising-for-performance) 二. 支助 [样式条目](https://npmcn.com/package/%40bradleyhodges/sfsymbols-react/#readme-styled-and-unstyled-entries) 二. 支助 [道具](https://npmcn.com/package/%40bradleyhodges/sfsymbols-react/#readme-props-and-precedence) 二. 支助 [VS 代码扩展](https://npmcn.com/package/%40bradleyhodges/sfsymbols-react/#readme-optional-vs-code-previews) 二. 支助 [问题](https://github.com/bradleyhodges/sfsymbols-react/issues) 二. 支助 [调取请求](https://github.com/bradleyhodges/sfsymbols-react/pulls)

> \[叹息\] SF符号由苹果公司许可,仅用于苹果平台. **此软件包或其他任何 @ bradleyhodges/ sfsymbols- \* 软件包, 在苹果平台外使用是不允许的 .**

## 可用图标

[@bradleyhodges/ sfsymbols (英语)](https://github.com/bradleyhodges/sfsymbols) 包含有8,111个图标,其中包括609个补充品牌图标. 所有7 502个 `Regular` 重量图标 [旧金山字体](https://github.com/bradleyhodges/SFWindows) 包含。 其它的权重和可变图标指令不在此包中,但通过将中风放入向量路径可以使图标权重更重.

简而言之, **我为这个软件包创建了一个基本的图标浏览器,你可以在这里访问: [bradleyhodges - sfsyms.vercel.app (原始内容存档于2017-03-28)](https://bradleyhodges-sfsymbols.vercel.app/)** [![Screenshot of a comment on a GitHub issue showing an image, added in the Markdown, of an Octocat smiling and raising a tentacle.](https://github.com/bradleyhodges/sfsymbols/blob/main/assets/icon-browser-screenshot.png?raw=true)](https://bradleyhodges-sfsymbols.vercel.app/)

## 开始

此软件包包含允许您在 React/Next.js 项目中使用这些图标的 React 组件和元数据助手 。 SF 符号 8 的实际图标和图标数据来自 [`sfsymbols` 软件包](https://www.npmjs.com/package/@bradleyhodges/sfsymbols),你还需要安装.

### 安装软件包

您需要安装以下软件包来使用您的工程中的图标 :

-   [`@bradleyhodges/sfsymbols`](https://www.npmjs.com/package/@bradleyhodges/sfsymbols) – 图标目录包(包含实际图标).
-   [`@bradleyhodges/sfsymbols-react`](https://www.npmjs.com/package/@bradleyhodges/sfsymbols-react) — React / Next.js 中用于图标使用的回放组件包装.

```bash
pnpm add @bradleyhodges/sfsymbols @bradleyhodges/sfsymbols-react
```

组件包装器使 Web DOM `<svg>` 要素. **React 本地应用程序需要本地 SVG 渲染器** 换句话说 该库支持React 18和19.

## 使用量

就这么简单了 一旦安装了上述软件包,就可以简单地导入和使用:

```tsx
import SFIcon from "@bradleyhodges/sfsymbols-react";
import { sfArrowUpCircleFill, sfCheckmark, sfCrossVialFill } from "@bradleyhodges/sfsymbols";

function MyComponent() {
    return (
        <div>
            <SFIcon icon={sfArrowUpCircleFill} />
            <SFIcon icon={sfCheckmark} weight={2} />
            <SFIcon icon={sfCrossVialFill} size={24} className="text-red-500" />
        </div>
    );
}
```

使用 [图标浏览器](https://bradleyhodges-sfsymbols.vercel.app/) 以找到要使用的图标.

### 业绩优化

这个 `default` 财务报告和审定财务报表 `SFIcon` 出口品是相同的纪念性、再现部分。 选择中直接导入图标时, 请使用精确 `sf*` 叶道. 这让一个捆绑者避免分析目录中的大根管:

```tsx
import { SFIcon } from "@bradleyhodges/sfsymbols-react";
import { sfArrowUpCircleFill } from "@bradleyhodges/sfsymbols/sfArrowUpCircleFill";

<SFIcon icon={sfArrowUpCircleFill} size={24} color="rebeccapurple" />;
```

不要建立只用于支持运行时查找的导入每个图标的应用程序注册 。 导入应用程序使用的图标, 或者按要求加载被绑定的组 .

## 样式和未样式条目

根项将这些相容类合并到 `className` 使用 [`cn engine`](https://github.com/shadcn-ui/cn) 带有默认的基准类集 : `inline-block align-middle overflow-visible text-current box-content h-[1em] -leading-[0.125em]`默认值 `h-[1em]` 当 `size` 或当地人 `height` 提供,而打工者则会赢得阶级冲突.

未设置的条目会让相同的 SVG 、 路径、 无障碍标记、 校正和事件不导入 `cn` 或添加类 :

```tsx
import SFIcon from "@bradleyhodges/sfsymbols-react/unstyled";

<SFIcon icon={sfArrowUpCircleFill} className="icon" />;
```

将根条目用于既定布局行为。 使用 `/unstyled` 当应用程序拥有全部SVG布局并想要更小的边界时.

## 主张和优先

`SFIcon` 接受普通 `React.SVGProps<SVGSVGElement>` 加上下列道具:

| Prop | 类型 | 行为 |
| --- | --- | --- |
| `icon` | `IconDefinition` | 所需的图标几何和元数据 . |
| `size` | `number | string | null` | 设定两个维度, 除非本地维度超过它 。 明确 `0` 被保存下来. |
| `width`, (中文(简体) ), `height` | 本地 SVG 值 | 覆盖 `size` 独立. |
| `color` | CSS 颜色 | 覆盖每个路径的源填充. |
| `weight` | `number | null` | 添加根填充,中风,中风宽度和圆相接. 这是一个中风效应,而不是选择苹果的原生SF符号重量. |
| `fillOpacity` | `string | number | null` | 覆盖源路径不透明。 与 `weight`,遗留的默认是 `1`。 。 。 . |
| `preservePathOpacity` | `boolean` | 保持源不透明, 当 `weight` 设置和 `fillOpacity` 缺席. |
| `className`, (中文(简体) ), `style` | 本地 SVG 值 | 应用到 SVG 。 风格的条目合并了类;普通CSS级联和内置式规则仍然适用. |
| `title` | `string` | 渲染器 `<title>` 并生成其链接的ID. |
| `description` | `string` | 渲染器 `<desc>` 并生成其链接的ID。 仅一个描述不命名图像; 也提供 `title`, (中文(简体) ), `aria-label`,或外部可访问名称. |
| `titleId`, (中文(简体) ), `descriptionId` | `string` | 替换相应的元素生成的ID 。 在缺少这一要素时,它们没有效力. |
| `svgChildren` | `ReactNode` | 插入 SVG 等内容 `defs` 在图标路径之前。 遗产 `children` 仍然被忽视. |
| `pathProps` | 路径道具或 `(path, index) => path props` | 应用在生成填充和不透明后的安全通路演示和事件道具. |

维度优先为本地 `width` 或者说 `height`,则 `size`,然后图标的正宽度,然后它的正高度,然后 `1em`。定义倒置是故意的相容平方。 零定义维度不用作倒置,而明确 `size={0}`, (中文(简体) ), `width={0}`,或 `height={0}` 仍为零.

路径填充优先级为 `pathProps.fill`, (中文(简体) ), `color`源头填充 `currentColor`。路径不透明优先 `pathProps.fillOpacity`,明确 `fillOpacity`遗产 `weight` 默认,除非 `preservePathOpacity` 是真实的,然后源不透明. `pathProps.style` 遵循普通反应样式优先。 几何和子女所有权由制作人负责: `d`, (中文(简体) ), `key`, (中文(简体) ), `ref`, (中文(简体) ), `children`,以及 `dangerouslySetInnerHTML` 被公共类型排除在外,并在运行时过滤.

原生的SVG道具,包括参考和事件处理器被转发. 明确 `role`, (中文(简体) ), `aria-hidden`, (中文(简体) ), `aria-label`, (中文(简体) ), `aria-labelledby`,以及 `aria-describedby` 覆盖生成的无障碍属性 。 何时 `title` 财务报告和审定财务报表 `aria-label` 都在场 标题生成了 `aria-labelledby` 优先命名; 明确覆盖 `aria-labelledby`,包括 `aria-labelledby={undefined}`,当 `aria-label` 应当提供名称。 没有无障碍名称 SVG 隐藏; 一个标题, `aria-label`外边 `aria-labelledby` 使其可见于无障碍API. 所生成的ID是独一无二的,在标题去除和修复之间是稳定的,当服务器输出需要时可以被确定性的ID所取代.

```tsx
const iconRef = React.createRef<SVGSVGElement>();

<SFIcon
    ref={iconRef}
    icon={sfArrowUpCircleFill}
    title="Upload"
    description="Moves the selected item upward"
    svgChildren={
        <defs>
            <linearGradient id="upload-gradient">...</linearGradient>
        </defs>
    }
    pathProps={(path, index) => ({
        fill: index === 0 ? "url(#upload-gradient)" : path.fill,
    })}
/>
```

普通系列道具和SVG儿童可以通过React Server组件来渲染. 诸如 `pathProps` 调用和事件处理器必须在应用程序的正常服务器/客户端边界下引入客户端; 软件包不添加一个 `use client` 指令.

## 元数据助手和类型

根和(或) `/metadata` 导出条目 `getIconKeywords` 财务报告和审定财务报表 `getIconVariants`. 既验证了遗留的目录形状而不发生变异,又忽略了所继承的地产和存取者,维护了源序,还原了被冻结的副本.

```ts
import {
    getIconKeywords,
    getIconVariants,
} from "@bradleyhodges/sfsymbols-react/metadata";

const keywords = getIconKeywords(sfArrowUpCircleFill);
const variants = getIconVariants<"custom">(sfArrowUpCircleFill);
```

关键字数组保留有效 `text`, (中文(简体) ), `generic`,并有限度 `priority` 字段。 遗产字符串词典成为 `{ text }` 未创建元数据条目。 变体地图保留了自己的字符串值并使用一个无效的原型,所以任意没有自定义名称,例如: `toString` 安全决定 `undefined`转换为 `{ ...variants }` 当一个API特别需要普通对象原型时.

React Server 组件道具是这样的一个边界,因为React的可序列对象形式需要普通对象原型:

```tsx
<ClientComponent variants={{ ...getIconVariants(icon) }} />
```

公共类型从根, `/unstyled`,且只选类型 `/types` 条目 : `IconDefinition`, (中文(简体) ), `SFIconProps`, (中文(简体) ), `SFIconPathProps`, (中文(简体) ), `SFIconPath`, (中文(简体) ), `SFIconKeyword`,以及 `SFIconVariant`添加剂 `SFIconProps` 类型保持了伴侣包遗留合同的完整.

## 可选 VS 代码预览

单独的扩展 [`extensions/vscode`](https://npmcn.com/package/%40bradleyhodges/sfsymbols-react/extensions/vscode/README.md) 提供本地徘徊预览 **SF 符号: 预览和导入图标**它将所安装的图标叶子描述为有界限的静态数据并插入精确的每立方厘米导入;它不是一个应用程序依赖,也不运送图标登记册.

在不安装或发布的情况下构建本地 VSIX :

```bash
cd extensions/vscode
pnpm install --frozen-lockfile
pnpm test
pnpm typecheck
pnpm package
```

那就选择 **扩展: 从 VSIX 安装..** 在 VS 代码中选择 `artifacts/sfsymbols-preview-0.1.0.vsix`。请参见支持的语法、安全界限、限制、指令检查和孤立的扩展主机工作流程的扩展 README.

## 常见问题

### @bradleyhodges/sfsymbols-react 是什么？

用于在 React 应用程序中使用来自 @bradleyhodges/ sfsymbols 包的图标的组件和公用设备\.

### 如何安装 @bradleyhodges/sfsymbols-react？

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

### @bradleyhodges/sfsymbols-react 支持 TypeScript 吗？

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

### @bradleyhodges/sfsymbols-react 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bradleyhodges/sfsymbols-react 可以商用吗？

@bradleyhodges/sfsymbols-react 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @bradleyhodges/sfsymbols-react 的下载量有多少？

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

### @bradleyhodges/sfsymbols-react 还在维护吗？

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