Merge pull request #189 from simple-robot/dev/image-b64-188

对图片、视频、语音文件进行base64编码时，默认使用 Base64.Default 进行编码

Author: ForteScarlet

simbot-component-onebot-v11/simbot-component-onebot-v11-message/api/simbot-component-onebot-v11-message.api

@@ -1,3 +1,14 @@
+public abstract interface class love/forte/simbot/component/onebot/v11/message/Base64Encoder {
+	public static final field Companion Llove/forte/simbot/component/onebot/v11/message/Base64Encoder$Companion;
+	public static final field Default Llove/forte/simbot/component/onebot/v11/message/Base64Encoder;
+	public static final field Mime Llove/forte/simbot/component/onebot/v11/message/Base64Encoder;
+	public static final field UrlSafe Llove/forte/simbot/component/onebot/v11/message/Base64Encoder;
+	public abstract fun encodeToAppendable ([BLjava/lang/Appendable;)Ljava/lang/Appendable;
+}
+
+public final class love/forte/simbot/component/onebot/v11/message/Base64Encoder$Companion {
+}
+
 public abstract interface class love/forte/simbot/component/onebot/v11/message/OneBotMessageContent : love/forte/simbot/message/MessageContent {
 	public abstract synthetic fun delete ([Llove/forte/simbot/ability/DeleteOption;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public abstract fun getId ()Llove/forte/simbot/common/id/ID;
@@ -427,7 +438,7 @@ public final class love/forte/simbot/component/onebot/v11/message/segment/OneBot
 public final class love/forte/simbot/component/onebot/v11/message/segment/OneBotImage : love/forte/simbot/component/onebot/v11/message/segment/OneBotMessageSegment, love/forte/simbot/component/onebot/v11/message/segment/OneBotMessageSegmentElementResolver {
 	public static final field Factory Llove/forte/simbot/component/onebot/v11/message/segment/OneBotImage$Factory;
 	public static final field TYPE Ljava/lang/String;
-	public synthetic fun <init> (Llove/forte/simbot/component/onebot/v11/message/segment/OneBotImage$Data;Llove/forte/simbot/resource/Resource;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public synthetic fun <init> (Llove/forte/simbot/component/onebot/v11/message/segment/OneBotImage$Data;Llove/forte/simbot/resource/Resource;Ljava/lang/String;Llove/forte/simbot/component/onebot/v11/message/Base64Encoder;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public static final fun create (Ljava/lang/String;)Llove/forte/simbot/component/onebot/v11/message/segment/OneBotImage;
 	public static final fun create (Llove/forte/simbot/component/onebot/v11/message/segment/OneBotImage$Data;)Llove/forte/simbot/component/onebot/v11/message/segment/OneBotImage;
 	public static final fun create (Llove/forte/simbot/component/onebot/v11/message/segment/OneBotImage$Data;Llove/forte/simbot/resource/Resource;)Llove/forte/simbot/component/onebot/v11/message/segment/OneBotImage;
@@ -455,11 +466,13 @@ public synthetic class love/forte/simbot/component/onebot/v11/message/segment/On
 
 public final class love/forte/simbot/component/onebot/v11/message/segment/OneBotImage$AdditionalParams {
 	public fun <init> ()V
+	public final fun getBase64Encoder ()Llove/forte/simbot/component/onebot/v11/message/Base64Encoder;
 	public final fun getCache ()Ljava/lang/Boolean;
 	public final fun getLocalFileToBase64 ()Z
 	public final fun getProxy ()Ljava/lang/Boolean;
 	public final fun getTimeout ()Ljava/lang/Integer;
 	public final fun getType ()Ljava/lang/String;
+	public final fun setBase64Encoder (Llove/forte/simbot/component/onebot/v11/message/Base64Encoder;)V
 	public final fun setCache (Ljava/lang/Boolean;)V
 	public final fun setLocalFileToBase64 (Z)V
 	public final fun setProxy (Ljava/lang/Boolean;)V
@@ -836,7 +849,7 @@ public final class love/forte/simbot/component/onebot/v11/message/segment/OneBot
 public final class love/forte/simbot/component/onebot/v11/message/segment/OneBotRecord : love/forte/simbot/component/onebot/v11/message/segment/OneBotMessageSegment {
 	public static final field Factory Llove/forte/simbot/component/onebot/v11/message/segment/OneBotRecord$Factory;
 	public static final field TYPE Ljava/lang/String;
-	public synthetic fun <init> (Llove/forte/simbot/component/onebot/v11/message/segment/OneBotRecord$Data;Llove/forte/simbot/resource/Resource;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public synthetic fun <init> (Llove/forte/simbot/component/onebot/v11/message/segment/OneBotRecord$Data;Llove/forte/simbot/resource/Resource;Ljava/lang/String;Llove/forte/simbot/component/onebot/v11/message/Base64Encoder;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public static final fun create (Ljava/lang/String;)Llove/forte/simbot/component/onebot/v11/message/segment/OneBotRecord;
 	public static final fun create (Llove/forte/simbot/component/onebot/v11/message/segment/OneBotRecord$Data;)Llove/forte/simbot/component/onebot/v11/message/segment/OneBotRecord;
 	public static final fun create (Llove/forte/simbot/component/onebot/v11/message/segment/OneBotRecord$Data;Llove/forte/simbot/resource/Resource;)Llove/forte/simbot/component/onebot/v11/message/segment/OneBotRecord;
@@ -863,11 +876,13 @@ public synthetic class love/forte/simbot/component/onebot/v11/message/segment/On
 
 public final class love/forte/simbot/component/onebot/v11/message/segment/OneBotRecord$AdditionalParams {
 	public fun <init> ()V
+	public final fun getBase64Encoder ()Llove/forte/simbot/component/onebot/v11/message/Base64Encoder;
 	public final fun getCache ()Ljava/lang/Boolean;
 	public final fun getLocalFileToBase64 ()Z
 	public final fun getMagic ()Ljava/lang/String;
 	public final fun getProxy ()Ljava/lang/Boolean;
 	public final fun getTimeout ()Ljava/lang/Integer;
+	public final fun setBase64Encoder (Llove/forte/simbot/component/onebot/v11/message/Base64Encoder;)V
 	public final fun setCache (Ljava/lang/Boolean;)V
 	public final fun setLocalFileToBase64 (Z)V
 	public final fun setMagic (Ljava/lang/String;)V
@@ -1143,7 +1158,7 @@ public final class love/forte/simbot/component/onebot/v11/message/segment/OneBot
 public final class love/forte/simbot/component/onebot/v11/message/segment/OneBotVideo : love/forte/simbot/component/onebot/v11/message/segment/OneBotMessageSegment {
 	public static final field Factory Llove/forte/simbot/component/onebot/v11/message/segment/OneBotVideo$Factory;
 	public static final field TYPE Ljava/lang/String;
-	public synthetic fun <init> (Llove/forte/simbot/component/onebot/v11/message/segment/OneBotVideo$Data;Llove/forte/simbot/resource/Resource;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public synthetic fun <init> (Llove/forte/simbot/component/onebot/v11/message/segment/OneBotVideo$Data;Llove/forte/simbot/resource/Resource;Ljava/lang/String;Llove/forte/simbot/component/onebot/v11/message/Base64Encoder;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public static final fun create (Ljava/lang/String;)Llove/forte/simbot/component/onebot/v11/message/segment/OneBotVideo;
 	public static final fun create (Llove/forte/simbot/component/onebot/v11/message/segment/OneBotVideo$Data;)Llove/forte/simbot/component/onebot/v11/message/segment/OneBotVideo;
 	public static final fun create (Llove/forte/simbot/component/onebot/v11/message/segment/OneBotVideo$Data;Llove/forte/simbot/resource/Resource;)Llove/forte/simbot/component/onebot/v11/message/segment/OneBotVideo;
@@ -1170,10 +1185,12 @@ public synthetic class love/forte/simbot/component/onebot/v11/message/segment/On
 
 public final class love/forte/simbot/component/onebot/v11/message/segment/OneBotVideo$AdditionalParams {
 	public fun <init> ()V
+	public final fun getBase64Encoder ()Llove/forte/simbot/component/onebot/v11/message/Base64Encoder;
 	public final fun getCache ()Ljava/lang/Boolean;
 	public final fun getLocalFileToBase64 ()Z
 	public final fun getProxy ()Ljava/lang/Boolean;
 	public final fun getTimeout ()Ljava/lang/Integer;
+	public final fun setBase64Encoder (Llove/forte/simbot/component/onebot/v11/message/Base64Encoder;)V
 	public final fun setCache (Ljava/lang/Boolean;)V
 	public final fun setLocalFileToBase64 (Z)V
 	public final fun setProxy (Ljava/lang/Boolean;)V

simbot-component-onebot-v11/simbot-component-onebot-v11-message/src/commonMain/kotlin/love/forte/simbot/component/onebot/v11/message/Base64Encoder.kt

@@ -0,0 +1,93 @@
+/*
+ * Copyright (c) 2025. ForteScarlet.
+ *
+ * This file is part of simbot-component-onebot.
+ *
+ * simbot-component-onebot is free software: you can redistribute it and/or modify it under the terms
+ * of the GNU Lesser General Public License as published by the Free Software Foundation,
+ * either version 3 of the License, or (at your option) any later version.
+ *
+ * simbot-component-onebot is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License along with simbot-component-onebot.
+ * If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package love.forte.simbot.component.onebot.v11.message
+
+import kotlin.io.encoding.Base64
+import kotlin.io.encoding.ExperimentalEncodingApi
+import kotlin.jvm.JvmField
+
+
+/**
+ * A base64 encoder.
+ *
+ * @since 1.6.1
+ *
+ * @author ForteScarlet
+ */
+public interface Base64Encoder {
+    /**
+     * Encodes [source] ByteArray to a Base64 encoded ByteArray.
+     */
+    public fun <A : Appendable> encodeToAppendable(source: ByteArray, destination: A): A
+
+    public companion object {
+        /**
+         * Get a [Base64Encoder] instance based on [kotlin.io.encoding.Base64.Default].
+         */
+        @ExperimentalEncodingApi
+        @JvmField
+        public val Default: Base64Encoder = KotlinBase64Encoder(Base64.Default)
+
+        /**
+         * Get a [Base64Encoder] instance based on [kotlin.io.encoding.Base64.Mime].
+         */
+        @ExperimentalEncodingApi
+        @JvmField
+        public val Mime: Base64Encoder = KotlinBase64Encoder(Base64.Mime)
+
+        /**
+         * Get a [Base64Encoder] instance based on [kotlin.io.encoding.Base64.UrlSafe].
+         */
+        @ExperimentalEncodingApi
+        @JvmField
+        public val UrlSafe: Base64Encoder = KotlinBase64Encoder(Base64.UrlSafe)
+    }
+}
+
+@ExperimentalEncodingApi
+private class KotlinBase64Encoder(val base64: Base64) : Base64Encoder {
+    override fun <A : Appendable> encodeToAppendable(source: ByteArray, destination: A): A {
+        base64.encodeToAppendable(source, destination)
+        return destination
+    }
+}
+
+@OptIn(ExperimentalEncodingApi::class)
+internal fun standardEncoderByName(name: String): Base64Encoder? {
+    return when {
+        name.equals("Default", true) -> Base64Encoder.Default
+        name.equals("Mime", true) -> Base64Encoder.Mime
+        name.equals("UrlSafe", true) || name.equals("url_safe", true)
+        -> Base64Encoder.UrlSafe
+
+        else -> null
+    }
+}
+
+@OptIn(ExperimentalEncodingApi::class)
+internal fun Base64Encoder.standardName(): String? {
+    return when (this) {
+        Base64Encoder.Default -> "Default"
+        Base64Encoder.Mime -> "Mime"
+        Base64Encoder.UrlSafe -> "UrlSafe"
+        else -> null
+    }
+}
+
+@OptIn(ExperimentalEncodingApi::class)
+internal val Base64Encoder.base64: Base64? get() = (this as? KotlinBase64Encoder)?.base64

simbot-component-onebot-v11/simbot-component-onebot-v11-message/src/commonMain/kotlin/love/forte/simbot/component/onebot/v11/message/segment/OneBotImage.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2024. ForteScarlet.
+ * Copyright (c) 2024-2025. ForteScarlet.
  *
  * This file is part of simbot-component-onebot.
  *
@@ -17,13 +17,19 @@
 
 package love.forte.simbot.component.onebot.v11.message.segment
 
+import kotlinx.serialization.ExperimentalSerializationApi
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.Transient
+import love.forte.simbot.component.onebot.v11.message.Base64Encoder
+import love.forte.simbot.component.onebot.v11.message.segment.OneBotImage.Factory.create
+import love.forte.simbot.component.onebot.v11.message.standardEncoderByName
+import love.forte.simbot.component.onebot.v11.message.standardName
 import love.forte.simbot.message.Image
 import love.forte.simbot.message.UrlAwareImage
 import love.forte.simbot.resource.ByteArrayResource
 import love.forte.simbot.resource.Resource
+import kotlin.io.encoding.ExperimentalEncodingApi
 import kotlin.jvm.JvmOverloads
 import kotlin.jvm.JvmStatic
 import kotlin.jvm.JvmSynthetic
@@ -33,14 +39,25 @@ import kotlin.jvm.JvmSynthetic
  *
  * 可用于发送。
  *
+ * ## 序列化
+ * ### Base64 encoder
+ * 在序列化并反序列化后，之前通过 [AdditionalParams.base64Encoder] 指定的 [Base64Encoder] **可能会丢失**。
+ * 如果丢失后再次需要使用 [Base64Encoder] 时，会选择使用 [Base64Encoder.Default]。
+ *
  * @author ForteScarlet
  */
+@OptIn(ExperimentalSerializationApi::class)
 @Serializable
 @SerialName(OneBotImage.TYPE)
 public class OneBotImage private constructor(
     override val data: Data,
     @Transient
     private val resource0: Resource? = null,
+    private val base64Encoder: String? = null,
+    @Transient
+    @OptIn(ExperimentalEncodingApi::class)
+    private val base64EncoderValue: Base64Encoder =
+        base64Encoder?.let { standardEncoderByName(it) } ?: Base64Encoder.Default
 ) : OneBotMessageSegment, OneBotMessageSegmentElementResolver {
     /**
      * 当前 [OneBotImage] 中的资源信息。
@@ -49,14 +66,14 @@ public class OneBotImage private constructor(
      * [Data.file] 的资源信息。
      */
     public val resource: Resource by lazy {
-        resource0 ?: data.resolveToResource()
+        resource0 ?: data.resolveToResource(base64EncoderValue)
     }
 
     public companion object Factory {
         public const val TYPE: String = "image"
 
-        private fun Data.resolveToResource(): Resource {
-            return resolveUrlOrFileToResource(url, file)
+        private fun Data.resolveToResource(encoder: Base64Encoder): Resource {
+            return resolveUrlOrFileToResource(url, file, encoder)
         }
 
         /**
@@ -67,6 +84,9 @@ public class OneBotImage private constructor(
          * - 如果 [Data.file] 是链接或者文件路径，
          * 解析为 `URIResource` 或 `PathResource` （仅支持 JVM 平台）
          *
+         * 如果需要指定 [Base64Encoder] (since 1.6.1),
+         * 选择使用 [create] 的另一个可以提供 [AdditionalParams] 的重载。
+         *
          * @throws UnsupportedOperationException 如果解析 [resource] 时平台不支持
          */
         @JvmStatic
@@ -97,12 +117,16 @@ public class OneBotImage private constructor(
          *
          * @throws UnsupportedOperationException 如果解析 [resource] 时平台不支持
          */
+        @OptIn(ExperimentalEncodingApi::class)
         @JvmStatic
         @JvmOverloads
         public fun create(resource: Resource, additional: AdditionalParams? = null): OneBotImage {
+            val base64Encoder = additional.base64EncoderOrDefault
+
             val file = resolveResourceToFileValue(
                 resource,
-                additional?.localFileToBase64 == true
+                additional?.localFileToBase64 == true,
+                base64Encoder
             )
 
             val data = Data(
@@ -113,7 +137,12 @@ public class OneBotImage private constructor(
                 timeout = additional?.timeout,
             )
 
-            return OneBotImage(data, resource)
+            return OneBotImage(
+                data,
+                resource,
+                base64Encoder.standardName(),
+                base64Encoder
+            )
         }
     }
 
@@ -152,10 +181,18 @@ public class OneBotImage private constructor(
 
     /**
      * 用于 [OneBotImage] 提供的部分工厂函数中，
-     * 指定 [Data] 中部分属性。
+     * 指定 [Data] 中部分属性或一些有用的额外参数。
      */
     public class AdditionalParams {
         public var localFileToBase64: Boolean = false
+
+        /**
+         * 当需要对资源进行 base64 编码时使用的编码器。
+         * 如果未配置则默认为 [Base64Encoder.Default]。
+         * @since 1.6.1
+         */
+        public var base64Encoder: Base64Encoder? = null
+
         public var type: String? = null
         public var cache: Boolean? = null
         public var proxy: Boolean? = null
@@ -196,3 +233,7 @@ public inline fun OneBotImage.Factory.create(
 ): OneBotImage {
     return create(resource, OneBotImage.AdditionalParams().also(block))
 }
+
+@OptIn(ExperimentalEncodingApi::class)
+private inline val OneBotImage.AdditionalParams?.base64EncoderOrDefault: Base64Encoder
+    get() = this?.base64Encoder ?: Base64Encoder.Default