Skip to content

README.md

Latest commit

 

History

History
672 lines (531 loc) · 16.4 KB

README.md

File metadata and controls

672 lines (531 loc) · 16.4 KB
Raw

QuickBox 组件库

开箱即用的快应用 ux 组件集合

📦 组件列表

布局组件

PageTitleBar - 页面标题栏

页面标题栏组件，支持固定和相对定位。

使用示例：

<import name="PageTitleBar" src="quickbox/components/PageTitleBar"></import>

<PageTitleBar
  title="我的页面"
  show-action="{{true}}"
  action-image="/assets/newImages/base/icon.png"
  position="fixed"
  top-offset="{{70}}"
  onaction-click="onActionClick"
/>

Props：

  • title (String): 标题文字
  • showAction (Boolean): 是否显示操作区域
  • actionImage (String): 操作图标URL
  • position (String): 位置样式，'fixed' | 'relative'
  • topOffset (Number): 顶部偏移量（px）

Events：

  • action-click: 操作区域点击事件

Slot：

  • action: 自定义操作区域

BackButton - 返回按钮

返回按钮组件，支持自定义图标和文字。

使用示例：

<import name="BackButton" src="quickbox/components/BackButton"></import>

<BackButton
  icon="/assets/newImages/base/back.png"
  text="返回"
  use-router="{{true}}"
  onback-click="onBackClick"
/>

Props：

  • icon (String): 返回图标URL
  • text (String): 返回文字
  • useRouter (Boolean): 是否使用路由返回

Events：

  • back-click: 返回按钮点击事件

Slot：

  • content: 自定义按钮内容

Card - 卡片组件

通用卡片组件，支持标题、内容、底部。

使用示例：

<import name="Card" src="quickbox/components/Card"></import>

<Card
  title="卡片标题"
  content="卡片内容"
  footer="底部文字"
  clickable="{{true}}"
  oncard-click="onCardClick"
>
  <div slot="content">
    <!-- 自定义内容 -->
  </div>
</Card>

Props：

  • title (String): 标题
  • content (String): 内容
  • footer (String): 底部文字
  • clickable (Boolean): 是否可点击

Events：

  • card-click: 卡片点击事件

Slot：

  • header: 自定义头部
  • content: 自定义内容
  • footer: 自定义底部

列表组件

List - 通用列表

通用列表组件，支持自定义列表项。

使用示例：

<import name="List" src="quickbox/components/List"></import>

<List
  title="列表标题"
  list="{{listData}}"
  loading="{{loading}}"
  has-more="{{hasMore}}"
  onload-more="onLoadMore"
  onitem-click="onItemClick"
>
  <div slot="item" item="{{$item}}" index="{{$idx}}">
    <!-- 自定义列表项 -->
  </div>
</List>

Props：

  • title (String): 列表标题
  • list (Array): 列表数据
  • loading (Boolean): 是否加载中
  • hasMore (Boolean): 是否还有更多
  • defaultImage (String): 默认图片
  • loadMoreMessage (String): 加载更多提示文字

Events：

  • load-more: 加载更多事件
  • item-click: 列表项点击事件

Slot：

  • item: 自定义列表项

GridList - 网格列表

网格列表组件，适用于视频、图片等内容展示。

使用示例：

<import name="GridList" src="quickbox/components/GridList"></import>

<GridList
  title="推荐内容"
  list="{{videoList}}"
  columns="{{2}}"
  loading="{{loading}}"
  has-more="{{hasMore}}"
  show-mask="{{true}}"
  onload-more="onLoadMore"
  onitem-click="onItemClick"
/>

Props：

  • title (String): 列表标题
  • list (Array): 列表数据
  • columns (Number): 列数，默认2
  • loading (Boolean): 是否加载中
  • hasMore (Boolean): 是否还有更多
  • showMask (Boolean): 是否显示图片遮罩
  • defaultImage (String): 默认图片

Events：

  • load-more: 加载更多事件
  • item-click: 列表项点击事件

Slot：

  • item: 自定义网格项

ListMore - 加载更多

加载更多组件，用于列表底部。

使用示例：

<import name="ListMore" src="quickbox/components/ListMore"></import>

<ListMore
  loading="{{loading}}"
  empty="{{!hasMore}}"
  message="加载更多"
  empty-message="没有更多了"
/>

Props：

  • loading (Boolean): 是否加载中
  • empty (Boolean): 是否为空（没有更多）
  • message (String): 加载中提示文字
  • emptyMessage (String): 空状态提示文字

