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:
2025-04-20 05:32:06 +08:00
parent 794c535789
commit 99abe3cd18
218 changed files with 13256 additions and 627 deletions

4
docs-source/.gitignore vendored Normal file
View File

@@ -0,0 +1,4 @@
/node_modules
/src/.vuepress/.cache
/src/.vuepress/.temp
/dist

3
docs-source/.vscode/settings.json vendored Normal file
View File

@@ -0,0 +1,3 @@
{
"git.ignoreLimitWarning": true
}

View File

@@ -0,0 +1,2 @@
cd ..
./gradlew :hikage-core:publishKDoc :hikage-extension:publishKDoc :hikage-extension-betterandroid:publishKDoc :hikage-extension-compose:publishKDoc

17
docs-source/package.json Normal file
View File

@@ -0,0 +1,17 @@
{
"name": "hikage_docs",
"license": "Apache-2.0",
"devDependencies": {
"@mr-hope/vuepress-plugin-copy-code": "^1.30.0",
"@vuepress/plugin-prismjs": "2.0.0-rc.0",
"@vuepress/plugin-search": "2.0.0-rc.0",
"@vuepress/plugin-shiki": "2.0.0-rc.0",
"vuepress": "2.0.0-rc.0"
},
"scripts": {
"docs:dev": "vuepress dev src",
"docs:build": "vuepress build src",
"docs:build-gh-pages": "vuepress build src && touch dist/.nojekyll && sh build-dokka.sh"
},
"dependencies": {}
}

View File

@@ -0,0 +1,64 @@
import { defaultTheme } from 'vuepress';
import { shikiPlugin } from '@vuepress/plugin-shiki';
import { searchPlugin } from '@vuepress/plugin-search';
import { navBarItems, sideBarItems, configs, pageLinkRefs } from './configs/template';
import { env, markdown } from './configs/utils';
export default {
dest: configs.dev.dest,
port: configs.dev.port,
base: configs.website.base,
head: [['link', { rel: 'icon', href: configs.website.icon }]],
title: configs.website.title,
description: configs.website.locales['/en/'].description,
locales: configs.website.locales,
theme: defaultTheme({
logo: configs.website.logo,
repo: configs.github.repo,
docsRepo: configs.github.repo,
docsBranch: configs.github.branch,
docsDir: configs.github.dir,
editLinkPattern: ':repo/edit/:branch/:path',
sidebar: sideBarItems,
sidebarDepth: 2,
locales: {
'/en/': {
navbar: navBarItems['/en/'],
selectLanguageText: 'English (US)',
selectLanguageName: 'English',
editLinkText: 'Edit this page on GitHub',
tip: 'Tips',
warning: 'Notice',
danger: 'Pay Attention',
},
'/zh-cn/': {
navbar: navBarItems['/zh-cn/'],
selectLanguageText: '简体中文 (CN)',
selectLanguageName: '简体中文',
editLinkText: '在 GitHub 上编辑此页',
notFound: ['这里什么都没有', '我们怎么到这来了?', '这是一个 404 页面', '看起来我们进入了错误的链接'],
backToHome: '回到首页',
contributorsText: '贡献者',
lastUpdatedText: '上次更新',
tip: '小提示',
warning: '注意',
danger: '特别注意',
openInNewWindow: '在新窗口中打开',
toggleColorMode: '切换颜色模式'
}
},
}),
extendsMarkdown: (md: markdownit) => {
markdown.injectLinks(md, env.dev ? pageLinkRefs.dev : pageLinkRefs.prod);
},
plugins: [
shikiPlugin({ theme: 'github-dark-dimmed' }),
searchPlugin({
isSearchable: (page) => page.path !== '/',
locales: {
'/en/': { placeholder: 'Search' },
'/zh-cn/': { placeholder: '搜索' }
}
})
]
};

View File

@@ -0,0 +1,151 @@
import { i18n } from './utils';
interface PageLinkRefs {
dev: Record<string, string>[];
prod: Record<string, string>[];
}
const navigationLinks = {
start: [
'/guide/home',
'/guide/quick-start'
],
library: [
'/library/hikage-core',
'/library/hikage-compiler',
'/library/hikage-extension',
'/library/hikage-extension-betterandroid',
'/library/hikage-extension-compose',
'/library/hikage-widget-androidx',
'/library/hikage-widget-material'
],
config: [
'/config/r8-proguard'
],
about: [
'/about/changelog',
'/about/future',
'/about/contacts',
'/about/about'
]
};
export const configs = {
dev: {
dest: 'dist',
port: 9000
},
website: {
base: '/Hikage/',
icon: '/Hikage/images/logo.svg',
logo: '/images/logo.svg',
title: 'Hikage',
locales: {
'/en/': {
lang: 'en-US',
description: 'An Android responsive UI building tool'
},
'/zh-cn/': {
lang: 'zh-CN',
description: '一个 Android 响应式 UI 构建工具'
}
}
},
github: {
repo: 'https://github.com/BetterAndroid/Hikage',
page: 'https://betterandroid.github.io/Hikage',
branch: 'main',
dir: 'docs-source/src'
}
};
export const pageLinkRefs: PageLinkRefs = {
dev: [
{ 'repo://': `${configs.github.repo}/` },
// KDoc URL for local debugging, non-fixed value, adjust according to your own needs.
// You can run ./build-dokka.sh and start the local server in dist/KDoc.
{ 'kdoc://': 'http://localhost:9001/' }
],
prod: [
{ 'repo://': `${configs.github.repo}/` },
{ 'kdoc://': `${configs.github.page}/KDoc/` }
]
};
export const navBarItems = {
'/en/': [{
text: 'Navigation',
children: [{
text: 'Get Started',
children: i18n.array(navigationLinks.start, 'en')
}, {
text: 'Libraries',
children: i18n.array(navigationLinks.library, 'en')
}, {
text: 'Configs',
children: i18n.array(navigationLinks.config, 'en')
}, {
text: 'About',
children: i18n.array(navigationLinks.about, 'en')
}]
}, {
text: 'Contact Us',
link: i18n.string(navigationLinks.about[2], 'en')
}],
'/zh-cn/': [{
text: '导航',
children: [{
text: '入门',
children: i18n.array(navigationLinks.start, 'zh-cn')
}, {
text: '依赖',
children: i18n.array(navigationLinks.library, 'zh-cn')
}, {
text: '配置',
children: i18n.array(navigationLinks.config, 'zh-cn')
}, {
text: '关于',
children: i18n.array(navigationLinks.about, 'zh-cn')
}]
}, {
text: '联系我们',
link: i18n.string(navigationLinks.about[2], 'zh-cn')
}]
};
export const sideBarItems = {
'/en/': [{
text: 'Get Started',
collapsible: true,
children: i18n.array(navigationLinks.start, 'en')
}, {
text: 'Libraries',
collapsible: true,
children: i18n.array(navigationLinks.library, 'en')
}, {
text: 'Configs',
collapsible: true,
children: i18n.array(navigationLinks.config, 'en')
}, {
text: 'About',
collapsible: true,
children: i18n.array(navigationLinks.about, 'en')
}],
'/zh-cn/': [{
text: '入门',
collapsible: true,
children: i18n.array(navigationLinks.start, 'zh-cn')
}, {
text: '依赖',
collapsible: true,
children: i18n.array(navigationLinks.library, 'zh-cn')
}, {
text: '配置',
collapsible: true,
children: i18n.array(navigationLinks.config, 'zh-cn')
}, {
text: '关于',
collapsible: true,
children: i18n.array(navigationLinks.about, 'zh-cn')
}]
};

View File

