BatteryView

一个功能丰富的 Android 自定义电池视图控件，支持水平和垂直两种方向，提供完整的电池状态展示和自定义功能。

✨ 特性

基础功能

🔋 支持水平/垂直两种方向
📊 实时显示电池电量百分比
🎨 根据电量自动变色（红/黄/绿）
⚡ 充电动画效果
🔄 充电循环动画（0-100%）

高级功能

🎨 渐变填充：支持横向/纵向渐变，自定义起始色和结束色
💫 低电量闪烁：电量低于阈值时闪烁提醒
📳 低电量震动：电量低于阈值时震动提醒
🎯 电量平滑过渡：电量变化时平滑动画

外观自定义

🎭 电池身设置
- 边框颜色
- 圆角半径（0-32dp，独立控制）
- 边框宽度（0-12dp）
🔋 电池头设置
- 电池头颜色（独立于边框颜色）
- 电池头圆角半径（0-32dp，独立控制）
- 电池头比例（0.2-0.8）
- 电池头紧贴设计：贴近电池身的边为直角，远离的边使用圆角，实现无缝贴合

文本自定义

📝 百分比文字大小
🎨 百分比文字颜色
📍 百分比文字位置（居中/顶部/底部/左侧/右侧）

🎯 设计亮点

1. 电池头紧贴设计

电池头与电池身无缝贴合，贴近电池身的边为直角，远离的边使用圆角

2. 独立圆角控制

电池身和电池头可以设置不同的圆角半径
支持更丰富的视觉效果组合
向后兼容旧的 batteryCornerRadius 属性

3. 充电循环动画

0→100% 单向循环（3秒周期）
平滑的电量过渡动画
可独立控制是否启用

4. 低电量智能提醒

闪烁提醒：电量低于阈值时自动闪烁
震动提醒：电量低于阈值时震动（需权限）
可自定义低电量阈值

📱 演示应用

应用提供了完整的演示界面，包含：

实时电量调节
6个功能设置弹窗（电量、基础、文本、渐变、尺寸、外观）
实时预览效果
一键重置功能
水平和垂直电池同步显示

🖼 截图预览

🚀 快速开始

1. 在布局文件中使用

<com.donkor.demo.BatteryView
    android:id="@+id/batteryView"
    android:layout_width="60dp"
    android:layout_height="120dp"
    app:batteryOrientation="vertical"
    app:batteryPower="75"
    app:batteryShowPercent="true"
    app:batteryPercentPosition="center"
    app:batteryCharging="false"
    app:batteryBodyCornerRadius="8dp"
    app:batteryHeadCornerRadius="8dp"
    app:batteryBorderWidth="2dp"
    app:batteryBorderColor="#000000"
    app:batteryHeadColor="#000000"
    app:batteryHeadScale="0.5"
    app:batteryGradientEnabled="true"
    app:batteryGradientVertical="true"
    app:batteryAnimatePower="true"
    app:batteryLowBlink="true"
    app:batteryVibrateOnLow="true"/>

2. 在代码中使用

val batteryView = findViewById<BatteryView>(R.id.batteryView)

// 基础设置
batteryView.setPower(75)                    // 设置电量
batteryView.setCharging(true)               // 设置充电状态
batteryView.setChargingCycle(true)          // 设置充电循环动画

// 外观设置 - 电池身
batteryView.setBodyCornerRadius(16f)        // 设置电池身圆角（像素）
batteryView.setBorderWidth(4f)              // 设置边框宽度（像素）
batteryView.setBorderColor(Color.BLACK)     // 设置边框颜色

// 外观设置 - 电池头
batteryView.setHeadCornerRadius(8f)         // 设置电池头圆角（像素）
batteryView.setHeadColor(Color.RED)         // 设置电池头颜色
batteryView.setHeadScale(0.6f)              // 设置电池头比例

// 渐变设置
batteryView.setGradientEnabled(true)        // 启用渐变
batteryView.setGradientVertical(true)       // 设置垂直渐变
batteryView.setGradientColors(Color.GREEN, Color.YELLOW) // 设置渐变颜色

// 文本设置
batteryView.setShowPercent(true)            // 显示百分比
batteryView.setPercentSize(14f * density)   // 设置文字大小（像素）
batteryView.setPercentColor(Color.WHITE)    // 设置文字颜色
batteryView.setPercentPosition(0)           // 设置文字位置（0=居中）

