Expo Symbolsexpo-symbols跨平台符号图标方案SF Symbols 与 Material Symbols 的集成指南【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expoExpo Symbols 是 Expo SDK 中负责跨平台符号图标的官方模块它在 iOS/tvOS 上渲染 Apple 的 SF Symbols在 Android 与 Web 上渲染 Material Symbols让开发者用同一套声明式SymbolView组件即可在多个平台展示高质量的系统图标。本文将围绕packages/expo-symbols的版本演进与源码实现完整讲解其安装配置、组件 API、跨平台名称映射、动画效果与已知问题帮助你直接上手并在项目中规避踩坑点。一、模块定位与平台覆盖从 README.md 的定位描述与 package.json 的说明来看expo-symbols 的职责非常清晰Provides access to native symbol libraries across platforms for React Native and Expo apps. Uses SF Symbols on iOS/tvOS and Material Symbols on Android and web.具体到平台支持以当前仓库版本 57.0.1为准平台图标来源渲染实现iOSSF SymbolstvOSSF Symbols同 iOS使用固定pointSize: 18.0见 SymbolView.swiftmacOSSF SymbolsmacOS 14 支持符号动画默认 scale 为.medium见 SymbolView.swiftAndroidMaterial Symbols通过expo-font加载 Material Symbols 字体渲染见 src/SymbolView.tsxWebMaterial Symbols与 Android 共用同一套字体渲染路径需要说明的是从版本演进看平台能力是逐步补齐的Android/Web 的 Material Symbols 支持在 55.0.0 中加入CHANGELOG.md 中 #39516macOS 支持在 56.0.6 中加入#46471。二、安装与工程配置托管managedExpo 项目直接使用 Expo CLI 安装即可命令会自动选取与当前 SDK 匹配的版本npx expo install expo-symbols裸bareReact Native 工程根据 README.md 的指引裸工程需要先完成expo包本身的安装与配置再执行npx expo install expo-symbols npx pod-install其中npx pod-install用于同步 iOS 的原生依赖。依赖关系从 package.json 可以看到模块自身的依赖设计运行时依赖expo-google-fonts/material-symbolsAndroid/Web 的 Material Symbols 字体包、sf-symbols-typescript提供 iOS SF Symbols 的类型名称保证name属性有完整的类型提示peer 依赖expo、expo-font、react、react-native——其中expo-font是 Android/Web 渲染路径的关键源码中用loadAsync加载字体子路径导出./androidWeights/*子路径专门导出各字重对应的字体资源供 Android/Web 端按需加载。三、SymbolView 组件核心 APISymbolView是模块对外的主要组件从 src/index.ts 可以看出模块整体导出结构export type { SFSymbol } from sf-symbols-typescript; export type { AndroidSymbol } from ./android; export { unstable_getMaterialSymbolSourceAsync } from ./materialImageSource; export type * from ./SymbolModule.types; export { SymbolView } from ./SymbolView;组件的全部 Props 定义在 src/SymbolModule.types.ts下面按用途分组说明。基础用法import { SymbolView } from expo-symbols; export default function App() { return ( SymbolView namehouse.fill tintColor#007AFF size{32} / ); }Props 详解Prop类型默认值平台说明nameSFSymbol \| { ios?, android?, web? }必填全部符号名称传对象可做跨平台映射见下文fallbackReactNode—全部当某平台未定义符号时渲染的兜底内容typemonochrome \| hierarchical \| palette \| multicolormonochromeiOS符号变体渲染模式scaledefault \| unspecified \| small \| medium \| largeunspecifiediOS符号缩放级别weightSymbolWeight \| { ios, android }unspecified全部字重Android/Web 端需从androidWeights子路径导入对应字重colorsColorValue \| ColorValue[]—iOSpalette模式下的调色板颜色数组sizenumber24全部符号尺寸tintColorColorValue见下文全部着色颜色resizeModeContentModescaleAspectFitiOS图片在容器内的缩放模式animationSpecAnimationSpec—iOS动画配置见下文SymbolWeight的取值集合为unspecified | ultraLight | thin | light | regular | medium | semibold | bold | heavy | black。ContentMode的取值集合为scaleToFill | scaleAspectFit | scaleAspectFill | redraw | center | top | bottom | left | right | topLeft | topRight | bottomLeft | bottomRight。平台映射与默认兜底当传入name为字符串时iOS/Android/Web 会直接使用该名称查找对应平台符号库中的符号若希望为不同平台显式指定不同符号可传入对象SymbolView name{{ ios: house.fill, android: home, web: home, }} /Android 端的符号名类型AndroidSymbol来自 src/android/index.ts 中由symbols.json推导出的联合类型androidSymbolToString会将符号名映射为字体中对应的 Unicode 码点String.fromCharCode(symbols[symbol])。当平台未定义符号时例如只提供了android未提供ios会渲染fallback属性iOS 实现里还会在原生 View 不存在时兜底渲染 fallback见 src/SymbolView.ios.tsx。Android/Web 的颜色默认值Android 端默认着色使用了系统平台色源码 src/SymbolView.tsxconst DEFAULT_SYMBOL_COLOR Platform.OS android ? PlatformColor(android:color/system_primary_dark) : #7d9bd4;即 Android 使用系统 primary dark 色Web 端默认回退为#7d9bd4。同时该文件也确认Android/Web 端SymbolView实际是「View Text」组合通过expo-font的loadAsync异步加载对应字重的 Material Symbols 字体再用androidSymbolToString渲染字形lineHeight与fontSize都取size以保证符号占据正确的方形空间对应 CHANGELOG 中 #41091 的修复。四、动画支持iOS 17 / macOS 14animationSpec是 iOS 平台专属能力底层映射到 Apple 的SymbolEffect见 ios/SymbolView.swift 中addSymbolEffects的实现。AnimationSpec 结构type AnimationSpec { effect?: AnimationEffect; repeating?: boolean; repeatCount?: number; speed?: number; variableAnimationSpec?: VariableAnimationSpec; }; type AnimationEffect { type: bounce | pulse | scale; wholeSymbol?: boolean; // 默认 falsetrue 表示整个符号一起动画 direction?: up | down; };原生侧的行为对应 SymbolView.swiftrepeating默认为false映射为SymbolEffectOptions.repeating / .nonRepeatingrepeatCount通过options.repeat(abs(repeatCount))设置重复次数speed通过options.speed(speed)设置动画速度若提供了variableAnimationSpec优先调用addSymbolEffect(variableAnimationSpec.toVariableEffect())走可变色动画分支。VariableAnimationSpec 可变色动画type VariableAnimationSpec { reversing?: boolean; // 每次重复时反向 nonReversing?: boolean; // 每次重复时不反向 cumulative?: boolean; // 各层依次点亮并保持到动画结束会取消 iterative iterative?: boolean; // 各层短暂点亮后恢复 hideInactiveLayers?: boolean; // 完全隐藏非激活层 dimInactiveLayers?: boolean; // 以降低的不透明度绘制非激活层 };这些效果是叠加的——每个置为true的字段都会额外叠加一个效果。使用示例SymbolView namewifi animationSpec{{ effect: { type: bounce, direction: up }, repeating: true, }} /注意原生实现中符号动画依赖if #available(iOS 17.0, tvOS 17.0, macOS 14.0, *)的运行时判断即 iOS 17 / tvOS 17 / macOS 14 以下系统会自动跳过动画部分因此动画能力与系统版本强相关。五、Android/Web 字重加载Android/Web 端由于采用字体渲染不同字重对应不同字体文件。按 SymbolModule.types.ts 中weight的说明Android/Web 端应通过子路径导入// 先导入字重字体资源 import expo-symbols/androidWeights/regular; import expo-symbols/androidWeights/bold; // 再渲染 SymbolView namestar weight{{ ios: bold, android: regular }} tintColor#FFD700 size{28} /仓库中 src/android/weights/ 目录下提供了regular、bold、light、medium、semiBold、thin、extraLight等字重入口对应 Material Symbols 字体的细分字重。weight也支持传对象分别指定 iOS 与 Android 的字重。六、实用辅助 APIunstable_getMaterialSymbolSourceAsync对于需要ImageSourcePropType而非组件的场景例如 tab bar 图标模块从 55.0.0 开始提供unstable_getMaterialSymbolSourceAsync#41064。其实现位于 src/materialImageSource.tsexport async function unstable_getMaterialSymbolSourceAsync( symbol: AndroidSymbol | null, size: number, color: string ): PromiseImageSourcePropType | null工作流程将 Material 符号名转换为字体字形码点androidSymbolToString用expo-font的loadAsync确保regular字重字体已加载调用expo-font的renderToImageAsync(fontChar, { fontFamily, size, color, lineHeight: size })将字形渲染成图片源。若expo-font未提供renderToImageAsync版本过旧会输出警告并返回null符号为空时也返回null。调用示例import { unstable_getMaterialSymbolSourceAsync } from expo-symbols; const icon await unstable_getMaterialSymbolSourceAsync(home, 24, #007AFF);七、iOS 原生实现要点iOS 端的原生视图位于 ios/SymbolView.swift核心流程在reloadSymbolIOS()中通过UIImage(systemName: name)创建符号图片用getSymbolConfig()构建UIImage.SymbolConfiguration按symbolType分别应用preferringMonochrome()iOS 16、hierarchicalColor、paletteColors调色板颜色数 1 时或preferringMulticolor()非 hierarchical 模式下通过withTintColor(tint, renderingMode: .alwaysOriginal)应用着色最后iOS 17先removeAllSymbolEffects()再按需添加动画效果。JS 侧 src/SymbolView.ios.tsx 会做 Props 归一化将colors统一为数组、用processColor处理颜色、计算animated布尔值、提取平台名称与字重最后通过requireNativeView(SymbolModule)渲染原生视图。macOS 端#if os(macOS)分支由于NSImage没有withTintColor实现上改用contentTintColor进行着色并把配置烘焙进新的NSImage见 SymbolView.swift。八、版本演进与踩坑记录以下是从 CHANGELOG.md 提炼的关键节点能帮助你判断升级风险破坏性变更Breaking changes56.0.02026-05-05最低 iOS/tvOS 版本提升到16.4macOS 提升到13.4#43296。升级到 56.x 前需确认工程的最低系统版本满足要求0.2.02024-10-22iOS/tvOS 部署目标提升到15.1#30840、#30865。新功能与稳定性Unpublished即将发布Expo Symbols 从 beta 转为stable#48537同时修复了非原生回退Android/Web 字体渲染中styleprop 被忽略的问题#4855356.0.6新增macOS 支持#4647155.0.0Android/Web 支持 Material Symbols#39516并加入unstable_getMaterialSymbolSourceAsync#410641.0.02025-08-13修复 Android 上「native view manager isnt exported」警告#385040.4.5改用processColor从而接受所有合法的颜色字符串#369140.4.0添加PlatformColor到类型定义#348900.1.4新增sizeprop 以对齐同类包 API#28497。依赖相关56.0.5修复expo-google-fonts/material-symbols的useFonts对expo-font和react的未声明依赖问题#45471升级时建议同步更新该字体包0.3.0修复 Android 端expo-modules.config的平台配置错误#35849并统一了expo-module.config.json的平台语法#34445。版本节奏说明本模块多数小版本如 57.0.1、57.0.0、56.0.4 等明确标注「不包含面向用户的功能变更」属于与 SDK 主版本对齐的例行发布需要关注的核心节奏是55.x 补齐 Android/Web、56.x 补齐 macOS 与系统版本下限、当前主线将模块转正为 stable。九、实践建议小结跨平台应用优先使用对象形式的name映射并为缺失平台提供fallback避免某些平台空白Android/Web 端记得导入字重子路径如expo-symbols/androidWeights/bold否则字重可能不符合预期需要图标作为图片源如 tab bar时使用unstable_getMaterialSymbolSourceAsync同时注意该 API 依赖较新的expo-font动画仅限 iOS 17 / tvOS 17 / macOS 14低版本会自动降级为静态符号设计动画前先确认目标系统版本升级 56.x 前核对最低系统版本iOS/tvOS 16.4、macOS 13.4避免 CI 或真机不满足要求需要查阅最新 API 细节时可继续阅读模块内 README.md、类型定义 src/SymbolModule.types.ts 以及原生实现 ios/SymbolView.swift并结合官方 SDK 文档确认稳定版行为。【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
