介绍

banner4cj 是一款广告轮播组件库，专为鸿蒙系统开发的仓颉语言三方库，广泛应用于广告图片轮播场景。

核心功能

• 自动轮播功能
• 无限循环播放
• 垂直轮播模式

源码结构

├─AppScope
├─doc            # API文档和使用手册存放目录                   
├─entry          # 示例代码文件夹                  
├─library[banner] # banner 库源目录                  
│  └─src
│      └─main
│          ├─cangjie
│          │  └─src              # 核心实现功能代码                       
│          └─resources
├─hvigor     # 构建工具目录
├─README.md  # banner4cj 介绍及使用说明

接口说明

主要类和函数接口说明详见 API 文档

使用指南

1. 通过模块引入

   1. 克隆下载项目
   2. 将 banner 模块复制到应用项目目录下
   3. 修改应用入口 entry 下的 oh-package.json5 文件，在 dependencies 字段添加依赖：

   {  
      "name": "entry",  
      "version": "1.0.0",  
      "description": "请填写基础信息描述",  
      "main": "",  
      "author": "",  
      "license": "",  
      "dependencies": {  
         "banner": "file:../banner"  
      }  
   }  
   

   4. 修改应用入口 entry/src/main/cangjie 下的 cjpm.toml 文件，在 [dependencies] 字段添加：

      [dependencies]  
          banner = {path = "../../../../banner/src/main/cangjie", version = "1.0.0"}  
      

   5. 在代码中通过 import banner.* 引入组件：

      import banner.*  
      

2. 作为三方库依赖引入

   1. 将 banner4cj 作为 git 子模块添加到工程中：

   > cd $工程根目录  
   > mkdir third-party  
   > cd third-party  
   > git submodule add "https://gitcode.com/Cangjie-TPC/banner4cj.git"  
   

   2. 修改应用入口 entry/src/main/cangjie 下的 cjpm.toml 文件，添加依赖：

   [dependencies]  
       banner = {path = "../../../../third-party/banner4cj/banner/src/main/cangjie", version = "1.0.0"}  
   

   3. 在代码中使用组件：

      import banner.*  
      

功能演示

完整示例见 entry 目录

高亮引导组件示例

import kit.UIKit.*
import kit.LocalizationKit.*
import ohos.state_macro_manage.*
import cjbanner.*
import cjbanner.indicator.CircleIndicator
import ohos.router.Router
import ohos.hilog.Hilog
import cjbanner.config.IndicatorConfig
import cjbanner.transformer.AnimatedEnum

@Entry
@Component
class BannerSamplePage {
    private var swiperController: SwiperController = SwiperController()
    private var touTiaoSwiperController: SwiperController = SwiperController()

    @State
    var data: ObservedArrayList<BannerBean> = ObservedArrayList<BannerBean>()

    @State
    var touTiaoData: ObservedArrayList<BannerBean> = ObservedArrayList<BannerBean>(
        [
            BannerBean(@r(app.media.jpg1), "听风,赏雨", 3),
            BannerBean(@r(app.media.jpg2), "迪力拉提拉", 1),
            BannerBean(@r(app.media.png3), "爱美,人间有之", 3),
            BannerBean(@r(app.media.png3), "洋洋洋,气质篇", 1),
            BannerBean(@r(app.media.png3), "生活的态度", 3)
        ]
    )

    var indicatorConfig: IndicatorConfig = IndicatorConfig(indicatorSize: 10, currentPosition: 0,
        selectedColor: Color(0x5CB85C), normalColor: Color.WHITE)

    var IMAGE_RESOURCES: Array<AppResource> = [@r(app.media.jpg1), @r(app.media.jpg2), @r(app.media.png3),
        @r(app.media.webp5)]

    @State
    var itemIndex: Int32 = 1

    @State
    var bannerSize: Int64 = 10

    @State
    var autoPlay: Bool = true // 自定播放

    @State
    var loop: Bool = true // 是否开启循环

    @State
    var vertical: Bool = false // 是否纵向滑动

    @State
    var interval: UInt32 = 3000 // 当前item停滞时间

    @State
    var duration: UInt32 = 800 // 子组件切换动画时长

    @State
    var animatedConfig: ?AnimatedConfig = Option<AnimatedConfig>.None

    @State
    var bannerMargin: BannerMargin = BannerMargin(left: 0.0, right: 0.0) // 水平是左右的margin,垂直为上下的margin

    func onChangeIndex(index: Int32) {
        this.itemIndex = index + 1
        this.indicatorConfig.setCurrentPosition(index)
    }

    func onGestureSwipe(index: Int64, extraInfo: SwiperAnimationEvent) {
    }

    func onAnimationStart(index: Int64, targetIndex: Int64, extraInfo: SwiperAnimationEvent) {
    }