// 低电量提醒
batteryView.setLowBlink(true)               // 启用低电量闪烁
batteryView.setVibrateOnLow(true)           // 启用低电量震动

// 动画设置
batteryView.setAnimatePower(true)           // 启用电量平滑过渡

📐 XML 属性

基础属性

属性	类型	说明	默认值
`batteryOrientation`	enum	电池方向（horizontal/vertical）	horizontal
`batteryPower`	integer	电池电量（0-100）	100
`batteryColor`	color	基础颜色	-
`batteryCharging`	boolean	是否充电	false

百分比文本属性

属性	类型	说明	默认值
`batteryShowPercent`	boolean	是否显示百分比	false
`batteryPercentColor`	color	百分比文字颜色	BLACK
`batteryPercentSize`	dimension	百分比文字大小	12sp
`batteryPercentPosition`	enum	百分比位置（center/top/bottom/start/end）	center

外观属性 - 电池身

属性	类型	说明	默认值
`batteryCornerRadius`	dimension	圆角半径（同时设置电池身和电池头）	3dp
`batteryBodyCornerRadius`	dimension	电池身圆角半径	3dp
`batteryBorderWidth`	dimension	边框宽度	2dp
`batteryBorderColor`	color	边框颜色	BLACK

外观属性 - 电池头

属性	类型	说明	默认值
`batteryHeadCornerRadius`	dimension	电池头圆角半径	3dp
`batteryHeadScale`	float	电池头比例（0.2-0.8）	0.5
`batteryHeadColor`	color	电池头颜色	BLACK

渐变属性

属性	类型	说明	默认值
`batteryGradientEnabled`	boolean	是否启用渐变	false
`batteryGradientStartColor`	color	渐变起始颜色	GREEN
`batteryGradientEndColor`	color	渐变结束颜色	YELLOW
`batteryGradientVertical`	boolean	是否垂直渐变	false

低电量提醒属性

属性	类型	说明	默认值
`batteryLowThreshold`	integer	低电量阈值（0-100）	20
`batteryLowBlink`	boolean	低电量闪烁	false
`batteryVibrateOnLow`	boolean	低电量震动	false

动画属性

属性	类型	说明	默认值
`batteryAnimatePower`	boolean	电量平滑过渡	false

🎨 API 方法

电量控制

setPower(power: Int)                   // 设置电量（0-100）
getPower(): Int                        // 获取当前电量
setAnimatePower(enable: Boolean)       // 设置电量平滑过渡动画

充电控制

setCharging(charging: Boolean)         // 设置充电状态
setChargingCycle(enable: Boolean)      // 设置充电循环动画（0-100%循环）

外观控制 - 电池身

setBodyCornerRadius(radiusPx: Float)   // 设置电池身圆角（像素）
setCornerRadius(radiusPx: Float)       // 同时设置电池身和电池头圆角（像素）
setBorderWidth(widthPx: Float)         // 设置边框宽度（像素）
setBorderColor(color: Int)             // 设置边框颜色

外观控制 - 电池头

setHeadCornerRadius(radiusPx: Float)   // 设置电池头圆角（像素）
setHeadColor(color: Int)               // 设置电池头颜色
setHeadScale(scale: Float)             // 设置电池头比例（0.2-0.8）

渐变控制

setGradientEnabled(enabled: Boolean)   // 启用/禁用渐变填充
setGradientVertical(vertical: Boolean) // 设置渐变方向（true=垂直，false=横向）
setGradientColors(start: Int, end: Int) // 设置渐变起始色和结束色

文本控制

setShowPercent(show: Boolean)          // 显示/隐藏百分比文字
setPercentSize(sizePx: Float)          // 设置文字大小（像素）
setPercentColor(color: Int)            // 设置文字颜色
setPercentPosition(position: Int)      // 设置文字位置（0=居中，1=顶部，2=底部，3=左侧，4=右侧）

低电量提醒

setLowBlink(enabled: Boolean)          // 启用/禁用低电量闪烁
setVibrateOnLow(enabled: Boolean)      // 启用/禁用低电量震动
setLowThreshold(threshold: Int)        // 设置低电量阈值（0-100）

💡 使用示例

示例1：简单的电池显示

<com.donkor.demo.BatteryView
    android:id="@+id/batteryView"
    android:layout_width="60dp"
    android:layout_height="30dp"
    app:batteryOrientation="horizontal"
    app:batteryPower="75"
    app:batteryShowPercent="true"/>

