[core] 优化 SuperFace API

cssxsh · Sep 2, 2023 · 71adb5f · 71adb5f
1 parent 59ff38a
commit 71adb5f
Show file tree

Hide file tree

Showing 4 changed files with 37 additions and 17 deletions.
diff --git a/mirai-core-api/compatibility-validation/android/api/android.api b/mirai-core-api/compatibility-validation/android/api/android.api
@@ -5312,14 +5312,14 @@ public final class net/mamoe/mirai/message/data/SuperFace : net/mamoe/mirai/mess
 	public fun contentToString ()Ljava/lang/String;
 	public fun equals (Ljava/lang/Object;)Z
 	public static final fun from (Lnet/mamoe/mirai/message/data/Face;)Lnet/mamoe/mirai/message/data/SuperFace;
+	public static final fun fromOrNull (Lnet/mamoe/mirai/message/data/Face;)Lnet/mamoe/mirai/message/data/SuperFace;
 	public final fun getFace ()I
 	public final fun getId ()Ljava/lang/String;
 	public fun getKey ()Lnet/mamoe/mirai/message/data/MessageKey;
 	public final fun getName ()Ljava/lang/String;
 	public final fun getType ()I
 	public fun hashCode ()I
 	public fun toString ()Ljava/lang/String;
-	public static final fun tryFrom (Lnet/mamoe/mirai/message/data/Face;)Lnet/mamoe/mirai/message/data/SuperFace;
 	public static final fun write$Self (Lnet/mamoe/mirai/message/data/SuperFace;Lkotlinx/serialization/encoding/CompositeEncoder;Lkotlinx/serialization/descriptors/SerialDescriptor;)V
 }
 
@@ -5336,14 +5336,14 @@ public final class net/mamoe/mirai/message/data/SuperFace$$serializer : kotlinx/
 
 public final class net/mamoe/mirai/message/data/SuperFace$Key : net/mamoe/mirai/message/data/AbstractPolymorphicMessageKey {
 	public final fun from (Lnet/mamoe/mirai/message/data/Face;)Lnet/mamoe/mirai/message/data/SuperFace;
+	public final fun fromOrNull (Lnet/mamoe/mirai/message/data/Face;)Lnet/mamoe/mirai/message/data/SuperFace;
 	public final fun serializer ()Lkotlinx/serialization/KSerializer;
-	public final fun tryFrom (Lnet/mamoe/mirai/message/data/Face;)Lnet/mamoe/mirai/message/data/SuperFace;
 }
 
 public final class net/mamoe/mirai/message/data/SuperFaceKt {
-	public static final synthetic fun SuperFace (I)Lnet/mamoe/mirai/message/data/SuperFace;
-	public static final synthetic fun SuperFace (Lnet/mamoe/mirai/message/data/Face;)Lnet/mamoe/mirai/message/data/SuperFace;
 	public static final synthetic fun toFace (Lnet/mamoe/mirai/message/data/SuperFace;)Lnet/mamoe/mirai/message/data/Face;
+	public static final synthetic fun toSuperFace (Lnet/mamoe/mirai/message/data/Face;)Lnet/mamoe/mirai/message/data/SuperFace;
+	public static final synthetic fun toSuperFaceOrNull (Lnet/mamoe/mirai/message/data/Face;)Lnet/mamoe/mirai/message/data/SuperFace;
 }
 
 public abstract interface class net/mamoe/mirai/message/data/UnsupportedMessage : net/mamoe/mirai/message/data/MessageContent {

diff --git a/mirai-core-api/compatibility-validation/jvm/api/jvm.api b/mirai-core-api/compatibility-validation/jvm/api/jvm.api
@@ -5312,14 +5312,14 @@ public final class net/mamoe/mirai/message/data/SuperFace : net/mamoe/mirai/mess
 	public fun contentToString ()Ljava/lang/String;
 	public fun equals (Ljava/lang/Object;)Z
 	public static final fun from (Lnet/mamoe/mirai/message/data/Face;)Lnet/mamoe/mirai/message/data/SuperFace;
+	public static final fun fromOrNull (Lnet/mamoe/mirai/message/data/Face;)Lnet/mamoe/mirai/message/data/SuperFace;
 	public final fun getFace ()I
 	public final fun getId ()Ljava/lang/String;
 	public fun getKey ()Lnet/mamoe/mirai/message/data/MessageKey;
 	public final fun getName ()Ljava/lang/String;
 	public final fun getType ()I
 	public fun hashCode ()I
 	public fun toString ()Ljava/lang/String;
-	public static final fun tryFrom (Lnet/mamoe/mirai/message/data/Face;)Lnet/mamoe/mirai/message/data/SuperFace;
 	public static final fun write$Self (Lnet/mamoe/mirai/message/data/SuperFace;Lkotlinx/serialization/encoding/CompositeEncoder;Lkotlinx/serialization/descriptors/SerialDescriptor;)V
 }
 
