轮播图

轮播图是展示图片和内容的视图组件，基于数据源实现图片轮播展示、内容切换和用户交互。它负责数据加载、图片渲染和事件处理，支持自动播放、手动切换、点击交互等功能，同时提供丰富的样式配置选项。

轮播图元素分层结构为Meta（components.Meta） → Type（components.Carousel） → 实例，开发者可通过JitAI的可视化开发工具快捷地创建轮播图实例元素。

当然，开发者也可以创建自己的Type元素，或者在自己的App中改写JitAi官方提供的components.CarouselType元素，以实现自己的封装。

快速开始

基础配置示例

推荐目录结构

pages/
└── MyPage/
    ├── e.json
    ├── scheme.json
    └── page.ts

scheme.json - 轮播图配置

{
  "componentList": [
    {
      "fullName": "components.Carousel",
      "type": "components.Carousel", 
      "name": "myCarousel",
      "title": "我的轮播图",
      "config": {
        "requireElements": [
          {
            "title": "轮播图的数据源",
            "type": "models.Meta",
            "name": "models.ProductModel",
            "filter": "",
            "orderBy": ""
          }
        ],
        "fieldTitle": ["name"],
        "abstract": ["description"], 
        "image": ["imageUrl"],
        "imageNum": 5,
        "style": {
          "autoplaySpeed": 3000,
          "dotPosition": "bottom",
          "effect": "scrollx"
        },
        "defaultRender": true
      },
      "showTitle": true
    }
  ]
}

调用示例

// 获取轮播图组件实例
const carousel = app.getElement('pages.MyPage.myCarousel');

// 监听点击事件
carousel.subscribeEvent('clickRow', async (data) => {
  console.log('点击的数据：', data.activeRow);
});

// 刷新数据
await carousel.call();

配置属性说明

参数名	类型	说明	默认值	必填
requireElements	requireElement[]	数据源配置，需要指定模型元素	-	是
fieldTitle	string[]	标题字段列表	[]	否
abstract	string[]	摘要字段列表	[]	否
image	string[]	图片字段列表	[]	是
imageNum	number	最大显示图片数量	5	否
style	CarouselStyle	样式配置对象	-	否
defaultRender	boolean	是否默认渲染	true	否

CarouselStyle配置：

参数名	类型	说明	默认值	必填
autoplaySpeed	number	自动播放速度（毫秒）	3000	否
dotPosition	'top' | 'bottom' | 'left' | 'right'	指示点位置	'bottom'	否
effect	'scrollx' | 'fade'	切换动画效果	'scrollx'	否

变量

displayRowList

展示的多行数据，类型为 RowList<T>，只读属性。

包含根据配置筛选和处理后的数据列表，用于轮播图渲染。

获取展示数据

const carousel = app.getElement('pages.MyPage.myCarousel');
const dataList = carousel.displayRowList.value;
console.log('轮播图数据：', dataList);

activeRow

操作的单行数据，类型为 RowData<T>，只读属性。

当前被点击或操作的数据行，在点击事件中会自动更新。

获取当前操作数据

const carousel = app.getElement('pages.MyPage.myCarousel');
carousel.subscribeEvent('clickRow', (data) => {
  console.log('当前操作的数据：', carousel.activeRow.value);
});

filter

筛选条件，类型为 QFilter<T>，只读属性。

当前应用的数据筛选条件，包含配置的过滤器和运行时传入的条件。

获取筛选条件

const carousel = app.getElement('pages.MyPage.myCarousel');
console.log('当前筛选条件：', carousel.filter.value);

loading

加载状态，类型为 Numeric，只读属性。

表示数据加载状态，0表示未加载，1表示加载中。

检查加载状态

const carousel = app.getElement('pages.MyPage.myCarousel');
console.log('是否正在加载：', carousel.loading.value === 1);

方法

call

刷新轮播图数据的异步方法。

参数详解

参数名	类型	说明	默认值	必填
qFilter	QFilter<T>	筛选条件对象	-	否

返回值

返回 Promise<void>

使用示例

刷新数据

const carousel = app.getElement('pages.MyPage.myCarousel');

// 无条件刷新
await carousel.call();

// 带筛选条件刷新
const filter = new app.datatypes.QFilter({
  value: "Q(status='active')"
});
await carousel.call(filter);

destroy

销毁组件实例的方法。

返回值

无返回值

使用示例

销毁组件

const carousel = app.getElement('pages.MyPage.myCarousel');

// 销毁组件，清理事件监听和资源
carousel.destroy();

publishEvent

发送组件事件的异步方法。

参数详解

参数名	类型	说明	默认值	必填
name	string	事件名称	-	是
ex	Record<string, any>	附加数据	-	否

返回值

返回 Promise<void>

使用示例

发送自定义事件

const carousel = app.getElement('pages.MyPage.myCarousel');

await carousel.publishEvent('customEvent', {
  customData: 'example'
});

runCode

执行代码片段的方法。

参数详解

参数名	类型	说明	默认值	必填
code	string	要执行的代码字符串	-	是

返回值

返回代码执行结果

使用示例

