mirror of
https://github.com/BetterAndroid/Hikage.git
synced 2025-09-09 12:04:21 +08:00
Bump hikage-core, hikage-extension, hikage-extension-betterandroid, hikage-extension-compose, hikage-compiler, hikage-widget-androidx, hikage-widget-material version to 1.0.0
This commit is contained in:
169
docs-source/src/zh-cn/library/hikage-compiler.md
Normal file
169
docs-source/src/zh-cn/library/hikage-compiler.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# hikage-compiler
|
||||
|
||||
|
||||
<span style="margin-left: 5px"/>
|
||||
|
||||
<span style="margin-left: 5px"/>
|
||||
|
||||
|
||||
这是 Hikage 的自动化编译模块。
|
||||
|
||||
## 配置依赖
|
||||
|
||||
你可以使用如下方式将此模块添加到你的项目中。
|
||||
|
||||
::: warning
|
||||
|
||||
你需要在你的项目中集成适合于你项目当前 Kotlin 版本的 [Google KSP](https://github.com/google/ksp/releases) 插件。
|
||||
|
||||
:::
|
||||
|
||||
### SweetDependency (推荐)
|
||||
|
||||
在你的项目 `SweetDependency` 配置文件中添加依赖。
|
||||
|
||||
```yaml
|
||||
plugins:
|
||||
com.google.devtools.ksp:
|
||||
version: +
|
||||
|
||||
libraries:
|
||||
com.highcapable.hikage:
|
||||
hikage-compiler:
|
||||
version: +
|
||||
```
|
||||
|
||||
在你的根项目 `build.gradle.kts` 中配置依赖。
|
||||
|
||||
```kotlin
|
||||
plugins {
|
||||
// ...
|
||||
autowire(libs.plugins.com.google.devtools.ksp) apply false
|
||||
}
|
||||
```
|
||||
|
||||
在你的项目 `build.gradle.kts` 中配置依赖。
|
||||
|
||||
```kotlin
|
||||
plugins {
|
||||
// ...
|
||||
autowire(libs.plugins.com.google.devtools.ksp)
|
||||
}
|
||||
|
||||
dependencies {
|
||||
// ...
|
||||
ksp(com.highcapable.hikage.hikage.compiler)
|
||||
}
|
||||
```
|
||||
|
||||
### 传统方式
|
||||
|
||||
在你的根项目 `build.gradle.kts` 中配置依赖。
|
||||
|
||||
```kotlin
|
||||
plugins {
|
||||
// ...
|
||||
id("com.google.devtools.ksp") version "<ksp-version>" apply false
|
||||
}
|
||||
```
|
||||
|
||||
在你的项目 `build.gradle.kts` 中配置依赖。
|
||||
|
||||
```kotlin
|
||||
plugins {
|
||||
// ...
|
||||
id("com.google.devtools.ksp")
|
||||
}
|
||||
|
||||
dependencies {
|
||||
// ...
|
||||
ksp("com.highcapable.hikage:hikage-compiler:<version>")
|
||||
}
|
||||
```
|
||||
|
||||
请将 `<version>` 修改为此文档顶部显示的版本，并将 `<ksp-version>` 修改为你项目当前使用的 Kotlin 版本对应的 KSP 版本。
|
||||
|
||||
## 功能介绍
|
||||
|
||||
Hikage 的编译模块将在运行时自动生成代码，在更新后，请重新运行 `assembleDebug` 或 `assembleRelease` Task 以生成最新的代码。
|
||||
|
||||
### 生成布局组件
|
||||
|
||||
Hikage 可以在编译时为指定的布局组件自动生成布局组件对应的 `Hikageable` 函数。
|
||||
|
||||
#### 自定义 View
|
||||
|
||||
你可以在你的自定义 `View` 上加入 `HikageView` 注解，以标记它生成为 Hikage 布局组件。
|
||||
|
||||
| 参数名称 | 描述 |
|
||||
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
|
||||
| `lparams` | 布局参数 `ViewGroup.LayoutParams` Class 对象，如果你的自定义 `View` 是 `ViewGroup` 的子类，则可以声明或留空使用默认值 |
|
||||
| `alias` | 布局组件的别名，即要生成的函数名称，默认获取当前 Class 的名称 |
|
||||
| `requireInit` | 是否要求填写布局的初始化方法块，默认为可省略的参数 |
|
||||
| `requirePerformer` | 是否要求填写布局的 `performer` 方法块，默认为可省略的参数，仅在你的自定义 `View` 是 `ViewGroup` 的子类时生效 |
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
@HikageView(lparams = LinearLayout.LayoutParams::class)
|
||||
class MyLayout(context: Context, attrs: AttributeSet? = null) : LinearLayout(context, attrs) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
编译后，你就可以在 Hikage 布局中使用 `MyLayout` 作为布局组件了。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
Hikageable {
|
||||
MyLayout {
|
||||
TextView(
|
||||
lparams = LayoutParams {
|
||||
topMargin = 16.dp
|
||||
}
|
||||
) {
|
||||
text = "Hello, World!"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 第三方组件
|
||||
|
||||
Hikage 同样可以为第三方提供的 `View` 组件自动生成布局组件函数，你可以使用 `HikageViewDeclaration` 注解来完成。
|
||||
|
||||
| 参数名称 | 描述 |
|
||||
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
|
||||
| `view` | 需要声明的布局组件的 Class 对象 |
|
||||
| `lparams` | 布局参数 `ViewGroup.LayoutParams` Class 对象，如果你的自定义 `View` 是 `ViewGroup` 的子类，则可以声明或留空使用默认值 |
|
||||
| `alias` | 布局组件的别名，即要生成的函数名称，默认获取 `view` Class 的名称 |
|
||||
| `requireInit` | 是否要求填写布局的初始化方法块，默认为可省略的参数 |
|
||||
| `requirePerformer` | 是否要求填写布局的 `performer` 方法块，默认为可省略的参数，仅在你的自定义 `View` 是 `ViewGroup` 的子类时生效 |
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
@HikageViewDeclaration(ThirdPartyView::class)
|
||||
object ThirdPartyViewDeclaration
|
||||
```
|
||||
|
||||
这个注解可以声明到任意一个 `object` 类上，仅作为注解扫描器需要自动纳入的类来使用，你可以将可见性设为 `private`，但要确保被注解的类一定是使用 `object` 修饰的。
|
||||
|
||||
同样地，编译后，你就可以在 Hikage 布局中使用 `ThirdPartyView` 作为布局组件了。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
Hikageable {
|
||||
ThirdPartyView {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
::: tip
|
||||
|
||||
Hikage 生成布局组件的函数包名路径为 `com.highcapable.hikage.widget` + 你的 `View` 或第三方 `View` 组件的完整包名。
|
||||
|
||||
:::
|
||||
502
docs-source/src/zh-cn/library/hikage-core.md
Normal file
502
docs-source/src/zh-cn/library/hikage-core.md
Normal file
@@ -0,0 +1,502 @@
|
||||
# hikage-core
|
||||
|
||||
|
||||
<span style="margin-left: 5px"/>
|
||||
|
||||
<span style="margin-left: 5px"/>
|
||||
|
||||
|
||||
这是 Hikage 的核心依赖，你需要引入此模块才能使用 Hikage 的基本功能。
|
||||
|
||||
## 配置依赖
|
||||
|
||||
你可以使用如下方式将此模块添加到你的项目中。
|
||||
|
||||
### SweetDependency (推荐)
|
||||
|
||||
在你的项目 `SweetDependency` 配置文件中添加依赖。
|
||||
|
||||
```yaml
|
||||
libraries:
|
||||
com.highcapable.hikage:
|
||||
hikage-core:
|
||||
version: +
|
||||
```
|
||||
|
||||
在你的项目 `build.gradle.kts` 中配置依赖。
|
||||
|
||||
```kotlin
|
||||
implementation(com.highcapable.hikage.hikage.core)
|
||||
```
|
||||
|
||||
### 传统方式
|
||||
|
||||
在你的项目 `build.gradle.kts` 中配置依赖。
|
||||
|
||||
```kotlin
|
||||
implementation("com.highcapable.hikage:hikage-core:<version>")
|
||||
```
|
||||
|
||||
请将 `<version>` 修改为此文档顶部显示的版本。
|
||||
|
||||
## 功能介绍
|
||||
|
||||
你可以 [点击这里](kdoc://hikage-core) 查看 KDoc。
|
||||
|
||||
### 基本用法
|
||||
|
||||
使用下方的代码创建你的第一个 Hikage 布局。
|
||||
|
||||
首先，使用 `Hikageable` 创建一个 `Hikage.Delegate` 对象。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
val myLayout = Hikageable {
|
||||
LinearLayout {
|
||||
TextView {
|
||||
text = "Hello, World!"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
然后，将其设置到你想要显示的父布局或根布局上。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
// 假设这就是你的 Activity
|
||||
val activity: Activity
|
||||
// 实例化 Hikage 对象
|
||||
val hikage = myLayout.create(activity)
|
||||
// 得到根布局
|
||||
val root = hikage.root
|
||||
// 设置为 Activity 的内容视图
|
||||
activity.setContentView(root)
|
||||
```
|
||||
|
||||
这样我们就完成了一个简单的布局创建与设置。
|
||||
|
||||
### 布局约定
|
||||
|
||||
Hikage 的布局基本元素基于 Android 原生的 `View` 组件，所有的布局元素都可以直接使用 Android 原生的 `View` 组件进行创建。
|
||||
|
||||
所有布局的创建过程都会被限定在指定的作用域 `Hikage.Performer` 中，它被称为布局的 “演奏者”，即饰演布局的角色对象，这个对象可以通过以下几种方式创建并维护。
|
||||
|
||||
#### Hikageable
|
||||
|
||||
正如 [基本用法](#基本用法) 所示，`Hikageable` 可以直接创建一个 `Hikage.Delegate` 或 `Hikage` 对象，在 DSL 中，你可以得到 `Hikage.Performer` 对象对布局内容进行创建。
|
||||
|
||||
第一种方案，在任意地方创建。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
// myLayout 是 Hikage.Delegate 对象
|
||||
val myLayout = Hikageable {
|
||||
// ...
|
||||
}
|
||||
// 假设这就是你的 Context
|
||||
val context: Context
|
||||
// 在需要 Context 的地方实例化 Hikage 对象
|
||||
val hikage = myLayout.create(context)
|
||||
```
|
||||
|
||||
第二种方案，在存在 `Context` 的地方直接创建。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
// 假设这就是你的 Context
|
||||
val context: Context
|
||||
// 创建布局，myLayout 是 Hikage 对象
|
||||
val myLayout = Hikageable(context) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### HikageBuilder
|
||||
|
||||
除了上述的方式以外，你还可以维护一个 `HikageBuilder` 对象来预创建布局。
|
||||
|
||||
首先，我们需要创建一个 `HikageBuilder` 对象并定义为单例。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
object MyLayout : HikageBuilder {
|
||||
|
||||
override fun build() = Hikageable {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
然后，在需要的地方使用它，可以有如下两种方案。
|
||||
|
||||
第一种方案，直接使用 `build` 创建 `Hikage.Delegate` 对象。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
// myLayout 是 Hikage.Delegate 对象
|
||||
val myLayout = MyLayout.build()
|
||||
// 假设这就是你的 Context
|
||||
val context: Context
|
||||
// 在需要 Context 的地方实例化 Hikage 对象
|
||||
val hikage = myLayout.create(context)
|
||||
```
|
||||
|
||||
第二种方案，使用 `Context.lazyHikage` 创建 `Hikage` 委托对象。
|
||||
|
||||
例如，我们可以在 `Activity` 中像 `ViewBinding` 一样使用它。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
class MyActivity : AppCompatActivity() {
|
||||
|
||||
private val myLayout by lazyHikage(MyLayout)
|
||||
|
||||
override fun onCreate(savedInstanceState: Bundle?) {
|
||||
super.onCreate(savedInstanceState)
|
||||
// 得到根布局
|
||||
val root = myLayout.root
|
||||
// 设置为 Activity 的内容视图
|
||||
setContentView(root)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 基本布局组件
|
||||
|
||||
Hikage 采用与 Jetpack Compose 一致的函数式创建组件方案，它的布局使用两种基础组件完成，`View` 和 `ViewGroup` 函数，
|
||||
它们分别对应于 Android 原生基于 `View` 和 `ViewGroup` 的组件。
|
||||
|
||||
#### View
|
||||
|
||||
`View` 函数的基础参数为以下三个，使用泛型定义创建的 `View` 对象类型。
|
||||
|
||||
如果不声明泛型类型，默认使用 `android.view.View` 作为创建的对象类型。
|
||||
|
||||
| 参数名称 | 描述 |
|
||||
| --------- | ------------------------------------------------------------------- |
|
||||
| `lparams` | 布局参数，即 `ViewGroup.LayoutParams`，使用 `LayoutParams` 进行创建 |
|
||||
| `id` | 用于查找已创建对象的 ID，使用字符串定义 |
|
||||
| `init` | `View` 的初始化方法体，作为最后一位 DSL 参数传入 |
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
View<TextView>(
|
||||
lparams = LayoutParams(),
|
||||
id = "my_text_view"
|
||||
) {
|
||||
text = "Hello, World!"
|
||||
textSize = 16f
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
```
|
||||
|
||||
#### ViewGroup
|
||||
|
||||
`ViewGroup` 函数的基础参数为四个，比较于 `View` 函数多了一个 `performer` 参数。
|
||||
|
||||
它必须声明一个泛型类型，因为 `ViewGroup` 是抽象类，需要一个具体的实现类。
|
||||
|
||||
`ViewGroup` 额外提供一个基于 `ViewGroup.LayoutParams` 的泛型参数，用于为子布局提供布局参数，不声明时默认使用 `ViewGroup.LayoutParams`。
|
||||
|
||||
| 参数名称 | 描述 |
|
||||
| ----------- | ------------------------------------------------------------------- |
|
||||
| `lparams` | 布局参数，即 `ViewGroup.LayoutParams`，使用 `LayoutParams` 进行创建 |
|
||||
| `id` | 用于查找已创建对象的 ID，使用字符串定义 |
|
||||
| `init` | `ViewGroup` 的初始化方法体，作为 DSL 参数传入 |
|
||||
| `performer` | `Hikage.Performer` 对象，作为最后一位 DSL 参数传入 |
|
||||
|
||||
`performer` 参数的作用是向下传递新的 `Hikage.Performer` 对象，作为子布局的创建者。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
ViewGroup<LinearLayout, LinearLayout.LayoutParams>(
|
||||
lparams = LayoutParams(),
|
||||
id = "my_linear_layout",
|
||||
// 初始化方法体将在这里使用 `init` 体现
|
||||
init = {
|
||||
orientation = LinearLayout.VERTICAL
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
) {
|
||||
// 可在这里继续创建子布局
|
||||
View()
|
||||
}
|
||||
```
|
||||
|
||||
#### LayoutParams
|
||||
|
||||
Hikage 中的布局均可使用 `LayoutParams` 函数设置布局参数，你可以使用以下参数创建它。
|
||||
|
||||
| 参数名称 | 描述 |
|
||||
| ------------------- | ------------------------------------------------- |
|
||||
| `width` | 手动指定布局宽度 |
|
||||
| `height` | 手动指定布局高度 |
|
||||
| `matchParent` | 是否使用 `MATCH_PARENT` 作为布局宽度和高度 |
|
||||
| `wrapContent` | 是否使用 `WRAP_CONTENT` 作为布局宽度和高度 |
|
||||
| `widthMatchParent` | 仅设置宽度为 `MATCH_PARENT` |
|
||||
| `heightMatchParent` | 仅设置高度为 `MATCH_PARENT` |
|
||||
| `body` | 布局参数的初始化方法体，作为最后一位 DSL 参数传入 |
|
||||
|
||||
在你不设置 `LayoutParams` 对象或不指定 `width` 和 `height` 时，Hikage 会自动使用 `WRAP_CONTENT` 作为布局参数。
|
||||
|
||||
`body` 方法体的类型来源于上层 [ViewGroup](#viewgroup) 提供的第二位泛型参数。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
View(
|
||||
// 假设上层提供的布局参数类型为 LinearLayout.LayoutParams
|
||||
lparams = LayoutParams(width = 100.dp) {
|
||||
topMargin = 20.dp
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
如果你只需要一个横向填充的布局，可以直接使用 `widthMatchParent = true`。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
View(
|
||||
lparams = LayoutParams(widthMatchParent = true)
|
||||
)
|
||||
```
|
||||
|
||||
#### Layout
|
||||
|
||||
Hikage 支持引用第三方布局，你可以传入 XML 布局资源 ID、其它 Hikage 对象以及 `View` 对象，甚至是 `ViewBinding`。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
ViewGroup<...> {
|
||||
// 引用 XML 布局资源 ID
|
||||
Layout(R.layout.my_layout)
|
||||
// 引用 ViewBinding
|
||||
Layout<MyLayoutBinding>()
|
||||
// 引用另一个 Hikage 或 Hikage.Delegate 对象
|
||||
Layout(myLayout)
|
||||
}
|
||||
```
|
||||
|
||||
### 定位布局组件
|
||||
|
||||
Hikage 支持使用 `id` 定位组件，在上面的示例中，我们使用了 `id` 参数设置了组件的 ID。
|
||||
|
||||
在设置 ID 后，你可以使用 `Hikage.get` 方法获取它们。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
val myLayout = Hikageable {
|
||||
View<TextView>(id = "my_text_view") {
|
||||
text = "Hello, World!"
|
||||
}
|
||||
}
|
||||
// 假设这就是你的 Context
|
||||
val context: Context
|
||||
// 在需要 Context 的地方实例化 Hikage 对象
|
||||
val hikage = myLayout.create(context)
|
||||
// 获取指定的组件，返回 View 类型
|
||||
val textView = hikage["my_text_view"]
|
||||
// 获取指定的组件并声明组件类型
|
||||
val textView = hikage.get<TextView>("my_text_view")
|
||||
// 如果不确定 ID 是否存在，可以使用 `getOrNull` 方法
|
||||
val textView = hikage.getOrNull<TextView>("my_text_view")
|
||||
```
|
||||
|
||||
### 自定义布局组件
|
||||
|
||||
Hikage 为 Android 基础的布局组件提供了组件类名对应的函数，你可以直接使用这些函数创建组件，而无需再使用泛型声明它们，如果你需要 Jetpack 或者 Material 提供的组件，
|
||||
可以引入 [hikage-widget-androidx](../library/hikage-widget-androidx.md) 或 [hikage-widget-material](../library/hikage-widget-material.md) 模块。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
LinearLayout(
|
||||
lparams = LayoutParams(),
|
||||
id = "my_linear_layout",
|
||||
init = {
|
||||
orientation = LinearLayout.VERTICAL
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
) {
|
||||
TextView(
|
||||
lparams = LayoutParams(),
|
||||
id = "my_text_view"
|
||||
) {
|
||||
text = "Hello, World!"
|
||||
textSize = 16f
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
初始化后的 `View` 或 `ViewGroup` 对象会返回其自身对象类型的实例，你可以在接下来的布局中使用它们。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
val textView = TextView {
|
||||
text = "Hello, World!"
|
||||
textSize = 16f
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
Button {
|
||||
text = "Click Me!"
|
||||
setOnClickListener {
|
||||
// 直接使用 textView 对象
|
||||
textView.text = "Clicked!"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果提供的组件不满足你的需求，你可以手动创建自己的组件。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
// 假设你已经定义好了你的自定义组件
|
||||
class MyCustomView(context: Context, attrs: AttributeSet? = null) : View(context, attrs) {
|
||||
// ...
|
||||
}
|
||||
|
||||
// 下面，创建组件对应的函数
|
||||
// 自定义组件必须声明此注解
|
||||
// 声明组件的注解具有传染性，在每个用于构建布局的作用域中，都需要存在此注解
|
||||
@Hikageable
|
||||
// 函数的命名可以随意，但是建议使用大驼峰命名
|
||||
// 函数的签名部分需要固定声明为 `inline fun <reified LP : ViewGroup.LayoutParams> Hikage.Performer<LP>`
|
||||
inline fun <reified LP : ViewGroup.LayoutParams> Hikage.Performer<LP>.MyCustomView(
|
||||
lparams: Hikage.LayoutParams? = null,
|
||||
id: String? = null,
|
||||
init: HikageView<MyCustomView> = {},
|
||||
// 如果此组件是容器，可以声明一个 `performer` 参数
|
||||
// performer: HikagePerformer<LP> = {}
|
||||
) = View<MyCustomView>(lparams, id, init)
|
||||
```
|
||||
|
||||
每次都手动实现这样复杂的函数看起来会很繁琐，如果你希望能够自动生成组件函数，可以引入并参考 [hikage-compiler](../library/hikage-compiler.md) 模块。
|
||||
|
||||
### 自定义布局装载器
|
||||
|
||||
Hikage 支持自定义布局装载器并同时兼容 `LayoutInflater.Factory2`，你可以通过以下方式自定义在 Hikage 布局装载过程中的事件和监听。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
val factory = HikageFactory { parent, base, context, params ->
|
||||
// 你可以在这里自定义布局装载器的行为
|
||||
// 例如，使用你自己的方式创建一个新的 View 对象
|
||||
// `parent` 为当前组件要添加到的 ViewGroup 对象，如果没有则为 `null`
|
||||
// `base` 为上一个 HikageFactory 创建的 View 对象，如果没有则为 `null`
|
||||
// `params` 对象中包含了组件 ID、AttributeSet 以及 View 的 Class 对象
|
||||
val view = MyLayoutFactory.createView(context, params)
|
||||
// 你还可以在这里对创建的 View 对象进行初始化和设置
|
||||
view.setBackgroundColor(Color.RED)
|
||||
// 返回创建的 View 对象
|
||||
// 返回 `null` 将会使用默认的组件装载方式
|
||||
view
|
||||
}
|
||||
```
|
||||
|
||||
你还可以直接传入 `LayoutInflater` 对象以自动装载并使用其中的 `LayoutInflater.Factory2`。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
// 假设这就是你的 LayoutInflater 对象
|
||||
val layoutInflater: LayoutInflater
|
||||
// 通过 LayoutInflater 创建 HikageFactory 对象
|
||||
val factory = HikageFactory(layoutInflater)
|
||||
```
|
||||
|
||||
然后使用以下方式将其设置到你需要装载的 Hikage 布局上。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
// 假设这就是你的 Context
|
||||
val context: Context
|
||||
// 创建 Hikage 对象
|
||||
val hikage = Hikageable(
|
||||
context = context,
|
||||
factory = {
|
||||
// 添加自定义的 HikageFactory 对象
|
||||
add(factory)
|
||||
// 直接添加
|
||||
add { parent, base, context, params ->
|
||||
// ...
|
||||
null
|
||||
}
|
||||
// 连续添加多个
|
||||
addAll(factories)
|
||||
}
|
||||
) {
|
||||
LinearLayout {
|
||||
TextView {
|
||||
text = "Hello, World!"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
::: tip
|
||||
|
||||
Hikage 在默认装载时将会根据传入 `Context` 对象的 `LayoutInflater.Factory2` 对布局进行装载，如果你正在使用 `AppCompatActivity`，
|
||||
布局中的组件将会自动被替换为对应的 Compat 组件或 Material 组件，与 XML 布局的特性保持一致。
|
||||
|
||||
如果你不需要默认生效此特性，可以使用以下方式全局关闭。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
Hikage.isAutoProcessWithFactory2 = false
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### 预览布局
|
||||
|
||||
Hikage 支持在 Android Studio 中预览布局，借助于 Android Studio 自带的自定义 `View` 预览插件，你可以使用以下方式预览布局。
|
||||
|
||||
你只需要定义一个预览布局的自定义 `View` 并继承于 `HikagePreview`。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
class MyLayoutPreview(context: Context, attrs: AttributeSet?) : HikagePreview(context, attrs) {
|
||||
|
||||
override fun build() = Hikageable {
|
||||
LinearLayout {
|
||||
TextView {
|
||||
text = "Hello, World!"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
然后在你当前的窗口右侧应该会出现预览窗格，打开后点击 “Build & Refresh”，等待编译完成后将会自动显示预览。
|
||||
|
||||
::: tip
|
||||
|
||||
`HikagePreview` 实现了 `HikageBuilder` 接口，你可以在 `build` 方法中返回任意的 Hikage 布局以进行预览。
|
||||
|
||||
:::
|
||||
|
||||
::: danger
|
||||
|
||||
`HikagePreview` 仅支持在 Android Studio 中预览布局，请勿在运行时使用它或将其添加到任何 XML 布局中。
|
||||
|
||||
:::
|
||||
@@ -0,0 +1,74 @@
|
||||
# hikage-extension-betterandroid
|
||||
|
||||
|
||||
<span style="margin-left: 5px"/>
|
||||
|
||||
<span style="margin-left: 5px"/>
|
||||
|
||||
|
||||
这是 Hikage 针对 [BetterAndroid](https://github.com/BetterAndroid/BetterAndroid) UI 组件相关功能的扩展依赖。
|
||||
|
||||
## 配置依赖
|
||||
|
||||
你可以使用如下方式将此模块添加到你的项目中。
|
||||
|
||||
### SweetDependency (推荐)
|
||||
|
||||
在你的项目 `SweetDependency` 配置文件中添加依赖。
|
||||
|
||||
```yaml
|
||||
libraries:
|
||||
com.highcapable.hikage:
|
||||
hikage-extension-betterandroid:
|
||||
version: +
|
||||
```
|
||||
|
||||
在你的项目 `build.gradle.kts` 中配置依赖。
|
||||
|
||||
```kotlin
|
||||
implementation(com.highcapable.hikage.hikage.extension.betterandroid)
|
||||
```
|
||||
|
||||
### 传统方式
|
||||
|
||||
在你的项目 `build.gradle.kts` 中配置依赖。
|
||||
|
||||
```kotlin
|
||||
implementation("com.highcapable.hikage:hikage-extension-betterandroid:<version>")
|
||||
```
|
||||
|
||||
请将 `<version>` 修改为此文档顶部显示的版本。
|
||||
|
||||
## 功能介绍
|
||||
|
||||
你可以 [点击这里](kdoc://hikage-extension-betterandroid) 查看 KDoc。
|
||||
|
||||
### 适配器 (Adapter) 扩展
|
||||
|
||||
Hikage 为 BetterAndroid 提供的 [适配器](https://betterandroid.github.io/BetterAndroid/zh-cn/library/ui-component#%E9%80%82%E9%85%8D%E5%99%A8-adapter)
|
||||
提供了布局扩展功能，你可以直接在适配器的原始扩展方法上使用 Hikage 布局。
|
||||
|
||||
它使用了 BetterAndroid 提供的 `ViewHolderDelegate` 来创建扩展方法。
|
||||
|
||||
下面提供了一个基于 `RecyclerView` 的简单示例。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
// 假设这就是你需要绑定的数据集
|
||||
val listData = ArrayList<CustomBean>()
|
||||
// 创建并绑定到自定义的 RecyclerView.Adapter
|
||||
val adapter = recyclerView.bindAdapter<CustomBean> {
|
||||
onBindData { listData }
|
||||
onBindItemView(
|
||||
Hikageable = {
|
||||
TextView(id = "text_view") {
|
||||
text = "Hello, World!"
|
||||
textSize = 16f
|
||||
}
|
||||
}
|
||||
) { hikage, bean, position ->
|
||||
hikage.get<TextView>("text_view").text = bean.name
|
||||
}
|
||||
}
|
||||
```
|
||||
87
docs-source/src/zh-cn/library/hikage-extension-compose.md
Normal file
87
docs-source/src/zh-cn/library/hikage-extension-compose.md
Normal file
@@ -0,0 +1,87 @@
|
||||
# hikage-extension-compose
|
||||
|
||||
|
||||
<span style="margin-left: 5px"/>
|
||||
|
||||
<span style="margin-left: 5px"/>
|
||||
|
||||
|
||||
这是 Hikage 针对 Jetpack Compose 组件相关功能的扩展依赖。
|
||||
|
||||
## 配置依赖
|
||||
|
||||
你可以使用如下方式将此模块添加到你的项目中。
|
||||
|
||||
::: warning
|
||||
|
||||
此模块依赖于 Jetpack Compose 编译插件，请确保你的项目中已经集成了 Jetpack Compose 相关依赖，详情请参考 [这里](https://developer.android.com/develop/ui/compose/compiler)。
|
||||
|
||||
:::
|
||||
|
||||
### SweetDependency (推荐)
|
||||
|
||||
在你的项目 `SweetDependency` 配置文件中添加依赖。
|
||||
|
||||
```yaml
|
||||
libraries:
|
||||
com.highcapable.hikage:
|
||||
hikage-extension-compose:
|
||||
version: +
|
||||
```
|
||||
|
||||
在你的项目 `build.gradle.kts` 中配置依赖。
|
||||
|
||||
```kotlin
|
||||
implementation(com.highcapable.hikage.hikage.extension.compose)
|
||||
```
|
||||
|
||||
### 传统方式
|
||||
|
||||
在你的项目 `build.gradle.kts` 中配置依赖。
|
||||
|
||||
```kotlin
|
||||
implementation("com.highcapable.hikage:hikage-extension-compose:<version>")
|
||||
```
|
||||
|
||||
请将 `<version>` 修改为此文档顶部显示的版本。
|
||||
|
||||
## 功能介绍
|
||||
|
||||
你可以 [点击这里](kdoc://hikage-extension-compose) 查看 KDoc。
|
||||
|
||||
### 在 Hikage 中使用 Jetpack Compose
|
||||
|
||||
你可以使用以下方式在一个 Hikage 布局中嵌入 Jetpack Compose 组件。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
Hikageable {
|
||||
ComposeView(
|
||||
lparams = LayoutParams(matchParent = true)
|
||||
) {
|
||||
Text("Hello, World!")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 在 Jetpack Compose 中使用 Hikage
|
||||
|
||||
你可以使用以下方式在一个 Jetpack Compose 布局中嵌入 Hikage 组件。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
Column(
|
||||
modifier = Modifier.fillMaxSize()
|
||||
) {
|
||||
HikageView {
|
||||
TextView(
|
||||
lparams = LayoutParams(matchParent = true)
|
||||
) {
|
||||
text = "Hello, World!"
|
||||
textSize = 20f
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
208
docs-source/src/zh-cn/library/hikage-extension.md
Normal file
208
docs-source/src/zh-cn/library/hikage-extension.md
Normal file
@@ -0,0 +1,208 @@
|
||||
# hikage-extension
|
||||
|
||||
|
||||
<span style="margin-left: 5px"/>
|
||||
|
||||
<span style="margin-left: 5px"/>
|
||||
|
||||
|
||||
这是 Hikage 针对 UI 组件相关功能的扩展依赖。
|
||||
|
||||
## 配置依赖
|
||||
|
||||
你可以使用如下方式将此模块添加到你的项目中。
|
||||
|
||||
### SweetDependency (推荐)
|
||||
|
||||
在你的项目 `SweetDependency` 配置文件中添加依赖。
|
||||
|
||||
```yaml
|
||||
libraries:
|
||||
com.highcapable.hikage:
|
||||
hikage-extension:
|
||||
version: +
|
||||
```
|
||||
|
||||
在你的项目 `build.gradle.kts` 中配置依赖。
|
||||
|
||||
```kotlin
|
||||
implementation(com.highcapable.hikage.hikage.extension)
|
||||
```
|
||||
|
||||
### 传统方式
|
||||
|
||||
在你的项目 `build.gradle.kts` 中配置依赖。
|
||||
|
||||
```kotlin
|
||||
implementation("com.highcapable.hikage:hikage-extension:<version>")
|
||||
```
|
||||
|
||||
请将 `<version>` 修改为此文档顶部显示的版本。
|
||||
|
||||
## 功能介绍
|
||||
|
||||
你可以 [点击这里](kdoc://hikage-extension) 查看 KDoc。
|
||||
|
||||
### Activity
|
||||
|
||||
Hikage 为 `Activity` 提供了更好用的扩展，在 `Activity` 中创建 Hikage 将会变得更加简单。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
class MainActivity : AppCompatActivity() {
|
||||
|
||||
override fun onCreate(savedInstanceState: Bundle?) {
|
||||
super.onCreate(savedInstanceState)
|
||||
setContentView {
|
||||
LinearLayout(
|
||||
lparams = LayoutParams(matchParent = true) {
|
||||
topMargin = 16.dp
|
||||
},
|
||||
init = {
|
||||
orientation = LinearLayout.VERTICAL
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
) {
|
||||
TextView {
|
||||
text = "Hello, World!"
|
||||
textSize = 16f
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
借助 `Hikage` 的 `setContentView` 扩展方法，你可以像 Jetpack Compose 一样使用 `setContent` 方法来设置布局。
|
||||
|
||||
### Window
|
||||
|
||||
在 `Window` 中使用 Hikage 创建布局与 [Activity](#activity) 保持一致，你只需要使用 `setContentView` 方法传入一个 `Hikage` 布局即可。
|
||||
|
||||
### Dialog
|
||||
|
||||
如果你想直接在 `AlertDialog` 中使用 Hikage 创建布局，现在你可以使用以下方案更加简单地进行。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
// 假设这就是你的 Context
|
||||
val context: Context
|
||||
// 创建对话框并显示
|
||||
AlertDialog.Builder(context)
|
||||
.setTitle("Hello, World!")
|
||||
.setView {
|
||||
TextView {
|
||||
text = "Hello, World!"
|
||||
textSize = 16f
|
||||
}
|
||||
}
|
||||
.show()
|
||||
```
|
||||
|
||||
在 `AlertDialog` 中使用 Hikage 创建布局，你只需要使用 `setView` 方法传入一个 `Hikage` 布局即可。
|
||||
|
||||
如果你是继承于 `Dialog` 进行自定义，那么你可以和像在 [Activity](#activity) 一样使用 `setContentView` 方法。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
class CustomDialog(context: Context) : Dialog(context) {
|
||||
|
||||
override fun onCreate(savedInstanceState: Bundle?) {
|
||||
super.onCreate(savedInstanceState)
|
||||
setContentView {
|
||||
LinearLayout(
|
||||
lparams = LayoutParams(matchParent = true) {
|
||||
topMargin = 16.dp
|
||||
},
|
||||
init = {
|
||||
orientation = LinearLayout.VERTICAL
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
) {
|
||||
TextView {
|
||||
text = "Hello, World!"
|
||||
textSize = 16f
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### PopupWindow
|
||||
|
||||
你可以继承于 `PopupWindow` 进行自定义，然后使用 Hikage 创建布局，你可以和像在 [Activity](#activity) 一样使用 `setContentView` 方法。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
class CustomPopupWindow(context: Context) : PopupWindow(context) {
|
||||
|
||||
init {
|
||||
setContentView(context) {
|
||||
LinearLayout(
|
||||
lparams = LayoutParams(matchParent = true) {
|
||||
topMargin = 16.dp
|
||||
},
|
||||
init = {
|
||||
orientation = LinearLayout.VERTICAL
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
) {
|
||||
TextView {
|
||||
text = "Hello, World!"
|
||||
textSize = 16f
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
::: danger
|
||||
|
||||
创建 Hikage 布局的 `PopupWindow` 需要使用 `Context` 构造方法进行初始化，如果当前无法立即获取到 `Context`，请对 `setContentView` 方法传入 `Context` 实例。
|
||||
|
||||
:::
|
||||
|
||||
### ViewGroup
|
||||
|
||||
Hikage 对 `ViewGroup` 的 `addView` 方法进行了扩展，你可以直接使用 Hikage 布局来为当前 `ViewGroup` 快速添加新的布局。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
// 假设这就是你的 ViewGroup
|
||||
val root: FrameLayout
|
||||
// 添加 Hikage 布局
|
||||
root.addView {
|
||||
TextView {
|
||||
text = "Hello, World!"
|
||||
textSize = 16f
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
或者，在自定义 `View` 中使用。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
class CustomView(context: Context, attrs: AttributeSet? = null) : FrameLayout(context, attrs) {
|
||||
|
||||
init {
|
||||
addView {
|
||||
TextView {
|
||||
text = "Hello, World!"
|
||||
textSize = 16f
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
64
docs-source/src/zh-cn/library/hikage-widget-androidx.md
Normal file
64
docs-source/src/zh-cn/library/hikage-widget-androidx.md
Normal file
@@ -0,0 +1,64 @@
|
||||
# hikage-widget-androidx
|
||||
|
||||
|
||||
<span style="margin-left: 5px"/>
|
||||
|
||||
<span style="margin-left: 5px"/>
|
||||
|
||||
|
||||
这是 Hikage 针对 Jetpack Compact 组件相关功能的扩展依赖。
|
||||
|
||||
## 配置依赖
|
||||
|
||||
你可以使用如下方式将此模块添加到你的项目中。
|
||||
|
||||
### SweetDependency (推荐)
|
||||
|
||||
在你的项目 `SweetDependency` 配置文件中添加依赖。
|
||||
|
||||
```yaml
|
||||
libraries:
|
||||
com.highcapable.hikage:
|
||||
hikage-widget-androidx:
|
||||
version: +
|
||||
```
|
||||
|
||||
在你的项目 `build.gradle.kts` 中配置依赖。
|
||||
|
||||
```kotlin
|
||||
implementation(com.highcapable.hikage.hikage.widget.androidx)
|
||||
```
|
||||
|
||||
### 传统方式
|
||||
|
||||
在你的项目 `build.gradle.kts` 中配置依赖。
|
||||
|
||||
```kotlin
|
||||
implementation("com.highcapable.hikage:hikage-widget-androidx:<version>")
|
||||
```
|
||||
|
||||
请将 `<version>` 修改为此文档顶部显示的版本。
|
||||
|
||||
## 功能介绍
|
||||
|
||||
这个依赖中继承了来自 Jetpack Compact 中的可用组件，你可以直接引用它们到 Hikage 中使用。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
LinearLayoutCompact(
|
||||
lparams = LayoutParams(matchParent = true) {
|
||||
topMargin = 16.dp
|
||||
},
|
||||
init = {
|
||||
orientation = LinearLayoutCompat.VERTICAL
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
) {
|
||||
AppCompatTextView {
|
||||
text = "Hello, World!"
|
||||
textSize = 16f
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
}
|
||||
```
|
||||
80
docs-source/src/zh-cn/library/hikage-widget-material.md
Normal file
80
docs-source/src/zh-cn/library/hikage-widget-material.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# hikage-widget-material
|
||||
|
||||
|
||||
<span style="margin-left: 5px"/>
|
||||
|
||||
<span style="margin-left: 5px"/>
|
||||
|
||||
|
||||
这是 Hikage 针对 Google Material (MDC) 组件相关功能的扩展依赖。
|
||||
|
||||
## 配置依赖
|
||||
|
||||
你可以使用如下方式将此模块添加到你的项目中。
|
||||
|
||||
### SweetDependency (推荐)
|
||||
|
||||
在你的项目 `SweetDependency` 配置文件中添加依赖。
|
||||
|
||||
```yaml
|
||||
libraries:
|
||||
com.highcapable.hikage:
|
||||
hikage-widget-material:
|
||||
version: +
|
||||
```
|
||||
|
||||
在你的项目 `build.gradle.kts` 中配置依赖。
|
||||
|
||||
```kotlin
|
||||
implementation(com.highcapable.hikage.hikage.widget.material)
|
||||
```
|
||||
|
||||
### 传统方式
|
||||
|
||||
在你的项目 `build.gradle.kts` 中配置依赖。
|
||||
|
||||
```kotlin
|
||||
implementation("com.highcapable.hikage:hikage-widget-material:<version>")
|
||||
```
|
||||
|
||||
请将 `<version>` 修改为此文档顶部显示的版本。
|
||||
|
||||
## 功能介绍
|
||||
|
||||
这个依赖中继承了来自 Google Material (MDC) 中的可用组件，你可以直接引用它们到 Hikage 中使用。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
LinearLayout(
|
||||
lparams = LayoutParams(matchParent = true) {
|
||||
topMargin = 16.dp
|
||||
},
|
||||
init = {
|
||||
orientation = LinearLayout.VERTICAL
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
) {
|
||||
MaterialTextView {
|
||||
text = "Hello, World!"
|
||||
textSize = 16f
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
MaterialButton {
|
||||
text = "Hello, World!"
|
||||
textSize = 16f
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
TextInputLayout(
|
||||
lparams = LayoutParams {
|
||||
topMargin = 16.dp
|
||||
},
|
||||
init = {
|
||||
minWidth = 200.dp
|
||||
hint = "Enter your text"
|
||||
}
|
||||
) {
|
||||
TextInputEditText()
|
||||
}
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user