@@ -5336,14 +5336,14 @@ public final class net/mamoe/mirai/message/data/SuperFace$$serializer : kotlinx/
 
 public final class net/mamoe/mirai/message/data/SuperFace$Key : net/mamoe/mirai/message/data/AbstractPolymorphicMessageKey {
 	public final fun from (Lnet/mamoe/mirai/message/data/Face;)Lnet/mamoe/mirai/message/data/SuperFace;
+	public final fun fromOrNull (Lnet/mamoe/mirai/message/data/Face;)Lnet/mamoe/mirai/message/data/SuperFace;
 	public final fun serializer ()Lkotlinx/serialization/KSerializer;
-	public final fun tryFrom (Lnet/mamoe/mirai/message/data/Face;)Lnet/mamoe/mirai/message/data/SuperFace;
 }
 
 public final class net/mamoe/mirai/message/data/SuperFaceKt {
-	public static final synthetic fun SuperFace (I)Lnet/mamoe/mirai/message/data/SuperFace;
-	public static final synthetic fun SuperFace (Lnet/mamoe/mirai/message/data/Face;)Lnet/mamoe/mirai/message/data/SuperFace;
 	public static final synthetic fun toFace (Lnet/mamoe/mirai/message/data/SuperFace;)Lnet/mamoe/mirai/message/data/Face;
+	public static final synthetic fun toSuperFace (Lnet/mamoe/mirai/message/data/Face;)Lnet/mamoe/mirai/message/data/SuperFace;
+	public static final synthetic fun toSuperFaceOrNull (Lnet/mamoe/mirai/message/data/Face;)Lnet/mamoe/mirai/message/data/SuperFace;
 }
 
 public abstract interface class net/mamoe/mirai/message/data/UnsupportedMessage : net/mamoe/mirai/message/data/MessageContent {

diff --git a/mirai-core-api/src/commonMain/kotlin/message/data/SuperFace.kt b/mirai-core-api/src/commonMain/kotlin/message/data/SuperFace.kt
@@ -17,10 +17,14 @@ import net.mamoe.mirai.utils.MiraiExperimentalApi
 import net.mamoe.mirai.utils.MiraiInternalApi
 import net.mamoe.mirai.utils.NotStableForInheritance
 import net.mamoe.mirai.utils.safeCast
-import kotlin.jvm.Throws
 
 /**
- * 超级表情
+ * 表示一个超级表情.
+ *
+ * 超级表情由[普通表情][Face]转换而来. 不是所有的普通表情都有对应的超级表情.
+ *
+ * 要构造超级表情, 使用 [SuperFace.from] 或 [SuperFace.fromOrNull].
+ * 在 Kotlin 还可以使用对应扩展函数: [Face.toSuperFace] 或 [Face.toSuperFaceOrNull].
  *
  * @see Face
  * @since 2.16
@@ -46,12 +50,12 @@ public class SuperFace @MiraiInternalApi constructor(
         /**
          * 将普通表情转换为超级表情.
          *
-         * @throws UnsupportedOperationException 无法转换时抛出
+         * @throws IllegalArgumentException 无法转换时抛出
          **/
         @JvmStatic
-        @Throws(UnsupportedOperationException::class)
         public fun from(face: Face): SuperFace {
-            return tryFrom(face = face) ?: throw UnsupportedOperationException("${face.id} - ${face.name}")
+            return fromOrNull(face = face)
+                ?: throw IllegalArgumentException("No SuperFace mapping from Face(id=${face.id}, name='${face.name}')")
         }
 
         /**
@@ -61,7 +65,7 @@ public class SuperFace @MiraiInternalApi constructor(
          **/
         @JvmStatic
         @OptIn(MiraiInternalApi::class)
-        public fun tryFrom(face: Face): SuperFace? {
+        public fun fromOrNull(face: Face): SuperFace? {
             val stickerId = when (face.id) {
                 Face.DA_CALL -> "1"
                 Face.BIAN_XING -> "2"
@@ -134,11 +138,27 @@ public class SuperFace @MiraiInternalApi constructor(
     }
 }
 
+/**
+ * 将超级表情转换为普通表情
+ *
+ * @since 2.16
+ */
 @JvmSynthetic
 public fun SuperFace.toFace(): Face = Face(id = face)
 
+/**
+ * 将普通表情转换为超级表情
+ *
+ * @since 2.16
+ * @throws IllegalArgumentException 无法转换时抛出
+ */
 @JvmSynthetic
-public fun SuperFace(face: Face): SuperFace = SuperFace.from(face)
+public fun Face.toSuperFace(): SuperFace = SuperFace.from(this)
 
+/**
+ * 将普通表情转换为超级表情, 在无法转换时返回 `null`
+ *
+ * @since 2.16
+ */
 @JvmSynthetic
-public fun SuperFace(face: Int): SuperFace = SuperFace.from(face = Face(id = face))
+public fun Face.toSuperFaceOrNull(): SuperFace? = SuperFace.fromOrNull(this)
diff --git a/mirai-core-api/src/commonTest/kotlin/message.data/MessageVisitorTest.kt b/mirai-core-api/src/commonTest/kotlin/message.data/MessageVisitorTest.kt
@@ -302,7 +302,7 @@ internal class MessageVisitorTest {
                 "visitSingleMessage",
                 "visitMessage",
             ),
-            SuperFace(Face.DA_CALL).accept(GetCalledMethodNames)
+            SuperFace.from(Face(Face.DA_CALL)).accept(GetCalledMethodNames)
         )
 
         assertContentEquals(