功能组件

AddDesktop - 添加桌面引导

添加桌面引导组件，支持华为和其他厂商的不同实现。

使用示例：

<import name="AddDesktop" src="quickbox/components/AddDesktop"></import>

<AddDesktop
  is-show="{{showAddDesktop}}"
  image="{{desktopImage}}"
  button-text="添加本剧到桌面，方便下次观看"
  bottom="{{120}}"
  page-type="20"
  add-type="{{6}}"
  onadd-click="onAddClick"
  onadd-success="onAddSuccess"
  onadd-error="onAddError"
/>

Props：

  • isShow (Boolean): 是否显示
  • image (String): 引导图片URL
  • buttonText (String): 按钮文字
  • bottom (Number): 距离底部距离（px）
  • addType (Number): 添加类型
  • pageType (String): 页面类型

Events：

  • add-click: 添加点击事件
  • add-success: 添加成功事件
  • add-error: 添加失败事件

ShareButton - 分享按钮

分享按钮组件，封装了分享功能。

使用示例：

<import name="ShareButton" src="quickbox/components/ShareButton"></import>

<ShareButton
  title="分享标题"
  summary="分享摘要"
  image-path="/assets/newImages/base/coin.png"
  target-url="https://example.com"
  platforms="{{['WEIXIN', 'WEIBO']}}"
  icon="/assets/newImages/video/share.png"
  text="分享"
  onshare-success="onShareSuccess"
  onshare-error="onShareError"
/>

Props：

  • title (String): 分享标题
  • summary (String): 分享摘要
  • imagePath (String): 分享图片
  • targetUrl (String): 分享链接
  • platforms (Array): 分享平台数组
  • icon (String): 按钮图标
  • text (String): 按钮文字

Events：

  • share-success: 分享成功事件
  • share-error: 分享失败事件

Slot：

  • content: 自定义按钮内容

视频播放器组件

VideoPlayer - 视频播放器

完整的视频播放器组件，支持播放控制、进度显示、封面图等。

使用示例：

<import name="VideoPlayer" src="quickbox/components/VideoPlayer"></import>

<template>
  <VideoPlayer
    video-id="video_1"
    video-url="{{videoUrl}}"
    cover-image="{{coverImage}}"
    video-info="{{videoInfo}}"
    content-info="{{contentInfo}}"
    follow-status="{{followStatus}}"
    autoplay="{{true}}"
    initial-time="{{playedSeconds}}"
    onplay="onPlay"
    onpause="onPause"
    onfinish="onFinish"
    onerror="onError"
    onshow-section="onShowSection"
    onlike="onLike"
    onfollow="onFollow"
  />
</template>

Props：

  • videoId (String): 视频ID，用于多个视频实例区分
  • videoUrl (String): 视频URL，必填
  • coverImage (String): 封面图URL
  • videoInfo (Object): 视频信息对象
  • contentInfo (Object): 内容信息对象
  • followStatus (Boolean): 追剧状态
  • autoplay (Boolean): 是否自动播放
  • initialTime (Number): 初始播放位置（秒）

Events：

  • play: 播放事件
  • pause: 暂停事件
  • finish: 播放完成事件
  • error: 播放错误事件
  • timeupdate: 时间更新事件
  • prepared: 视频准备完成事件
  • show-section: 显示章节选择
  • like: 点赞事件
  • follow: 追剧事件

Methods：

  • play(): 播放视频
  • pause(): 暂停视频
  • setCurrentTime(time): 设置播放位置

VideoControl - 视频控制栏

视频播放控制栏组件，包含播放/暂停按钮、进度条、时间显示。

使用示例：

<import name="VideoControl" src="quickbox/components/VideoPlayer/VideoControl"></import>

<VideoControl
  is-play="{{isPlay}}"
  media-duration="{{duration}}"
  current-time="{{currentTime}}"
  onon-start="onStart"
  onon-pause="onPause"
/>

VideoInfo - 视频信息栏

视频信息栏组件，显示点赞、追剧、选集等操作按钮。

使用示例：

<import name="VideoInfo" src="quickbox/components/VideoPlayer/VideoInfo"></import>

<VideoInfo
  video-info="{{videoInfo}}"
  content-info="{{contentInfo}}"
  follow-status="{{followStatus}}"
  onon-like="onLike"
  onon-follow="onFollow"
  onon-show-section="onShowSection"