@@ -0,0 +1,39 @@
export const env = {
dev: process.env.NODE_ENV === 'development'
};
export const i18n = {
space: ' ',
string: (content: string, locale: string) => {
return '/' + locale + content;
},
array: (contents: string[], locale: string) => {
const newContents: string[] = [];
contents.forEach((content) => {
newContents.push(i18n.string(content, locale));
});
return newContents;
}
};
export const markdown = {
injectLinks: (md: markdownit, maps: Record<string, string>[]) => {
const defaultRender = md.renderer.rules.link_open || function (tokens, idx, options, _env, self) {
return self.renderToken(tokens, idx, options);
};
md.renderer.rules.link_open = function (tokens, idx, options, env, self) {
const hrefIndex = tokens[idx].attrIndex('href');
let current = tokens[idx].attrs!![hrefIndex][1];
for (const map of maps) {
for (const [search, replace] of Object.entries(map)) {
if (current.startsWith(search)) {
current = current.replace(search, replace);
tokens[idx].attrs!![hrefIndex][1] = current;
break;
}
}
}
return defaultRender(tokens, idx, options, env, self);
};
}
};

View File

@@ -0,0 +1,11 @@
<svg width="512" height="512" viewBox="0 0 512 512" fill="none" xmlns="http://www.w3.org/2000/svg">
<rect width="512" height="512" rx="128" fill="#4EA16B"/>
<rect x="100" y="220" width="79" height="79" rx="24" fill="white" fill-opacity="0.9"/>
<rect x="100" y="315" width="79" height="79" rx="39.5" fill="white" fill-opacity="0.9"/>
<rect x="96" y="118" width="320" height="86" rx="30" fill="white"/>
<path fill-rule="evenodd" clip-rule="evenodd" d="M250.829 235.577C249.606 235.736 248.427 236.135 247.359 236.752C246.281 237.36 245.334 238.175 244.574 239.152C243.813 240.129 243.254 241.247 242.929 242.442C242.604 243.637 242.518 244.884 242.679 246.112C242.839 247.341 243.241 248.524 243.862 249.596L260.34 278.47C232.519 295.058 214 324.376 214 357.705C214 359.809 214.074 361.925 214.22 363.997C214.798 372.166 221.607 378.5 229.813 378.5H396.187C404.497 378.5 411.294 372.019 411.789 363.849C411.929 361.822 412 359.756 412 357.705C412 324.376 393.48 295.058 365.66 278.47L382.138 249.596C382.759 248.524 383.161 247.341 383.321 246.112C383.482 244.884 383.396 243.637 383.071 242.442C382.746 241.247 382.187 240.129 381.426 239.152C380.666 238.175 379.719 237.36 378.641 236.752C377.573 236.135 376.394 235.736 375.171 235.577C373.948 235.419 372.706 235.504 371.517 235.829C370.327 236.154 369.213 236.711 368.24 237.468C367.266 238.226 366.452 239.169 365.845 240.244L348.649 270.375C337.583 266.323 325.561 264.1 313.001 264.1C300.44 264.1 288.417 266.323 277.351 270.376L260.155 240.244C259.547 239.169 258.734 238.226 257.76 237.468C256.787 236.711 255.673 236.154 254.483 235.829C253.294 235.504 252.052 235.419 250.829 235.577ZM286.6 328.45C286.6 334.221 281.921 338.9 276.15 338.9C270.379 338.9 265.7 334.221 265.7 328.45C265.7 322.679 270.379 318 276.15 318C281.921 318 286.6 322.679 286.6 328.45ZM349.85 338.9C355.621 338.9 360.3 334.221 360.3 328.45C360.3 322.679 355.621 318 349.85 318C344.079 318 339.4 322.679 339.4 328.45C339.4 334.221 344.079 338.9 349.85 338.9Z" fill="white"/>
<path d="M149.849 146.129C148.678 144.957 146.778 144.957 145.607 146.129L132.879 158.857C132.289 159.446 131.996 160.22 132 160.993C131.996 161.765 132.289 162.539 132.879 163.129L145.607 175.857C146.778 177.028 148.678 177.028 149.849 175.857C151.021 174.685 151.021 172.786 149.849 171.614L139.228 160.993L149.849 150.371C151.021 149.2 151.021 147.3 149.849 146.129Z" fill="#4EA16B"/>
<path d="M138.757 160.995C138.757 159.338 140.101 157.995 141.757 157.995H183.757C185.414 157.995 186.757 159.338 186.757 160.995C186.757 162.652 185.414 163.995 183.757 163.995H141.757C140.101 163.995 138.757 162.652 138.757 160.995Z" fill="#4EA16B"/>
<path d="M362.151 146.129C363.322 144.957 365.222 144.957 366.393 146.129L379.121 158.857C379.711 159.446 380.004 160.22 380 160.993C380.004 161.765 379.711 162.539 379.121 163.129L366.393 175.857C365.222 177.028 363.322 177.028 362.151 175.857C360.979 174.685 360.979 172.786 362.151 171.614L372.772 160.993L362.151 150.371C360.979 149.2 360.979 147.3 362.151 146.129Z" fill="#4EA16B"/>
<path d="M373.243 160.995C373.243 159.338 371.9 157.995 370.243 157.995H328.243C326.586 157.995 325.243 159.338 325.243 160.995C325.243 162.652 326.586 163.995 328.243 163.995H370.243C371.9 163.995 373.243 162.652 373.243 160.995Z" fill="#4EA16B"/>
</svg>

After

Width:  |  Height:  |  Size: 3.2 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 44 KiB

View File

@@ -0,0 +1,179 @@
$primary-color: rgb(99, 159, 112);
$accent-color: rgb(130, 180, 140);
$content-width: 965px;
$scroll-bar-width: 8px;
$scroll-bar-height: 6.5px;
$scroll-bar-border-radius: 50px;
$scroll-bar-track-color-code: rgb(86, 96, 110);
$scroll-bar-thumb-hover-color-code: rgb(121, 135, 155);
:root {
--c-brand: #{$primary-color};
--c-brand-light: #{$accent-color};
--content-width: #{$content-width};
}
code {
padding: 3px 5px 3px 5px;
border-radius: 5px;
}
.badge {
margin-bottom: 5px;
}
.custom-container {
border-radius: 5px;
}
.sidebar-item {
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
}
.language-text {
::-webkit-scrollbar-track {
background: #{$scroll-bar-track-color-code};
border-radius: #{$scroll-bar-border-radius};
}
::-webkit-scrollbar-thumb:hover {
background: #{$scroll-bar-thumb-hover-color-code};
}
}
.language-kotlin {
::-webkit-scrollbar-track {
background: #{$scroll-bar-track-color-code};
border-radius: #{$scroll-bar-border-radius};
}
::-webkit-scrollbar-thumb:hover {
background: #{$scroll-bar-thumb-hover-color-code};
}
}
.language-java {
::-webkit-scrollbar-track {
background: #{$scroll-bar-track-color-code};
border-radius: #{$scroll-bar-border-radius};
}
::-webkit-scrollbar-thumb:hover {
background: #{$scroll-bar-thumb-hover-color-code};
}
}
.language-groovy {
::-webkit-scrollbar-track {
background: #{$scroll-bar-track-color-code};
border-radius: #{$scroll-bar-border-radius};
}
::-webkit-scrollbar-thumb:hover {
background: #{$scroll-bar-thumb-hover-color-code};
}
}
.language-xml {
::-webkit-scrollbar-track {
background: #{$scroll-bar-track-color-code};
border-radius: #{$scroll-bar-border-radius};
}
::-webkit-scrollbar-thumb:hover {
background: #{$scroll-bar-thumb-hover-color-code};
}
}
.hidden-anchor-page {
h6 {
color: transparent;
margin-bottom: -35px;
padding-top: 50px;
}
}
.code-page {
h1 {
font-size: 24pt;
}
h2 {
font-size: 18pt;
}
h3 {
font-size: 15pt;
}
h4 {
font-size: 12pt;
}
h5 {
font-size: 9.6pt;
}
h6 {
font-size: 8.4pt;
}
.symbol {
color: rgb(142, 155, 168);
}
.deprecated {
color: rgb(142, 155, 168);
text-decoration: line-through;
}
}
html {
scroll-behavior: smooth;
::-webkit-scrollbar {
width: #{$scroll-bar-width};
height: #{$scroll-bar-height};
}
::-webkit-scrollbar-track {
background: rgb(234, 236, 239);
}
::-webkit-scrollbar-thumb {
background: rgb(189, 189, 189);
border-radius: #{$scroll-bar-border-radius};
}
::-webkit-scrollbar-thumb:hover {
background: rgb(133, 133, 133);
border-radius: #{$scroll-bar-border-radius};
}
}
html.dark {
--c-brand: #{$primary-color};
--c-brand-light: #{$accent-color};
--content-width: #{$content-width};
::-webkit-scrollbar {
width: #{$scroll-bar-width};
height: #{$scroll-bar-height};
}
::-webkit-scrollbar-track {
background: rgb(41, 46, 53);
}
::-webkit-scrollbar-thumb {
background: rgb(65, 72, 83);
border-radius: #{$scroll-bar-border-radius};
}
::-webkit-scrollbar-thumb:hover {
background: rgb(56, 62, 72);
border-radius: #{$scroll-bar-border-radius};
}
}

