https://github.com/youth5201314/banner

🔥🔥🔥Banner 2.0 来了！Android广告图片轮播控件，内部基于ViewPager2实现，Indicator和UI都可以自定义。
https://github.com/youth5201314/banner

androidx banner indicator viewpager viewpager2

Last synced: about 22 hours ago
JSON representation

🔥🔥🔥Banner 2.0 来了！Android广告图片轮播控件，内部基于ViewPager2实现，Indicator和UI都可以自定义。

• Host: GitHub
• URL: https://github.com/youth5201314/banner
• Owner: youth5201314
• License: apache-2.0
• Created: 2016-04-22T05:50:25.000Z (about 8 years ago)
• Default Branch: master
• Last Pushed: 2024-01-11T08:41:56.000Z (5 months ago)
• Last Synced: 2024-02-29T03:35:27.412Z (4 months ago)
• Topics: androidx, banner, indicator, viewpager, viewpager2
• Language: Java
• Homepage:
• Size: 10.8 MB
• Stars: 12,660
• Watchers: 236
• Forks: 2,499
• Open Issues: 10
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Lists

• awesome-android - banner
• awesome-github-android-ui - banner - Android广告图片轮播控件 (轮播图)
• awesome-github-android-ui - banner - Android广告图片轮播控件 (轮播图)

README

        

## Banner 2.0 全新升级

> 只做一个可以自定义的轮播容器，不侵入UI ———— Banner 2.0

```

> 各位老铁反馈的问题我都有看，不是不解决，有时真的很难复现，

> 如果能在提交问题时，有条件提供个demo发到我邮箱，方便定位问题，毕竟大家的场景和使用方式都有差异，

> 我自己也在使用，在多个千万级APP上一直稳定运行，如果真有严重问题肯定第一时间就修复了

```

Banner 1.4.10(还想看老版本的可以点击这里)

### 阔别已久，从新回归

* 首先我声明几点：

    * 这只是一个开源库，如果满意你可以使用、可以借鉴修改，希望对你们有所帮助。

    * 如果不满意请友好的提出，注明错误的详细信息或者修改建议，好的想法和自定义的东西亦可以直接提交，大家都能来一起完善。

    * 如果你觉得实在是没用，也请你做一个有自我修养的人。

   

### 主要改进功能介绍

最开始是想上传以前基于viewpager更新好的版本，但是看着viewpager2正式版已经出来了，就上新的吧，viewpager2确实比viewpager性能好很多。

- [x] 使用了ViewPager2为基础控件  ViewPager2介绍

- [x] 支持了androidx兼容包

- [x] 方便了UI、Indicator自定义

- [x] 支持画廊效果、魅族效果

- [x] 兼容了水平和垂直轮播，也可以实现类似淘宝头条的效果

- [x] 依赖包目前只需要导入了ViewPager2

### 效果图

更多效果运行demo查看

![默认](images/banner_example.gif)

![画廊](images/banner_example2.gif)

![魅族](images/banner_example1.gif)

![头条](images/banner_example3.gif)

##### 内置了多种PageTransformer效果

![DepthPageTransformer](images/DepthPageTransformer.gif)

![ZoomOutPageTransformer](images/ZoomOutPageTransformer.gif)

|内置的PageTransformer|

|---|

|AlphaPageTransformer|

|DepthPageTransformer|

|RotateDownPageTransformer|

|RotateUpPageTransformer|

|RotateYTransformer|

|ScaleInTransformer|

|ZoomOutPageTransformer|

 也可以组合使用效果更佳

## 方法

更多方法以实际使用为准，下面不一定全部列出了

|方法名|返回类型|描述|

|---|---|---|

|getAdapter()|extends BannerAdapter|获取你设置的BannerAdapter

|getViewPager2()|ViewPager2|获取ViewPager2

|getIndicator()|Indicator|获取你设置的指示器（没有设置直接获取会抛异常哦）

