从入门到精通：ViewPagerIndicator的XML属性与API完全手册

从入门到精通ViewPagerIndicator的XML属性与API完全手册【免费下载链接】viewpagerindicator Worked with ViewPager and ViewPager2,support multiple slider styles and multiple slide mode.This repo was split from BannerViewPager-项目地址: https://gitcode.com/gh_mirrors/view/viewpagerindicatorViewPagerIndicator 是一个功能强大的 Android 指示器库完美支持 ViewPager 和 ViewPager2提供多种滑块样式和滑动模式。无论你是 Android 开发新手还是经验丰富的开发者这份完整手册将帮助你快速掌握 ViewPagerIndicator 的所有 XML 属性和 API 用法。 快速入门指南要在你的 Android 项目中开始使用 ViewPagerIndicator首先需要添加依赖。在你的项目根目录的build.gradle文件中添加 JitPack 仓库allprojects { repositories { maven { url https://jitpack.io } } }然后在模块的build.gradle中添加依赖implementation com.github.zhpanvip:viewpagerindicator:latestVersion安装完成后你就可以在布局文件中使用 ViewPagerIndicator 了RelativeLayout android:layout_widthmatch_parent android:layout_heightwrap_content androidx.viewpager2.widget.ViewPager2 android:idid/viewPager android:layout_widthmatch_parent android:layout_height200dp / com.zhpan.indicator.IndicatorView android:idid/indicatorView android:layout_widthwrap_content android:layout_heightwrap_content android:layout_alignParentBottomtrue android:layout_centerHorizontaltrue android:layout_margin10dp / /RelativeLayout 核心XML属性详解ViewPagerIndicator 提供了丰富的 XML 属性让你可以在布局文件中轻松配置指示器。所有属性都以vpi_前缀开头易于识别。基本样式属性vpi_style- 设置指示器样式可选值circle、dash、round_rect默认值circle说明决定指示器的基本形状圆形、短横线或圆角矩形vpi_slide_mode- 设置滑块滑动模式可选值normal、smooth、worm、scale、color默认值normal说明控制页面切换时指示器的动画效果vpi_orientation- 设置指示器方向可选值horizontal、vertical、rtl默认值horizontal说明支持水平、垂直和从右到左布局颜色与尺寸属性vpi_slider_normal_color- 未选中滑块颜色格式color默认值#8C18171C说明设置指示器未选中状态的颜色vpi_slider_checked_color- 选中滑块颜色格式color默认值#6C6D72说明设置指示器选中状态的颜色vpi_slider_radius- 滑块半径或宽度格式dimension默认值8dp说明对于圆形样式是半径对于其他样式是宽度的一半 完整API方法手册除了 XML 属性ViewPagerIndicator 还提供了丰富的 API 方法让你在代码中动态配置指示器。样式配置方法setIndicatorStyle(style: Int)// 设置指示器样式 indicatorView.setIndicatorStyle(IndicatorStyle.CIRCLE) // 圆形 indicatorView.setIndicatorStyle(IndicatorStyle.DASH) // 短横线 indicatorView.setIndicatorStyle(IndicatorStyle.ROUND_RECT) // 圆角矩形setSlideMode(mode: Int)// 设置滑动模式 indicatorView.setSlideMode(IndicatorSlideMode.NORMAL) // 普通模式 indicatorView.setSlideMode(IndicatorSlideMode.SMOOTH) // 平滑模式 indicatorView.setSlideMode(IndicatorSlideMode.WORM) // 蠕虫模式 indicatorView.setSlideMode(IndicatorSlideMode.COLOR) // 颜色渐变 indicatorView.setSlideMode(IndicatorSlideMode.SCALE) // 缩放效果颜色与尺寸配置setSliderColor(normalColor: Int, selectedColor: Int)// 设置滑块颜色 val normalColor Color.parseColor(#8C18171C) val selectedColor Color.parseColor(#6C6D72) indicatorView.setSliderColor(normalColor, selectedColor)setSliderWidth(width: Float)// 设置滑块宽度圆形时为直径 val widthInDp resources.getDimension(R.dimen.dp_10) indicatorView.setSliderWidth(widthInDp)setSliderWidth(normalWidth: Float, checkedWidth: Float)// 分别设置未选中和选中状态的宽度 val normalWidth resources.getDimension(R.dimen.dp_8) val checkedWidth resources.getDimension(R.dimen.dp_12) indicatorView.setSliderWidth(normalWidth, checkedWidth)setSliderHeight(height: Float)// 设置指示器高度仅对DASH和ROUND_RECT样式有效 val heightInDp resources.getDimension(R.dimen.dp_5) indicatorView.setSliderHeight(heightInDp)setSliderGap(gap: Float)// 设置滑块之间的间距 val gapInDp resources.getDimension(R.dimen.dp_6) indicatorView.setSliderGap(gapInDp)方向与布局配置setOrientation(orientation: Int)// 设置指示器方向 indicatorView.setOrientation(IndicatorOrientation.HORIZONTAL) // 水平 indicatorView.setOrientation(IndicatorOrientation.VERTICAL) // 垂直 indicatorView.setOrientation(IndicatorOrientation.RTL) // 从右到左数据绑定与更新setPageSize(pageSize: Int)// 设置页面数量 indicatorView.setPageSize(5)notifyDataChanged()// 通知数据变化重新绘制 indicatorView.notifyDataChanged()setupWithViewPager(viewPager: ViewPager)// 关联 ViewPager indicatorView.setupWithViewPager(viewPager)setupWithViewPager(viewPager: ViewPager2)// 关联 ViewPager2 indicatorView.setupWithViewPager(viewPager2) 五种滑动模式详解1. NORMAL 普通模式最简单的切换效果选中状态直接跳转适合性能要求高的场景。2. SMOOTH 平滑模式滑块平滑过渡到下一个位置提供流畅的视觉体验。3. WORM 蠕虫模式滑块像虫子一样伸缩移动效果生动有趣。4. COLOR 颜色渐变模式颜色平滑过渡未选中和选中状态的颜色渐变切换。5. SCALE 缩放模式选中状态的滑块会放大未选中的会缩小形成层次感。 三种指示器样式对比CIRCLE 圆形样式最经典的指示器样式适合大多数应用场景。在indicator/src/main/java/com/zhpan/indicator/drawer/CircleDrawer.kt中实现。DASH 短横线样式简洁的横线设计适合现代简约风格的应用。在indicator/src/main/java/com/zhpan/indicator/drawer/DashDrawer.kt中实现。ROUND_RECT 圆角矩形样式圆角矩形设计视觉上更加柔和。在indicator/src/main/java/com/zhpan/indicator/drawer/RoundRectDrawer.kt中实现。 与 ViewPager/ViewPager2 的关联方法ViewPagerIndicator 提供了两种方式与 ViewPager 关联方法一自动关联推荐val indicatorView findViewByIdIndicatorView(R.id.indicator_view) val viewPager2 findViewByIdViewPager2(R.id.view_pager2) indicatorView.apply { setSliderColor(normalColor, checkedColor) setSliderWidth(resources.getDimension(R.dimen.dp_10)) setSliderHeight(resources.getDimension(R.dimen.dp_5)) setSlideMode(IndicatorSlideMode.WORM) setIndicatorStyle(IndicatorStyle.CIRCLE) setupWithViewPager(viewPager2) // 自动关联 }方法二手动关联val indicatorView findViewByIdIndicatorView(R.id.indicator_view) val viewPager2 findViewByIdViewPager2(R.id.view_pager2) // 设置页面数量 indicatorView.setPageSize(viewPager2.adapter!!.itemCount) indicatorView.notifyDataChanged() // 手动监听页面变化 viewPager2.registerOnPageChangeCallback(object : ViewPager2.OnPageChangeCallback() { override fun onPageScrolled(position: Int, positionOffset: Float, positionOffsetPixels: Int) { super.onPageScrolled(position, positionOffset, positionOffsetPixels) indicatorView.onPageScrolled(position, positionOffset, positionOffsetPixels) } override fun onPageSelected(position: Int) { super.onPageSelected(position) indicatorView.onPageSelected(position) } }) 自定义指示器实现ViewPagerIndicator 支持高度自定义你可以创建自己的指示器样式。使用 DrawableIndicatorval drawableIndicator findViewByIdDrawableIndicator(R.id.indicator_view) val dp20 resources.getDimensionPixelOffset(R.dimen.dp_20) drawableIndicator.apply { setIndicatorGap(resources.getDimensionPixelOffset(R.dimen.dp_2_5)) setIndicatorDrawable(R.drawable.heart_empty, R.drawable.heart_red) setIndicatorSize(dp20, dp20, dp20, dp20) setupWithViewPager(view_pager2) }继承 BaseIndicatorView 创建自定义指示器在app/src/main/java/com/zhpan/viewpagerindicator/DrawableIndicator.kt中可以查看自定义指示器的实现示例。 属性与API对照表XML 属性对应 API 方法说明vpi_stylesetIndicatorStyle()设置指示器样式vpi_slide_modesetSlideMode()设置滑动模式vpi_orientationsetOrientation()设置方向vpi_slider_normal_colorsetSliderColor()设置未选中颜色vpi_slider_checked_colorsetSliderColor()设置选中颜色vpi_slider_radiussetSliderWidth()设置滑块尺寸 高级使用技巧1. 动态切换样式// 根据用户偏好动态切换样式 when (userPreference) { simple - indicatorView.setIndicatorStyle(IndicatorStyle.CIRCLE) modern - indicatorView.setIndicatorStyle(IndicatorStyle.DASH) rounded - indicatorView.setIndicatorStyle(IndicatorStyle.ROUND_RECT) }2. 响应式尺寸调整// 根据屏幕密度调整尺寸 val density resources.displayMetrics.density val sliderWidth when { density 3.0 - 12f // xxhdpi及以上 density 2.0 - 10f // xhdpi else - 8f // 其他 } indicatorView.setSliderWidth(resources.getDimension(R.dimen.dp_${sliderWidth.toInt()}))3. 颜色主题适配// 根据应用主题动态设置颜色 val isDarkTheme resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK Configuration.UI_MODE_NIGHT_YES val normalColor if (isDarkTheme) { Color.parseColor(#CCCCCC) } else { Color.parseColor(#333333) } val selectedColor if (isDarkTheme) { Color.parseColor(#FFFFFF) } else { Color.parseColor(#000000) } indicatorView.setSliderColor(normalColor, selectedColor) 常见问题解答Q: 为什么我的指示器不显示A: 确保已经调用了setPageSize()或setupWithViewPager()方法并且页面数量大于0。Q: 如何实现垂直方向的指示器A: 使用setOrientation(IndicatorOrientation.VERTICAL)或 XML 属性vpi_orientationvertical。Q: 支持 ViewPager 和 ViewPager2 有什么区别A: ViewPagerIndicator 同时支持两者API 用法完全相同只是关联方法略有不同。Q: 自定义指示器需要注意什么A: 确保继承BaseIndicatorView并正确实现onDraw()方法参考DrawableIndicator.kt的实现。 最佳实践建议性能优化对于大量页面建议使用NORMAL滑动模式减少动画计算开销。视觉一致性保持指示器颜色与应用主题色一致提升用户体验。响应式设计根据屏幕尺寸和密度调整指示器大小确保在不同设备上都有良好的显示效果。无障碍访问为指示器添加内容描述方便屏幕阅读器用户使用。测试覆盖测试所有滑动模式和样式组合确保在各种情况下都能正常工作。通过这份完整手册你已经掌握了 ViewPagerIndicator 的所有 XML 属性和 API 方法。无论是简单的圆形指示器还是复杂的自定义样式ViewPagerIndicator 都能满足你的需求。开始在你的 Android 项目中应用这些知识打造出色的用户界面吧✨【免费下载链接】viewpagerindicator Worked with ViewPager and ViewPager2,support multiple slider styles and multiple slide mode.This repo was split from BannerViewPager-项目地址: https://gitcode.com/gh_mirrors/view/viewpagerindicator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考