    func onAnimationEnd(index: Int64, extraInfo: SwiperAnimationEvent) {
    }

    func setBannerOptions(): BannerOptions {
        return BannerOptions(this.swiperController, this.autoPlay, this.interval, SwiperIndicator(), this.loop, this.duration,
            this.vertical, Curve.Linear, this.bannerMargin, AnimatedEnum.ZoomOutPage, this.animatedConfig, onChangeIndex, onGestureSwipe, onAnimationStart, onAnimationEnd)
    }

    func setTouTiaoBannerOptions(): BannerOptions {
        return BannerOptions(this.touTiaoSwiperController, true, 3000, SwiperIndicator(), true, 800, true, Curve.Linear,
            this.bannerMargin, AnimatedEnum.ScaleIn, this.animatedConfig, onChangeIndex, onGestureSwipe, onAnimationStart, onAnimationEnd)
    }

    public override func aboutToAppear() {
        this.createNewDataList()
    }

    func createNewDataList() {
        let list = ObservedArrayList<BannerBean>()
        for (i in 0..bannerSize) {
            list.append(BannerBean(IMAGE_RESOURCES[i % 4], "数字：${i + 1}", 3))
        }
        this.data.set(list)
        this.indicatorConfig.setIndicatorSize(this.data.size)
    }

    var VIEW_TYPE_NAME: Array<String> = ["1号店", "淘宝头条", "京东快报"]

    @Builder
    func bannerContent(data: ObservedArrayList<BannerBean>, index: Int64) {
        Stack(Alignment.Center) {
            Image(IMAGE_RESOURCES[index % this.IMAGE_RESOURCES.size])
                .objectFit(ImageFit.Fill)
                .width(100.percent)
                .height(100.percent)
            Flex(FlexParams(direction: FlexDirection.Row, justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center)) {
                Text("这是第${index + 1}个页面，用户数据为：${data[index].title}").fontColor(Color.WHITE)
            }.position(x: 0, y: 200).height(40).width(100.percent).backgroundColor(Color(0x44000000))
        }.width(100.percent).height(240)
    }

    @Builder
    func bannerContent2(data: ObservedArrayList<BannerBean>, index: Int64) {
        Column() {
            Text(data[index].title).fontSize(30).fontColor(0x222222)
            Row() {
                Text(VIEW_TYPE_NAME[data[index].viewType % this.VIEW_TYPE_NAME.size]).fontColor(0x5CB85C).fontSize(8)
                Text('2020年1月23日').fontSize(22).margin(left: 20)
            }.margin(top: 20)
        }.alignItems(HorizontalAlign.Start).justifyContent(FlexAlign.Start).width(100.percent).height(80)
    }

    func build() {
        Scroll() {
            Column() {
                Button("点击返回上一页").width(100.percent).height(50).margin(10).onClick({
                    event => Router.back()
                })
                Text("缩放渐变动效展示+指示器与banner分离").margin(top: 20, bottom: 20)
                Stack() {
                    Column() {
                        Banner(bannerOptions: setBannerOptions(), data: this.data, currentPosition: 0,
                            bannerContent: this.bannerContent)
                    }.width(100.percent).height(240)

                    Flex(
                        FlexParams(direction: FlexDirection.RowReverse, justifyContent: FlexAlign.Start,
                            alignItems: ItemAlign.Center)) {
                        
                    }.width(100.percent).height(40).position(x: 0, y: 200)
                }.width(100.percent).height(240)

                Flex(
                    FlexParams(direction: FlexDirection.RowReverse, justifyContent: FlexAlign.Start,
                        alignItems: ItemAlign.Center)) {
                    Text("${(this.itemIndex)}/${this.data.size}").fontColor(Color.WHITE).margin(left: 20, right: 40)

                    CircleIndicator(indicatorConfig: this.indicatorConfig)
                }.width(100.percent).height(40).backgroundColor(Color.GRAY)

                Text("垂直轮播+缩放动效展示").margin(top: 20, bottom: 20)

                Row() {
                    Text("热点").fontSize(30).width(25.percent).height(80)
                    Banner(bannerOptions: setTouTiaoBannerOptions(), data: this.touTiaoData, currentPosition: 0,
                        bannerContent: this.bannerContent2)
                    Stack() {
                        Image(@r(app.media.right_arrow)).objectFit(ImageFit.Contain)
                    }
                }.width(100.percent).height(80)
            }.width(100.percent)
        }.width(100.percent).height(100.percent)
    }
}

兼容性说明

已通过以下版本验证：

DevEco Studio 5.1.0 Release
仓颉支持插件 5.1.0.828
仓颉编译器：1.0.0 (cjnative)

开源许可

本项目遵循 Apache License 2.0 协议，欢迎自由使用并参与开源协作。

贡献指南

诚挚邀请您通过提交PR、创建Issue或任何形式参与项目贡献。