/>

SectionSelector - 章节选择器

章节选择组件，支持分组显示和章节选择。

使用示例：

<import name="SectionSelector" src="quickbox/components/SectionSelector"></import>

<SectionSelector
  is-show="{{showSectionSelector}}"
  content-name="{{contentName}}"
  current-section-id="{{currentSectionId}}"
  current-section-name="{{currentSectionName}}"
  section-list="{{sectionList}}"
  page-size="{{30}}"
  onclose="onCloseSection"
  onchange-section="onChangeSection"
/>

Props：

  • isShow (Boolean): 是否显示
  • contentName (String): 内容名称
  • currentSectionId (String): 当前章节ID
  • currentSectionName (String): 当前章节名称
  • sectionList (Array): 章节列表
  • pageSize (Number): 每页显示数量，默认30

Events：

  • close: 关闭事件
  • change-section: 章节变化事件

阅读器组件

Reader - 小说阅读器

完整的小说阅读器组件，支持上下阅读、左右翻页、字号调节、主题切换等。

使用示例：

<import name="Reader" src="quickbox/components/Reader"></import>

<template>
  <Reader
    content-id="{{contentId}}"
    current-chapter-id="{{chapterId}}"
    chapter-name="{{chapterName}}"
    content="{{content}}"
    prev-chapter-id="{{prevChapterId}}"
    next-chapter-id="{{nextChapterId}}"
    read-type="{{readType}}"
    config="{{readerConfig}}"
    onback="goBack"
    onselect-chapter="onSelectChapter"
    onprev-chapter="onPrevChapter"
    onnext-chapter="onNextChapter"
    onconfig-change="onConfigChange"
    onread-type-change="onReadTypeChange"
  />
</template>

<script>
export default {
  data: {
    readerConfig: {
      fontSize: 30,
      bgColor: '#ffffff',
      textColor: '#333333',
      menuBg: '#ffffff',
      menuText: '#333333',
      lineColor: '#e5e5e5',
      theme: 'default'
    }
  }
};
</script>

Props：

  • contentId (String): 内容ID，必填
  • currentChapterId (String): 当前章节ID，必填
  • chapterName (String): 章节名称
  • content (Array): 章节内容（段落数组）
  • prevChapterId (String): 上一章ID
  • nextChapterId (String): 下一章ID
  • readType (String): 阅读类型，'vertical'（上下）或 'horizontal'（左右翻页）
  • config (Object): 配置对象

Events：

  • back: 返回事件
  • select-chapter: 选择章节事件
  • prev-chapter: 上一章事件
  • next-chapter: 下一章事件
  • config-change: 配置变化事件
  • read-type-change: 阅读类型变化事件
  • menu-toggle: 菜单切换事件
  • page-change: 页面变化事件（左右翻页模式）

Methods：

  • toggleMenus(show): 切换菜单显示

ReaderControl - 阅读器控制栏

阅读器控制栏组件，包含字号调节、主题切换、翻页方式设置等。

ReaderCatalog - 阅读器目录

阅读器目录组件，显示章节列表并支持章节选择。

通用组件

Dialog - 通用弹窗

通用的弹窗组件，支持自定义标题、内容、按钮。

使用示例：

<import name="Dialog" src="quickbox/components/Dialog"></import>

<Dialog
  is-show="{{showDialog}}"
  title="提示"
  message="确定要删除吗？"
  buttons="{{[
    { text: '取消', color: '#999' },
    { text: '确定', color: '#007AFF', primary: true }
  ]}}"
  show-close="{{true}}"
  close-on-backdrop="{{true}}"
  onbutton-click="onDialogButtonClick"
  onclose="onDialogClose"
/>

Props：

  • isShow (Boolean): 是否显示
  • title (String): 标题
  • message (String): 消息内容
  • buttons (Array): 按钮配置数组
  • showClose (Boolean): 是否显示关闭按钮
  • closeOnBackdrop (Boolean): 点击背景是否关闭

Events：

  • button-click: 按钮点击事件
  • close: 关闭事件

Slot：

  • content: 自定义内容插槽

Loading - 加载组件

加载提示组件，支持全屏和局部加载。

使用示例：

<import name="Loading" src="quickbox/components/Loading"></import>

<!-- 局部加载 -->
<Loading message="加载中..." />

<!-- 全屏加载 -->
<Loading className="fullscreen" message="加载中..." />

