翻译:
Forge UI 的跨平台图标库, 以 材料符号 (外形,重量400,光学尺寸24). 通过 react-native-svg 并且目标iOS,Android,和Web 从一个代码库.
完整的材料符号概要集可供使用,每个图标都有概要和已填充的变体,同时支持自定义的SVG. 浏览 图标浏览器。 。 。 .
安装
pnpm add @cdx-ui/icons
同伴依赖关系
| 软件包 | 版本 |
|---|---|
react | ^18.2.0 || ^19.0.0 |
react-native | >=0.76.0 (可选) |
react-native-svg | ^13.0.0 || ^14.0.0 || ^15.0.0 |
使用量
import { Home, Favorite, Settings } from '@cdx-ui/icons';
// Outlined (default)
<Home size={24} color="blue" />
// Filled variant
<Favorite size={24} color="red" filled />
// Toggle between variants
<Home filled={isActive} />
每个图标都是 forwardRef 接受所有标准的组件 SvgProps 加上下面的道具.
道具
| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
size | number | string | 24 | 设置两者 width 财务报告和审定财务报表 height。 。 。 . |
color | string | 'currentColor' | 用于图标的填充颜色 . |
filled | boolean | false | 当 true。如果不存在填充数据,则重新列出. |
accessibilityLabel | string | —— 说 | 图标一旦提供,即成为信息(accessible={true}, (中文(简体) ), accessibilityRole="image") (中文(简体) ). 省略时,图标默认为装饰. |
data-testid | string | —— 说 | 转发到根 <Svg> 用于测试的元素. |
所有其他道具都分布在根上 <Svg> 元素,包括标准 React 本地无障碍道具.
工厂和类型
| 导出 | 说明 |
|---|---|
createForgeIcon | 从 SVG 数据创建自定义 Forge 风格图标组件的工厂函数 |
ForgeIconProps | 工厂创建的图标的道具界面 |
ForgeIcon | Forge 图标组件的别名类型 |
IconNode | 工厂消耗的SVG路径数据类型 |
IconData | 概要 + 已填充路径数据对的类型 |
命名公约
每个图标都有三种导出模式:
| 图案 | 示例 | 使用大小写 |
|---|---|---|
| 帕斯卡案件 | Home | 初级进口 |
| 后缀 | HomeIcon | 避免与自己的碰撞 Home 组件 |
| 前缀 | CdxHome | 混合多个图标库时的命名空间 |
import { Home } from '@cdx-ui/icons';
import { HomeIcon } from '@cdx-ui/icons';
import { CdxHome } from '@cdx-ui/icons';
别名
图标可以在 icon-metadata.json. 异名允许您在替代名下引用相同的基本图标——用于遗留相容性,域名名名词,或与其他图标集使用的名称相匹配. 生成脚本与标准出品同时生产出别名再出品,因此别名在运行时为零成本.
每个条目 icon-metadata.json 将基准图标名称(将其 SVG 文件名匹配)映射到一系列别名。 异名可以是普通字符串或对象 deprecated: true (单位:千美元) deprecationReason 以标记应该移出的名称.
// icon-metadata.json
{
"home": {
"aliases": [
"house",
{
"name": "old-home-icon",
"deprecated": true,
"deprecationReason": "Renamed to Home",
},
],
},
"settings": {
"aliases": ["gear", "preferences"],
},
}
上面的配置产生以下行为:
House, (中文(简体) ),HouseIcon,以及CdxHouse所有决心Home图标Gear财务报告和审定财务报表Preferences决议Settings图标OldHomeIcon决定:Home但显示@deprecated Renamed to HomeJSDoc在你的编辑中警告, 将消费者裸体到犬名
import { House } from '@cdx-ui/icons'; // alias → Home
import { Gear } from '@cdx-ui/icons'; // alias → Settings
import { OldHomeIcon } from '@cdx-ui/icons'; // deprecated alias → Home (editor warning)
与现有图标名称相撞的异名在生成过程中被默默跳过,以避免重复导出 .
国家旗帜
国家旗帜从 @cdx-ui/icons/flags 子路径,不是主路径 @cdx-ui/icons 枪管 每个旗帜是 ForgeIcon。一个α-2代码将其字母保留在组件名中,例如 FlagUS 或者说 FlagXK。一个子分区代码在组件名称中用下划线取代连字符(FlagGB_ENG 页:1 GB-ENG) (中文(简体) ). 子路径还输出 a flags 以代码键入,包括连字符,以及 a FlagCode 工会. FlagCode 与 国家 -- -- 旗子 3x2 设定此套件是用该套件构建的,包括包船用于 手机号码-js。 。 。 .
每个旗道都有明确的填充,所以艺术品保持了源色. 文本颜色类和主题符号不重彩.
CountryFlag 从 @cdx-ui/components 是产品UI的组件,包括选定国家的主要槽。 它解决艺术通过 flags 记录,所以渲染 CountryFlag 包住每一面旗帜。 一个显示一面固定旗帜的应用程序可以导入图标 :
import { FlagUS, flags, type FlagCode } from '@cdx-ui/icons/flags';
<FlagUS />;
const Flag = flags.US;
无障碍
图标是 默认装饰 在无辅助技术时隐藏在辅助技术中 accessibilityLabel 提供。 这是文本标签旁边或标签容器内部图标的正确行为.
// Decorative (default) — screen readers skip this
<Home size={20} color={theme.colors.icon} />
// Informative — screen readers announce "Home, image"
<Home size={20} accessibilityLabel="Home" />
| 假设 | 怎么办 |
|---|---|
| 文本标签旁边的图标 | 留作默认(装饰) |
标签内的图标 Button | 留作默认——按钮的标签覆盖 |
| 独立图标传递意义 | 添加 accessibilityLabel 在上下文中描述图标的目的 |
| 只有图标的按钮 | 标记 Pressable 包装,不是图标 |
跨平台行为 :
- iOS(声音over): 宣布为“ { label}, 图像 ”
- Android (TalkBack) (英语: 宣布为“ { label}, 图形 ”
- 网络( 反应土著网络) : 渲染器
role="img"+ 键aria-label
反应原生 0.76别名 aria-label 改为 accessibilityLabel,所以无论是道具工作.
详细情况见 图标无障碍指导 在文件网站.
自定义图标
将自定义 SVG 置入 icons/custom/。生成脚本从两者中读取 icons/material/outlined/ 财务报告和审定财务报表 icons/custom/,因此自定义图标与材料符号图标得到相同的处理.
- 使用
{name}.svg备选案文 - 可选添加
{name}-fill.svg用于填充的变体 - 在
0 -960 960 960坐标空间.createForgeIcon部队viewBox="0 -960 960 960"在每一个图标上,生成器只保留根的孩子 元素——它丢弃每个SVG自己的viewBox编号 :width编号 :height。标准 24px 导出 (路径坐标在0..24)为 没有 相容性:它使一个微小的斑点在 视图框(有效隐形). - 可提取的元素必须是:
<svg>。 。 。 . 解析器是深一层,所以<path>窝在一<g>被删除。 平整任何团体(并将其转换成 路径d) 承诺之前.
要将一个 24px 品牌/ Figma 输出转换为 960 格网, 请应用 afine 转换
x' = 40·x, (中文(简体) ), y' = 40·y − 960 (统一尺度×40,再由−960将y翻译为路径数据-)
例如,与 svgpath数字 :
svgpath(d).scale(40).translate(0, -960).round(2).toString()。见 icons/custom/whats_app.svg
用于正常参考。 注意图标在 currentColor; 任何来源
fill 被压在地上 color 道具 (英语).
品牌标志
品牌标志 (WhatsApp, Google, GitHub,.) 被命名 Logo<Brand> 在图片图标库中,
但已公布 无 前缀并带有品牌外壳——例如:Figma LogoWhatsApp →
导出 WhatsApp。将 SVG 命名为已去除前缀、 蛇 cased 文件名, 因此生成器
生成正确的导出 :
| 图像组件 | SVG 文件名 | 导出 |
|---|---|---|
LogoWhatsApp | whats_app.svg | WhatsApp |
LogoYouTube | you_tube.svg | YouTube |
LogoGitHub | git_hub.svg | GitHub |
LogoLinkedIn | linked_in.svg | LinkedIn |
代码连接批次脚本( repo- root) scripts/generate-icon-batch.ts剥去 Logo 前缀 当
对照本地文件交叉引用 Figma 组件,因此映射自动解决.
真正开始的材料符号 Logo (例如:. logo_dev)首先按确切名称匹配
且不受影响.
发展
正在下载材料符号 SVGs
SVG通过自定义下载脚本直接取自Google Fonts CDN(scripts/download-icons.ts) (中文(简体) ). 脚本查询 Google 的元数据 API 活动图标列表,然后只下载 概述 样式( 重量 400, opsz 24 ) , 两种填充状态。 下载的 SVG 不检查为 git .
pnpm --filter @cdx-ui/icons download-icons
此下载每个图标的大纲和已填入的 SVG icons/material/outlined/。通过 --clean 从头重新下载,而不是跳过已有文件.
生成图标组件
生成脚本( E)scripts/generate-icons.ts)从两者读取 SVGs icons/material/outlined/ 财务报告和审定财务报表 icons/custom/,用 svgson,然后将 TypeScript 文件写入 src/icons/ 财务报告和审定财务报表 src/aliases/。 。 。 .
pnpm --filter @cdx-ui/icons generate
生成的文件包括:
src/icons/{name}.ts– 每个图标有一个文件,其中既有概述的也有填充的路径数据src/icons/index.ts- 所有图标的桶导出src/aliases/aliases.ts——由元数据驱动的后遗症名图src/aliases/suffixed.ts—— 说{Name}Icon导出每个图标和别名src/aliases/prefixed.ts—— 说Cdx{Name}导出每个图标和别名
每个生成的图标文件都包含一个基数64编码 @preview JSDoc标签,所以在您编辑器中的图标导入上徘徊显示一个视觉预览.
生成下塔布图标
原生底标签需要图像资产,而不是反应组件. 第二代剧本( A)scripts/generate-tab-icons.ts光栅化 所申报的被管理子集 tab-icons.config.json 成为单色模板 PNGs (24/48/72 px −) @1x编号 :@2x编号 :@3x)使用 @resvg/resvg-js,并发布通过 @cdx-ui/icons/tab-icons 子路径导出 .
pnpm --filter @cdx-ui/icons generate:tab-icons
生成文件( gitignored, 如 src/icons/:
src/tab-icons/assets/{name}[-fill][@2x|@3x].png– 模板 PNG (黑色 + alpha; 标签栏在运行时将其涂入)src/tab-icons/generated/{name}.ts——网络描述符(仅包含SVG组件,不包含资产进口)src/tab-icons/generated/{name}.native.ts——以静态为主的本土描述词require()资产进口src/tab-icons/generated/registry.ts—— 说TAB_ICON_NAMES扭伤,TabIconName类型,以及TAB_ICON_COMPONENTS地图src/tab-icons/generated/index.ts- 桶出口描述器+登记册
要在所编集中添加图标,请将其基名添加到 tab-icons.config.json 以及重建——未知名称使建设失败. 消费者化的用法记录在寄存器的图标指南中.
标签图标注册
生成脚本也发出 a 登记册模块 ,提供程序访问所设置的标签图标集。 登记册出口可从 @cdx-ui/icons/tab-icons 子路径 :
| 导出 | 类型 | 说明 |
|---|---|---|
TAB_ICON_NAMES | readonly string[] (连翘) | 从配置中排序了全部蛇 大小写图标名称的数组 |
TabIconName | 联盟类型 | 弦字结合由 tu(如. 'home' | 'settings' | …(中文(简体) ) |
TAB_ICON_COMPONENTS | Record<TabIconName, ForgeIcon> | 将每个名称映射到它的 SVG 图标组件 |
import { TAB_ICON_NAMES, TAB_ICON_COMPONENTS, type TabIconName } from '@cdx-ui/icons/tab-icons';
// Iterate available names
TAB_ICON_NAMES.forEach((name) => console.log(name));
// Look up a component by name
const Icon = TAB_ICON_COMPONENTS['home'];
// Type-safe name parameter
function getTabIcon(name: TabIconName) {
return TAB_ICON_COMPONENTS[name];
}
大楼
pnpm --filter @cdx-ui/icons build
这个运行 clean - > (中文) generate - > (中文) generate:tab-icons - > (中文) bob buildA级 prebuild 钩子运行 download-icons 首先,一个干净的取出会自动在生成前获取源 SVG 。 输出到 lib/ 有三个目标:
lib/commonjs/- CJS模块lib/module/——无害环境管理模块lib/typescript/——每个文件.d.ts声明
软件包由 react-native-builder-bob,与所有其他工作空间软件包一致。 不同于其他工作空间软件包 react-native 字段指向 lib/module/index.js (预先建立的无害环境管理产出)而不是来源。 这意味着图标包 必须建造 (单位:千美元)pnpm build:packages 或者说 pnpm --filter @cdx-ui/icons build在Metro解决之前 原始地图被排除在已出版的软件包之外(!lib/**/*.map 内 files)来减少安装大小.
软件包结构
icons/
├── icons/
│ ├── material/outlined/ # Downloaded SVGs (not checked in)
│ └── custom/ # Hand-authored custom SVGs
├── scripts/
│ ├── download-icons.ts # Downloads outlined SVGs from Google Fonts CDN
│ ├── generate-icons.ts # SVG → TypeScript generation script
│ ├── generate-tab-icons.ts # SVG → template PNG + descriptor generation
│ ├── generate-manifest.ts # Emits icon-manifest.json (the ./manifest export)
│ └── shared.ts # Naming utilities shared by both generators
├── src/
│ ├── icons/ # Generated icon components
│ ├── aliases/ # Generated alias re-exports
│ ├── tab-icons/ # Bottom-tab descriptors (entry + generated assets)
│ ├── createForgeIcon.ts # Factory function
│ ├── defaultAttributes.ts # SVG defaults (viewBox, fill)
│ ├── types.ts # TypeScript types
│ └── index.ts # Main entry point
├── types/png.d.ts # Ambient *.png module declaration (kept out of src/)
├── icon-metadata.json # Alias and deprecation metadata
├── tab-icons.config.json # Curated bottom-tab icon subset
├── package.json
├── tsconfig.json
└── tsconfig.build.json
src/icons/, (中文(简体) ), src/aliases/, (中文(简体) ), src/tab-icons/assets/,以及 src/tab-icons/generated/ 包含生成的文件(除 .gitkeep 卫所.
建筑
软件包遵循的是 清晰的反应-内在,为材料符号所改编. 关键差异 :
- 基于填充的图标 — 材料符号图标使用
fill完全(无)stroke属性)。 这个color道具映射到fill。 。 。 . - 960x960坐标系统 —— 说
viewBox="0 -960 960 960"而不是卢西德的0 0 24 24编辑size道具控件使尺寸化;视图Box处理内部坐标. - 大纲/填充变体 ——每个图标通过
filled道具,建模材料符号"填充轴. 此选项将导出计数对单独的组件减半 . - 默认装饰 ——图标隐藏在辅助技术中,除非
accessibilityLabel提供. - OTA 兼容性 —— 说
childDefaultAttributes明确设定fill围绕CodePush/expo-updates中的继承错误工作.
完整的研究和设计原理记录在寄存器的图标包研究尖锐.