Update document file

2025-09-06 02:35:40 +08:00 · 2022-05-01 09:52:53 +08:00
parent 8d226bc42d
commit dfa3362c35
30 changed files with 1957 additions and 164 deletions
--- a/docs/config/api-example.md
+++ b/docs/config/api-example.md
@@ -177,6 +177,57 @@ class HookEntryClass : IYukiHookXposedInit {
 }
 ```

+### 扩展特性
+
+如果你当前使用的 Hook Framework 支持并启用了资源钩子(Resources Hook)功能，你现在可以直接在 `encase` 中创建 Resources Hook。
+
+你完全不需要与之前在使用 Xposed API 那样区分 `initZygote`、`handleLoadPackage`、`handleInitPackageResources` 方法来执行不同的功能。
+
+在 `YukiHookAPI` 中，这些功能**是无缝的**。
+
+> 示例如下
+
+```kotlin
+encase {
+    loadApp(name = "com.example.demo") {
+        findClass(name = "$packageName.DemoClass").hook { 
+            // Your code here.
+        }
+        // 创建一个 Resources Hook (固定用法)
+        resources().hook {
+            // Your code here.
+        }
+    }
+}
+```
+
+你还可以同时使用 `loadZygote` 方法来装载系统框架。
+
+> 示例如下
+
+```kotlin
+encase {
+    loadZygote {
+        ActivityClass.hook { 
+            // Your code here.
+        }
+        // 在 Zygote 中创建 Resources Hook
+        resources().hook {
+            // Your code here.
+        }
+    }
+    loadApp(name = "com.example.demo") {
+        findClass(name = "$packageName.DemoClass").hook { 
+            // Your code here.
+        }
+        // 在 APP 中创建 Resources Hook
+        resources().hook {
+            // Your code here.
+        }
+    }
+}
+```
+
 ## 作为 Hook API 使用需要注意的地方

 若你作为 Hook API 使用，那么你只需要在入口处对 `encase` 方法进行区分。
@@ -196,4 +247,6 @@ fun encase(baseContext: Context?, vararg hooker: YukiBaseHooker)

 此处的 `baseContext` 只需填入你在 `attachBaseContext` 处得到的 `Context` 即可，其它用法与上述内容完全一致。

-!> 切勿以 Xposed 方式使用 `encase` 方法而漏掉 `baseContext` 参数，否则你的 Hook 将完全不工作。
+!> 切勿以 Xposed 方式使用 `encase` 方法而漏掉 `baseContext` 参数，否则你的 Hook 将完全不工作。
+
+!> Resources Hook 功能不支持作为 Hook API 使用。
--- a/docs/config/api-exception.md
+++ b/docs/config/api-exception.md
@@ -16,11 +16,11 @@

 请确认你在正确的地方装载了 `YukiHookAPI` 的 `encase` 方法，详情请参考 [作为 Xposed 模块使用的相关配置](config/xposed-using) 以及 [作为 Hook API 使用的相关配置](config/api-using)。

-!> `loggerE` You cannot load a hooker in "onInit" method! Aborted
+!> `loggerE` You cannot load a hooker in "onInit" or "onXposedEvent" method! Aborted

 **异常原因**

-你尝试在继承 `IYukiHookXposedInit` 的 Hook 入口类的 `onInit` 方法中装载了 `encase` 方法。
+你尝试在继承 `IYukiHookXposedInit` 的 Hook 入口类的 `onInit` 或 `onXposedEvent` 方法中装载了 `encase` 或 `resources` 方法。

 > 示例如下

@@ -34,6 +34,13 @@ class HookEntry : IYukiHookXposedInit {
        }
    }

+    override fun onXposedEvent() {
+        // ❗错误的使用方法
+        YukiHookAPI.encase {
+            // Your code here.
+        }
+    }
+
    override fun onHook() {
        // Your code here.
    }
@@ -75,6 +82,16 @@ class HookEntry : IYukiHookXposedInit {

 通常情况下这种错误不会轻易发生，若一旦发生此错误，请自行查看控制台打印的日志定位问题，确定并非自己的代码发生的问题后，可提交日志进行反馈。

+!> `loggerE` YukiHookAPI bind initZygote failed
+
+**异常原因**
+
+`YukiHookAPI` 在尝试装载 Xposed 原生接口 `initZygote` 方法时发生了不能处理的异常。
+
+**解决方案**
+
+通常情况下这种错误不会轻易发生，若一旦发生此错误，请自行查看控制台打印的日志定位问题，确定并非自己的代码发生的问题后，可提交日志进行反馈。
+
 !> `loggerE` HookClass \[**NAME**\] not found

 **异常原因**
@@ -361,6 +378,50 @@ method {

 请检查查询条件中 `param` 的 `index` 号下标的 `Class` 是否存在，然后再试一次。

+!> `loggerE` Resources Hook condition name/type cannot be empty \[**TAG**\]
+
+**异常原因**
+
+在查找 Resources 时并未设置任何条件。
+
+> 示例如下
+
+```kotlin
+// 情况 1
+conditions {
+    // 这里没有设置任何条件
+}
+// 情况 2
+conditions {
+    name = "test"
+    // 这里缺少了 type 条件
+}
+```
+
+**解决方案**
+
+Resources 的 Hook 并非类似方法的 Hook，其必须拥有完整的名称和类型描述才能查询成功，请将查询条件补充完整并再试一次。
+
+!> `loggerE` Resources Hook type is invalid \[**TAG**\]
+
+**异常原因**
+
+在 Hook Resources 时发生了类型错误的异常。
+
+**解决方案**
+
+`YukiHookAPI` 会尝试在 `initZygote` 与 `handleInitPackageResources` 中装载 Resources Hook，若全部装载失败可能会发生此异常，当前 Hook Framework 需要支持并启用资源钩子(Resources Hook)功能，请检查后再试一次。
+
+!> `loggerE` Resources Hook got an Exception \[**TAG**\]
+
+**异常原因**
+
+在 Hook Resources 时发生了任意的异常。
+
+**解决方案**
+
+这是一个异常汇总，请自行向下查看日志具体的异常是什么，例如找不到 Resources Id 的问题。
+
 ## 阻断异常

 > 这些异常会直接导致 APP 停止运行(FC)，同时会在控制台打印 `E` 级别的日志，还会造成 Hook 进程“死掉”。
@@ -682,6 +743,42 @@ encase {

 `appContext` 在宿主环境初始化完成之前有大的概率可能是空的，请延迟获取或在宿主的 Hook 方法回调方法体内再使用此变量。

+!> `IllegalStateException` Current Hook Framework not support moduleAppResources
+
+**异常原因**
+
+在 `PackageParam` 中调用了 `moduleAppResources` 变量但是无法获取到实例对象。
+
+> 示例如下
+
+```kotlin
+encase {
+    // 调用了此变量
+    moduleAppResources...
+}
+```
+
+**解决方案**
+
+`moduleAppResources` 需要当前 Hook Framework 支持 `initZygote` 功能，请检查后再试一次。
+
+!> `IllegalStateException` You cannot call to appResources in this time
+
+在 `PackageParam` 中调用了 `appResources` 变量但是无法获取到实例对象。
+
+> 示例如下
+
+```kotlin
+encase {
+    // 调用了此变量
+    appResources...
+}
+```
+
+**解决方案**
+
+`appResources` 不会在 `initZygote` 中装载，另外，这个功能需要当前 Hook Framework 支持并启用资源钩子(Resources Hook)功能，请检查后再试一次。
+
 !> `IllegalStateException` VariousClass match failed of those **CLASSES**

 **异常原因**
@@ -713,6 +810,48 @@ TargetClass.hook {

 详情请参考 [状态监听](guide/example?id=状态监听)。

+!> `IllegalStateException` LayoutInflatedParam View instance got null
+
+**异常原因**
+
+在布局 Hook 回调中调用了 `currentView` 但没取到实例对象。
+
+> 示例如下
+
+```kotlin
+injectResource {
+    conditions {
+        name = "activity_main"
+        layout()
+    }
+    injectAsLayout {
+        // 调用了此变量
+        currentView...
+    }
+}
+```
+
+**解决方案**
+
+这种情况基本上不存在，除非被 Hook 的宿主当前 `Activity` 已经销毁或 Hook Framework 自身存在问题。
+
+!> `IllegalStateException` XResForwarder is invalid
+
+**异常原因**
+
+在 `YukiResForwarder` 中调用了 `resources` 但没取到实例对象。
+
+> 示例如下
+
+```kotlin
+// 调用了此变量
+moduleAppResources.fwd(...).resources
+```
+
+**解决方案**
+
+这种情况基本上不存在，除非 Hook Framework 自身存在问题。
+
 !> `IllegalStateException` Hook Members is empty, hook aborted

 **异常原因**
@@ -731,6 +870,24 @@ TargetClass.hook {

 你必须在 `hook` 方法体内加入至少一个 `injectMember` 方法。

+!> `IllegalStateException` Hook Resources is empty, hook aborted
+
+**异常原因**
+
+使用了 `hook` 方法体但其中并没有填写内容。
+
+> 示例如下
+
+```kotlin
+resources().hook {
+    // 这里没有填写任何内容
+}
+```
+
+**解决方案**
+
+你必须在 `hook` 方法体内加入至少一个 `injectResources` 方法。
+
 !> `IllegalStateException` paramTypes is empty, please use emptyParam() instead

 **异常原因**
@@ -771,4 +928,14 @@ method {
    name = "test"
    paramCount = 0
 }
-```
+```
+
+!> `IllegalStateException` Invalid YukiHookCallback type
+
+**异常原因**
+
+`YukiHookAPI` 的核心 Hook 功能发生故障。
+
+**解决方案**
+
+这种情况基本上不存在，若发生上述问题，确定并非自己的代码发生的问题后，可提交日志进行反馈。
--- a/docs/config/r8-proguard.md
+++ b/docs/config/r8-proguard.md
@@ -10,16 +10,7 @@

 > ~~如果你仍然在使用 `Proguard`，你需要做一些规则配置。~~

-~~在 `proguard-rules.pro` 添加如下代码即可。~~
-
-> ~~示例如下~~
-
-```proguard
-keep class com.highcapable.yukihookapi.hook.xposed.YukiHookModuleStatus {*;}
-keep class 这里填你的 HookEntryClass 入口类完整包名_YukiHookXposedInit {*;}
-```
-
-!> Proguard 规则已被弃用，请不要再使用，自从 Android Gradle Plugin 4.2 后，拥有 Android Jetpack 套件最新版本的混淆处理程序默认均为 `R8`，基本可以不需要考虑混淆的问题。
+!> Proguard 规则已被弃用，请不要再使用，自从 Android Gradle Plugin 4.2 后，拥有 Android Jetpack 套件最新版本的混淆处理程序默认均为 `R8`，不再需要考虑混淆的问题。

 若要在任何版本下启用 `R8`，请在 `gradle.properties` 文件中加入如下规则，Android Gradle Plugin 7.0 及以上版本无需任何配置。

--- a/docs/config/xposed-using.md
+++ b/docs/config/xposed-using.md
@@ -96,7 +96,7 @@ Xposed 入口类处理如下。
 > 示例如下

 ```kotlin
