android-frame/frame/commonui/CLAUDE.md

CommonUI 模块

模块概述

CommonUI 模块是公共UI组件库，提供了项目中常用的自定义视图组件、通用布局、动画效果等UI相关功能。该模块旨在统一UI风格，提高开发效率，确保用户体验的一致性。

主要功能

1. 自定义视图组件

• 通用按钮: 支持各种状态和样式的按钮组件
• 输入框: 增强功能的编辑框组件
• 进度指示器: 加载进度和状态指示组件
• 标签组件: 文本标签和徽章组件

2. 布局组件

• 卡片布局: 统一的卡片样式容器
• 列表项布局: 标准化的列表项组件
• 头部组件: 页面标题栏和导航栏
• 底部组件: 底部导航和操作栏

3. 交互组件

• 对话框: 通用对话框和弹窗组件
• 下拉刷新: 标准化的下拉刷新组件
• 侧滑菜单: 侧边栏和抽屉式导航
• 轮播图: 图片轮播和页面指示器

4. 动画效果

• 转场动画: 页面切换动画效果
• 加载动画: 各种加载状态的动画
• 交互反馈: 点击波纹等交互动画
• 自定义动画: 可配置的动画工具类

核心组件

通用按钮

class CommonButton : Button {
    enum class ButtonStyle {
        PRIMARY,    // 主要按钮
        SECONDARY,  // 次要按钮
        OUTLINE,    // 边框按钮
        TEXT        // 文本按钮
    }
    
    fun setButtonStyle(style: ButtonStyle)
    fun setLoading(loading: Boolean)
    fun setEnabled(enabled: Boolean)
}

输入框组件

class CommonEditText : EditText {
    fun setHint(hint: String)
    fun setError(error: String?)
    fun setMaxLength(maxLength: Int)
    fun addTextChangedListener(listener: TextWatcher)
}

对话框组件

class CommonDialog {
    fun setTitle(title: String): CommonDialog
    fun setMessage(message: String): CommonDialog
    fun setPositiveButton(text: String, listener: OnClickListener): CommonDialog
    fun setNegativeButton(text: String, listener: OnClickListener): CommonDialog
    fun show()
    fun dismiss()
}

使用方式

1. XML 中使用

<!-- 通用按钮 -->
<com.adealink.frame.commonui.CommonButton
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:text="确定"
    app:button_style="primary"
    app:loading="false" />

<!-- 输入框 -->
<com.adealink.frame.commonui.CommonEditText
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:hint="请输入内容"
    app:max_length="100" />

<!-- 卡片布局 -->
<com.adealink.frame.commonui.CardLayout
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:card_corner_radius="8dp"
    app:card_elevation="4dp">
    
    <!-- 内容 -->
    
</com.adealink.frame.commonui.CardLayout>

2. 代码中使用

// 创建对话框
CommonDialog.Builder(context)
    .setTitle("提示")
    .setMessage("确定要删除吗？")
    .setPositiveButton("确定") { dialog, _ ->
        // 确定操作
        dialog.dismiss()
    }
    .setNegativeButton("取消") { dialog, _ ->
        dialog.dismiss()
    }
    .show()

// 设置按钮状态
button.setButtonStyle(CommonButton.ButtonStyle.PRIMARY)
button.setLoading(true)

// 输入框验证
editText.addTextChangedListener(object : TextWatcher {
    override fun afterTextChanged(s: Editable?) {
        val text = s?.toString() ?: ""
        if (text.length > 50) {
            editText.setError("输入内容过长")
        } else {
            editText.setError(null)
        }
    }
})

3. 主题和样式配置

<!-- styles.xml -->
<style name="CommonButtonPrimary">
    <item name="android:background">@drawable/button_primary_bg</item>
    <item name="android:textColor">@color/white</item>
    <item name="android:textSize">16sp</item>
    <item name="android:padding">12dp</item>
</style>

<style name="CommonCard">
    <item name="cardCornerRadius">8dp</item>
    <item name="cardElevation">4dp</item>
    <item name="cardBackgroundColor">@color/white</item>
</style>

属性配置

自定义属性

<!-- attrs.xml -->
<declare-styleable name="CommonButton">
    <attr name="button_style" format="enum">
        <enum name="primary" value="0" />
        <enum name="secondary" value="1" />
        <enum name="outline" value="2" />
        <enum name="text" value="3" />
    </attr>
    <attr name="loading" format="boolean" />
    <attr name="corner_radius" format="dimension" />
</declare-styleable>

<declare-styleable name="CommonEditText">
    <attr name="max_length" format="integer" />
    <attr name="error_text" format="string" />
    <attr name="required" format="boolean" />
</declare-styleable>

动画和效果

1. 过渡动画

// 页面切换动画
AnimationUtils.slideInFromRight(context, view)
AnimationUtils.slideOutToLeft(context, view)
AnimationUtils.fadeIn(context, view, duration)
AnimationUtils.fadeOut(context, view, duration)

2. 加载动画

// 显示加载动画
LoadingView.show(context, "加载中...")
LoadingView.dismiss()

// 刷新动画
refreshLayout.setRefreshing(true)
refreshLayout.setOnRefreshListener {
    // 刷新逻辑
    refreshLayout.setRefreshing(false)
}

依赖关系

编译时依赖

• androidx.appcompat - AppCompat 支持
• androidx.core.ktx - Android 核心扩展
• androidx.constraintlayout - 约束布局
• com.google.android.material - Material Design 组件

内部依赖

• frame:base - 基础框架模块
• frame:util - 工具类模块

构建配置

implementation "com.wenext.android:frame-commonui:6.0.0"

注意事项

1. 主题配置: 确保应用主题继承自 Material 或 AppCompat 主题
2. 资源命名: 遵循统一的资源命名规范，避免冲突
3. 性能考虑: 复杂动画注意性能影响，适当优化
4. 兼容性: 确保组件在不同 Android 版本上的兼容性
5. 无障碍: 添加适当的内容描述，支持无障碍访问
6. 国际化: 支持多语言文本和 RTL 布局
7. 自定义: 提供足够的自定义接口，满足不同需求
8. 文档: 为每个组件提供详细的使用文档和示例