Kotlin Android 水印功能实现指南：使用 Watermark 库

我们来详细讲解如何在 Kotlin 项目中使用 Watermark 这个强大的库来实现照片水印功能。

1. 添加依赖

首先，在你的 app 模块下的 build.gradle 文件中添加依赖：

dependencies {
    implementation 'com.huangyz0918:androidwm:0.2.3' // 请检查最新版本
}

注意：请前往 Watermark 的 GitHub 页面 查看最新的版本号，替换掉 0.2.3。

然后同步 (Sync) 你的项目。

2. 核心概念与基本用法

Watermark 库的核心是链式调用，非常直观。它主要支持两种水印：

1. 文字水印 (TextWatermark)
2. 图片水印 (ImageWatermark)

示例 1：添加一个简单的文字水印

这个例子展示了如何给一张图片添加文字水印，并显示在 ImageView 上。

// 1. 获取原始图片的 Bitmap (这里从资源文件中获取)
val originalBitmap = BitmapFactory.decodeResource(resources, R.drawable.your_original_image)

// 2. 使用链式调用创建并应用水印
Watermark.create(this) // 'this' 是 Context
    .loadImage(originalBitmap) // 加载原图
    .addWatermark(TextWatermark("机密文件 © 2023") // 创建文字水印
        .setPositionX(0.5) // 设置X坐标（相对位置，0.5代表中心）
        .setPositionY(0.5) // 设置Y坐标（相对位置，0.5代表中心）
        .setTextAlpha(100) // 设置透明度 (0-255, 0完全透明，255完全不透明)
        .setTextColor(Color.RED) // 设置文字颜色
        .setTextSize(40) // 设置文字大小（单位：SP）
        .setRotation(-30f)) // 设置旋转角度
    .setToImageView(yourImageView) // 将处理后的图片设置到ImageView

示例 2：添加一个图片水印（Logo）

这个例子展示了如何在图片的右下角添加一个 Logo 水印。

// 1. 获取原始图片和Logo水印图片的 Bitmap
val originalBitmap = BitmapFactory.decodeResource(resources, R.drawable.your_original_image)
val logoBitmap = BitmapFactory.decodeResource(resources, R.drawable.your_logo)

// 2. 使用链式调用创建并应用水印
Watermark.create(this)
    .loadImage(originalBitmap)
    .addWatermark(ImageWatermark(logoBitmap) // 创建图片水印
        .setSize(0.2) // 设置水印图片大小（原图的0.2倍）
        .setPosition(WatermarkPosition.BOTTOM_RIGHT) // 使用内置枚举设置位置到右下角
        .setMargin(20, 20, 20, 20) // 设置边距 (左, 上, 右, 下)
        .setAlpha(150)) // 设置透明度
    .setToImageView(yourImageView)

示例 3：同时添加文字和图片水印，并保存到文件

这个例子展示了如何添加多个水印，并且将最终结果保存为文件。

// 假设 originalBitmap 已经加载

Watermark.create(this)
    .loadImage(originalBitmap)
    .addWatermark(TextWatermark("@Username")
        .setPosition(WatermarkPosition.TOP_LEFT) // 文字放在左上角
        .setTextColor(Color.WHITE)
        .setTextSize(30)
        .setTextAlpha(200)
        .setBackgroundColor(Color.parseColor("#66000000"))) // 设置文字背景色（半透明黑）
    .addWatermark(ImageWatermark(logoBitmap)
        .setPosition(WatermarkPosition.BOTTOM_RIGHT) // Logo放在右下角
        .setSize(0.15)
        .setAlpha(180))
    .getWatermarkBitmap { outputBitmap -> // 获取处理后的Bitmap的回调
        // 在这里处理 outputBitmap
        yourImageView.setImageBitmap(outputBitmap)

        // 保存到文件
        saveBitmapToFile(outputBitmap, "watermarked_image.jpg")
    }

// 将Bitmap保存到文件的函数
private fun saveBitmapToFile(bitmap: Bitmap, filename: String) {
    val imagesDir = getExternalFilesDir(Environment.DIRECTORY_PICTURES)
    val imageFile = File(imagesDir, filename)
    try {
        val fos = FileOutputStream(imageFile)
        bitmap.compress(Bitmap.CompressFormat.JPEG, 90, fos)
        fos.close()
        Toast.makeText(this, "图片已保存: ${imageFile.absolutePath}", Toast.LENGTH_SHORT).show()
    } catch (e: IOException) {
        e.printStackTrace()
    }
}

