docs: merge some future to migrate docs

2025-09-01 08:15:37 +08:00 · 2023-10-07 16:29:05 +08:00
parent 5939e1dcd3
commit 6d82c28081
5 changed files with 323 additions and 94 deletions
--- a/docs-source/src/.vuepress/configs/template.ts
+++ b/docs-source/src/.vuepress/configs/template.ts
@@ -16,6 +16,7 @@ const navigationLinks = {
        '/config/api-exception',
        '/config/xposed-using',
        '/config/api-using',
+        '/config/move-to-api-1-2-x',
        '/config/r8-proguard'
    ],
    tools: '/tools/yukihookapi-projectbuilder',
@@ -143,7 +144,8 @@ export const navBarItems = {
                { text: 'API Exception Handling', link: i18n.string(navigationLinks.config[1], 'en') },
                { text: 'Use as Xposed Module Configs', link: i18n.string(navigationLinks.config[2], 'en') },
                { text: 'Use as Hook API Configs', link: i18n.string(navigationLinks.config[3], 'en') },
-                { text: 'R8 & Proguard Obfuscate', link: i18n.string(navigationLinks.config[4], 'en') }
+                { text: 'Migrate to YukiHookAPI 1.2.x', link: i18n.string(navigationLinks.config[4], 'en') },
+                { text: 'R8 & Proguard Obfuscate', link: i18n.string(navigationLinks.config[5], 'en') }
            ]
        }, {
            text: 'Tools',
@@ -193,7 +195,8 @@ export const navBarItems = {
                { text: 'API 异常处理', link: i18n.string(navigationLinks.config[1], 'zh-cn') },
                { text: '作为 Xposed 模块使用的相关配置', link: i18n.string(navigationLinks.config[2], 'zh-cn') },
                { text: '作为 Hook API 使用的相关配置', link: i18n.string(navigationLinks.config[3], 'zh-cn') },
-                { text: 'R8 与 Proguard 混淆', link: i18n.string(navigationLinks.config[4], 'zh-cn') }
+                { text: '迁移到 YukiHookAPI 1.2.x', link: i18n.string(navigationLinks.config[4], 'zh-cn') },
+                { text: 'R8 与 Proguard 混淆', link: i18n.string(navigationLinks.config[5], 'zh-cn') }
            ]
        }, {
            text: '工具',
--- a/docs-source/src/en/about/future.md
+++ b/docs-source/src/en/about/future.md
@@ -58,50 +58,4 @@ All functions are expected to be completed in `2.0.0` version, so stay tuned.

 - [New Xposed Module Config Plan](https://github.com/fankes/YukiHookAPI/issues/49)
 - [New Hook Entry Class](https://github.com/fankes/YukiHookAPI/issues/48)
- [New Hook Code Style](https://github.com/fankes/YukiHookAPI/issues/33)
-
-#### New Hook Code Style (Preview)
-
-`YukiHookAPI` introduced the `New Hook Code Style` (New API) of `2.0.0` in the `1.2.0` version, it is now in the experimental stage.
-
-You can before the `2.0.0` version is officially released, start migrating and experience the New API.
-
-For example, we want to Hook the `test` method in the `com.example.Test` class.
-
-> Legacy API
-
-```kotlin
-findClass("com.example.Test").hook {
-    injectMember {
-        method {
-            name = "test"
-        }
-        beforeHook {
-            // Your code here.
-        }
-        afterHook {
-            // Your code here.
-        }
-    }
-}
-```
-
-> New API
-
-```kotlin
-"com.example.Test".toClass()
-    .method {
-        name = "test"
-    }.hook {
-        before {
-            // Your code here.
-        }
-        after {
-            // Your code here.
-        }
-    }
-```
-
-The Hook object of the New API has been migrated from `Class` to `Member`, which will be more intuitive.
-
-All legacy APIs have been marked `LegacyHookApi`, you can use `@OptIn(LegacyHookApi::class)` to eliminate the warning and continue to use the legacy API.
+- [New Hook Code Style](https://github.com/fankes/YukiHookAPI/issues/33)
--- a/docs-source/src/en/config/move-to-api-1-2-x.md
+++ b/docs-source/src/en/config/move-to-api-1-2-x.md
@@ -0,0 +1,160 @@
+# Migrate to YukiHookAPI 1.2.x
+
+`YukiHookAPI` has undergone a lot of adjustments since version `1.2.0`, you can read on to see what are the notes and new features.
+
+## Default Behavior Changes
+
+Since version `1.2.0`, the `isUsingResourcesHook` function in `@InjectYukiHookWithXposed` is no longer enabled by default, please enable it manually if necessary.
+
+::: warning
+
+Resources Hook will be removed in version **2.0.0** and is now marked **LegacyResourcesHook**.
+
+You can use **@OptIn(LegacyResourcesHook::class)** to eliminate the warning, continue to use version **1.x.x**.
+
+:::
+
+## New API
+
+`YukiHookAPI` introduced the [New Hook Code Style](https://github.com/fankes/YukiHookAPI/issues/33) (New API) of `2.0.0` in the `1.2.0` version, it is now in the experimental stage.
+
+You can before the `2.0.0` version is officially released, start migrating and experience the New API.
+
+::: warning
+
+All legacy APIs have been marked **LegacyHookApi**, you can use **@OptIn(LegacyHookApi::class)** to eliminate the warning and continue to use the legacy API.
+
+:::
+
+For example, we want to Hook the `test` method in the `com.example.Test` class.
+
+> Legacy API
+
+```kotlin
+findClass("com.example.Test").hook {
+    injectMember {
+        method {
+            name = "test"
+        }
+        beforeHook {
+            // Your code here.
+        }
+        afterHook {
+            // Your code here.
+        }
+    }
+}
+```
+
+> New API
+
+```kotlin
+"com.example.Test".toClass()
+    .method {
+        name = "test"
+    }.hook {
+        before {
+            // Your code here.
+        }
+        after {
+            // Your code here.
+        }
+    }
+```
+
+The Hook object of the New API has been migrated from `Class` to `Member`, which will be more intuitive.
+
+## Differential Functions
+
+The following are some of the different functions of connecting to the new version of the API.
+
+### New Multi-Hook Usage
+
+Previously we needed to hook all methods that match conditions like this.
+
+> The following example
+
+```kotlin
+injectMembers {
+    method {
+        name { it.contains("some") }
+    }.all()
+    afterHook {
+        // Your code here.
+    }
+}
+```
+
+Now, you can use the following method instead.
+
+> The following example
+
+```kotlin
+method {
+    name { it.contains("some") }
+}.hookAll {
+    after {
+        // Your code here.
+    }
+}
+```
+
+### New `allMembers(...)` Usage
+
+Previously we needed to hook all methods and constructors like this.
+
+> The following example
+
+```kotlin
+injectMembers {
+    allMembers(MembersType.METHOD)
+    afterHook {
+        // Your code here.
+    }
+}
+```
+
+```kotlin
+injectMembers {
+    allMembers(MembersType.CONSTRUCTOR)
+    afterHook {
+        // Your code here.
+    }
+}
+```
+
+Now, you can use the following method instead.
+
+> The following example
+
+```kotlin
+method().hookAll {
+    after {
+        // Your code here.
+    }
+}
+```
+
+```kotlin
+constructor().hookAll {
+    after {
+        // Your code here.
+    }
+}
+```
+
+When the find conditions are not filled in, all members in the current `Class` are obtained by default.
+
+If you want to hook `MembersType.ALL`, there is currently no direct method, but you can concatenate all members and then hook.
+
+> The following example
+
+```kotlin
+(method().giveAll() + constructor().giveAll()).hookAll {
+    after {
+        // Your code here.
+    }
+}
+```
+
+But we do not recommend this approach, too many hook members at one time are uncontrollable and problems may occur.
--- a/docs-source/src/zh-cn/about/future.md
+++ b/docs-source/src/zh-cn/about/future.md
@@ -52,48 +52,4 @@ API 已经提供了 Xposed 原生 API 监听接口，你可以 [在这里](../co

 - [New Xposed Module Config Plan](https://github.com/fankes/YukiHookAPI/issues/49)
 - [New Hook Entry Class](https://github.com/fankes/YukiHookAPI/issues/48)
- [New Hook Code Style](https://github.com/fankes/YukiHookAPI/issues/33)
-
-#### New Hook Code Style (Preview)
-
-`YukiHookAPI` 在 `1.2.0` 版本引入了 `2.0.0` 准备实现的 `New Hook Code Style` (新版 API)，现处于实验性阶段，你可以在 `2.0.0` 版本正式发布前，开始迁移并体验新版 API。
-
-例如，我们要 Hook `com.example.Test` 类中的 `test` 方法。
-
-> 旧版 API
-
-```kotlin
-findClass("com.example.Test").hook {
-    injectMember {
-        method {
-            name = "test"
-        }
-        beforeHook {
-            // Your code here.
-        }
-        afterHook {
-            // Your code here.
-        }
-    }
-}
-```
-
-> 新版 API
-
-```kotlin
-"com.example.Test".toClass()
-    .method {
-        name = "test"
-    }.hook {
-        before {
-            // Your code here.
-        }
-        after {
-            // Your code here.
-        }
-    }
-```
-
-新版 API 的 Hook 对象从 `Class` 迁移到了 `Member`，这种方式将更加直观。
-
-所有旧版 API 已被标记 `LegacyHookApi`，你可以使用 `@OptIn(LegacyHookApi::class)` 的方式消除警告，继续使用旧版 API。
+- [New Hook Code Style](https://github.com/fankes/YukiHookAPI/issues/33)
--- a/docs-source/src/zh-cn/config/move-to-api-1-2-x.md
+++ b/docs-source/src/zh-cn/config/move-to-api-1-2-x.md
@@ -0,0 +1,156 @@
+# 迁移到 YukiHookAPI 1.2.x
+
+`YukiHookAPI` 从 `1.2.0` 版本开始进行了大量调整，你可以继续向下阅读以查看有哪些注意事项和新功能。
+
+## 默认行为变更
+
+从 `1.2.0` 版本开始，`@InjectYukiHookWithXposed` 中 `isUsingResourcesHook` 功能默认不再启用，如有需要请手动启用。
+
+::: warning
+
+Resources Hook (资源钩子) 将在 **2.0.0** 版本被移除，现已被标记 **LegacyResourcesHook**，你可以使用 **@OptIn(LegacyResourcesHook::class)** 的方式消除警告以继续在 **1.x.x** 版本使用。
+
+:::
+
+## 新版 API
+
+`YukiHookAPI` 在 `1.2.0` 版本引入了 `2.0.0` 准备实现的 [New Hook Code Style](https://github.com/fankes/YukiHookAPI/issues/33) (新版 API)，现处于实验性阶段，你可以在 `2.0.0` 版本正式发布前，开始迁移并体验新版 API。
+
+::: warning
+
+所有旧版 API 已被标记 **LegacyHookApi**，你可以使用 **@OptIn(LegacyHookApi::class)** 的方式消除警告以继续使用旧版 API。
+
+:::
+
+例如，我们要 Hook `com.example.Test` 类中的 `test` 方法。
+
+> 旧版 API
+
+```kotlin
+findClass("com.example.Test").hook {
+    injectMember {
+        method {
+            name = "test"
+        }
+        beforeHook {
+            // Your code here.
+        }
+        afterHook {
+            // Your code here.
+        }
+    }
+}
+```
+
+> 新版 API
+
+```kotlin
+"com.example.Test".toClass()
+    .method {
+        name = "test"
+    }.hook {
+        before {
+            // Your code here.
+        }
+        after {
+            // Your code here.
+        }
+    }
+```
+
+新版 API 的 Hook 对象从 `Class` 迁移到了 `Member`，这种方式将更加直观。
+
+## 差异性功能
+
+下面是对接新版 API 的部分差异性功能。
+
+### 新的多重 Hook 用法
+
+之前我们需要这样去 Hook 所有匹配条件的方法。
+
+> 示例如下
+
+```kotlin
+injectMembers {
+    method {
+        name { it.contains("some") }
+    }.all()
+    afterHook {
+        // Your code here.
+    }
+}
+```
+
+现在，你可以改用下面这种方式。
+
+> 示例如下
+
+```kotlin
+method {
+    name { it.contains("some") }
+}.hookAll {
+    after {
+        // Your code here.
+    }
+}
+```
+
+### 新的 `allMembers(...)` 用法
+
+之前我们需要这样去 Hook 所有方法、构造方法。
+
+> 示例如下
+
+```kotlin
+injectMembers {
+    allMembers(MembersType.METHOD)
+    afterHook {
+        // Your code here.
+    }
+}
+```
+
+```kotlin
+injectMembers {
+    allMembers(MembersType.CONSTRUCTOR)
+    afterHook {
+        // Your code here.
+    }
+}
+```
+
+现在，你可以改用下面这种方式。
+
+> 示例如下
+
+```kotlin
+method().hookAll {
+    after {
+        // Your code here.
+    }
+}
+```
+
+```kotlin
+constructor().hookAll {
+    after {
+        // Your code here.
+    }
+}
+```
+
+当不填写查找条件时，默认获取当前 `Class` 中的所有成员对象。
+
+如果你想 Hook `MembersType.ALL`，目前暂时没有可以直接对接的方法，但是你可以将所有成员对象拼接后进行 Hook。
+
+> 示例如下
+
+```kotlin
+(method().giveAll() + constructor().giveAll()).hookAll {
+    after {
+        // Your code here.
+    }
+}
+```
+
+但我们并不推荐这种做法，一次性 Hook 过多的成员是不可控的，还会发生问题。