Titanium SDK 中的 Android 进度指示器(ProgressIndicator)详解
项目地址: https://gitcode.com/gh_mirrors/ti/titanium-sdk 概述
在移动应用开发中，进度指示器（ProgressIndicator）是提升用户体验的重要组件。Titanium SDK 为 Android 平台提供了强大的 Ti.UI.Android.ProgressIndicator 组件，支持多种显示模式和自定义配置。本文将深入解析其实现原理、使用方法和最佳实践。
核心特性
显示位置支持
- 状态栏进度指示器（STATUS_BAR）：在应用标题栏显示进度
- 对话框进度指示器（DIALOG）：以模态对话框形式显示
进度类型
- 不确定进度（INDETERMINANT）：循环动画，用于未知耗时操作
- 确定进度（DETERMINANT）：线性进度条，显示具体完成百分比
架构设计
类关系图
属性配置表
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
message | String | "" | 进度指示器显示的消息文本 |
value | Number | 0 | 当前进度值（仅对确定类型有效） |
location | Number | DIALOG | 显示位置：STATUS_BAR 或 DIALOG |
type | Number | INDETERMINANT | 进度类型：INDETERMINANT 或 DETERMINANT |
min | Number | 0 | 进度最小值 |
max | Number | 100 | 进度最大值 |
cancelable | Boolean | false | 是否可通过返回键取消 |
canceledOnTouchOutside | Boolean | false | 是否可通过点击外部取消 |
使用示例
基本用法
// 创建不确定进度对话框
var indicator = Ti.UI.Android.createProgressIndicator({
message: '正在加载中...',
location: Ti.UI.Android.PROGRESS_INDICATOR_DIALOG,
type: Ti.UI.Android.PROGRESS_INDICATOR_INDETERMINANT,
cancelable: false
});
// 显示进度指示器
indicator.show();
// 执行耗时操作
setTimeout(function() {
// 隐藏进度指示器
indicator.hide();
}, 3000);
确定进度示例
// 创建确定进度指示器
var progressIndicator = Ti.UI.Android.createProgressIndicator({
message: '下载进度',
location: Ti.UI.Android.PROGRESS_INDICATOR_DIALOG,
type: Ti.UI.Android.PROGRESS_INDICATOR_DETERMINANT,
min: 0,
max: 100,
value: 0,
cancelable: true
});
// 显示进度
progressIndicator.show();
// 模拟进度更新
var currentProgress = 0;
var interval = setInterval(function() {
currentProgress += 10;
if (currentProgress > 100) {
clearInterval(interval);
progressIndicator.hide();
} else {
progressIndicator.value = currentProgress;
}
}, 500);
状态栏进度指示器
// 在状态栏显示进度
var statusBarIndicator = Ti.UI.Android.createProgressIndicator({
message: '处理中...',
location: Ti.UI.Android.PROGRESS_INDICATOR_STATUS_BAR,
type: Ti.UI.Android.PROGRESS_INDICATOR_DETERMINANT,
value: 50
});
statusBarIndicator.show();
实现原理深度解析
1. 视图创建机制
ProgressIndicatorProxy 继承自 TiDialogProxy，通过 createView() 方法创建 TiUIProgressIndicator 实例：
@Override
public TiUIView createView(Activity activity) {
return new TiUIProgressIndicator(this);
}
2. 状态栏进度实现
状态栏进度使用 Android 原生的 Activity.setProgressBar* 方法：
if (location == STATUS_BAR) {
incrementFactor = 10000 / (max - min);
if (type == INDETERMINANT) {
parent.setProgressBarIndeterminate(true);
parent.setProgressBarIndeterminateVisibility(true);
} else if (type == DETERMINANT) {
parent.setProgressBarIndeterminate(false);
parent.setProgressBarIndeterminateVisibility(false);
parent.setProgressBarVisibility(true);
parent.setProgress((progressValue - this.min) * this.incrementFactor);
}
}
3. 对话框进度实现
对话框进度使用 ProgressDialog 组件，支持丰富的自定义选项：
progressDialog = new ProgressDialog(a);
progressDialog.setMessage(message);
progressDialog.setCanceledOnTouchOutside(
proxy.getProperties().optBoolean(TiC.PROPERTY_CANCELED_ON_TOUCH_OUTSIDE, false));
progressDialog.setCancelable(proxy.getProperties().optBoolean(TiC.PROPERTY_CANCELABLE, false));
事件处理
取消事件监听
@Override
public void onCancel(DialogInterface dialog) {
if (dialog != this.progressDialog) {
return;
}
this.visible = false;
this.progressDialog = null;
fireEvent(TiC.EVENT_CANCEL, null);
}
属性变更响应
进度指示器实时响应属性变化：
public void propertyChanged(String key, Object oldValue, Object newValue, KrollProxy proxy) {
if (key.equals(TiC.PROPERTY_MESSAGE)) {
// 更新消息文本
} else if (key.equals(TiC.PROPERTY_VALUE)) {
// 更新进度值
}
}
最佳实践
1. 内存管理
// 正确使用方式：重用实例
var indicator = null;
function showProgress(message) {
if (!indicator) {
indicator = Ti.UI.Android.createProgressIndicator({
location: Ti.UI.Android.PROGRESS_INDICATOR_DIALOG,
type: Ti.UI.Android.PROGRESS_INDICATOR_INDETERMINANT
});
}
indicator.message = message;
indicator.show();
}
function hideProgress() {
if (indicator) {
indicator.hide();
}
}
2. 错误处理
function safeShowProgress(indicator) {
try {
indicator.show();
} catch (e) {
Ti.API.error('显示进度指示器失败: ' + e.message);
// 备用方案
showToast('操作进行中...');
}
}
3. 性能优化
// 避免频繁创建销毁
var progressPool = {};
function getProgressIndicator(type) {
if (!progressPool[type]) {
progressPool[type] = Ti.UI.Android.createProgressIndicator({
type: type,
location: Ti.UI.Android.PROGRESS_INDICATOR_DIALOG
});
}
return progressPool[type];
}
兼容性考虑
Android 版本适配
// Android 5.x 及以下版本的颜色处理
if ((Build.VERSION.SDK_INT < 23) && progressDialog.isIndeterminate()) {
var view = progressDialog.findViewById(android.R.id.progress);
if (view instanceof ProgressBar) {
int colorValue = MaterialColors.getColor(
progressDialog.getContext(), android.R.attr.indeterminateTint, Color.TRANSPARENT);
var drawable = ((ProgressBar) view).getIndeterminateDrawable();
if ((colorValue != Color.TRANSPARENT) && (drawable != null)) {
drawable.setColorFilter(new PorterDuffColorFilter(colorValue, PorterDuff.Mode.SRC_IN));
}
}
}
常见问题解决方案
1. 对话框不显示
检查当前是否有可用的 Activity：
if (Ti.Android.currentActivity) {
indicator.show();
} else {
Ti.API.warn('没有可用的Activity显示进度指示器');
}
2. 进度更新延迟
使用主线程更新进度：
function updateProgress(value) {
Ti.UI.mainThread(function() {
indicator.value = value;
});
}
3. 内存泄漏预防
及时释放资源：
function cleanup() {
if (indicator) {
indicator.hide();
indicator = null;
}
}
// 在页面关闭时清理
window.addEventListener('close', cleanup);
总结
Titanium SDK 的 Android 进度指示器提供了强大而灵活的功能，支持多种显示模式和丰富的自定义选项。通过理解其底层实现原理和掌握最佳实践，开发者可以创建出既美观又高效的用户体验。
关键要点：
- 合理选择进度类型和显示位置
- 注意内存管理和资源释放
- 处理兼容性问题和错误情况
- 重用实例提升性能
通过本文的详细解析，相信您已经对 Titanium SDK 中的 Android 进度指示器有了全面的理解，能够在实际项目中灵活运用这一重要组件。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