|getIndicatorConfig()|IndicatorConfig|获取你设置的指示器配置信息（没有设置直接获取会抛异常哦）

|getRealCount()|int|返回banner真实总数

|setUserInputEnabled(boolean)|this|禁止手动滑动Banner;true 允许，false 禁止

|setDatas(List)|this|重新设置banner数据

|isAutoLoop(boolean)|this|是否允许自动轮播

|setLoopTime(long)|this|设置轮播间隔时间（默认3000毫秒）

|setScrollTime(long)|this|设置轮播滑动的时间（默认800毫秒）

|start()|this|开始轮播(主要配合生命周期使用)，或者你手动暂停再次启动

|stop()|this|停止轮播(主要配合生命周期使用)，或者你需要手动暂停

|setAdapter(T extends BannerAdapter)|this|设置banner的适配器

|setAdapter(T extends BannerAdapter,boolean)|this|设置banner的适配器,是否支持无限循环

|setOrientation(@Orientation)|this|设置banner轮播方向(垂直or水平)

|setOnBannerListener(this)|this|设置点击事件，下标是从0开始

|addOnPageChangeListener(this)|this|添加viewpager2的滑动监听

|setPageTransformer(PageTransformer)|this|设置viewpager的切换效果

|addPageTransformer(PageTransformer)|this|添加viewpager的切换效果（可以设置多个）

|setIndicator(Indicator)|this|设置banner轮播指示器(提供有base和接口，可以自定义)

|setIndicator(Indicator,boolean)|this|设置指示器（传false代表不将指示器添加到banner上，配合布局文件，可以自我发挥）

|setIndicatorSelectedColor(@ColorInt)|this|设置指示器选中颜色

|setIndicatorSelectedColorRes(@ColorRes)|this|设置指示器选中颜色

|setIndicatorNormalColor(@ColorInt)|this|设置指示器默认颜色

|setIndicatorNormalColorRes(@ColorRes)|this|设置指示器默认颜色

|setIndicatorGravity(@IndicatorConfig.Direction)|this|设置指示器位置（左，中，右）

|setIndicatorSpace(int)|this|设置指示器之间的间距

|setIndicatorMargins(IndicatorConfig.Margins)|this|设置指示器的Margins

|setIndicatorWidth(int,int)|this|设置指示器选中和未选中的宽度，直接影响绘制指示器的大小

|setIndicatorNormalWidth(int)|this|设置指示器未选中的宽度

|setIndicatorSelectedWidth(int)|this|设置指示器选中的宽度

|setIndicatorRadius(int)|this|设置指示器圆角，不要圆角可以设置为0

|setIndicatorHeight(int)|this|设置指示器高度

|setBannerRound(float)|this|设置banner圆角（还有一种setBannerRound2方法，需要5.0以上）

|setBannerGalleryEffect(int,int,float)|this|画廊效果

|setBannerGalleryMZ(int,float)|this|魅族效果

|setStartPosition(int)|this|设置开始的位置 (需要在setAdapter或者setDatas之前调用才有效哦)

|setIndicatorPageChange()|this|设置指示器改变监听 (一般是为了配合数据操作使用，看情况自己发挥)

|setCurrentItem()|this|设置当前位置，和原生使用效果一样

|addBannerLifecycleObserver()|this|给banner添加生命周期观察者，内部自动管理banner的生命周期

## Attributes属性

>在banner布局文件中调用,如果你自定义了indicator请做好兼容处理。

下面的属性并不是每个指示器都用得到，所以使用时要注意！

|Attributes|format|describe

|---|---|---|

|banner_loop_time|integer|轮播间隔时间，默认3000

|banner_auto_loop|boolean|是否自动轮播，默认true

|banner_infinite_loop|boolean|是否支持无限循环（即首尾直接过渡），默认true

|banner_orientation|enum|轮播方向：horizontal（默认） or vertical

|banner_radius|dimension|banner圆角半径，默认0（不绘制圆角）

