From 7a62fc289431aa87deb185accd8409bedb182e8b Mon Sep 17 00:00:00 2001 From: fankesyooni Date: Fri, 22 Sep 2023 21:59:20 +0800 Subject: [PATCH] docs: update some functions --- README-zh-CN.md | 6 -- README.md | 8 -- docs-source/src/.vuepress/configs/template.ts | 4 +- docs-source/src/en/api/features.md | 10 ++ docs-source/src/en/guide/home.md | 4 +- docs-source/src/en/guide/quick-start.md | 102 +++++++++++++++--- docs-source/src/en/index.md | 29 ++++- docs-source/src/zh-cn/api/features.md | 10 ++ docs-source/src/zh-cn/guide/home.md | 4 +- docs-source/src/zh-cn/guide/quick-start.md | 97 ++++++++++++++--- docs-source/src/zh-cn/index.md | 29 ++++- 11 files changed, 256 insertions(+), 47 deletions(-) diff --git a/README-zh-CN.md b/README-zh-CN.md index 419c4b2..c0278b9 100644 --- a/README-zh-CN.md +++ b/README-zh-CN.md @@ -17,12 +17,6 @@ 名称取自 [《ももくり》女主 栗原 雪(Yuki)](https://www.bilibili.com/bangumi/play/ss5016)。 -## 它能做什么 - -取代 Java 原生的反射 API，使用更加人性化的语言实现一套更加完善的反射方案。 - -使用注解的方式声明需要反射的类或方法、变量，构造一个 `stub`，直接调用即可实现与反射 API 相同的功能，更加优雅高效。 (正在开发，预计在后期逐渐实现此功能) - ## 开始使用 [点击这里](https://fankes.github.io/YukiReflection/zh-cn/) 前往文档页面查看更多详细教程和内容。 diff --git a/README.md b/README.md index 57f9b07..6b89ae9 100644 --- a/README.md +++ b/README.md @@ -18,14 +18,6 @@ and it is also the core function being used by [YukiHookAPI](https://github.com/ The name is taken from ["ももくり" heroine Yuki Kurihara](https://www.bilibili.com/bangumi/play/ss5016). -## What it can do - -Instead of Java's native Reflection API, use a more user-friendly language to implement a more complete set of reflection solutions. - -Use annotations to declare classes, methods, and fields that need reflection, construct a `stub`, -and call directly to achieve the same function as the Reflection API, which is more elegant and efficient. -(under development, and it is expected to gradually implement this function later) - ## Get Started [Click here](https://fankes.github.io/YukiReflection/en/) go to the documentation page for more detailed tutorials and content. diff --git a/docs-source/src/.vuepress/configs/template.ts b/docs-source/src/.vuepress/configs/template.ts index 7f4a543..75b3c0a 100644 --- a/docs-source/src/.vuepress/configs/template.ts +++ b/docs-source/src/.vuepress/configs/template.ts @@ -63,11 +63,11 @@ export const configs = { locales: { '/en/': { lang: 'en-US', - description: 'An efficient Reflection API for the Android platform built in Kotlin' + description: 'An efficient Reflection API for Java and Android built in Kotlin' }, '/zh-cn/': { lang: 'zh-CN', - description: '一个使用 Kotlin 构建的 Android 平台高效反射 API' + description: '一个使用 Kotlin 构建的用于 Java 和 Android 平台高效反射 API' } } }, diff --git a/docs-source/src/en/api/features.md b/docs-source/src/en/api/features.md index 3e34a21..0153edc 100644 --- a/docs-source/src/en/api/features.md +++ b/docs-source/src/en/api/features.md @@ -126,6 +126,8 @@ At this point, there is `DexClassFinder`, its role is to determine the instance ::: warning +**This feature is only available on the Android platform.** + At present, the function of **DexClassFinder** is still in the experimental stage. Since the search function is only implemented through the Java layer, the performance may not reach the optimal level when there are too many current app's **Class**. @@ -142,6 +144,14 @@ Please note that the more the same type **Class** is matched, the slower the spe ::: +::: danger + +After **YukiHookAPI** 2.x.x released, this function will be deprecated and will be removed directly from **YukiReflection**. + +We welcome all developers to start using [DexKit](https://github.com/LuckyPray/DexKit), which is a high-performance runtime parsing library for **Dex** implemented in C++, which is more efficient than the Java layer in terms of performance, efficient and excellent, it is still in the development stage, your valuable suggestions are welcome. + +::: + #### Get Started Below is a simple usage example. diff --git a/docs-source/src/en/guide/home.md b/docs-source/src/en/guide/home.md index aaf50c2..d406fcf 100644 --- a/docs-source/src/en/guide/home.md +++ b/docs-source/src/en/guide/home.md @@ -1,6 +1,6 @@ # Introduce -> `YukiReflection` is a Reflection API based on the Android platform. +> `YukiReflection` is a Reflection API based on the Java and Android platform. ## Background @@ -24,7 +24,7 @@ All Demo sample codes in the document will be described using `Kotlin`, if you d ## Source of Inspiration -`YukiReflection` was originally the core function integrated in the [YukiHookAPI](https://github.com/fankes/YukiHookAPI) project, and now it is decoupled so that this Reflection API can be used in any Android platform project. +`YukiReflection` was originally the core function integrated in the [YukiHookAPI](https://github.com/fankes/YukiHookAPI) project, and now it is decoupled so that this Reflection API can be used in any Java and Android platform project. Now, we only need to write a small amount of code to implement a simple reflection call. diff --git a/docs-source/src/en/guide/quick-start.md b/docs-source/src/en/guide/quick-start.md index 8ff4196..66c773c 100644 --- a/docs-source/src/en/guide/quick-start.md +++ b/docs-source/src/en/guide/quick-start.md @@ -16,51 +16,127 @@ - Gradle 7.0 and above -- JVM 11 and above +- Java 11 and above ## Project Requirements -The project needs to be created using `Android Studio` or `IntelliJ IDEA` and the type is an Android project and the `Kotlin` environment dependency has been integrated. +The project needs to be created using `Android Studio` or `IntelliJ IDEA` and the type is an Java or Android project and the `Kotlin` environment dependency has been integrated. ## Integration Dependencies -**(Optional)** Add dependencies to your project `build.gradle`. +We recommend using Kotlin DSL as the Gradle build script language and [SweetDependency](https://github.com/HighCapable/SweetDependency) to manage dependencies. + +#### SweetDependency Method + +Add the repositories and dependencies in your project's `SweetDependency` configuration file. > The following example +```yaml +repositories: + # MavenCentral has a 2-hour cache, + # if the latest version cannot be integrated, please add this + sonatype-oss-releases: + +libraries: + com.highcapable.yukireflection: + api: + version: + + ... +``` + +After adding it, run Gradle Sync and all dependencies will be autowired. + +Next, deploy dependencies in your project `build.gradle.kts`. + +> The following example + +```kotlin +dependencies { + implementation(com.highcapable.yukireflection.api) + // ... +} +``` + +#### Traditional Method (Not Recommended) + +Add repositories in your project `build.gradle.kts` or `build.gradle`. + +> Kotlin DSL + +```kotlin +repositories { + google() + mavenCentral() + // MavenCentral has a 2-hour cache, if the latest version cannot be integrated, please add this URL + maven { url("https://s01.oss.sonatype.org/content/repositories/releases/") } +} +``` + +> Groovy DSL + ```groovy repositories { google() mavenCentral() - // MavenCentral has a 2-hour cache, if you cannot integrate the latest version, please add this address - maven { url "https://s01.oss.sonatype.org/content/repositories/releases" } + // MavenCentral has a 2-hour cache, if the latest version cannot be integrated, please add this URL + maven { url 'https://s01.oss.sonatype.org/content/repositories/releases/' } } ``` -Add dependencies to your app `build.gradle`. +Add dependencies in your project `build.gradle.kts` or `build.gradle`. -> The following example +> Kotlin DSL + +```kotlin +dependencies { + implementation("com.highcapable.yukireflection:api:") + // ... +} +``` + +> Groovy DSL ```groovy dependencies { - // Base dependencies implementation 'com.highcapable.yukireflection:api:' + // ... } ``` -Please change **<yuki-version>** to the latest version from [here](../about/changelog). +Please change **<yuki-version>** to the latest version [here](../about/changelog). ::: danger -If your project is currently using [YukiHookAPI](https://github.com/fankes/YukiHookAPI), please do not repeatedly integrate **YukiReflection**, because **YukiHookAPI** already contains the functions and exists for related functional changes and repeated integration will cause functional conflicts and cause exceptions. +If your project is currently using the 1.x.x version of [YukiHookAPI](https://github.com/fankes/YukiHookAPI), please do not integrate **YukiReflection** repeatedly, because **YukiHookAPI** already includes it functions and there are changes to related functions. -At this time, you should go to the [documentation](https://fankes.github.io/YukiHookAPI/en/) of **YukiHookAPI** to view the corresponding tutorial. +Repeated integration will cause functional conflicts and cause exceptions. + +In this case, you should go to the [Documentation](https://fankes.github.io/YukiHookAPI/zh-cn/) of **YukiHookAPI** view the corresponding usage tutorial. + +**YukiHookAPI** will be completely separated from **YukiReflection** in version 2.x.x, by which time you can use it with **YukiHookAPI** at the same time. ::: -Modify the `Kotlin` Jvm version to 11 and above in your app `build.gradle`. +#### Configure Java Version -> The following example +Modify the Java version of Kotlin in your project `build.gradle.kts` or `build.gradle` to 11 or above. + +> Kotlin DSL + +```kt +android { + compileOptions { + sourceCompatibility = JavaVersion.VERSION_11 + targetCompatibility = JavaVersion.VERSION_11 + } + kotlinOptions { + jvmTarget = "11" + } +} +``` + +> Groovy DSL ```groovy android { diff --git a/docs-source/src/en/index.md b/docs-source/src/en/index.md index c153ebe..8cf10ea 100644 --- a/docs-source/src/en/index.md +++ b/docs-source/src/en/index.md @@ -9,5 +9,32 @@ actions: - text: Changelog link: /en/about/changelog type: secondary +features: + - title: Light and Elegant + details: A powerful, elegant, beautiful API built with Kotlin lambda can help you quickly implement bytecode finding and reflection functions. + - title: Cross-Platform Available + details: Not only the Android platform, it is highly compatible with the Java API and can be used on any Kotlin on JVM project, wherever Java is available. + - title: Quickly Started + details: Simple and easy to use it now! Do not need complex configuration and full development experience, Integrate dependencies and enjoy yourself. footer: MIT License | Copyright (C) 2019-2023 HighCapable ---- \ No newline at end of file +--- + +### Bring it on! Let reflection become poetic and picturesque + +```java +public class World { + + private void sayHello(String content) { + System.out.println("Hello " + content + "!"); + } +} +``` + +```kotlin +val newWorld = World() +classOf().method { + name = "sayHello" + param(StringClass) + type = UnitType +}.get(newWorld).call("YukiReflection") +``` \ No newline at end of file diff --git a/docs-source/src/zh-cn/api/features.md b/docs-source/src/zh-cn/api/features.md index 73eb92d..a851e7b 100644 --- a/docs-source/src/zh-cn/api/features.md +++ b/docs-source/src/zh-cn/api/features.md @@ -118,6 +118,8 @@ var isExist = "com.demo.Test".hasClass(customClassLoader) ::: warning +**此功能仅适用于 Android 平台。** + 目前 **DexClassFinder** 的功能尚在试验阶段，由于仅通过 Java 层实现查找功能，在当前 APP **Class** 过多时性能可能不能达到最佳水平，如果发生查找不到、定位有误的问题欢迎向我们反馈。 由于是反射层面的 API，目前它只能通过**类与成员**的特征来定位指定的 **Class**，不能通过指定字节码中的字符串和方法内容特征来进行定位。 @@ -126,6 +128,14 @@ var isExist = "com.demo.Test".hasClass(customClassLoader) ::: +::: danger + +在 **YukiHookAPI** 发布 2.x.x 版本后，此功能将被标记为作废，且将会直接从 **YukiReflection** 中移除。 + +我们欢迎各位开发者开始使用 [DexKit](https://github.com/LuckyPray/DexKit)，它是一个使用 C++ 实现的 **Dex** 高性能运行时解析库，在性能方面比 Java 层更加高效与优秀，目前尚在开发阶段，欢迎提出宝贵建议。 + +::: + #### 开始使用 下面是一个简单的用法示例。 diff --git a/docs-source/src/zh-cn/guide/home.md b/docs-source/src/zh-cn/guide/home.md index 8d2d570..4a42e24 100644 --- a/docs-source/src/zh-cn/guide/home.md +++ b/docs-source/src/zh-cn/guide/home.md @@ -1,6 +1,6 @@ # 介绍 -> `YukiReflection` 是一个基于 Android 平台的反射 API。 +> `YukiReflection` 是一个基于 Java 和 Android 平台的反射 API。 ## 背景 @@ -24,7 +24,7 @@ ## 灵感来源 -`YukiReflection` 最初是集成在 [YukiHookAPI](https://github.com/fankes/YukiHookAPI) 项目中的核心功能，现在进行了解耦合，使得这套反射 API 可以在任何 Android 平台的项目中使用。 +`YukiReflection` 最初是集成在 [YukiHookAPI](https://github.com/fankes/YukiHookAPI) 项目中的核心功能，现在进行了解耦合，使得这套反射 API 可以在任何 Java 和 Android 平台的项目中使用。 现在，我们只需要编写少量的代码，就能实现一个简单的反射调用。 diff --git a/docs-source/src/zh-cn/guide/quick-start.md b/docs-source/src/zh-cn/guide/quick-start.md index 8ee4423..231e714 100644 --- a/docs-source/src/zh-cn/guide/quick-start.md +++ b/docs-source/src/zh-cn/guide/quick-start.md @@ -4,7 +4,7 @@ ## 环境要求 -- Windows 7 及以上/macOS 10.14 及以上/Linux 发行版(Arch/Debian) +- Windows 7 及以上/macOS 10.14 及以上/Linux 发行版 (Arch/Debian) - Android Studio 2021.1 及以上 @@ -16,35 +16,90 @@ - Gradle 7.0 及以上 -- Jvm 11 及以上 +- Java 11 及以上 ## 项目要求 -项目需要使用 `Android Studio` 或 `IntelliJ IDEA` 创建且类型为 Android 项目并已集成 `Kotlin` 环境依赖。 +项目需要使用 `Android Studio` 或 `IntelliJ IDEA` 创建且类型为 Java 或 Android 项目并已集成 `Kotlin` 环境依赖。 -## 集成依赖 +### 集成依赖 -**(可选)** 在你的项目 `build.gradle` 中添加依赖。 +我们推荐使用 Kotlin DSL 作为 Gradle 构建脚本语言并推荐使用 [SweetDependency](https://github.com/HighCapable/SweetDependency) 来管理依赖。 + +#### SweetDependency 方式 + +在你的项目 `SweetDependency` 配置文件中添加存储库和依赖。 > 示例如下 +```yaml +repositories: + # MavenCentral 有 2 小时缓存，若无法集成最新版本请添加 + sonatype-oss-releases: + +libraries: + com.highcapable.yukireflection: + api: + version: + + ... +``` + +添加完成后运行一次 Gradle Sync，所有依赖版本将自动装配。 + +接下来，在你的项目 `build.gradle.kts` 中部署依赖。 + +> 示例如下 + +```kotlin +dependencies { + implementation(com.highcapable.yukireflection.api) + // ... +} +``` + +#### 传统方式 (不推荐) + +在你的项目 `build.gradle.kts` 或 `build.gradle` 中添加存储库。 + +> Kotlin DSL + +```kotlin +repositories { + google() + mavenCentral() + // MavenCentral 有 2 小时缓存，若无法集成最新版本请添加此地址 + maven { url("https://s01.oss.sonatype.org/content/repositories/releases/") } +} +``` + +> Groovy DSL + ```groovy repositories { google() mavenCentral() // MavenCentral 有 2 小时缓存，若无法集成最新版本请添加此地址 - maven { url "https://s01.oss.sonatype.org/content/repositories/releases" } + maven { url 'https://s01.oss.sonatype.org/content/repositories/releases/' } } ``` -在你的 app `build.gradle` 中添加依赖。 +在你的项目 `build.gradle.kts` 或 `build.gradle` 中添加依赖。 -> 示例如下 +> Kotlin DSL + +```kotlin +dependencies { + implementation("com.highcapable.yukireflection:api:") + // ... +} +``` + +> Groovy DSL ```groovy dependencies { - // 基础依赖 implementation 'com.highcapable.yukireflection:api:' + // ... } ``` @@ -52,13 +107,31 @@ dependencies { ::: danger -如果你的项目目前正在使用 [YukiHookAPI](https://github.com/fankes/YukiHookAPI)，请不要重复集成 **YukiReflection**，因为 **YukiHookAPI** 已经包含了其中的功能且存在针对相关功能的改动，重复集成会造成功能性冲突引发异常，此时你应该前往 **YukiHookAPI** 的 [文档](https://fankes.github.io/YukiHookAPI/zh-cn/) 查看对应使用教程。 +如果你的项目目前正在使用 [YukiHookAPI](https://github.com/fankes/YukiHookAPI) 的 1.x.x 版本，请不要重复集成 **YukiReflection**，因为 **YukiHookAPI** 已经包含了其中的功能且存在针对相关功能的改动，重复集成会造成功能性冲突引发异常，此时你应该前往 **YukiHookAPI** 的 [文档](https://fankes.github.io/YukiHookAPI/zh-cn/) 查看对应的使用教程。 + +**YukiHookAPI** 将在 2.x.x 版本完全分离 **YukiReflection**，届时你可以同时与 **YukiHookAPI** 使用。 ::: -在你的 app `build.gradle` 中修改 `Kotlin` 的 Jvm 版本为 11 及以上。 +#### 配置 Java 版本 -> 示例如下 +在你的项目 `build.gradle.kts` 或 `build.gradle` 中修改 Kotlin 的 Java 版本为 11 及以上。 + +> Kotlin DSL + +```kt +android { + compileOptions { + sourceCompatibility = JavaVersion.VERSION_11 + targetCompatibility = JavaVersion.VERSION_11 + } + kotlinOptions { + jvmTarget = "11" + } +} +``` + +> Groovy DSL ```groovy android { diff --git a/docs-source/src/zh-cn/index.md b/docs-source/src/zh-cn/index.md index 9908c96..bfe1b04 100644 --- a/docs-source/src/zh-cn/index.md +++ b/docs-source/src/zh-cn/index.md @@ -9,5 +9,32 @@ actions: - text: 更新日志 link: /zh-cn/about/changelog type: secondary +features: + - title: 轻量优雅 + details: 拥有一套强大、优雅、人性化、完全使用 Kotlin lambda 打造的 API，可以帮你快速实现字节码的查找以及反射功能。 + - title: 可跨平台 + details: 不仅仅是 Android 平台，它与 Java API 高度兼容，可使用在任何 Kotlin on JVM 的项目上，有 Java 的地方就可以使用。 + - title: 快速上手 + details: 简单易用，不需要繁琐的配置，不需要十足的开发经验，搭建环境集成依赖即可立即开始使用。 footer: MIT License | Copyright (C) 2019-2023 HighCapable ---- \ No newline at end of file +--- + +### 来吧！让反射也变得诗情画意 + +```java +public class World { + + private void sayHello(String content) { + System.out.println("Hello " + content + "!"); + } +} +``` + +```kotlin +val newWorld = World() +classOf().method { + name = "sayHello" + param(StringClass) + type = UnitType +}.get(newWorld).call("YukiReflection") +``` \ No newline at end of file