QuickTV仓库
论坛

qt-media-series-pro 媒体分集组件

qt-media-series-pro 是一个用于展示媒体分集列表的专业级组件，支持多种样式切换、分页加载、自动分组以及焦点联动等功能。适用于影视剧、综艺等多集数节目的分集展示场景。

核心功能

  • 多种样式: 支持纯数字、纯文字、左图右文、上图下文以及自定义样式。
  • 自动分组: 当集数较多时，自动进行分页分组（如 1-10, 11-20），提升用户查找效率。
  • 分页加载: 支持大规模数据的分页按需加载，提供数据加载回调。
  • 焦点联动: 分集列表与分组列表之间的双向焦点联动，滚动分集时分组自动切换，点击分组时分集自动跳转。
  • 高度可定制: 支持自定义 Item 宽度、高度、分组大小等。

组件引入 

//在main.ts中全局引入QuickTVUI后即可直接使用
import { QuickTVUI } from '@quicktvui/quicktvui3'
app.use(QuickTVUI)

代码示例

1. 基础用法 (纯数字样式)

最简单的用法，只需指定总集数。 由于播放状态对应currentIndex，因此使用者需要自行维护currentIndex值，以实现播放状态的显示。

<template>
  <qt-media-series-pro
    :totalEpisodes="50"
    :currentIndex="currentIndex"
    @item-click="onItemClick"
  />
</template>

<script setup lang="ts">
const currentIndex=ref(0)
const onItemClick = (index: number) => {
  console.log('点击了第', index + 1, '集');
  currentIndex.value=index
};
</script>

2. 分页加载数据

当集数非常多或需要展示详细信息（标题、图片）时，建议使用分页加载。 按照类型规则传入参数SeriesItemLoad，包含title、subtitle、imageUrl,corner属性。

<template>
  <qt-media-series-pro
    :totalEpisodes="100"
    :seriesStyle="SeriesStyleType.IMAGE_LEFT_TEXT_RIGHT"
    :onLoadPageData="loadPageData"
    @item-click="onItemClick"
  />
</template>

<script setup lang="ts">
import { SeriesStyleType } from '@quicktvui/quicktvui3';
import type { SeriesItemLoad } from '@quicktvui/quicktvui3';

const loadPageData = async (pageIndex: number, pageSize: number): Promise<SeriesItemLoad[]> => {
  // 模拟接口请求
  return new Promise((resolve) => {
    setTimeout(() => {
      const data: SeriesItemLoad[] = [];
      for (let i = 0; i < pageSize; i++) {
        const globalIndex = pageIndex * pageSize + i;
        data.push({
          type: 1,
          title: `第${globalIndex + 1}集 精彩标题`,
          subtitle: '更新至2024-03-05',
          imageUrl: 'https://example.com/poster.jpg'
        });
      }
      resolve(data);
    }, 500);
  });
};
</script>

3. 自定义样式

如果内置样式无法满足需求，可以使用 custom 样式并通过插槽自定义内容。 isPlaying属性值内部维护，需要根据播放状态显示时，可以直接使用showIf="${isPlaying==true}"或者showIf="${isPlaying==false}"

<template>
  <qt-media-series-pro
    :totalEpisodes="12"
    :seriesStyle="SeriesStyleType.CUSTOM"
    :itemWidth="200"
    :itemHeight="300"
  >
    <template #custom>
      <qt-view type="1" :focusable="true" class="custom-item">
        <qt-text text="${title}" />
        <qt-text text="${subtitle}" />
        <play-mark
showIf="${isPlaying}" name="playMark" class="detail-series-item-mark"
                 markColor="#13161B" :gap="2" :focusable="false"/>
      </qt-view>
    </template>
  </qt-media-series-pro>
</template>

API 参考

Props

参数说明类型默认值
totalEpisodes总集数number0
currentIndex当前播放/选中的集数索引（从0开始）number0
groupSize分组大小（多少集一组）number3
showGroup是否显示分组列表booleantrue
seriesStyle分集样式类型 (见下文)SeriesStyleTypenumber_only
pageSize分页加载的大小number10
itemWidth分集 Item 的宽度 (CUSTOM 样式下生效)number160
itemHeight分集 Item 的高度 (CUSTOM 样式下生效)number240
onLoadPageData分页数据加载异步回调(pageIndex, pageSize) => Promise<SeriesItemLoad[]>-
seriesListName为了细化焦点范围，需要指定列表名称stringseriesListView
groupListName为了细化焦点范围，需要指定分组列表名称stringgroupListView
seriesListUpName为了细化焦点范围，需要指定列表向上名称stringseriesListUpView
groupListDownName为了细化焦点范围，需要指定分组列表向下名称stringgroupListDownView

SeriesStyleType 样式枚举

枚举值说明
number_only纯数字（如：1, 2, 3...）
text_only纯文字（展示 title 字段）
image_left_text_right左图右文
image_top_text_bottom上图下文
custom自定义样式（需配合插槽使用）

Events

事件名说明回调参数
item-click分集被点击时触发(index: number)
item-focused分集获得焦点时触发(index: number)
group-click分组被点击时触发(groupIndex, startIndex, endIndex)
group-focused分组获得焦点时触发(groupIndex, startIndex, endIndex)

Methods (通过 ref 调用)

此处的方法只有在qt-vue-section中使用才需要，因为目前qt-vue-section中的组件监听不到外部属性值的变化，只能通过方法调用更新。

方法名说明参数
updateTotalEpisodes动态更新总集数(totalEpisodes: number, index?: number)
updateCurrentIndex动态更新当前选中集数(index: number)
setSelectedIndex设置列表选中状态(index: number)

Source

Docs