View File

@@ -0,0 +1,27 @@
# About This Document
> This document is powered by [VuePress](https://v2.vuepress.vuejs.org/en).
## License
[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.
```
Copyright © 2019 HighCapable

View File

@@ -0,0 +1,59 @@
# Changelog
> The version update history of `Hikage` is recorded here.
::: danger
We will only maintain the latest API version, if you are using an outdate API version, you voluntarily renounce any possibility of maintenance.
:::
::: warning
To avoid translation time consumption, Changelog will use **Google Translation** from **Chinese** to **English**, please refer to the original text for actual reference.
Time zone of version release date: **UTC+8**
:::
## hikage-core
### 1.0.0 | 2025.04.20 &ensp;<Badge type="tip" text="latest" vertical="middle" />
- The first version is submitted to Maven
## hikage-compiler
### 1.0.0 | 2025.04.20 &ensp;<Badge type="tip" text="latest" vertical="middle" />
- The first version is submitted to Maven
## hikage-extension
### 1.0.0 | 2025.04.20 &ensp;<Badge type="tip" text="latest" vertical="middle" />
- The first version is submitted to Maven
## hikage-extension-betterandroid
### 1.0.0 | 2025.04.20 &ensp;<Badge type="tip" text="latest" vertical="middle" />
- The first version is submitted to Maven
## hikage-extension-compose
### 1.0.0 | 2025.04.20 &ensp;<Badge type="tip" text="latest" vertical="middle" />
- The first version is submitted to Maven
## hikage-widget-androidx
### 1.0.0 | 2025.04.20 &ensp;<Badge type="tip" text="latest" vertical="middle" />
- The first version is submitted to Maven
## hikage-widget-material
### 1.0.0 | 2025.04.20 &ensp;<Badge type="tip" text="latest" vertical="middle" />
- The first version is submitted to Maven

View File

@@ -0,0 +1,16 @@
# Contact Us
> If you have any questions in use, or have any constructive suggestions, you can contact us.
Join our developers group.
- [Click to join Telegram group](https://t.me/BetterAndroid)
- [Click to join Telegram group (Developer)](https://t.me/HighCapable_Dev)
Find me on **Twitter** [@fankesyooni](https://twitter.com/fankesyooni).
## Help with Maintenance
Thank you for choosing and using `Hikage`.
If you have code-related suggestions and requests, you can submit a Pull Request on GitHub.

View File

@@ -0,0 +1,75 @@
# Looking for Future
> The future is bright and uncertain, let us look forward to the future development space of `Hikage`.
## Future Plans
> Features that `Hikage` may add later are included here.
### Process AttrtibuteSet
`Hikage` will support processing `AttributeSet` in the future to dock with the original XML properties to implement the takeover
of some third-party components that are not open to customization of layout properties in the code.
`Hikage` currently supports automated creation of `XmlBlock`, but does not support the direct processing
of customized `AttributeSet`. Because of its historical problems and high processing difficulty, it may compromise whether to continue to improve this function in the later stage.
> The following example
```kotlin
TextView(
id = "text_view",
// Attributes passed through AttributeSet.
attrs = {
namespace("android") {
set("text", "Hello, World!")
set("textSize", "16sp")
set("gravity", "center")
}
}
) {
// Attributes passed through code.
text = "Hello, World!"
textSize = 16f
gravity = Gravity.CENTER
}
```
### Generate Components ID
`Hikage` may support the direct call function to generate component IDs customized with strings as required in the future.
> The following example
```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
// Create TypedHikage.
val myLayout = MyLayout.asTyped().build().create(context)
// Or, use lazy init.
val myLayout by context.lazyTypedHikage(MyLayout)
// Directly call the ID generated from the string.
val linLayout = myLayout.linLayout
val textView = myLayout.textView
// Get the root layout, i.e. LinearLayout.
val root = myLayout.root
```

View File

@@ -0,0 +1,18 @@
# R8 & Proguard Obfuscate
> In most scenarios, the app packages can be compressed through obfuscation,
> here is an introduction to how to configure obfuscation rules.
`Hikage` does not require additional configuration of obfuscation rules, since `View` loaded by Hikage does not need to be defined in XML, they can be equally obfuscated.
You can force them to be confused with your custom `View`, such as `com.yourpackage.YourView`, using the following rules.
```
-allowobfuscation class com.yourpackage.YourView
```
If you must prevent `Hikage` from being confused or something that occurs after being confused, you can use the following rules to prevent `Hikage` from being confused.
```
-keep class com.highcapable.hikage**
```

View File

@@ -0,0 +1,120 @@
# Introduce
> `Hikage` (Pronunciation /ˈhɪkɑːɡeɪ/) is an Android responsive UI building tool.
## Background
This is an Android responsive UI build tool designed to focus on **Real-time code building UI**.
The project icon was designed by [MaiTungTM](https://github.com/Lagrio),
the name is taken from the original song "Haru**hikage**" in "BanG Dream It's MyGO!!!!!".
<details><summary>Why...</summary>
<div align="center">
<img src="/images/nagasaki_soyo.png" width = "100" height = "100" alt="LOGO"/>
**なんで春日影レイアウト使いの?**
</div>
</details>
Unlike Jetpack Compose's declarative UI, Hikage focuses on Android native platforms,
and its design goal is to enable developers to quickly build UIs and directly support Android native components.
**<u>Hikage is just a UI build tool and does not provide any UI components themselves</u>**.
Rejecting duplicate wheels, our solution is always compatible and efficient. Now you can abandon ViewBinding and XML and even `findViewById` and try
to use the code layout directly.
`Hikage` works better with another project [BetterAndroid](https://github.com/BetterAndroid/BetterAndroid) and
`Hikage` itself will automatically reference the `BetterAndroid` related dependencies as the core content.
## Usage
Hikage is mainly suitable for developers focusing on native Android platform development.
Since Kotlin became the primary development language, there hasn't been a perfect tool to implement dynamic code layouts using DSL.
Therefore, projects that do not use Jetpack Compose still need to use the original XML. Although ViewBinding provides support, it is still not very user-friendly.
Hikage inherits the design schemes of [Anko](https://github.com/Kotlin/anko) and [Splitties](https://github.com/LouisCAD/Splitties),
and draws on the DSL function naming scheme of Jetpack Compose. On this basis, it has made many improvements,
making it closer to native in terms of usage cost and closer to Jetpack Compose in terms of writing style.
> Comparison of various DSL layout schemes
:::: 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
)
}
```
:::
::::
The basic part of Hikage **does not require any external or additional compilation plugins**.
It can be **plug-and-play** and **create a View object anywhere** that can be set to the parent layout and `Window`.
Hikage **fully supports** hybrid layouts. You can embed XML (using the `R.layout` scheme to load layouts), ViewBinding, and even Jetpack Compose within Hikage.
## Language Requirement
It is recommended to use Kotlin as the preferred development language. This project is entirely written in Kotlin, and there are no plans to support Java compatibility.
All demo examples in the documentation will be described using Kotlin. If you are not familiar with Kotlin, you may encounter difficulties in using this project effectively.
## Contribution
The maintenance of this project is inseparable from the support and contributions of all developers.
This project is currently in its early stages, and there may still be some problems or lack of functions you need.
If possible, feel free to submit a PR to contribute features you think are needed to this project or goto [GitHub Issues](repo://issues)
to make suggestions to us.

View File

@@ -0,0 +1,89 @@
# Quick Start
> Integrate `Hikage` into your project.
## Project Requirements
The project needs to be created using `Android Studio` or `IntelliJ IDEA` and be of type Android or Kotlin Multiplatform
project and have integrated Kotlin environment dependencies.
- Android Studio (It is recommended to get the latest version [from here](https://developer.android.com/studio))
- IntelliJ IDEA (It is recommended to get the latest version [from here](https://www.jetbrains.com/idea))
- Kotlin 1.9.0+, Gradle 8+, Java 17+, Android Gradle Plugin 8+
### Configure Repositories
The dependencies of `Hikage` are published in **Maven Central** and our public repository,
you can use the following method to configure repositories.
We recommend using Kotlin DSL as the Gradle build script language and [SweetDependency](https://github.com/HighCapable/SweetDependency)
to manage dependencies.
#### SweetDependency (Recommended)
Configure repositories in your project's `SweetDependency` configuration file.
```yaml
repositories:
google:
maven-central:
# (Optional) You can add this URL to use our public repository
# When Sonatype-OSS fails and cannot publish dependencies, this repository is added as a backup
# For details, please visit: https://github.com/HighCapable/maven-repository
highcapable-maven-releases:
url: https://raw.githubusercontent.com/HighCapable/maven-repository/main/repository/releases
```
#### Traditional Method
Configure repositories in your project `build.gradle.kts`.
```kotlin
repositories {
google()
mavenCentral()
// (Optional) You can add this URL to use our public repository
// When Sonatype-OSS fails and cannot publish dependencies, this repository is added as a backup
// For details, please visit: https://github.com/HighCapable/maven-repository
maven("https://raw.githubusercontent.com/HighCapable/maven-repository/main/repository/releases")
}
```
### Configure Java Version
Modify the Java version of Kotlin in your project `build.gradle.kts` to 17 or above.
> Kotlin DSL
```kt
android {
compileOptions {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
}
kotlinOptions {
jvmTarget = "17"
}
}
```
## Functional Overview
The project is divided into multiple modules. You can choose the module you wish to include as a dependency in your project, but be sure to include the **hikage-core** module.
Click the corresponding module below to view detailed feature descriptions.
- [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
You can find some samples [here](repo://tree/main/samples) view the corresponding demo project to better understand how these functions work and quickly
select the functions you need.

View File

@@ -0,0 +1,65 @@
---
home: true
title: Home
heroImage: /images/logo.svg
actions:
- text: Get Started
link: /en/guide/home
type: primary
- text: Changelog
link: /en/about/changelog
type: secondary
features:
- title: Native Control
details: Using View as the foundation and Kotlin as the development language, 100% dynamic code layout, no additional configuration required, supports custom Views.
- title: Fully Compatible
details: Supports embedding and mixing XML, ViewBinding, and Jetpack Compose, and provides support for Material components and Jetpack.
- 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: Apache-2.0 License | Copyright (C) 2019 HighCapable
---
### Layout, it's that flexible.
:::: 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>
```
:::
::::

View File

@@ -0,0 +1,171 @@
# hikage-compiler
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.hikage/hikage-compiler?logo=apachemaven&logoColor=orange)
<span style="margin-left: 5px"/>
![Maven metadata URL](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fraw.githubusercontent.com%2FHighCapable%2Fmaven-repository%2Frefs%2Fheads%2Fmain%2Frepository%2Freleases%2Fcom%2Fhighcapable%2Fhikage%2Fhikage-compiler%2Fmaven-metadata.xml&logo=apachemaven&logoColor=orange&label=highcapable-maven-releases)
<span style="margin-left: 5px"/>
![Android Min SDK](https://img.shields.io/badge/Min%20SDK-21-orange?logo=android)
This is a Hikage automatic compilation module.
## Configure Dependency
You can add this module to your project using the following method.
::: warning
You need to integrate the [Google KSP](https://github.com/google/ksp/releases) plugin in your project that is suitable for the current Kotlin version of your project.
:::
### SweetDependency (Recommended)
Add dependency in your project's `SweetDependency` configuration file.
```yaml
plugins:
com.google.devtools.ksp:
version: +
libraries:
com.highcapable.hikage:
hikage-compiler:
version: +
```
Configure dependency in your root project `build.gradle.kts`.
```kotlin
plugins {
// ...
autowire(libs.plugins.com.google.devtools.ksp) apply false
}
```
Configure dependency in your project `build.gradle.kts`.
```kotlin
plugins {
// ...
autowire(libs.plugins.com.google.devtools.ksp)
}
dependencies {
// ...
ksp(com.highcapable.hikage.hikage.compiler)
}
```
### Traditional Method
Configure dependency in your root project `build.gradle.kts`.
```kotlin
plugins {
// ...
id("com.google.devtools.ksp") version "<ksp-version>" apply false
}
```
Configure dependency in your project `build.gradle.kts`.
```kotlin
plugins {
// ...
id("com.google.devtools.ksp")
}
dependencies {
// ...
ksp("com.highcapable.hikage:hikage-compiler:<version>")
}
```
Please change `<version>` to the version displayed at the top of this document,
and change `<ksp-version>` to the KSP version corresponding to the Kotlin version currently used by your project.
## Function Introduction
Hikage's compilation module will automatically generate code at runtime.
After update, please re-run the `assembleDebug` or `assembleRelease` task to generate the latest code.
### Generate Layout Components
Hikage can automatically generate the `Hikageable` function corresponding to the layout component for the specified layout component at compile time.
#### Custom View
You can add the `HikageView` annotation on your custom `View` to mark it as a Hikage layout component.
| Parameter Name | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lparams` | LayoutParams `Class` object, if your custom `View` is a subclass of `ViewGroup`, you can declare or leave it blank to use the default value |
| `alias` | The alias of the layout component, that is, the function name to be generated, gets the name of the current Class by default |
| `requireInit` | Whether to fill in the initialization method block of the layout, the default is the omitted parameters |
| `requirePerformer` | Whether to fill in the `performer` method block of the layout, the default is an omitted parameter, which only takes effect when your custom `View` is a subclass of `ViewGroup` |
> The following example
```kotlin
@HikageView(lparams = LinearLayout.LayoutParams::class)
class MyLayout(context: Context, attrs: AttributeSet? = null) : LinearLayout(context, attrs) {
// ...
}
```
Once compiled, you can use `MyLayout` as the layout component in the Hikage layout.
> The following example
```kotlin
Hikageable {
MyLayout {
TextView(
lparams = LayoutParams {
topMargin = 16.dp
}
) {
text = "Hello, World!"
}
}
}
```
#### Third-party Components
Hikage can also automatically generate layout component functions for the `View` component provided by third parties, and you can use the `HikageViewDeclaration` annotation to complete it.
| Parameter Name | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `view` | Class object of layout component that needs to be declared |
| `lparams` | LayoutParams `Class` object, if your custom `View` is a subclass of `ViewGroup`, you can declare or leave it blank to use the default value |
| `alias` | The alias of the layout component, that is, the name of the function to be generated, obtains the name of the `view` Class by default |
| `requireInit` | Whether to fill in the initialization method block of the layout, the default is the omitted parameters |
| `requirePerformer` | Whether to fill in the `performer` method block of the layout, the default is an omitted parameter, which only takes effect when your custom `View` is a subclass of `ViewGroup` |
> The following example
```kotlin
@HikageViewDeclaration(ThirdPartyView::class)
object ThirdPartyViewDeclaration
```
This annotation can be declared on any `object` class and is only used as a class that needs to be automatically included by the annotation scanner. You can set visibility to `private`, but make sure that the annotated class must be modified with `object`.
Similarly, after compilation, you can use `ThirdPartyView` as the layout component in the Hikage layout.
> The following example
```kotlin
Hikageable {
ThirdPartyView {
// ...
}
}
```
::: tip
Hikage The function package name path for generating layout components is `com.highcapable.hikage.widget` + the full package name of your `View` or third-party `View` component.
:::

View File

@@ -0,0 +1,524 @@
# hikage-core
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.hikage/hikage-core?logo=apachemaven&logoColor=orange)
<span style="margin-left: 5px"/>
![Maven metadata URL](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fraw.githubusercontent.com%2FHighCapable%2Fmaven-repository%2Frefs%2Fheads%2Fmain%2Frepository%2Freleases%2Fcom%2Fhighcapable%2Fhikage%2Fhikage-core%2Fmaven-metadata.xml&logo=apachemaven&logoColor=orange&label=highcapable-maven-releases)
<span style="margin-left: 5px"/>
![Android Min SDK](https://img.shields.io/badge/Min%20SDK-21-orange?logo=android)
This is the core dependency of Hikage, and you need to introduce this module to use the basic features of Hikage.
## Configure Dependency
You can add this module to your project using the following method.
### SweetDependency (Recommended)
Add dependency in your project's `SweetDependency` configuration file.
```yaml
libraries:
com.highcapable.hikage:
hikage-core:
version: +
```
Configure dependency in your project `build.gradle.kts`.
```kotlin
implementation(com.highcapable.hikage.hikage.core)
```
### Traditional Method
Configure dependency in your project `build.gradle.kts`.
```kotlin
implementation("com.highcapable.hikage:hikage-core:<version>")
```
Please change `<version>` to the version displayed at the top of this document.
## Function Introduction
You can view the KDoc [click here](kdoc://hikage-core).
### Basic Usage
Use the code below to create your first Hikage layout.
First, use `Hikageable` to create a `Hikage.Delegate` object.
> The following example
```kotlin
val myLayout = Hikageable {
LinearLayout {
TextView {
text = "Hello, World!"
}
}
}
```
Then, set it to the parent or root layout you want to display.
> The following example
```kotlin
// Assume that's your Activity.
val activity: Activity
// Instantiate the Hikage object.
val hikage = myLayout.create(activity)
// Get the root layout.
val root = hikage.root
// Content view set to Activity.
activity.setContentView(root)
```
In this way, we complete a simple layout creation and setting.
### Layout Agreement
The basic layout elements of Hikage are based on the Android native `View` component.
All layout elements can be created directly using the Android native `View` component.
The creation process of all layouts will be limited to the specified scope `Hikage.Performer`,
which is called the "player" of the layout, that is, the role object that plays the layout.
This object can be created and maintained in the following ways.
#### Hikageable
As shown in [Basic Usage](#basic-usage), `Hikageable` can directly create a `Hikage.Delegate` or `Hikage` object.
In DSL, you can get the `Hikage.Performer` object to create the layout content.
The first solution is created anywhere.
> The following example
```kotlin
// myLayout is a Hikage.Delegate object.
val myLayout = Hikageable {
// ...
}
// Assume that's your Context.
val context: Context
// Instantiate the Hikage object where the Context is needed.
val hikage = myLayout.create(context)
```
The second solution is created directly where `Context` exists.
> The following example
```kotlin
// Assume that's your Context.
val context: Context
// Create a layout, myLayout is a Hikage object.
val myLayout = Hikageable(context) {
// ...
}
```
#### HikageBuilder
In addition to the above methods, you can also maintain a `HikageBuilder` object to pre-create the layout.
First, we need to create a `HikageBuilder` object and define it as a singleton.
> The following example
```kotlin
object MyLayout : HikageBuilder {
override fun build() = Hikageable {
// ...
}
}
```
Then, use it where needed, there are two options as follows.
The first solution is to create a `Hikage.Delegate` object directly using `build`.
> The following example
```kotlin
// myLayout is a Hikage.Delegate object.
val myLayout = MyLayout.build()
// Assume that's your Context.
val context: Context
// Instantiate the Hikage object where the Context is needed.
val hikage = myLayout.create(context)
```
The second solution is to create the `Hikage` delegate object using `Context.lazyHikage`.
For example, we can use it like `ViewBinding` in `Activity`.
> The following example
```kotlin
class MyActivity: AppCompatActivity() {
private val myLayout by lazyHikage(MyLayout)
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Get the root layout.
val root = myLayout.root
// Content view set to Activity.
setContentView(root)
}
}
```
### Basic Layout Components
Hikage uses a functional component creation scheme consistent with Jetpack Compose.
Its layout is done using two basic components, the `View` and `ViewGroup` functions.
They correspond to Android native components based on `View` and `ViewGroup`, respectively.
#### View
The basic parameters of the `View` function are the following three, and the `View` object type created using generic definitions.
If the generic type is not declared, the default is to use `android.view.View` as the object type created.
| Parameter Name | Description |
| -------------- | ----------------------------------------------------------------------------- |
| `lparams` | Layout parameter, i.e. `ViewGroup.LayoutParams`, created using `LayoutParams` |
| `id` | Used to find the ID of the created object, defined using a string |
| `init` | The initialization method body of `View`, passed as the last DSL parameter |
> The following example
```kotlin
View<TextView>(
lparams = LayoutParams(),
id = "my_text_view"
) {
text = "Hello, World!"
textSize = 16f
gravity = Gravity.CENTER
}
```
#### ViewGroup
The basic parameters of the `ViewGroup` function are four, and compared with the `View` function, there is one more `performer` parameter.
It must declare a generic type because `ViewGroup` is an abstract class and requires a concrete implementation class.
`ViewGroup` provides an additional generic parameter based on `ViewGroup.LayoutParams` to provide layout parameters for sub-layouts.
`ViewGroup.LayoutParams` is used by default when not declared.
| Parameter Name | Description |
| -------------- | ----------------------------------------------------------------------------- |
| `lparams` | Layout parameter, i.e. `ViewGroup.LayoutParams`, created using `LayoutParams` |
| `id` | Used to find the ID of the created object, defined using a string |
| `init` | The initialization method body of `ViewGroup`, passed in as DSL parameter |
| `performer` | `Hikage.Performer` object, passed as the last DSL parameter |
The function of the `performer` parameter is to pass a new `Hikage.Performer` object downward as the creator of the sub-layout.
> The following example
```kotlin
ViewGroup<LinearLayout, LinearLayout.LayoutParams>(
lparams = LayoutParams(),
id = "my_linear_layout",
// Initialization method body will be reflected here using `init`.
init = {
orientation = LinearLayout.VERTICAL
gravity = Gravity.CENTER
}
) {
// You can continue to create sub-layouts here.
View()
}
```
#### LayoutParams
Layouts in Hikage can be set using the `LayoutParams` function, you can create it using the following parameters.
| Parameter Name | Description |
| ------------------- | --------------------------------------------------------------------------------------------- |
| `width` | Manually specify layout width |
| `height` | Manually specify layout height |
| `matchParent` | Whether to use `MATCH_PARENT` as layout width and height |
| `wrapContent` | Whether to use `WRAP_CONTENT` as layout width and height |
| `widthMatchParent` | Set width to `MATCH_PARENT` only |
| `heightMatchParent` | Set the height to `MATCH_PARENT` only |
| `body` | The initialization method body of the layout parameter, passed into as the last DSL parameter |
When you do not set the `LayoutParams` object or specify `width` and `height`, Hikage will automatically use `WRAP_CONTENT` as layout parameters.
The type of the `body` method body comes from the second generic parameter provided by the upper layer [ViewGroup](#viewgroup).
> The following example
```kotlin
View(
// Assume that the layout parameter type provided by the upper layer is LinearLayout.LayoutParams.
lparams = LayoutParams(width = 100.dp) {
topMargin = 20.dp
}
)
```
If you only need a horizontally filled layout, you can use `widthMatchParent = true` directly.
> The following example
```kotlin
View(
lparams = LayoutParams(widthMatchParent = true)
)
```
#### Layout
Hikage supports references to third-party layouts, you can pass in XML layout resource IDs, other Hikage objects, and `View` objects, and even `ViewBinding`.
> The following example
```kotlin
ViewGroup<...> {
// Quote XML layout resource ID.
Layout(R.layout.my_layout)
// Quote ViewBinding.
Layout<MyLayoutBinding>()
// Reference another Hikage or Hikage.Delegate object.
Layout(myLayout)
}
```
### Positioning Layout Components
Hikage supports locating components using `id`. In the example above, we used the `id` parameter to set the component's ID.
After setting the ID, you can use the `Hikage.get` method to get them.
> The following example
```kotlin
val myLayout = Hikageable {
View<TextView>(id = "my_text_view") {
text = "Hello, World!"
}
}
// Assume that's your Context.
val context: Context
// Instantiate the Hikage object where the Context is needed.
val hikage = myLayout.create(context)
// Get the specified component and return the View type.
val textView = hikage["my_text_view"]
// Get the specified component and declare the component type.
val textView = hikage.get<TextView>("my_text_view")
// If you are not sure whether the ID exists, you can use the `getOrNull` method.
val textView = hikage.getOrNull<TextView>("my_text_view")
```
### Custom Layout Components
Hikage provides functions corresponding to component class names for Android basic layout components.
You can directly use these functions to create components without using generics to declare them. If you need components provided by Jetpack or Material,
the [hikage-widget-androidx](../library/hikage-widget-androidx.md) or [hikage-widget-material](../library/hikage-widget-material.md) modules can be introduced.
> The following example
```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
}
}
```
The initialized `View` or `ViewGroup` objects return instances of their own object type, which you can use in the following layout.
> The following example
```kotlin
val textView = TextView {
text = "Hello, World!"
textSize = 16f
gravity = Gravity.CENTER
}
Button {
text = "Click Me!"
setOnClickListener {
// Use the textView object directly.
textView.text = "Clicked!"
}
}
```
If the provided components do not meet your needs, you can create your own components manually.
> The following example
```kotlin
// Suppose you have defined your custom components.
class MyCustomView(context: Context, attrs: AttributeSet? = null) : View(context, attrs) {
// ...
}
// Below, create the function corresponding to the component.
// Custom components must declare this annotation.
// Declaring the annotation of the component is contagious,
// and this annotation is required in every scope used to build the layout.
@Hikageable
// The naming of functions can be done at will, but it is recommended to use a big camel name.
// The signature part of the function needs to be fixedly
// declared as `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> = {},
// If this component is a container, you can declare a `performer` parameter.
// performer: HikagePerformer<LP> = {}
) = View<MyCustomView>(lparams, id, init)
```
It would seem tedious to implement such complex functions manually every time.
If you want to be able to automatically generate component functions, you can introduce and refer to the [hikage-compiler](../library/hikage-compiler.md) module.
### Custom Layout Factory
Hikage supports custom layout factories and is compatible with `LayoutInflater.Factory2`.
You can customize events and listening during the Hikage layout inflating process in the following ways.
> The following example
```kotlin
val factory = HikageFactory { parent, base, context, params ->
// You can customize the behavior of the layout factory here.
// For example, create a new View object in your own way.
// `parent` is the ViewGroup object to which the current component is to be added,
// and if not, it is `null`.
// `base` is the View object created for the previous HikageFactory, if not, it is `null`.
// `params` object contains the component ID, AttributeSet and Class objects of View.
val view = MyLayoutFactory.createView(context, params)
// You can also initialize and set the created View object here.
view.setBackgroundColor(Color.RED)
// Return the created View object.
// Return `null` will use the default component inflating method.
view
}
```
You can also pass in the `LayoutInflater` object directly to automatically inflate and use the `LayoutInflater.Factory2` in it.
> The following example
```kotlin
// Assume that this is your LayoutInflater object.
val layoutInflater: LayoutInflater
// Create HikageFactory object through LayoutInflater.
val factory = HikageFactory(layoutInflater)
```
Then set it to the Hikage layout you need to inflate.
> The following example
```kotlin
// Assume that's your Context.
val context: Context
// Create Hikage object.
val hikage = Hikageable(
context = context,
factory = {
// Add a custom HikageFactory object.
add(factory)
// Add directly.
add { parent, base, context, params ->
// ...
null
}
// Add multiple consecutively.
addAll(factories)
}
) {
LinearLayout {
TextView {
text = "Hello, World!"
}
}
}
```
::: tip
Hikage will inflate the layout according to the `LayoutInflater.Factory2` of the `Context` object, if you are using `AppCompatActivity`,
Components in the layout will be automatically replaced with the corresponding Compat component or Material component,
which is consistent with the characteristics of the XML layout.
If you do not need this feature to be effective by default, you can turn it off globally using the following method.
> The following example
```kotlin
Hikage.isAutoProcessWithFactory2 = false
```
:::
### Preview Layout
Hikage supports previewing layouts in Android Studio.
With the help of the custom `View` preview plugin that comes with Android Studio, you can preview the layout using the following methods.
You just need to define a custom `View` for the preview layout and inherit from `HikagePreview`.
> The following example
```kotlin
class MyLayoutPreview(context: Context, attrs: AttributeSet?) : HikagePreview(context, attrs) {
override fun build() = Hikageable {
LinearLayout {
TextView {
text = "Hello, World!"
}
}
}
}
```
Then the preview pane should appear on the right side of your current window.
After opening, click "Build & Refresh". The preview will be automatically displayed after the compilation is completed.
:::tip
`HikagePreview` implements the `HikageBuilder` interface, you can return any Hikage layout in the `build` method for preview.
:::
::: danger
`HikagePreview` supports previewing layouts in Android Studio only, do not use it at runtime or add it to any XML layout.
:::

View File

@@ -0,0 +1,74 @@
# hikage-extension-betterandroid
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.hikage/hikage-extension-betterandroid?logo=apachemaven&logoColor=orange)
<span style="margin-left: 5px"/>
![Maven metadata URL](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fraw.githubusercontent.com%2FHighCapable%2Fmaven-repository%2Frefs%2Fheads%2Fmain%2Frepository%2Freleases%2Fcom%2Fhighcapable%2Fhikage%2Fhikage-extension-betterandroid%2Fmaven-metadata.xml&logo=apachemaven&logoColor=orange&label=highcapable-maven-releases)
<span style="margin-left: 5px"/>
![Android Min SDK](https://img.shields.io/badge/Min%20SDK-21-orange?logo=android)
This is a Hikage extension dependency for [BetterAndroid](https://github.com/BetterAndroid/BetterAndroid) UI component-related features.
## Configure Dependency
You can add this module to your project using the following method.
### SweetDependency (Recommended)
Add dependency in your project's `SweetDependency` configuration file.
```yaml
libraries:
com.highcapable.hikage:
hikage-extension-betterandroid:
version: +
```
Configure dependency in your project `build.gradle.kts`.
```kotlin
implementation(com.highcapable.hikage.hikage.extension.betterandroid)
```
### Traditional Method
Configure dependency in your project `build.gradle.kts`.
```kotlin
implementation("com.highcapable.hikage:hikage-extension-betterandroid:<version>")
```
Please change `<version>` to the version displayed at the top of this document.
## Function Introduction
You can view the KDoc [click here](kdoc://hikage-extension-betterandroid).
### Adapter Extension
Hikage provides layout extension function for BetterAndroid's [Adapter](https://betterandroid.github.io/BetterAndroid/en/library/ui-component#adapter),
you can use the Hikage layout directly on the original extension method of the adapter.
It uses the `ViewHolderDelegate` provided by BetterAndroid to create extension methods.
Here is a simple example based on `RecyclerView`.
> The following example
```kotlin
// Assume this is the dataset you need to bind to.
val listData = ArrayList<CustomBean>()
// Create and bind to a custom 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
}
}
```

View File

@@ -0,0 +1,89 @@
# hikage-extension-compose
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.hikage/hikage-extension-compose?logo=apachemaven&logoColor=orange)
<span style="margin-left: 5px"/>
![Maven metadata URL](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fraw.githubusercontent.com%2FHighCapable%2Fmaven-repository%2Frefs%2Fheads%2Fmain%2Frepository%2Freleases%2Fcom%2Fhighcapable%2Fhikage%2Fhikage-extension-compose%2Fmaven-metadata.xml&logo=apachemaven&logoColor=orange&label=highcapable-maven-releases)
<span style="margin-left: 5px"/>
![Android Min SDK](https://img.shields.io/badge/Min%20SDK-21-orange?logo=android)
This is a Hikage extension dependency for Jetpack Compose component-related features.
## Configure Dependency
You can add this module to your project using the following method.
::: warning
This module relies on the Jetpack Compose compiler plugin.
Please make sure that your project has integrated Jetpack Compose-related dependencies.
Please refer to [here](https://developer.android.com/develop/ui/compose/compiler) for details.
:::
### SweetDependency (Recommended)
Add dependency in your project's `SweetDependency` configuration file.
```yaml
libraries:
com.highcapable.hikage:
hikage-extension-compose:
version: +
```
Configure dependency in your project `build.gradle.kts`.
```kotlin
implementation(com.highcapable.hikage.hikage.extension.compose)
```
### Traditional Method
Configure dependency in your project `build.gradle.kts`.
```kotlin
implementation("com.highcapable.hikage:hikage-extension-compose:<version>")
```
Please change `<version>` to the version displayed at the top of this document.
## Function Introduction
You can view the KDoc [click here](kdoc://hikage-extension-compose).
### Use Jetpack Compose in Hikage
You can use the following methods to embed Jetpack Compose components in a Hikage layout.
> The following example
```kotlin
Hikageable {
ComposeView(
lparams = LayoutParams(matchParent = true)
) {
Text("Hello, World!")
}
}
```
### Use Hikage in Jetpack Compose
You can use the following methods to embed Hikage components in a Jetpack Compose layout.
> The following example
```kotlin
Column(
modifier = Modifier.fillMaxSize()
) {
HikageView {
TextView(
lparams = LayoutParams(matchParent = true)
) {
text = "Hello, World!"
textSize = 20f
}
}
}
```

View File

@@ -0,0 +1,210 @@
# hikage-extension
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.hikage/hikage-extension?logo=apachemaven&logoColor=orange)
<span style="margin-left: 5px"/>
![Maven metadata URL](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fraw.githubusercontent.com%2FHighCapable%2Fmaven-repository%2Frefs%2Fheads%2Fmain%2Frepository%2Freleases%2Fcom%2Fhighcapable%2Fhikage%2Fhikage-extension%2Fmaven-metadata.xml&logo=apachemaven&logoColor=orange&label=highcapable-maven-releases)
<span style="margin-left: 5px"/>
![Android Min SDK](https://img.shields.io/badge/Min%20SDK-21-orange?logo=android)
This is a Hikage extension dependency for UI component-related features.
## Configure Dependency
You can add this module to your project using the following method.
### SweetDependency (Recommended)
Add dependency in your project's `SweetDependency` configuration file.
```yaml
libraries:
com.highcapable.hikage:
hikage-extension:
version: +
```
Configure dependency in your project `build.gradle.kts`.
```kotlin
implementation(com.highcapable.hikage.hikage.extension)
```
### Traditional Method
Configure dependency in your project `build.gradle.kts`.
```kotlin
implementation("com.highcapable.hikage:hikage-extension:<version>")
```
Please change `<version>` to the version displayed at the top of this document.
## Function Introduction
You can view the KDoc [click here](kdoc://hikage-extension).
### Activity
Hikage provides better extensions for `Activity`, and creating a Hikage in `Activity` will be easier.
> The following example
```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
}
}
}
}
}
```
With the `setContentView` extension method of `Hikage`, you can set the layout using the `setContent` method like Jetpack Compose.
### Window
Using Hikage to create a layout in Window is consistent with [Activity](#activity), you just need to use the `setContentView` method to pass in a `Hikage` layout.
### Dialog
If you want to create a layout using Hikage directly in `AlertDialog`, you can now do it more simply using the following scheme.
> The following example
```kotlin
// Assume this is your Context.
val context: Context
// Create a dialog box and display it.
AlertDialog.Builder(context)
.setTitle("Hello, World!")
.setView {
TextView {
text = "Hello, World!"
textSize = 16f
}
}
.show()
```
To create a layout using Hikage in `AlertDialog`, you just need to use the `setView` method to pass in a `Hikage` layout.
If you inherited from `Dialog` for customization, you can use the `setContentView` method as in [Activity](#activity).
> The following example
```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
You can inherit from `PopupWindow` for customization and then use Hikage to create the layout,
and you can use the `setContentView` method like in [Activity](#activity).
> The following example
```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
To create a `PopupWindow` for Hikage layout, you need to use the `Context` constructor method to initialize it.
If the `Context` cannot be obtained immediately, please pass the `Context` instance to the `setContentView` method.
:::
### ViewGroup
Hikage extends the `addView` method of `ViewGroup`, and you can use the Hikage layout directly to quickly add new layouts to the current `ViewGroup`.
> The following example
```kotlin
// Assume this is your ViewGroup.
val root: FrameLayout
// Add Hikage layout.
root.addView {
TextView {
text = "Hello, World!"
textSize = 16f
}
}
```
Or, use in a custom `View`.
> The following example
```kotlin
class CustomView(context: Context, attrs: AttributeSet? = null) : FrameLayout(context, attrs) {
init {
addView {
TextView {
text = "Hello, World!"
textSize = 16f
}
}
}
}
```

View File

@@ -0,0 +1,64 @@
# hikage-widget-androidx
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.hikage/hikage-widget-androidx?logo=apachemaven&logoColor=orange)
<span style="margin-left: 5px"/>
![Maven metadata URL](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fraw.githubusercontent.com%2FHighCapable%2Fmaven-repository%2Frefs%2Fheads%2Fmain%2Frepository%2Freleases%2Fcom%2Fhighcapable%2Fhikage%2Fhikage-widget-androidx%2Fmaven-metadata.xml&logo=apachemaven&logoColor=orange&label=highcapable-maven-releases)
<span style="margin-left: 5px"/>
![Android Min SDK](https://img.shields.io/badge/Min%20SDK-21-orange?logo=android)
This is a Hikage extension dependency for Jetpack Compact component-related features.
## Configure Dependency
You can add this module to your project using the following method.
### SweetDependency (Recommended)
Add dependency in your project's `SweetDependency` configuration file.
```yaml
libraries:
com.highcapable.hikage:
hikage-widget-androidx:
version: +
```
Configure dependency in your project `build.gradle.kts`.
```kotlin
implementation(com.highcapable.hikage.hikage.widget.androidx)
```
### Traditional Method
Configure dependency in your project `build.gradle.kts`.
```kotlin
implementation("com.highcapable.hikage:hikage-widget-androidx:<version>")
```
Please change `<version>` to the version displayed at the top of this document.
## Function Introduction
This dependency inherits the available components from Jetpack Compact, which you can directly reference to use in Hikage.
> The following example
```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
}
}
```

View File

@@ -0,0 +1,80 @@
# hikage-widget-material
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.hikage/hikage-widget-material?logo=apachemaven&logoColor=orange)
<span style="margin-left: 5px"/>
![Maven metadata URL](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fraw.githubusercontent.com%2FHighCapable%2Fmaven-repository%2Frefs%2Fheads%2Fmain%2Frepository%2Freleases%2Fcom%2Fhighcapable%2Fhikage%2Fhikage-widget-material%2Fmaven-metadata.xml&logo=apachemaven&logoColor=orange&label=highcapable-maven-releases)
<span style="margin-left: 5px"/>
![Android Min SDK](https://img.shields.io/badge/Min%20SDK-21-orange?logo=android)
This is a Hikage extension dependency for Google Material (MDC) component-related features.
## Configure Dependency
You can add this module to your project using the following method.
### SweetDependency (Recommended)
Add dependency in your project's `SweetDependency` configuration file.
```yaml
libraries:
com.highcapable.hikage:
hikage-widget-material:
version: +
```
Configure dependency in your project `build.gradle.kts`.
```kotlin
implementation(com.highcapable.hikage.hikage.widget.material)
```
### Traditional Method
Configure dependency in your project `build.gradle.kts`.
```kotlin
implementation("com.highcapable.hikage:hikage-widget-material:<version>")
```
Please change `<version>` to the version displayed at the top of this document.
## Function Introduction
This dependency inherits the available components from Google Material (MDC), which you can directly reference to use in Hikage.
> The following example
```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()
}
}
```

17
docs-source/src/index.md Normal file
View File

@@ -0,0 +1,17 @@
---
home: true
navbar: false
sidebar: false
title: null
heroAlt: null
heroText: null
tagline: Select a language
actions:
- text: English
link: /en/
type: secondary
- text: 简体中文
link: /zh-cn/
type: secondary
footer: Apache-2.0 License | Copyright (C) 2019 HighCapable
---

View 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

View File

@@ -0,0 +1,51 @@
# 更新日志
> 这里记录了 `Hikage` 的版本更新历史。
::: danger
我们只会对最新的 API 版本进行维护,若你正在使用过时的 API 版本则代表你自愿放弃一切维护的可能性。
:::
## hikage-core
### 1.0.0 | 2025.04.20 &ensp;<Badge type="tip" text="最新" vertical="middle" />
- 首个版本提交至 Maven
## hikage-compiler
### 1.0.0 | 2025.04.20 &ensp;<Badge type="tip" text="最新" vertical="middle" />
- 首个版本提交至 Maven
## hikage-extension
### 1.0.0 | 2025.04.20 &ensp;<Badge type="tip" text="最新" vertical="middle" />
- 首个版本提交至 Maven
## hikage-extension-betterandroid
### 1.0.0 | 2025.04.20 &ensp;<Badge type="tip" text="最新" vertical="middle" />
- 首个版本提交至 Maven
## hikage-extension-compose
### 1.0.0 | 2025.04.20 &ensp;<Badge type="tip" text="最新" vertical="middle" />
- 首个版本提交至 Maven
## hikage-widget-androidx
### 1.0.0 | 2025.04.20 &ensp;<Badge type="tip" text="最新" vertical="middle" />
- 首个版本提交至 Maven
## hikage-widget-material
### 1.0.0 | 2025.04.20 &ensp;<Badge type="tip" text="最新" vertical="middle" />
- 首个版本提交至 Maven

View 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。

View 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
```

View 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**
```

View 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 的声明式 UIHikage 专注于 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) 向我们提出建议。

View 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) 找到一些示例,查看对应的演示项目来更好地了解这些功能的运作方式,快速地挑选出你需要的功能。

View 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>
```
:::
::::

View File

@@ -0,0 +1,169 @@
# hikage-compiler
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.hikage/hikage-compiler?logo=apachemaven&logoColor=orange)
<span style="margin-left: 5px"/>
![Maven metadata URL](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fraw.githubusercontent.com%2FHighCapable%2Fmaven-repository%2Frefs%2Fheads%2Fmain%2Frepository%2Freleases%2Fcom%2Fhighcapable%2Fhikage%2Fhikage-compiler%2Fmaven-metadata.xml&logo=apachemaven&logoColor=orange&label=highcapable-maven-releases)
<span style="margin-left: 5px"/>
![Android Min SDK](https://img.shields.io/badge/Min%20SDK-21-orange?logo=android)
这是 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` 组件的完整包名。
:::

View File

@@ -0,0 +1,502 @@
# hikage-core
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.hikage/hikage-core?logo=apachemaven&logoColor=orange)
<span style="margin-left: 5px"/>
![Maven metadata URL](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fraw.githubusercontent.com%2FHighCapable%2Fmaven-repository%2Frefs%2Fheads%2Fmain%2Frepository%2Freleases%2Fcom%2Fhighcapable%2Fhikage%2Fhikage-core%2Fmaven-metadata.xml&logo=apachemaven&logoColor=orange&label=highcapable-maven-releases)
<span style="margin-left: 5px"/>
![Android Min SDK](https://img.shields.io/badge/Min%20SDK-21-orange?logo=android)
这是 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 布局中。
:::

View File

@@ -0,0 +1,74 @@
# hikage-extension-betterandroid
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.hikage/hikage-extension-betterandroid?logo=apachemaven&logoColor=orange)
<span style="margin-left: 5px"/>
![Maven metadata URL](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fraw.githubusercontent.com%2FHighCapable%2Fmaven-repository%2Frefs%2Fheads%2Fmain%2Frepository%2Freleases%2Fcom%2Fhighcapable%2Fhikage%2Fhikage-extension-betterandroid%2Fmaven-metadata.xml&logo=apachemaven&logoColor=orange&label=highcapable-maven-releases)
<span style="margin-left: 5px"/>
![Android Min SDK](https://img.shields.io/badge/Min%20SDK-21-orange?logo=android)
这是 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
}
}
```

View File

@@ -0,0 +1,87 @@
# hikage-extension-compose
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.hikage/hikage-extension-compose?logo=apachemaven&logoColor=orange)
<span style="margin-left: 5px"/>
![Maven metadata URL](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fraw.githubusercontent.com%2FHighCapable%2Fmaven-repository%2Frefs%2Fheads%2Fmain%2Frepository%2Freleases%2Fcom%2Fhighcapable%2Fhikage%2Fhikage-extension-compose%2Fmaven-metadata.xml&logo=apachemaven&logoColor=orange&label=highcapable-maven-releases)
<span style="margin-left: 5px"/>
![Android Min SDK](https://img.shields.io/badge/Min%20SDK-21-orange?logo=android)
这是 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
}
}
}
```

View File

@@ -0,0 +1,208 @@
# hikage-extension
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.hikage/hikage-extension?logo=apachemaven&logoColor=orange)
<span style="margin-left: 5px"/>
![Maven metadata URL](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fraw.githubusercontent.com%2FHighCapable%2Fmaven-repository%2Frefs%2Fheads%2Fmain%2Frepository%2Freleases%2Fcom%2Fhighcapable%2Fhikage%2Fhikage-extension%2Fmaven-metadata.xml&logo=apachemaven&logoColor=orange&label=highcapable-maven-releases)
<span style="margin-left: 5px"/>
![Android Min SDK](https://img.shields.io/badge/Min%20SDK-21-orange?logo=android)
这是 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
}
}
}
}
```