|banner_indicator_normal_width|dimension|指示器默认的宽度，默认5dp （对RoundLinesIndicator无效）

|banner_indicator_selected_width|dimension|指示器选中的宽度，默认7dp 

|banner_indicator_normal_color|color|指示器默认颜色，默认0x88ffffff

|banner_indicator_selected_color|color|指示器选中颜色，默认0x88000000

|banner_indicator_space|dimension|指示器之间的间距，默认5dp （对RoundLinesIndicator无效）

|banner_indicator_gravity|dimension|指示器位置，默认center

|banner_indicator_margin|dimension|指示器的margin,默认5dp，不能和下面的同时使用

|banner_indicator_marginLeft|dimension|指示器左边的margin

|banner_indicator_marginTop|dimension|指示器上边的margin

|banner_indicator_marginRight|dimension|指示器右边的margin

|banner_indicator_marginBottom|dimension|指示器下边的margin

|banner_indicator_height|dimension|指示器高度（对CircleIndicator无效）

|banner_indicator_radius|dimension|指示器圆角（对CircleIndicator无效）

|banner_round_top_left|boolean|设置要绘制的banner圆角方向（如果都不设置默认全部）

|banner_round_top_right|boolean|设置要绘制的banner圆角方向（如果都不设置默认全部）

|banner_round_bottom_left|boolean|设置要绘制的banner圆角方向（如果都不设置默认全部）

|banner_round_bottom_right|boolean|设置要绘制的banner圆角方向（如果都不设置默认全部）

## 使用步骤

>以下提供的是最简单的步骤，需要复杂的样式自己可以自定义

#### Step 1.依赖banner

Gradle 

```groovy

repositories {

    maven { url "https://s01.oss.sonatype.org/content/groups/public" }

}

dependencies{

    //2.1.0以前jcenter的依赖

    //implementation 'com.youth.banner:banner:2.1.0'

    //现在Maven Central

    implementation 'io.github.youth5201314:banner:2.2.3'

}

```

#### Step 2.添加权限到你的 AndroidManifest.xml

```xml

 

```

#### Step 3.在布局文件中添加Banner，可以设置自定义属性

！！！此步骤可以省略，可以直接在Activity或者Fragment中new Banner();

```xml

```

#### Step 4.继承BannerAdapter，和RecyclerView的Adapter一样（如果你只是图片轮播也可以使用默认的）

！！！此步骤可以省略，图片轮播提供有默认适配器，其他的没有提供是因为大家的可变性要求不确定，所以直接自定义的比较好。

```java

/**

 * 自定义布局，下面是常见的图片样式，更多实现可以看demo，可以自己随意发挥

 */

public class ImageAdapter extends BannerAdapter {

    public ImageAdapter(List mDatas) {

        //设置数据，也可以调用banner提供的方法,或者自己在adapter中实现

        super(mDatas);

    }

    //创建ViewHolder，可以用viewType这个字段来区分不同的ViewHolder

    @Override

    public BannerViewHolder onCreateHolder(ViewGroup parent, int viewType) {

        ImageView imageView = new ImageView(parent.getContext());

        //注意，必须设置为match_parent，这个是viewpager2强制要求的

        imageView.setLayoutParams(new ViewGroup.LayoutParams(

                ViewGroup.LayoutParams.MATCH_PARENT,

                ViewGroup.LayoutParams.MATCH_PARENT));

        imageView.setScaleType(ImageView.ScaleType.CENTER_CROP);

        return new BannerViewHolder(imageView);

    }

    @Override

    public void onBindView(BannerViewHolder holder, DataBean data, int position, int size) {

        holder.imageView.setImageResource(data.imageRes);

    }

    class BannerViewHolder extends RecyclerView.ViewHolder {

        ImageView imageView;

        public BannerViewHolder(@NonNull ImageView view) {

            super(view);

            this.imageView = view;

        }

    }

}

```

#### Step 5.Banner具体方法调用 