3. 常用配置选项

对于 TextWatermark:

方法 描述 示例
setText(String) 设置水印文字 .setText(“Hello”)
setTextColor(int) 设置文字颜色 .setTextColor(Color.RED)
setTextSize(float) 设置文字大小 (单位 sp) .setTextSize(40f)
setTextAlpha(int) 设置透明度 (0-255) .setTextAlpha(128)
setPositionX(float) 设置X坐标 (相对位置，0.0-1.0) .setPositionX(0.1f)
setPositionY(float) 设置Y坐标 (相对位置，0.0-1.0) .setPositionY(0.9f)
setPosition(WatermarkPosition) 使用预设位置 .setPosition(WatermarkPosition.CENTER)
setRotation(float) 设置旋转角度 .setRotation(-45f)
setBackgroundColor(int) 设置文字背景色 .setBackgroundColor(Color.BLACK)

对于 ImageWatermark:

方法 描述 示例
setImageBitmap(Bitmap) 设置水印图片 .setImageBitmap(logoBitmap)
setSize(float) 设置大小 (相对于原图的比例) .setSize(0.2f)
setAlpha(int) 设置透明度 (0-255) .setAlpha(150)
setPosition(…) 设置位置 (同文字水印) .setPosition(WatermarkPosition.BOTTOM_RIGHT)
setMargin(int, int, int, int) 设置边距 (左, 上, 右, 下) .setMargin(10, 10, 10, 10)

内置位置枚举 (WatermarkPosition):
TOP_LEFT,TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT, CENTER, TOP_CENTER, BOTTOM_CENTER

4. 完整 Activity 示例

class MainActivity : AppCompatActivity() {

    private lateinit var imageView: ImageView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        imageView = findViewById(R.id.image_view)
        val addWatermarkBtn: Button = findViewById(R.id.add_watermark_btn)

        addWatermarkBtn.setOnClickListener {
            addWatermarkToImage()
        }
    }

    private fun addWatermarkToImage() {
        // 从资源加载图片
        val originalBitmap = BitmapFactory.decodeResource(resources, R.drawable.demo_image)
        val logoBitmap = BitmapFactory.decodeResource(resources, R.drawable.app_logo)

        // 使用Watermark库
        Watermark.create(this)
            .loadImage(originalBitmap)
            .addWatermark(TextWatermark("旅行日记\n2023-10-27")
                .setPosition(WatermarkPosition.BOTTOM_LEFT)
                .setTextColor(Color.WHITE)
                .setTextSize(20f)
                .setTextAlpha(200)
                .setBackgroundColor(Color.parseColor("#4D000000")) // 带透明的黑色背景
                .setMargin(16, 16, 16, 16))
            .addWatermark(ImageWatermark(logoBitmap)
                .setPosition(WatermarkPosition.TOP_RIGHT)
                .setSize(0.1f)
                .setAlpha(200)
                .setMargin(16, 16, 16, 16))
            .setToImageView(imageView) // 直接显示
            // .getWatermarkBitmap { bitmap -> } // 或者获取Bitmap进行其他操作
    }
}

注意事项

1. 性能：处理高分辨率图片是一个耗时操作，务必在后台线程进行（例如使用 Coroutines 或 RxJava），然后在主线程更新 UI。Watermark 库的 getWatermarkBitmap 回调本身是在后台线程的。
2. 内存管理：Bitmap 非常消耗内存。及时回收不再使用的 Bitmap（调用 recycle() 方法），特别是在处理多张图片时，避免内存溢出 (OOM)。
3. 权限：如果要从设备存储或网络加载图片，或者需要保存处理后的图片，别忘了在 AndroidManifest.xml 中申请相应的存储权限 (READ_EXTERNAL_STORAGE, WRITE_EXTERNAL_STORAGE)。

通过上述介绍，你应该可以轻松地在你的 Kotlin Android 项目中使用 Watermark 库来实现各种水印需求了。