一、前言
在 HarmonyOS 应用开发中,系统自带的 TextPicker、Select 等选择器组件样式固定,难以满足品牌化 UI 需求。本文分享一个基于 ArkTS 实现的底部滚轮弹窗选择器 CommonBottomSheet,支持连续滚动偏移动画、吸附居中、多屏适配、防重复弹出等特性,已在实际售后工单项目中投入使用。
二、效果预览
底部弹出 → 滚轮滑动 → 松手吸附居中 → 选中项放大加粗品牌色 → 点击确定回调
核心视觉特征:
- 选中项:字体最大 + 加粗 + 品牌色 #00428E
- 远离中心:逐级缩小、变淡、变灰
- 顶部/底部白色渐变遮罩,营造滚轮立体感

三、整体架构
CommonBottomSheet.ets
├── CommonBottomSheetItem // 列表项数据接口
├── CommonBottomSheetParam // 弹窗参数接口
├── CommonBottomSheetParamWithContext // 含 UIContext 的完整参数
├── WheelPickerComponent // 滚轮选择器主体 @Component
├── buildCommonBottomSheetComponent // @Builder 构建函数
├── commonBottomSheetBuilder // 模块级 WrappedBuilder 常量
└── CommonBottomSheet // 静态类:show / close
四、核心实现
4.1 数据模型
export interface CommonBottomSheetItem {
id: number
text: string
subText?: string // 副文本(可选)
emeType?: number
faultTypeCode?: string
}
export interface CommonBottomSheetParam {
title: string
items: CommonBottomSheetItem[]
selectedId?: number // 默认选中项 id
confirmText?: string // 确定按钮文案
onItemSelected?: (item: CommonBottomSheetItem) => void
onConfirm?: () => void
onCancel?: () => void
}
4.2 滚轮动画核心 —— 连续偏移距离
整个滚轮的动画效果(缩放、字号、颜色、透明度)都基于一个核心函数:计算每项到可视区域中心的连续距离。
private getItemContinuousDistance(index: number): number {
const visibleHeight = this.itemHeight * VISIBLE_COUNT // 可视区域总高
const centerY = this.scrollOffset + visibleHeight / 2 - this.itemHeight / 2
const itemY = (index + CENTER_INDEX) * this.itemHeight
return Math.abs(itemY - centerY) / this.itemHeight // 归一化距离(0=正中间)
}
scrollOffset 在 onDidScroll 中实时更新,使得距离值连续变化,从而驱动所有视觉属性平滑过渡,而非离散跳变。
4.3 四维视觉映射
基于连续距离 dist,分别映射四个视觉维度:
| 维度 | 函数 | 中心值(dist=0) | 边缘值(dist≥2) |
| 缩放 | getItemScale | 1.0 | 0.6 |
| 字号 | getItemFontSize | 18fp | 14fp |
| 颜色 | getItemFontColor | #00428E | #CCCCCC |
| 透明度 | getItemOpacity | 1.0 | 0.3 |
// 缩放:选中项1.0,远离中心逐渐缩小至0.6
getItemScale(index: number): number {
const dist = this.getItemContinuousDistance(index)
return Math.max(0.6, 1.0 - dist * 0.15)
}
// 字体颜色:分档渐变
getItemFontColor(index: number): string {
const dist = this.getItemContinuousDistance(index)
if (dist < 0.5) return '#00428E' // 品牌色
if (dist < 1.0) return '#555555'
if (dist < 1.5) return '#777777'
if (dist < 2.0) return '#999999'
return '#CCCCCC'
}
4.4 吸附居中
onScrollStop 时将滚动位置吸附到最近的整数项:
.onScrollStop(() => {
const offset = this.scrollController.currentOffset().yOffset
const idx = Math.round(offset / this.itemHeight)
const clampedIdx = Math.max(0, Math.min(this.items.length - 1, idx))
this.currentIndex = clampedIdx
// 偏差>1px时补位动画
if (Math.abs(offset - clampedIdx * this.itemHeight) > 1) {
this.scrollController.scrollTo({
yOffset: clampedIdx * this.itemHeight,
animation: { duration: 200, curve: Curve.EaseOut }
})
}
})
4.5 上下留白 + 渐变遮罩
为了让首尾项也能滚到中心,在 List 头尾各插入 CENTER_INDEX(2) 个空白项:
// 上方留白
ForEach(new Array<number>(CENTER_INDEX).fill(0), ...)
// 实际数据项
ForEach(this.items, ...)
// 下方留白
ForEach(new Array<number>(CENTER_INDEX).fill(0), ...)
遮罩使用 linearGradient + hitTestBehavior(HitTestMode.Transparent),不拦截触摸事件:
Column()
.linearGradient({
direction: GradientDirection.Bottom,
colors: [['#40FFFFFF', 0.0], ['#00FFFFFF', 1.0]]
})
.hitTestBehavior(HitTestMode.Transparent)
4.6 弹窗管理 —— ComponentContent + PromptAction
使用 ComponentContent 包装 WrappedBuilder,通过 PromptAction.openCustomDialog 以底部对齐方式弹出:
static async show(context: UIContext, param: CommonBottomSheetParam) {
if (CommonBottomSheet.getShowing()) return // 防重复
CommonBottomSheet.setShowing(true)
const dialogParam: CommonBottomSheetParamWithContext = { ...param, context }
CommonBottomSheet.contentNode = new ComponentContent(
context, commonBottomSheetBuilder, dialogParam
)
context.getPromptAction().openCustomDialog(CommonBottomSheet.contentNode, {
alignment: DialogAlignment.Bottom,
maskColor: '#8000428E',
onWillDismiss: (dialog) => {
dialog.dismiss()
CommonBottomSheet.contentNode?.dispose()
CommonBottomSheet.contentNode = null
CommonBottomSheet.setShowing(false)
}
})
}
关键设计点:
- 模块级 WrappedBuilder 常量:避免每次 show() 都 wrapBuilder,减少开销
- isShowing 静态标志:防止快速多次调用导致弹窗叠加
- lastSelectedId 记忆:再次打开时自动定位上次选择
- 全屏布局 + 状态栏品牌色:setWindowLayoutFullScreen(true) + setWindowSystemBarProperties
4.7 多屏适配
所有尺寸值通过 CommonBreakpoint 根据当前断点(sm/md/lg)动态返回:
aboutToAppear(): void {
this.itemHeight = CommonBreakpoint.public_height_50 // 手机50vp / 平板更大
}
字号、间距、圆角同理,一套代码适配手机/平板/折叠屏。
五、使用方式
import { CommonBottomSheet, CommonBottomSheetItem } from '@common/CommonBottomSheet'
// 构建数据
const items: CommonBottomSheetItem[] = [
{ id: 1, text: '张三', subText: '13800138000' },
{ id: 2, text: '李四', subText: '13900139000' },
{ id: 3, text: '王五', subText: '13700137000' },
]
// 弹出选择
CommonBottomSheet.show(this.uiContext!, {
title: '选择客户',
items: items,
selectedId: this.selectedId,
onItemSelected: (item) => {
this.selectedId = item.id
this.selectedName = item.text
},
onConfirm: () => {
console.log('确认选择')
}
})
六、设计亮点总结
| 特性 | 实现方式 |
| 连续平滑动画 | onDidScroll 实时更新 scrollOffset,驱动四维视觉映射 |
| 吸附居中 | onScrollStop + scrollTo 补位动画 |
| 防重复弹出 | isShowing 静态标志位 |
| Builder 复用 | 模块级 WrappedBuilder 常量 |
| 多屏适配 | CommonBreakpoint 断点值动态解析 |
| 选择记忆 | lastSelectedId 跨次保持 |
| 立体滚轮感 | 上下白色渐变遮罩 + 缩放/透明度渐变 |
| 副文本支持 | subText 可选字段,独立字号渐变 |
七、结语
CommonBottomSheet 的核心思路是用连续滚动偏移量驱动所有视觉属性,而非传统的离散索引切换。这使得滚动过程中的缩放、变色、淡入淡出完全连续,体验接近原生 iOS Picker 的丝滑感。配合 ComponentContent + PromptAction 的命令式弹窗管理,实现了与页面解耦的通用选择器组件。
源代码地址:华为开发者文章HarmonyOS 自定义底部滚轮选择器 CommonBottomSheet 实现详解华为开发者文章
作者:J.query
邮箱:j-query@foxmail.com
日期:2026/09/04
372



被折叠的 条评论
为什么被折叠?