```java

public class BannerActivity extends AppCompatActivity {

    public void useBanner() {

        //--------------------------简单使用-------------------------------

        banner.addBannerLifecycleObserver(this)//添加生命周期观察者

                .setAdapter(new BannerExampleAdapter(DataBean.getTestData()))

                .setIndicator(new CircleIndicator(this));

        

        //—————————————————————————如果你想偷懒，而又只是图片轮播————————————————————————

         banner.setAdapter(new BannerImageAdapter(DataBean.getTestData3()) {

                    @Override

                    public void onBindView(BannerImageHolder holder, DataBean data, int position, int size) {

                        //图片加载自己实现

                        Glide.with(holder.itemView)

                             .load(data.imageUrl)

                             .apply(RequestOptions.bitmapTransform(new RoundedCorners(30)))

                             .into(holder.imageView);

                    }

                })

                .addBannerLifecycleObserver(this)//添加生命周期观察者

                .setIndicator(new CircleIndicator(this));

        //更多使用方法仔细阅读文档，或者查看demo

    }

}

```

## Banner使用中优化体验

**如果你需要考虑更好的体验，可以看看下面的代码**

#### Step 1.（可选）生命周期改变时

```java

public class BannerActivity {

  

    //方法一：自己控制banner的生命周期

    

    @Override

    protected void onStart() {

        super.onStart();

        //开始轮播

        banner.start();

    }

    

    @Override

    protected void onStop() {

        super.onStop();

        //停止轮播

        banner.stop();

    }

    

    @Override

    protected void onDestroy() {

        super.onDestroy();

        //销毁

        banner.destroy();

    }

    

    //方法二：调用banner的addBannerLifecycleObserver()方法，让banner自己控制

   

    protected void onCreate(Bundle savedInstanceState) {

         //添加生命周期观察者

        banner.addBannerLifecycleObserver(this);

    }

}

```

## 常见问题（收录被反复询问的问题）

* 网络图片加载不出来？

  `banner本身不提供图片加载功能，首先确认banner本身使用是否正确，具体参考demo，

  然后请检查你的图片加载框架或者网络请求框架，服务端也可能加了https安全认证，是看下是否报有证书相关错误`

  

* 怎么实现视频轮播？

  `demo中有实现类似淘宝商品详情的效果，第一个放视频，后面的放的是图片，并且可以设置首尾不能滑动。

  因为大家使用的播放器不一样业务环境也不同，具体情况自己把握，demo就是给一个思路哈！可以参考和修改`

* 我想指定轮播开始的位置？

  `现在提供了setStartPosition()方法，在sheAdapter和setDatas直接调用一次就行了，当然setAdapter后通过setCurrentItem设置也行`

* 父控件滑动时，banner切换会获取焦点，然后自动全部显示。不想让banner获取焦点可以给父控件加上：

    ```

        //banner也一定要用最新版哦！

        android:focusable="true"

        android:focusableInTouchMode="true"

    ```

* 怎么设置圆角？

  1、调用提供的方法或者自定义属性进行设置，这里设置的是banner本身的圆角，不是轮播内view的圆角

  2、在adapter中对自定义的view进行自己实现，就拿图片举例：可以自己定义一个圆角的ImageView控件，或者使用glide渲染都行。请举一反三，view都自定义了还有什么不能改的？

  

    

## Thanks

- [MZBannerView](https://github.com/pinguo-zhouwei/MZBannerView)

- [MagicViewPager](https://github.com/hongyangAndroid/MagicViewPager)

- [zguop的viewpager2的滑动时间解决方案](https://github.com/zguop/banner/blob/master/pager2banner/src/main/java/com/to/aboomy/pager2banner/Banner.java)

### 联系方式  

* 我的个人微博：https://weibo.com/u/3013494003 有兴趣的也可以关注，大家一起交流

* 有问题可以加群大家一起交流，如果你觉得对你有帮助可以扫描下面支付宝二维码随意打赏下哦！

 

## 更新说明

[更新说明](update_message.md)