ReactNative for OpenHarmony项目鸿蒙化三方库：rn-placeholder — 骨架屏占位组件

欢迎加入开源鸿蒙跨平台社区https://openharmonycrossplatform.csdn.net开发环境声明本文基于 React Native 0.72.90 版本进行开发适配 一、开篇引言rn-placeholder 是一个优雅的占位符组件库用于在内容加载时显示骨架屏Skeleton Screen效果。它提供了 Placeholder、PlaceholderLine、PlaceholderMedia 等基础组件以及 Fade、Shine、ShineOverlay 等多种动画效果帮助开发者快速实现内容加载占位提升用户体验。本文将带你深入了解如何在 HarmonyOS 平台上集成和使用这个实用的占位符组件库。1.1 你将学到什么✅ rn-placeholder 的核心组件与概念✅ HarmonyOS 平台的完整集成流程✅ Placeholder、PlaceholderLine、PlaceholderMedia 组件使用✅ 多种动画效果的应用✅ 自定义占位符样式与布局 二、库概览2.1 基本信息项目内容库名称rn-placeholder版本信息3.0.3官方仓库https://github.com/mfrachet/rn-placeholder开源协议MIT2.2 版本兼容性三方库版本支持RN版本说明3.0.30.72/0.77推荐使用2.3 核心能力矩阵能力项描述HarmonyOS 支持Placeholder占位符容器组件✅ 完全支持PlaceholderLine行占位符组件✅ 完全支持PlaceholderMedia媒体占位符组件✅ 完全支持Fade淡入淡出动画✅ 完全支持Shine闪光动画✅ 完全支持ShineOverlay闪光覆盖层动画✅ 完全支持Progressive渐进加载动画✅ 完全支持Loader加载器动画✅ 完全支持2.4 动画效果对比动画名称效果描述适用场景Fade整体淡入淡出效果通用加载场景Shine局部闪光效果现代风格应用ShineOverlay覆盖层闪光效果浅色背景应用Progressive渐进式加载效果数据逐步加载场景LoaderActivityIndicator 风格iOS 风格应用 三、安装与配置3.2 安装依赖在项目根目录执行以下命令npminstallrn-placeholder3.0.3 --legacy-peer-deps3.3 验证安装安装完成后检查package.json文件中是否包含以下依赖{dependencies:{rn-placeholder:^3.0.3}}3.4 无需原生配置rn-placeholder 是纯 JavaScript 库基于 React Native Animated API 实现不依赖任何原生模块。3.5 基本导入import{Placeholder,PlaceholderMedia,PlaceholderLine,Fade,Shine,ShineOverlay,Progressive,Loader,}fromrn-placeholder; 四、API 详解4.1 Placeholder 容器组件Placeholder 是所有占位符组件的外层容器它负责管理占位符的整体布局和动画效果。单独使用 Placeholder 并不会产生有趣的效果需要在其中放入 PlaceholderLine 或 PlaceholderMedia 等子组件才能发挥作用。核心功能Placeholder 组件接受 React Native View 的全部属性同时提供了几个特有的属性来控制占位符的布局和动画。它通过 Left 和 Right 属性可以在左右两侧放置 PlaceholderMedia 组件形成常见的列表项布局。Animation 属性Animation 属性接受一个动画组件用于为占位符添加动画效果。rn-placeholder 提供了 Fade、Shine、ShineOverlay、Progressive、Loader 五种动画组件每种都有独特的视觉效果。动画组件会自动应用到 Placeholder 内的所有子组件上。Left 和 Right 属性Left 和 Right 属性用于在占位符的左右两侧放置媒体组件。通常传入 PlaceholderMedia 组件用于表示头像、图标等元素。这两个属性使得创建常见的列表项布局变得非常简单。import { Placeholder, PlaceholderMedia, PlaceholderLine, Fade } from rn-placeholder; const PlaceholderExample () { return ( Placeholder Animation{Fade} Left{PlaceholderMedia} Right{PlaceholderMedia} PlaceholderLine width{80} / PlaceholderLine / PlaceholderLine width{30} / /Placeholder ); };布局说明Placeholder 组件使用 flex 布局子组件会垂直排列。Left 和 Right 属性指定的组件会分别放置在内容的左右两侧。这种设计非常适合创建类似列表项、卡片等常见的 UI 布局。4.2 PlaceholderLine 行占位符组件PlaceholderLine 是占位符的两种基础可视组件之一用于表示文本行。它显示为一个灰色的矩形条模拟文本内容的占位效果。视觉特点PlaceholderLine 默认显示为一个浅灰色的矩形条高度为 12宽度为 100%相对于父容器。多条 PlaceholderLine 组合使用时会自动添加底部边距形成类似段落文本的视觉效果。width 属性width 属性控制行占位符的宽度可以设置为数字表示百分比或字符串。例如 width{80} 表示宽度为父容器的 80%width“200px” 表示固定宽度 200 像素。通过设置不同的宽度值可以模拟不同长度的文本行。height 属性height 属性控制行占位符的高度默认值为 12。可以根据实际文本大小调整这个值例如标题可以使用较大的高度正文使用默认高度。color 属性color 属性设置占位符的颜色默认为 “#efefef”。可以根据应用的配色方案调整这个值使占位符与整体设计风格保持一致。noMargin 属性noMargin 属性控制是否添加底部边距默认为 false添加边距。当需要紧密排列多个占位符时可以设置为 true。import { Placeholder, PlaceholderLine, Shine } from rn-placeholder; const LineExample () { return ( Placeholder Animation{Shine} PlaceholderLine width{60} height{20} / PlaceholderLine width{90} / PlaceholderLine width{70} / PlaceholderLine width{40} noMargin / /Placeholder ); };使用技巧第一行通常使用较大的高度和较短的宽度模拟标题中间行使用默认高度和变化的宽度模拟正文最后一行设置 noMargin{true}避免多余空白4.3 PlaceholderMedia 媒体占位符组件PlaceholderMedia 是占位符的另一种基础可视组件用于表示图片、头像等媒体元素。它显示为一个灰色的方块或圆形模拟媒体内容的占位效果。视觉特点PlaceholderMedia 默认显示为一个 40x40 的灰色方块。通过 isRound 属性可以将其变为圆形非常适合表示头像。它也可以单独使用不一定要放在 Placeholder 容器内。size 属性size 属性控制媒体占位符的大小宽度和高度相同默认值为 40。可以根据实际需求调整例如头像可以使用 48 或 60缩略图可以使用 80 或 100。isRound 属性isRound 属性控制媒体占位符是否为圆形默认为 false方形。设置为 true 时占位符会显示为圆形非常适合表示用户头像。color 属性color 属性设置占位符的颜色默认为 “#efefef”。与 PlaceholderLine 保持一致的颜色可以获得更好的视觉效果。import { Placeholder, PlaceholderMedia, PlaceholderLine, Fade } from rn-placeholder; const MediaExample () { return ( View style{styles.container} Placeholder Animation{Fade} Left{PlaceholderMedia} PlaceholderLine width{50} height{16} / PlaceholderLine width{80} / /Placeholder Placeholder Animation{Fade} Left{() ( PlaceholderMedia size{60} isRound / )} PlaceholderLine width{40} height{14} / PlaceholderLine width{60} / PlaceholderLine width{30} / /Placeholder /View ); };自定义样式PlaceholderMedia 支持 style 属性可以进一步自定义样式。例如添加边框、阴影等效果使占位符更接近实际内容的样式。4.4 Fade 淡入淡出动画Fade 是最基础的动画效果它会让占位符内容在指定的时间间隔内逐渐清晰和模糊形成呼吸般的效果。动画原理Fade 动画通过改变占位符的透明度来实现效果。占位符会在完全可见和半透明之间循环变化给人一种等待中的感觉。这种动画效果简洁、不突兀适合大多数应用场景。自定义参数Fade 动画支持通过属性自定义动画参数。可以通过 animationDuration 属性调整动画周期时长通过 animationEasing 属性设置缓动函数。import { Placeholder, PlaceholderLine, Fade } from rn-placeholder; const FadeExample () { return ( Placeholder Animation{props ( Fade {...props} style{{ backgroundColor: #f0f0f0 }} / )} PlaceholderLine / PlaceholderLine / PlaceholderLine / /Placeholder ); };使用场景Fade 动画是最通用的动画效果适合各种加载场景。它的视觉效果柔和不会分散用户注意力同时又能清晰地传达加载中的状态。4.5 Shine 闪光动画Shine 动画实现了一种从左到右的闪光效果类似于 iOS 系统的骨架屏效果。它通过动画占位符的不同部分来实现闪光效果视觉效果现代、精致。动画原理Shine 动画会在占位符上创建一个从左到右移动的高亮区域模拟光线扫过的效果。与 ShineOverlay 不同Shine 动画是直接对占位符进行动画而不是添加覆盖层。视觉特点Shine 动画的闪光效果更加自然不会出现覆盖层带来的样式问题。它适合各种背景颜色不需要担心与背景色的兼容性问题。import { Placeholder, PlaceholderLine, PlaceholderMedia, Shine } from rn-placeholder; const ShineExample () { return ( Placeholder Animation{Shine} Left{() PlaceholderMedia isRound size{50} /} PlaceholderLine width{50} height{16} / PlaceholderLine width{80} / PlaceholderLine width{60} / /Placeholder ); };使用场景Shine 动画适合现代风格的应用特别是需要精致视觉效果的场景。它的闪光效果流畅自然能够给用户一种正在加载的明确反馈。4.6 ShineOverlay 覆盖层闪光动画ShineOverlay 动画通过在占位符上添加一个从左到右移动的覆盖层来实现闪光效果。它的视觉效果类似于 Shine但实现方式不同。动画原理ShineOverlay 在占位符上方添加一个半透明的覆盖层覆盖层从左到右移动产生闪光效果。这种实现方式简单但需要注意覆盖层与背景色的兼容性。使用限制ShineOverlay 动画在不自定义样式时效果最佳仅在白色背景上显示灰色线条时表现良好。如果自定义了占位符颜色或背景色可能会出现视觉问题。import { Placeholder, PlaceholderLine, ShineOverlay } from rn-placeholder; const ShineOverlayExample () { return ( View style{{ backgroundColor: #fff, padding: 20 }} Placeholder Animation{ShineOverlay} PlaceholderLine / PlaceholderLine / PlaceholderLine / /Placeholder /View ); };使用建议ShineOverlay 适合简单的白色背景场景。如果需要更灵活的自定义建议使用 Shine 动画代替。4.7 Progressive 渐进加载动画Progressive 动画实现了一种渐进式加载效果占位符会逐步显示模拟数据逐步加载的过程。动画原理Progressive 动画会让占位符的内容逐步显现从左到右或从上到下逐渐显示。这种效果给人一种数据正在逐步加载的感觉非常适合分步加载的场景。适用场景Progressive 动画特别适合数据分步加载的场景例如先加载标题再加载正文最后加载图片。它能够给用户一种加载进度的反馈减少等待的焦虑感。import { Placeholder, PlaceholderLine, PlaceholderMedia, Progressive } from rn-placeholder; const ProgressiveExample () { return ( Placeholder Animation{Progressive} Left{() PlaceholderMedia size{60} /} PlaceholderLine width{60} height{18} / PlaceholderLine width{90} / PlaceholderLine width{70} / PlaceholderLine width{50} noMargin / /Placeholder ); };4.8 Loader 加载器动画Loader 动画基于各平台原生的 ActivityIndicator 实现显示一个系统风格的加载指示器。动画原理Loader 动画会在占位符中心显示一个 ActivityIndicator使用系统原生的加载动画风格。在 iOS 上显示 UIActivityIndicatorView 风格在 Android 上显示 ProgressBar 风格。视觉特点Loader 动画的视觉效果与系统原生加载指示器一致用户非常熟悉。它适合需要与系统风格保持一致的应用。import { Placeholder, PlaceholderLine, Loader } from rn-placeholder; const LoaderExample () { return ( Placeholder Animation{Loader} PlaceholderLine / PlaceholderLine / PlaceholderLine / /Placeholder ); };使用场景Loader 动画适合 iOS 风格的应用或者需要与系统原生加载效果保持一致的场景。4.9 自定义动画rn-placeholder 支持自定义动画效果可以通过创建自定义动画组件来实现独特的加载效果。自定义动画原理自定义动画组件需要接收 props 参数并将其传播到子组件。props 中包含动画相关的属性如 animating、animationDuration 等。自定义动画组件需要正确处理这些属性否则会出现异常行为。import { Placeholder, PlaceholderLine } from rn-placeholder; import { Animated, Easing } from react-native; const CustomAnimation (props: any) { const { children, style } props; return ( Animated.View style{[style, { opacity: 0.6 }]} {children} /Animated.View ); }; const CustomAnimationExample () { return ( Placeholder Animation{CustomAnimation} PlaceholderLine / PlaceholderLine / PlaceholderLine / /Placeholder ); }; 五、完整代码示例一个完整的骨架屏加载示例importReact,{useState,useEffect}fromreact;import{View,Text,StyleSheet,SafeAreaView,ScrollView,TouchableOpacity,Image,}fromreact-native;import{Placeholder,PlaceholderMedia,PlaceholderLine,Fade,Shine,}fromrn-placeholder;interfaceUser{id:number;name:string;avatar:string;title:string;description:string;}constmockUsers:User[][{id:1,name:张三,avatar:https://i.pravatar.cc/100?img1,title:前端开发工程师,description:专注于 React Native 跨平台开发},{id:2,name:李四,avatar:https://i.pravatar.cc/100?img2,title:后端开发工程师,description:专注于 Node.js 服务端开发},{id:3,name:王五,avatar:https://i.pravatar.cc/100?img3,title:UI 设计师,description:专注于移动端 UI/UX 设计},];constUserCard({user}:{user:User})(View style{styles.card}Image source{{uri:user.avatar}}style{styles.avatar}/View style{styles.cardContent}Text style{styles.name}{user.name}/TextText style{styles.title}{user.title}/TextText style{styles.description}{user.description}/Text/View/View);constUserCardPlaceholder()(View style{styles.card}Placeholder Animation{Shine}Left{()PlaceholderMedia isRound size{50}/}PlaceholderLine width{40}height{16}style{styles.namePlaceholder}/PlaceholderLine width{60}height{12}/PlaceholderLine width{80}height{12}noMargin//Placeholder/View);constPlaceholderDemo(){const[loading,setLoading]useState(true);const[users,setUsers]useStateUser[]([]);useEffect((){consttimersetTimeout((){setUsers(mockUsers);setLoading(false);},2000);return()clearTimeout(timer);},[]);consthandleRefresh(){setLoading(true);setUsers([]);setTimeout((){setUsers(mockUsers);setLoading(false);},2000);};return(SafeAreaView style{styles.container}View style{styles.header}Text style{styles.headerTitle}用户列表/TextTouchableOpacity style{styles.refreshButton}onPress{handleRefresh}Text style{styles.refreshText}刷新/Text/TouchableOpacity/ViewScrollView contentContainerStyle{styles.content}{loading?(UserCardPlaceholder/UserCardPlaceholder/UserCardPlaceholder//):(users.map(userUserCard key{user.id}user{user}/))}/ScrollView/SafeAreaView);};conststylesStyleSheet.create({container:{flex:1,backgroundColor:#f5f5f5,},header:{flexDirection:row,justifyContent:space-between,alignItems:center,backgroundColor:#fff,paddingHorizontal:16,paddingVertical:12,borderBottomWidth:1,borderBottomColor:#eee,},headerTitle:{fontSize:18,fontWeight:bold,color:#333,},refreshButton:{backgroundColor:#007AFF,paddingHorizontal:16,paddingVertical:6,borderRadius:14,},refreshText:{color:#fff,fontSize:14,fontWeight:500,},content:{padding:16,},card:{backgroundColor:#fff,borderRadius:12,padding:16,marginBottom:12,flexDirection:row,shadowColor:#000,shadowOffset:{width:0,height:2},shadowOpacity:0.1,shadowRadius:4,elevation:3,},avatar:{width:50,height:50,borderRadius:25,marginRight:12,},cardContent:{flex:1,},name:{fontSize:16,fontWeight:600,color:#333,marginBottom:4,},namePlaceholder:{marginBottom:8,},title:{fontSize:13,color:#666,marginBottom:4,},description:{fontSize:12,color:#999,},});exportdefaultPlaceholderDemo; 六、属性参考Placeholder 属性属性类型必填说明AnimationComponentType否动画组件LeftComponentType否左侧组件RightComponentType否右侧组件styleobject否自定义样式PlaceholderLine 属性属性类型必填默认值说明widthnumber否100宽度百分比heightnumber否12高度colorstring否#efefef颜色noMarginboolean否false是否取消底部边距styleobject否-自定义样式PlaceholderMedia 属性属性类型必填默认值说明sizenumber否40大小宽高相同isRoundboolean否false是否为圆形colorstring否#efefef颜色styleobject否-自定义样式⚠️ 七、常见问题Q1: 占位符不显示A: 确保 Placeholder 组件内有 PlaceholderLine 或 PlaceholderMedia 子组件。单独使用 Placeholder 不会显示任何内容。Q2: 动画效果不流畅A: 检查是否有其他繁重的动画同时运行。可以尝试调整 animationDuration 属性来优化动画效果。Q3: 如何自定义占位符颜色A: 通过 color 属性设置占位符颜色建议与应用的整体配色方案保持一致。Q4: ShineOverlay 动画显示异常A: ShineOverlay 动画在白色背景上效果最佳。如果使用其他背景色建议改用 Shine 动画。 八、总结rn-placeholder 为 HarmonyOS 平台提供了优雅的骨架屏解决方案通过组合 Placeholder、PlaceholderLine、PlaceholderMedia 等组件可以快速实现各种加载占位效果。通过本篇文章你已经掌握了核心组件的使用方法多种动画效果的应用场景自定义占位符样式和布局实际项目中的最佳实践