-class HookEntry_YukiHookXposedInit: IXposedHookLoadPackage, ...
+class HookEntry_YukiHookXposedInit: IXposedHookZygoteInit, IXposedHookLoadPackage, IXposedHookInitPackageResources
 ```

 编译后的类名结构如下。
@@ -105,6 +105,7 @@ class HookEntry_YukiHookXposedInit: IXposedHookLoadPackage, ...

 ```
 ...hook.HookEntry ← 你的入口类
+...hook.HookEntry_Impl ← 自动生成的 Impl 类
 ...hook.HookEntry_YukiHookXposedInit ← 自动生成的 Xposed 入口类
 ```

@@ -122,7 +123,7 @@ Xposed 入口类处理如下。
 > 示例如下

 ```kotlin
-class HookXposedEntry: IXposedHookLoadPackage, ...
+class HookXposedEntry: IXposedHookZygoteInit, IXposedHookLoadPackage, IXposedHookInitPackageResources
 ```

 编译后的类名结构如下。
@@ -131,6 +132,7 @@ class HookXposedEntry: IXposedHookLoadPackage, ...

 ```
 ...hook.HookEntry ← 你的入口类
+...hook.HookEntry_Impl ← 自动生成的 Impl 类
 ...hook.HookXposedEntry ← 自动生成的 Xposed 入口类
 ```

@@ -138,21 +140,47 @@ class HookXposedEntry: IXposedHookLoadPackage, ...

 ### IYukiHookXposedInit 接口

-```kotlin
-interface IYukiHookXposedInit {
-
-    fun onInit()
-
-    fun onHook()
-}
-```
-
 `IYukiHookXposedInit` 接口为你的 `HookEntryClass` 必须实现的接口，这是你的模块开始 Hook 的起点。

 若要了解更多可 [点击这里](api/document?id=iyukihookxposedinit-interface) 进行查看。

 当你的模块被 Xposed 装载后，`onHook` 方法将会被回调，你需要在此方法中开始使用 `YukiHookAPI`。

-> 基本的调用流程为 `YukiHookInjectXposedInitClass.handleLoadPackage` → `HookEntryClass.onInit` → `HookEntryClass.onHook` → `YukiHookAPI.onXposedLoaded`
+> 基本的调用流程为 `_YukiHookXposedInit` → `IYukiHookXposedInit.onXposedEvent` → `IYukiHookXposedInit.onInit` → `IYukiHookXposedInit.onHook`

-详情请参考 [API 基本配置](config/api-example)。
+详情请参考 [API 基本配置](config/api-example)。
+
+## 原生 Xposed API 事件
+
+若你当前的 Xposed 模块使用了第三方的资源，但是短时间内可能无法转移它们，此时，你可以使用 `onXposedEvent` 实现监听原生 Xposed API 的全部装载事件。
+
+> 示例如下
+
+```kotlin
+@InjectYukiHookWithXposed
+class HookEntry: IYukiHookXposedInit {
+
+    override fun onHook() {
+        // Your code here.
+    }
+
+    override fun onXposedEvent() {
+        // 监听原生 Xposed API 的装载事件
+        YukiXposedEvent.events {
+            onInitZygote {
+                // it 对象即 [StartupParam]
+            }
+            onHandleLoadPackage {
+                // it 对象即 [LoadPackageParam]
+            }
+            onHandleInitPackageResources {
+                // it 对象即 [InitPackageResourcesParam]
+            }
+        }
+    }
+}
+```
+
+`onXposedEvent` 与 `onHook` 方法完全独立存在，互不影响，你可以继续在 `onHook` 方法中使用 `YukiHookAPI`。
+
+若要了解更多可 [点击这里](api/document?id=onxposedevent-method) 进行查看。