View File

@@ -0,0 +1,64 @@
# hikage-widget-androidx
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.hikage/hikage-widget-androidx?logo=apachemaven&logoColor=orange)
<span style="margin-left: 5px"/>
![Maven metadata URL](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fraw.githubusercontent.com%2FHighCapable%2Fmaven-repository%2Frefs%2Fheads%2Fmain%2Frepository%2Freleases%2Fcom%2Fhighcapable%2Fhikage%2Fhikage-widget-androidx%2Fmaven-metadata.xml&logo=apachemaven&logoColor=orange&label=highcapable-maven-releases)
<span style="margin-left: 5px"/>
![Android Min SDK](https://img.shields.io/badge/Min%20SDK-21-orange?logo=android)
这是 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
}
}
```

View File

@@ -0,0 +1,80 @@
# hikage-widget-material
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.hikage/hikage-widget-material?logo=apachemaven&logoColor=orange)
<span style="margin-left: 5px"/>
![Maven metadata URL](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fraw.githubusercontent.com%2FHighCapable%2Fmaven-repository%2Frefs%2Fheads%2Fmain%2Frepository%2Freleases%2Fcom%2Fhighcapable%2Fhikage%2Fhikage-widget-material%2Fmaven-metadata.xml&logo=apachemaven&logoColor=orange&label=highcapable-maven-releases)
<span style="margin-left: 5px"/>
![Android Min SDK](https://img.shields.io/badge/Min%20SDK-21-orange?logo=android)
这是 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()
}
}
```

2004
docs-source/yarn.lock Normal file

File diff suppressed because it is too large Load Diff