执行代码

const carousel = app.getElement('pages.MyPage.myCarousel');

// 执行代码片段
const result = carousel.runCode('this.displayRowList.value.length');
console.log('数据数量：', result);

setConfig

设置组件配置的方法。

参数详解

参数名	类型	说明	默认值	必填
next	Partial<T>	新的配置对象	-	是
clean	boolean	是否清空原配置	false	否

返回值

无返回值

使用示例

设置配置

const carousel = app.getElement('pages.MyPage.myCarousel');

// 合并配置
carousel.setConfig({ imageNum: 8 });

// 替换全部配置
carousel.setConfig({ imageNum: 8, style: { autoplaySpeed: 2000 } }, true);

subscribeEvent

订阅组件事件的方法。

参数详解

参数名	类型	说明	默认值	必填
name	string	事件名称	-	是
evtCb	Function	事件回调函数	-	是
unSubscribeExist	boolean	是否取消已存在的订阅	true	否

返回值

返回订阅ID字符串

使用示例

订阅事件

const carousel = app.getElement('pages.MyPage.myCarousel');

const subscriptionId = carousel.subscribeEvent('clickRow', async (data) => {
  console.log('轮播图被点击：', data);
});

unSubscribeEvent

取消事件订阅的方法。

参数详解

参数名	类型	说明	默认值	必填
id	string	订阅ID	-	是

返回值

无返回值

使用示例

取消订阅

const carousel = app.getElement('pages.MyPage.myCarousel');

const subscriptionId = carousel.subscribeEvent('clickRow', callback);
carousel.unSubscribeEvent(subscriptionId);

updateConfig

更新组件配置的方法。

参数详解

参数名	类型	说明	默认值	必填
config	ComponentConfig	新的配置对象	-	是

返回值

无返回值

使用示例

更新配置

const carousel = app.getElement('pages.MyPage.myCarousel');

carousel.updateConfig({
  config: {
    imageNum: 10,
    style: {
      autoplaySpeed: 5000,
      dotPosition: 'top'
    }
  }
});

属性

config

组件配置对象，类型为 CarouselCompConfig & { requireElements: requireElement[] }，可读写。

包含轮播图的完整配置信息，可以通过updateConfig方法进行更新。

访问配置

const carousel = app.getElement('pages.MyPage.myCarousel');
console.log('当前配置：', carousel.config);
console.log('图片数量：', carousel.config.imageNum);

app

应用实例，类型为 App，只读属性。

当前运行的应用实例引用。

访问应用实例

const carousel = app.getElement('pages.MyPage.myCarousel');
console.log('应用实例：', carousel.app);

compType

组件类型枚举，类型为 COMPONENT_TYPE，只读属性。

组件的类型分类。

name

组件名称，类型为 string，只读属性。

在页面中的唯一标识符。

获取组件名称

const carousel = app.getElement('pages.MyPage.myCarousel');
console.log('组件名称：', carousel.name);

page

页面实例，类型为 BasePage，只读属性。

当前页面实例引用。

访问页面实例

const carousel = app.getElement('pages.MyPage.myCarousel');
console.log('页面实例：', carousel.page);

showTitle

是否显示标题，类型为 boolean，只读属性。

控制组件标题的显示状态。

检查标题显示状态

const carousel = app.getElement('pages.MyPage.myCarousel');
console.log('是否显示标题：', carousel.showTitle);

title

组件标题，类型为 string，只读属性。

组件的显示标题。

获取组件标题

const carousel = app.getElement('pages.MyPage.myCarousel');
console.log('组件标题：', carousel.title);

type

组件类型标识，类型为 string，只读属性。

组件的Type元素标识。

获取组件类型

const carousel = app.getElement('pages.MyPage.myCarousel');
console.log('组件类型：', carousel.type); // "components.Carousel"

事件

clickRow

轮播图项目点击事件。

参数详解

参数名	类型	说明	默认值	必填
activeRow	RowData<T>	被点击的数据行	-	-

使用示例

处理点击事件

const carousel = app.getElement('pages.MyPage.myCarousel');

carousel.subscribeEvent('clickRow', async (data) => {
  const clickedItem = data.activeRow;
  console.log('点击的商品：', clickedItem.value);
  
  // 跳转到详情页
  await app.navigate('pages.ProductDetail', {
    productId: clickedItem.value.id
  });
});

高级特性

响应式配置

轮播图支持移动端和PC端不同的渲染方式，通过e.json中的frontBundleEntry和frontMobileBundleEntry分别指定不同入口文件。

移动端适配配置

{
  "config": {
    "style": {
      "autoplaySpeed": 4000,
      "dotPosition": "bottom", 
      "effect": "fade"
    },
    "imageNum": 3
  }
}

组件生命周期管理

组件提供完整的生命周期管理，支持动态创建、配置更新和资源清理。

完整生命周期示例

// 创建并配置组件
const carousel = app.getElement('pages.MyPage.myCarousel');

// 更新配置
carousel.updateConfig({
  config: { imageNum: 10 }
});

// 使用完毕后清理资源
carousel.destroy();