mirror of
https://github.com/BetterAndroid/Hikage.git
synced 2025-09-09 03:54:13 +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:
27
docs-source/src/zh-cn/about/about.md
Normal file
27
docs-source/src/zh-cn/about/about.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# 关于此文档
|
||||
|
||||
> 此文档由 [VuePress](https://v2.vuepress.vuejs.org/zh) 强力驱动。
|
||||
|
||||
## 许可证
|
||||
|
||||
[Apache-2.0](https://github.com/BetterAndroid/Hikage/blob/main/LICENSE)
|
||||
|
||||
```:no-line-numbers
|
||||
Apache License Version 2.0
|
||||
|
||||
Copyright (C) 2019 HighCapable
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
https://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
```
|
||||
|
||||
版权所有 © 2019 HighCapable
|
||||
51
docs-source/src/zh-cn/about/changelog.md
Normal file
51
docs-source/src/zh-cn/about/changelog.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# 更新日志
|
||||
|
||||
> 这里记录了 `Hikage` 的版本更新历史。
|
||||
|
||||
::: danger
|
||||
|
||||
我们只会对最新的 API 版本进行维护，若你正在使用过时的 API 版本则代表你自愿放弃一切维护的可能性。
|
||||
|
||||
:::
|
||||
|
||||
## hikage-core
|
||||
|
||||
### 1.0.0 | 2025.04.20  <Badge type="tip" text="最新" vertical="middle" />
|
||||
|
||||
- 首个版本提交至 Maven
|
||||
|
||||
## hikage-compiler
|
||||
|
||||
### 1.0.0 | 2025.04.20  <Badge type="tip" text="最新" vertical="middle" />
|
||||
|
||||
- 首个版本提交至 Maven
|
||||
|
||||
## hikage-extension
|
||||
|
||||
### 1.0.0 | 2025.04.20  <Badge type="tip" text="最新" vertical="middle" />
|
||||
|
||||
- 首个版本提交至 Maven
|
||||
|
||||
## hikage-extension-betterandroid
|
||||
|
||||
### 1.0.0 | 2025.04.20  <Badge type="tip" text="最新" vertical="middle" />
|
||||
|
||||
- 首个版本提交至 Maven
|
||||
|
||||
## hikage-extension-compose
|
||||
|
||||
### 1.0.0 | 2025.04.20  <Badge type="tip" text="最新" vertical="middle" />
|
||||
|
||||
- 首个版本提交至 Maven
|
||||
|
||||
## hikage-widget-androidx
|
||||
|
||||
### 1.0.0 | 2025.04.20  <Badge type="tip" text="最新" vertical="middle" />
|
||||
|
||||
- 首个版本提交至 Maven
|
||||
|
||||
## hikage-widget-material
|
||||
|
||||
### 1.0.0 | 2025.04.20  <Badge type="tip" text="最新" vertical="middle" />
|
||||
|
||||
- 首个版本提交至 Maven
|
||||
15
docs-source/src/zh-cn/about/contacts.md
Normal file
15
docs-source/src/zh-cn/about/contacts.md
Normal file
@@ -0,0 +1,15 @@
|
||||
# 联系我们
|
||||
|
||||
> 如在使用中有任何问题，或有任何建设性的建议，都可以联系我们。
|
||||
|
||||
加入我们的开发者群组。
|
||||
|
||||
- [点击加入 Telegram 群组](https://t.me/BetterAndroid)
|
||||
- [点击加入 Telegram 群组 (开发者)](https://t.me/HighCapable_Dev)
|
||||
- [点击加入 QQ 群 (开发者)](https://qm.qq.com/cgi-bin/qm/qr?k=Pnsc5RY6N2mBKFjOLPiYldbAbprAU3V7&jump_from=webapi&authKey=X5EsOVzLXt1dRunge8ryTxDRrh9/IiW1Pua75eDLh9RE3KXE+bwXIYF5cWri/9lf)
|
||||
|
||||
在 **酷安** 找到我 [@星夜不荟](http://www.coolapk.com/u/876977)。
|
||||
|
||||
## 助力维护
|
||||
|
||||
感谢您选择并使用 `Hikage`，如有代码相关的建议和请求，可在 GitHub 提交 Pull Request。
|
||||
73
docs-source/src/zh-cn/about/future.md
Normal file
73
docs-source/src/zh-cn/about/future.md
Normal file
@@ -0,0 +1,73 @@
|
||||
# 展望未来
|
||||
|
||||
> 未来是美好的，也是不确定的，让我们共同期待 `Hikage` 在未来的发展空间。
|
||||
|
||||
## 未来的计划
|
||||
|
||||
> 这里收录了 `Hikage` 可能会在后期添加的功能。
|
||||
|
||||
### 处理 AttrtibuteSet
|
||||
|
||||
`Hikage` 未来将会支持处理 `AttributeSet` 来对接 XML 原始的属性以实现接管一些并未在代码中对布局属性开放自定义的第三方组件。
|
||||
|
||||
`Hikage` 目前已经支持自动化创建 `XmlBlock`，但尚未支持直接处理自定义的 `AttributeSet`，因为其历史遗留问题和处理难度较高，可能会折中考虑后期是否要继续完善此功能。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
TextView(
|
||||
id = "text_view",
|
||||
// 通过 AttributeSet 传入的属性
|
||||
attrs = {
|
||||
namespace("android") {
|
||||
set("text", "Hello, World!")
|
||||
set("textSize", "16sp")
|
||||
set("gravity", "center")
|
||||
}
|
||||
}
|
||||
) {
|
||||
// 通过代码传入的属性
|
||||
text = "Hello, World!"
|
||||
textSize = 16f
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
```
|
||||
|
||||
### 生成组件 ID
|
||||
|
||||
`Hikage` 未来可能会根据需求支持生成使用字符串自定义的组件 ID 的直接调用功能。
|
||||
|
||||
> 示例如下
|
||||
|
||||
```kotlin
|
||||
object MyLayout : HikageBuilder {
|
||||
|
||||
override fun build() = Hikageable(context) {
|
||||
LinearLayout(
|
||||
id = "lin_layout",
|
||||
lparams = LayoutParams(matchParent = true),
|
||||
init = {
|
||||
orientation = LinearLayout.VERTICAL
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
) {
|
||||
TextView(id = "text_view") {
|
||||
text = "Hello, World!"
|
||||
textSize = 16f
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
val context: Context
|
||||
// 创建 TypedHikage
|
||||
val myLayout = MyLayout.asTyped().build().create(context)
|
||||
// 或者，使用懒加载
|
||||
val myLayout by context.lazyTypedHikage(MyLayout)
|
||||
// 直接调用根据字符串生成的 ID
|
||||
val linLayout = myLayout.linLayout
|
||||
val textView = myLayout.textView
|
||||
// 获取根布局，即 LinearLayout
|
||||
val root = myLayout.root
|
||||
```
|
||||
17
docs-source/src/zh-cn/config/r8-proguard.md
Normal file
17
docs-source/src/zh-cn/config/r8-proguard.md
Normal file
@@ -0,0 +1,17 @@
|
||||
# R8 与 Proguard 混淆
|
||||
|
||||
> 大部分场景下应用程序安装包可通过混淆压缩体积，这里介绍了混淆规则的配置方法。
|
||||
|
||||
`Hikage` 不需要额外配置混淆规则，由于 Hikage 装载的 `View` 不需要在 XML 中被定义，它们也可以同样被混淆。
|
||||
|
||||
你可以将你的自定义 `View`，例如 `com.yourpackage.YourView` 使用以下规则强制让它们被混淆。
|
||||
|
||||
```
|
||||
-allowobfuscation class com.yourpackage.YourView
|
||||
```
|
||||
|
||||
如果你一定要防止 `Hikage` 被混淆或者混淆后发生了问题，那么你可以使用以下规则来防止 `Hikage` 被混淆。
|
||||
|
||||
```
|
||||
-keep class com.highcapable.hikage**
|
||||
```
|
||||
109
docs-source/src/zh-cn/guide/home.md
Normal file
109
docs-source/src/zh-cn/guide/home.md
Normal file
@@ -0,0 +1,109 @@
|
||||
# 介绍
|
||||
|
||||
> `Hikage` (发音 /ˈhɪkɑːɡeɪ/) 是一个 Android 响应式 UI 构建工具。
|
||||
|
||||
## 背景
|
||||
|
||||
这是一个 Android 响应式 UI 构建工具，它的设计聚焦于 **实时代码构建 UI**。
|
||||
|
||||
项目图标由 [MaiTungTM](https://github.com/Lagrio) 设计，名称取自 「BanG Dream It's MyGO!!!!!」 中的原创歌曲《春日影》(Haru**hikage**)。
|
||||
|
||||
<details><summary>为什么要...</summary>
|
||||
<div align="center">
|
||||
<img src="/images/nagasaki_soyo.png" width = "100" height = "100" alt="LOGO"/>
|
||||
|
||||
**なんで春日影レイアウト使いの？**
|
||||
</div>
|
||||
</details>
|
||||
|
||||
不同于 Jetpack Compose 的声明式 UI，Hikage 专注于 Android 原生平台，它的设计目标是为了让开发者能够快速构建 UI 并可直接支持 Android 原生组件。
|
||||
|
||||
**<u>Hikage 只是一个 UI 构建工具，自身并不提供任何 UI 组件</u>**。
|
||||
|
||||
拒绝重复造轮子，我们的方案始终是兼容与高效，现在你可以抛弃 ViewBinding 和 XML 甚至是 `findViewById`，直接来尝试使用代码布局吧。
|
||||
|
||||
`Hikage` 配合我们的另一个项目 [BetterAndroid](https://github.com/BetterAndroid/BetterAndroid) 使用效果更佳，同时 `Hikage` 自身将自动引用 `BetterAndroid` 相关依赖作为核心内容。
|
||||
|
||||
## 用途
|
||||
|
||||
Hikage 主要适用于专注原生 Android 平台开发的开发者，自从 Kotlin 作为主要开发语言后，依然没有一套比较完美的工具能够使用 DSL 实现动态代码布局，
|
||||
所以没有使用 Jetpack Compose 的项目依然需要使用原始的 XML，虽然有着 ViewBinding 的支持，但是依然不是很友好。
|
||||
|
||||
Hikage 继承了 [Anko](https://github.com/Kotlin/anko)、[Splitties](https://github.com/LouisCAD/Splitties) 的设计方案以及借鉴了 Jetpack Compose 的 DSL 函数命名方案，
|
||||
并且在此基础上进行了大量改进，使得它在使用成本上更贴近原生，写法上更贴近 Jetpack Compose。
|
||||
|
||||
> 各种 DSL 布局方案对比
|
||||
|
||||
:::: code-group
|
||||
::: code-group-item Hikage
|
||||
|
||||
```kotlin
|
||||
LinearLayout(
|
||||
lparams = LayoutParams(matchParent = true) {
|
||||
topMargin = 16.dp
|
||||
},
|
||||
init = {
|
||||
orientation = LinearLayout.VERTICAL
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
) {
|
||||
TextView {
|
||||
text = "Hello, World!"
|
||||
textSize = 16f
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::
|
||||
::: code-group-item Anko、Splitties
|
||||
|
||||
```kotlin
|
||||
verticalLayout {
|
||||
gravity = Gravity.CENTER
|
||||
textView("Hello, World!") {
|
||||
textSize = 16f
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
}.lparams(
|
||||
width = matchParent,
|
||||
height = matchParent
|
||||
) {
|
||||
topMargin = dip(16)
|
||||
}
|
||||
```
|
||||
|
||||
:::
|
||||
::: code-group-item Jetpack Compose
|
||||
|
||||
```kotlin
|
||||
Column(
|
||||
modifier = Modifier.padding(top = 16.dp),
|
||||
verticalArrangement = Arrangement.Center,
|
||||
horizontalAlignment = Alignment.CenterHorizontally
|
||||
) {
|
||||
Text(
|
||||
text = "Hello, World!",
|
||||
fontSize = 16.sp,
|
||||
textAlign = TextAlign.Center
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
:::
|
||||
::::
|
||||
|
||||
Hikage 的基础部分**完全不需要借助外部及额外的编译插件**，它能**即插即用**并在**任何地方创建**一个可被设置到父布局以及 `Window` 上的 `View` 对象。
|
||||
|
||||
Hikage **全面兼容**混合式布局，你可以在 Hikage 中嵌入 XML (使用 `R.layout` 方案装载布局)、ViewBinding 甚至是 Jetpack Compose。
|
||||
|
||||
## 语言要求
|
||||
|
||||
推荐使用 Kotlin 作为首选开发语言，本项目完全使用 Kotlin 编写，且不再有计划兼容 Java。
|
||||
|
||||
文档全部的 Demo 示例代码都将使用 Kotlin 进行描述，如果你完全不会使用 Kotlin，那么你将有可能无法正常使用本项目。
|
||||
|
||||
## 功能贡献
|
||||
|
||||
本项目的维护离不开各位开发者的支持和贡献，目前这个项目处于初期阶段，可能依然存在一些问题或者缺少你需要的功能，
|
||||
如果可能，欢迎提交 PR 为此项目贡献你认为需要的功能或前往 [GitHub Issues](repo://issues) 向我们提出建议。
|
||||
85
docs-source/src/zh-cn/guide/quick-start.md
Normal file
85
docs-source/src/zh-cn/guide/quick-start.md
Normal file
@@ -0,0 +1,85 @@
|
||||
# 快速开始
|
||||
|
||||
> 集成 `Hikage` 到你的项目中。
|
||||
|
||||
## 项目要求
|
||||
|
||||
项目需要使用 `Android Studio` 或 `IntelliJ IDEA` 创建且类型为 Android 或 Kotlin Multiplatform 项目并已集成 Kotlin 环境依赖。
|
||||
|
||||
- Android Studio (建议 [从这里](https://developer.android.com/studio) 获取最新版本)
|
||||
|
||||
- IntelliJ IDEA (建议 [从这里](https://www.jetbrains.com/idea) 获取最新版本)
|
||||
|
||||
- Kotlin 1.9.0+、Gradle 8+、Java 17+、Android Gradle Plugin 8+
|
||||
|
||||
### 配置存储库
|
||||
|
||||
`Hikage` 的依赖发布在 **Maven Central** 和我们的公共存储库中，你可以使用如下方式配置存储库。
|
||||
|
||||
我们推荐使用 Kotlin DSL 作为 Gradle 构建脚本语言并推荐使用 [SweetDependency](https://github.com/HighCapable/SweetDependency) 来管理依赖。
|
||||
|
||||
#### SweetDependency (推荐)
|
||||
|
||||
在你的项目 `SweetDependency` 配置文件中配置存储库。
|
||||
|
||||
```yaml
|
||||
repositories:
|
||||
google:
|
||||
maven-central:
|
||||
# (可选) 你可以添加此 URL 以使用我们的公共存储库
|
||||
# 当 Sonatype-OSS 发生故障无法发布依赖时，此存储库作为备选进行添加
|
||||
# 详情请前往：https://github.com/HighCapable/maven-repository
|
||||
highcapable-maven-releases:
|
||||
# 中国大陆用户请将下方的 "raw.githubusercontent.com" 修改为 "raw.gitmirror.com"
|
||||
url: https://raw.githubusercontent.com/HighCapable/maven-repository/main/repository/releases
|
||||
```
|
||||
|
||||
#### 传统方式
|
||||
|
||||
在你的项目 `build.gradle.kts` 中配置存储库。
|
||||
|
||||
```kotlin
|
||||
repositories {
|
||||
google()
|
||||
mavenCentral()
|
||||
// (可选) 你可以添加此 URL 以使用我们的公共存储库
|
||||
// 当 Sonatype-OSS 发生故障无法发布依赖时，此存储库作为备选进行添加
|
||||
// 详情请前往：https://github.com/HighCapable/maven-repository
|
||||
// 中国大陆用户请将下方的 "raw.githubusercontent.com" 修改为 "raw.gitmirror.com"
|
||||
maven("https://raw.githubusercontent.com/HighCapable/maven-repository/main/repository/releases")
|
||||
}
|
||||
```
|
||||
|
||||
### 配置 Java 版本
|
||||
|
||||
在你的项目 `build.gradle.kts` 中修改 Kotlin 的 Java 版本为 17 及以上。
|
||||
|
||||
```kt
|
||||
android {
|
||||
compileOptions {
|
||||
sourceCompatibility = JavaVersion.VERSION_17
|
||||
targetCompatibility = JavaVersion.VERSION_17
|
||||
}
|
||||
kotlinOptions {
|
||||
jvmTarget = "17"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 功能一览
|
||||
|
||||
整个项目分为多个模块，你可以选择你希望引入的模块作为依赖应用到你的项目中，但一定要包含 **hikage-core** 模块。
|
||||
|
||||
你可以点击下方对应的模块前往查看详细的功能介绍。
|
||||
|
||||
- [hikage-core](../library/hikage-core.md)
|
||||
- [hikage-compiler](../library/hikage-compiler.md)
|
||||
- [hikage-extension](../library/hikage-extension.md)
|
||||
- [hikage-extension-betterandroid](../library/hikage-extension-betterandroid.md)
|
||||
- [hikage-extension-compose](../library/hikage-extension-compose.md)
|
||||
- [hikage-widget-androidx](../library/hikage-widget-androidx.md)
|
||||
- [hikage-widget-material](../library/hikage-widget-material.md)
|
||||
|
||||
## Demo
|
||||
|
||||
你可以在 [这里](repo://tree/main/samples) 找到一些示例，查看对应的演示项目来更好地了解这些功能的运作方式，快速地挑选出你需要的功能。
|
||||
65
docs-source/src/zh-cn/index.md
Normal file
65
docs-source/src/zh-cn/index.md
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
home: true
|
||||
title: 首页
|
||||
heroImage: /images/logo.svg
|
||||
actions:
|
||||
- text: 快速上手
|
||||
link: /zh-cn/guide/home
|
||||
type: primary
|
||||
- text: 更新日志
|
||||
link: /zh-cn/about/changelog
|
||||
type: secondary
|
||||
features:
|
||||
- title: 原生可控
|
||||
details: 使用 View 作为基础，Kotlin 作为开发语言，100% 动态代码布局，无需任何额外配置，支持自定义 View。
|
||||
- title: 全面兼容
|
||||
details: 支持 XML、ViewBinding 以及 Jetpack Compose 嵌入混合使用，并对 Material 组件及 Jetpack 提供支持。
|
||||
- title: 快速上手
|
||||
details: 简单易用，不需要繁琐的配置，不需要十足的开发经验，搭建环境集成依赖即可立即开始使用。
|
||||
footer: Apache-2.0 License | Copyright (C) 2019 HighCapable
|
||||
---
|
||||
|
||||
### 布局，就是这么灵活。
|
||||
|
||||
:::: code-group
|
||||
::: code-group-item Hikage (Kotlin DSL)
|
||||
|
||||
```kotlin
|
||||
LinearLayout(
|
||||
lparams = LayoutParams(matchParent = true),
|
||||
init = {
|
||||
orientation = LinearLayout.VERTICAL
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
) {
|
||||
TextView(id = "text_view") {
|
||||
text = "Hello, World!"
|
||||
textSize = 16f
|
||||
gravity = Gravity.CENTER
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::
|
||||
::: code-group-item XML
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
|
||||
android:layout_width="match_parent"
|
||||
android:layout_height="match_parent"
|
||||
android:orientation="vertical"
|
||||
android:gravity="center">
|
||||
|
||||
<TextView
|
||||
android:id="@+id/text_view"
|
||||
android:layout_width="wrap_content"
|
||||
android:layout_height="wrap_content"
|
||||
android:text="Hello, World!"
|
||||
android:textSize="16sp"
|
||||
android:gravity="center" />
|
||||
</LinearLayout>
|
||||
```
|
||||
|
||||
:::
|
||||
::::
|
||||
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