示例2：带渐变效果的充电电池

<com.donkor.demo.BatteryView
    android:id="@+id/batteryView"
    android:layout_width="60dp"
    android:layout_height="120dp"
    app:batteryOrientation="vertical"
    app:batteryPower="50"
    app:batteryCharging="true"
    app:batteryGradientEnabled="true"
    app:batteryGradientVertical="true"
    app:batteryGradientStartColor="#4CAF50"
    app:batteryGradientEndColor="#FFC107"/>

示例3：自定义外观的电池

<com.donkor.demo.BatteryView
    android:id="@+id/batteryView"
    android:layout_width="80dp"
    android:layout_height="40dp"
    app:batteryOrientation="horizontal"
    app:batteryPower="30"
    app:batteryBodyCornerRadius="12dp"
    app:batteryHeadCornerRadius="6dp"
    app:batteryBorderWidth="3dp"
    app:batteryBorderColor="#FF5722"
    app:batteryHeadColor="#FF5722"
    app:batteryHeadScale="0.6"
    app:batteryShowPercent="true"
    app:batteryPercentColor="#FFFFFF"
    app:batteryPercentSize="14sp"/>

示例4：低电量提醒电池

val batteryView = findViewById<BatteryView>(R.id.batteryView)
batteryView.apply {
    setPower(15)                    // 低电量
    setLowBlink(true)               // 启用闪烁
    setVibrateOnLow(true)           // 启用震动
    setLowThreshold(20)             // 低于20%触发
    setShowPercent(true)
    setPercentColor(Color.RED)
}

示例5：充电循环动画

val batteryView = findViewById<BatteryView>(R.id.batteryView)
batteryView.apply {
    setCharging(true)               // 启用充电
    setChargingCycle(true)          // 启用循环动画（0-100%）
    setAnimatePower(true)           // 平滑过渡
    setGradientEnabled(true)        // 渐变效果
}

📦 技术栈

语言：Kotlin
最低 SDK：21 (Android 5.0)
目标 SDK：35 (Android 15)
构建工具：Gradle 8.3.2

❓ 常见问题

Q1: 如何设置电池头和电池身不同的圆角？

batteryView.setBodyCornerRadius(16f)  // 电池身大圆角
batteryView.setHeadCornerRadius(4f)   // 电池头小圆角

Q2: 如何让电池头和电池身使用不同的颜色？

batteryView.setBorderColor(Color.BLACK)  // 电池身边框黑色
batteryView.setHeadColor(Color.RED)      // 电池头红色

Q3: 充电循环动画如何工作？

启用充电循环动画后，电量会从0%平滑上升到100%，然后立即跳回0%，周期为3秒：

batteryView.setCharging(true)        // 启用充电
batteryView.setChargingCycle(true)   // 启用循环动画

Q4: 如何自定义低电量阈值？

batteryView.setLowThreshold(15)      // 设置低电量阈值为15%
batteryView.setLowBlink(true)        // 启用闪烁
batteryView.setVibrateOnLow(true)    // 启用震动

Q5: 渐变方向如何控制？

// 横向渐变（从左到右或从上到下）
batteryView.setGradientVertical(false)

// 纵向渐变（从下到上或从右到左）
batteryView.setGradientVertical(true)

Q6: 如何在XML中同时设置电池身和电池头圆角？

使用 batteryCornerRadius 会同时设置两者：

app:batteryCornerRadius="8dp"

或者分别设置：

app:batteryBodyCornerRadius="12dp"
app:batteryHeadCornerRadius="6dp"

Q7: 电量平滑过渡动画的作用是什么？

启用后，调用 setPower() 时电量会平滑过渡到目标值，而不是立即跳变：

batteryView.setAnimatePower(true)
batteryView.setPower(80)  // 从当前电量平滑过渡到80%

📄 许可证

Copyright 2025 Donkor

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

👨‍💻 作者

Donkor

⭐ 如果这个项目对你有帮助，请给个 Star！

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.idea		.idea
app		app
gradle/wrapper		gradle/wrapper
screenshot		screenshot
.gitignore		.gitignore
README.md		README.md
build.gradle		build.gradle
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle		settings.gradle

Donkor798/BatteryView

Folders and files

Latest commit

History

Repository files navigation