<!-- 黑色背景加载 -->
<Loading className="black" message="加载中..." />

Props：

  • className (String): 自定义类名（'fullscreen' | 'black'）
  • showSpinner (Boolean): 是否显示加载动画
  • message (String): 提示文字

Empty - 空状态组件

空状态组件，用于数据为空时的展示。

使用示例：

<import name="Empty" src="quickbox/components/Empty"></import>

<Empty
  message="暂无内容"
  show-image="{{true}}"
  show-button="{{true}}"
  button-text="去查看"
  onbutton-click="onEmptyButtonClick"
/>

Props：

  • showImage (Boolean): 是否显示图片
  • imageUrl (String): 图片URL
  • message (String): 提示文字
  • showButton (Boolean): 是否显示按钮
  • buttonText (String): 按钮文字

Events：

  • button-click: 按钮点击事件

Slot：

  • action: 自定义操作区域插槽

PayConfirm - 支付确认弹窗

支付确认弹窗组件，用于支付过程中的状态确认。

使用示例：

<import name="PayConfirm" src="quickbox/components/PayConfirm"></import>

<PayConfirm
  is-show="{{showPayConfirm}}"
  order-id="{{orderId}}"
  auto-close-time="{{10}}"
  oncontinue-pay="onContinuePay"
  onpay-done="onPayDone"
  onpay-success="onPaySuccess"
  onclose="onClosePayConfirm"
/>

Props：

  • isShow (Boolean): 是否显示
  • orderId (String): 订单ID
  • autoCloseTime (Number): 自动关闭时间（秒），0表示不自动关闭

Events：

  • continue-pay: 继续支付事件
  • pay-done: 支付完成事件
  • pay-success: 支付成功事件
  • close: 关闭事件

🎨 主题配置

阅读器主题

阅读器支持以下主题：

  • default: 白色背景，黑色文字
  • yellow: 米黄色背景
  • green: 绿色背景
  • blue: 蓝色背景
  • black: 黑色背景，白色文字

自定义样式

所有组件都支持通过 class 和 style 属性自定义样式。

📝 使用注意事项

  1. 组件路径：使用相对路径引入组件
  2. 事件命名：所有事件使用 on 前缀（如 onplay、onclose）
  3. Props验证：组件会验证必填的props
  4. 样式隔离：组件样式使用 scoped，不会影响外部样式
  5. 依赖QuickBox：部分组件依赖 QuickBox API，确保已正确引入
  6. Slot插槽：组件支持使用 slot 自定义内容
  7. 样式自定义：所有组件支持通过 class 和 style 属性自定义样式

🎯 组件分类

布局组件

用于页面布局和导航的组件：

  • PageTitleBar: 页面标题栏，支持固定和相对定位
  • BackButton: 返回按钮，自动处理路由返回
  • Card: 卡片容器，支持标题、内容、底部插槽

列表组件

用于数据展示的列表组件：

  • List: 通用列表，支持自定义列表项
  • GridList: 网格列表，适用于视频、图片等内容展示
  • ListMore: 加载更多组件，用于列表底部

视频播放器组件

完整的视频播放解决方案：

  • VideoPlayer: 主播放器组件，包含播放控制、进度显示
  • VideoControl: 控制栏组件，播放/暂停、进度条
  • VideoInfo: 信息栏组件，点赞、追剧、选集等操作
  • SectionSelector: 章节选择器，支持分组显示

阅读器组件

完整的小说阅读解决方案：

  • Reader: 主阅读器组件，支持上下阅读、左右翻页
  • ReaderControl: 控制栏组件，字号、主题、翻页方式设置
  • ReaderCatalog: 目录组件，章节列表和选择

通用组件

通用的UI组件：

  • Dialog: 弹窗组件，支持自定义标题、内容、按钮
  • Loading: 加载组件，支持全屏、局部、黑色背景
  • Empty: 空状态组件，可自定义图片、文字、按钮
  • PayConfirm: 支付确认弹窗，支持自动关闭

功能组件

特定功能的组件：

  • AddDesktop: 添加桌面引导，自动适配华为和其他厂商
  • ShareButton: 分享按钮，封装分享功能

🔧 扩展组件

如果需要扩展组件功能，可以：

  1. 继承现有组件
  2. 使用 slot 插槽自定义内容
  3. 通过 props 传递配置
  4. 监听组件事件进行自定义处理

📚 完整示例

查看 使用示例文档 获取详细的代码示例和组合使用场景。