docs: add new future

2025-09-05 10:15:40 +08:00 · 2023-12-18 07:25:53 +08:00
parent be9ae3bde7
commit a92328268e
2 changed files with 221 additions and 0 deletions
--- a/docs-source/src/en/about/future.md
+++ b/docs-source/src/en/about/future.md
@@ -101,4 +101,119 @@ MyClass().also {

 The above functions may change after the actual release, and the functions of the actual version shall prevail.

+:::
+
+### Automatically Generate Directly Called Class Objects
+
+In Kotlin, the way to represent Java class objects is `YourObject::class.java`.
+
+This writing method is usually very long and will be very unsightly when used extensively during reflection.
+
+In the existing version, we have built-in commonly used `Class` objects, but this will increase the size of dependencies, and these objects may not be used in most cases.
+
+For example, `StringClass`, `IntType`, etc., these objects are built in `YukiReflection`.
+
+So we plan to add a function in the future, which can use `properties` to create a list of `Class` objects that need to be generated,
+and generate these `Class` objects in sequence through the Gradle plugin.
+
+`Class` objects of primitive types such as those mentioned above will still be built into `YukiReflection`,
+and the remaining `Class` objects need to be defined by yourself.
+
+The generated name specification is **Class Name + Class**.
+
+In order to prevent package name conflicts, you can control the sub-package name of the generated `Class` object.
+
+In the configuration file, you don't need to add `Class` as a suffix.
+
+You can define the generated root package name in the Gradle plugin, which defaults to `com.highcapable.yukireflection.generated.classes`.
+
+> The following example
+
+```properties
+# The most basic way to define is to write the name directly
+# Will be generated to com.highcapable.yukireflection.generated.classes.BundleClass
+android.os.Bundle=Bundle
+# You can use the "." form in front to define the prefixed subpackage name
+# For example, we want to define this class to the desired package name
+# Will be generated to com.highcapable.yukireflection.generated.classes.myandroid.myos.BundleClass
+android.os.Bundle=myandroid.myos.Bundle
+# You can also not fill in the key value content, which will use the key value name
+# as the defined package name and class name
+# Will be generated to com.highcapable.yukireflection.generated.classes.android.os.BundleClass
+android.os.Bundle
+```
+
+The approximate code form of the `Class` object generated by the above method is as follows.
+
+```kotlin
+package com.highcapable.yukireflection.generated.classes.android.os
+
+// Used with default ClassLoader
+val BundleClass: Class<*> = "android.os.Bundle".toClass()
+
+// Used when ClassLoader is specified
+fun BundleClass(loader: ClassLoader): Class<*> = "android.os.Bundle".toClass(loader)
+```
+
+Maybe this `Class` may not be obtained in some cases.
+
+In this case, you can refer to the following configuration method.
+
+> The following example
+
+```properties
+# Add "?" after the key value to define a nullable Class object
+android.os.Bundle?
+```
+
+The approximate code form of the `Class` object generated by the above method is as follows.
+
+```kotlin
+package com.highcapable.yukireflection.generated.classes.android.os
+
+// Used with default ClassLoader
+val BundleClass: Class<*>? = "android.os.Bundle".toClassOrNull()
+
+// Used when ClassLoader is specified
+fun BundleClass(loader: ClassLoader): Class<*>? = "android.os.Bundle".toClassOrNull(loader)
+```
+
+If this `Class` object can be referenced by direct call, you can refer to the following configuration method at this time.
+
+> The following example
+
+```properties
+# Add "!!" after the key value to define a Class object that can be called directly
+android.os.Bundle!!
+```
+
+The approximate code form of the `Class` object generated by the above method is as follows.
+
+```kotlin
+package com.highcapable.yukireflection.generated.classes.android.os
+
+import android.os.Bundle
+
+// Used with default ClassLoader
+val BundleClass: Class<Bundle> = classOf<Bundle>()
+
+// Used when ClassLoader is specified
+fun BundleClass(loader: ClassLoader): Class<Bundle> = classOf<Bundle>(loader)
+```
+
+With the generated `Class` object, we can happily use `YukiReflection` for reflection.
+
+> The following example
+
+```kotlin
+method {
+    name = "onCreate"
+    param(BundleClass)
+}
+```
+
+::: tip
+
+The above functions may change after the actual release, and the functions of the actual version shall prevail.
+
 :::
--- a/docs-source/src/zh-cn/about/future.md
+++ b/docs-source/src/zh-cn/about/future.md
@@ -101,4 +101,110 @@ MyClass().also {

 以上功能可能会在实际推出后有所变化，最终以实际版本的功能为准。

+:::
+
+### 自动生成可直接调用的 Class 对象
+
+在 Kotlin 中，表示 Java 的类对象的方式是 `YourObject::class.java`，这个写法通常会很长，在反射过程中大量使用会很不美观。
+
+在现有版本中，我们内置了常用的 `Class` 对象，但是这会增大依赖的体积，而且大多数情况下可能都用不到这些对象。
+
+例如 `StringClass`、`IntType` 等等，这些对象都是在 `YukiReflection` 中内置的。
+
+所以我们计划在后期添加一个功能，可以使用 `properties` 的方式创建一个需要生成的 `Class` 对象列表，通过 Gradle 插件依次生成这些 `Class` 对象。
+
+诸如上面提到的这些原始类型的 `Class` 对象依然会内置在 `YukiReflection` 中，其余的 `Class` 对象需要自行定义。
+
+生成的名称规范为 **类名 + Class**，为了防止包名冲突，你可以控制生成的 `Class` 对象的子包名。
+
+在配置文件中，你无需添加 `Class` 作为后缀。
+
+你可以在 Gradle 插件中定义生成的根包名，默认为 `com.highcapable.yukireflection.generated.classes`。
+
+> 示例如下
+
+```properties
+# 最基本的定义方式就是直接写名称
+# 将会生成到 com.highcapable.yukireflection.generated.classes.BundleClass
+android.os.Bundle=Bundle
+# 你可以在前方使用 "." 的形式来定义前置子包名
+# 例如我们想把这个类定义到想要的包名
+# 将会生成到 com.highcapable.yukireflection.generated.classes.myandroid.myos.BundleClass
+android.os.Bundle=myandroid.myos.Bundle
+# 你也可以不填写键值内容，这将使用键值名称作为定义的包名和类名
+# 将会生成到 com.highcapable.yukireflection.generated.classes.android.os.BundleClass
+android.os.Bundle
+```
+
+上述方式生成的 `Class` 对象的大概代码形式如下。
+
+```kotlin
+package com.highcapable.yukireflection.generated.classes.android.os
+
+// 在默认 ClassLoader 的情况下使用
+val BundleClass: Class<*> = "android.os.Bundle".toClass()
+
+// 在指定 ClassLoader 的情况下使用
+fun BundleClass(loader: ClassLoader): Class<*> = "android.os.Bundle".toClass(loader)
+```
+
+也许这个 `Class` 可能在一些情况下无法被得到，这个时候你可以参考以下配置方式。
+
+> 示例如下
+
+```properties
+# 在键值后添加 "?" 的形式来定义可空的 Class 对象
+android.os.Bundle?
+```
+
+上述方式生成的 `Class` 对象的大概代码形式如下。
+
+```kotlin
+package com.highcapable.yukireflection.generated.classes.android.os
+
+// 在默认 ClassLoader 的情况下使用
+val BundleClass: Class<*>? = "android.os.Bundle".toClassOrNull()
+
+// 在指定 ClassLoader 的情况下使用
+fun BundleClass(loader: ClassLoader): Class<*>? = "android.os.Bundle".toClassOrNull(loader)
+```
+
+如果这个 `Class` 对象能使用直接调用的方式进行引用，这个时候你可以参考以下配置方式。
+
+> 示例如下
+
+```properties
+# 在键值后添加 "!!" 的形式来定义可直接调用的 Class 对象
+android.os.Bundle!!
+```
+
+上述方式生成的 `Class` 对象的大概代码形式如下。
+
+```kotlin
+package com.highcapable.yukireflection.generated.classes.android.os
+
+import android.os.Bundle
+
+// 在默认 ClassLoader 的情况下使用
+val BundleClass: Class<Bundle> = classOf<Bundle>()
+
+// 在指定 ClassLoader 的情况下使用
+fun BundleClass(loader: ClassLoader): Class<Bundle> = classOf<Bundle>(loader)
+```
+
+有了生成的 `Class` 对象，我们就可以愉快地使用 `YukiReflection` 进行反射了。
+
+> 示例如下
+
+```kotlin
+method {
+    name = "onCreate"
+    param(BundleClass)
+}
+```
+
+::: tip
+
+以上功能可能会在实际推出后有所变化，最终以实际版本的功能为准。
+
 :::