docs: merge to new document and release first alpha version

This commit is contained in:
2024-01-11 00:52:17 +08:00
parent 86cadeddc4
commit 5616bb29e2
6 changed files with 622 additions and 14 deletions

View File

@@ -5,21 +5,31 @@
[![Telegram](https://img.shields.io/badge/discussion%20dev-Telegram-blue.svg?logo=telegram)](https://t.me/HighCapable_Dev)
[![QQ](https://img.shields.io/badge/discussion%20dev-QQ-blue.svg?logo=tencent-qq&logoColor=red)](https://qm.qq.com/cgi-bin/qm/qr?k=Pnsc5RY6N2mBKFjOLPiYldbAbprAU3V7&jump_from=webapi&authKey=X5EsOVzLXt1dRunge8ryTxDRrh9/IiW1Pua75eDLh9RE3KXE+bwXIYF5cWri/9lf)
[English](https://github.com/BetterAndroid/FlexiUI/blob/compose-dev/README.md) | 简体中文
[English](README.md) | 简体中文
| <img src="https://github.com/BetterAndroid/.github/blob/main/img-src/logo.png?raw=true" width = "30" height = "30" alt="LOGO"/> | [BetterAndroid](https://github.com/BetterAndroid) |
|---------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
这个项目属于上述组织,**点击上方链接关注这个组织**,发现更多好项目。
## 开发进行中说明
## 开始使用
> **Warning**
> 该项目仍处于开发的早期阶段,所有 API 都有可能发生重大变化。
>
> 该项目正式发布后,将会推送代码从 `compose-dev` 到 `compose` 分支。
[点击这里](docs/guide-zh-CN.md) 查看使用文档。
你可以随时为此分支贡献你的代码 (如果可能) 以更快地完善这个项目。
## 更新日志
[点击这里](docs/changelog-zh-CN.md) 查看历史更新日志。
## 项目推广
<!--suppress HtmlDeprecatedAttribute -->
<div align="center">
<h2>嘿,还请君留步!👋</h2>
<h3>这里有 Android 开发工具、UI 设计、Gradle 插件、Xposed 模块和实用软件等相关项目。</h3>
<h3>如果下方的项目能为你提供帮助,不妨为我点个 star 吧!</h3>
<h3>所有项目免费、开源,遵循对应开源许可协议。</h3>
<h1><a href="https://github.com/fankes/fankes/blob/main/project-promote/README-zh-CN.md">→ 查看更多关于我的项目,请点击这里 ←</a></h1>
</div>
## 第三方开源使用声明

View File

@@ -5,21 +5,31 @@
[![Telegram](https://img.shields.io/badge/discussion%20dev-Telegram-blue.svg?logo=telegram)](https://t.me/HighCapable_Dev)
[![QQ](https://img.shields.io/badge/discussion%20dev-QQ-blue.svg?logo=tencent-qq&logoColor=red)](https://qm.qq.com/cgi-bin/qm/qr?k=Pnsc5RY6N2mBKFjOLPiYldbAbprAU3V7&jump_from=webapi&authKey=X5EsOVzLXt1dRunge8ryTxDRrh9/IiW1Pua75eDLh9RE3KXE+bwXIYF5cWri/9lf)
English | [简体中文](https://github.com/BetterAndroid/FlexiUI/blob/compose-dev/README-zh-CN.md)
English | [简体中文](README-zh-CN.md)
| <img src="https://github.com/BetterAndroid/.github/blob/main/img-src/logo.png?raw=true" width = "30" height = "30" alt="LOGO"/> | [BetterAndroid](https://github.com/BetterAndroid) |
|---------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
This project belongs to the above-mentioned organization, **click the link above to follow this organization** and discover more good projects.
## WIP Notice
## Get Started
> **Warning**
> This project is still in the early stages of development, and all APIs are subject to major changes.
>
> After the project is officially released, the code will be pushed from `compose-dev` to the `compose` branch.
Click [here](docs/guide.md) to view the usage documentation.
You can always contribute your code to this branch (if possible) to improve the project faster.
## Changelog
Click [here](docs/changelog.md) to view the historical changelog.
## Promotion
<!--suppress HtmlDeprecatedAttribute -->
<div align="center">
<h2>Hey, please stay! 👋</h2>
<h3>Here are related projects such as Android development tools, UI design, Gradle plugins, Xposed Modules and practical software. </h3>
<h3>If the project below can help you, please give me a star! </h3>
<h3>All projects are free, open source, and follow the corresponding open source license agreement. </h3>
<h1><a href="https://github.com/fankes/fankes/blob/main/project-promote/README.md">→ To see more about my projects, please click here ←</a></h1>
</div>
## Third-Party Open Source Usage Statement

13
docs/changelog-zh-CN.md Normal file
View File

@@ -0,0 +1,13 @@
# 更新日志
## core
### 0.1.0-alpha01 | 2024.01.11
- 首个版本提交至 Maven
## resources
### 0.1.0-alpha01 | 2024.01.11
- 首个版本提交至 Maven

13
docs/changelog.md Normal file
View File

@@ -0,0 +1,13 @@
# Changelog
## core
### 0.1.0-alpha01 | 2024.01.11
- The first version is submitted to Maven
## resources
### 0.1.0-alpha01 | 2024.01.11
- The first version is submitted to Maven

279
docs/guide-zh-CN.md Normal file
View File

@@ -0,0 +1,279 @@
# Flexi UI 使用文档 (Jetpack Compose)
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.flexiui/core?logo=apachemaven&logoColor=orange&label=core)
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.flexiui/resources?logo=apachemaven&logoColor=orange&label=resources)
> ⚠️ 注意
>
> Flexi UI 尚在开发与测试,在 `1.0.0` 版本正式发布前 API 可能会发生变化,欢迎前往 [GitHub Issues](https://github.com/BetterAndroid/FlexiUI/issues)
> 向我们提出建议。
在开始使用之前,建议你仔细阅读此文档,以便你能更好地了解它的作用方式与功能。
你可以配合 [BetterAndroid](https://github.com/BetterAndroid/BetterAndroid) 一起使用效果更佳。
## 配置依赖
Flexi UI 分为 `core``resources` 两个模块,通常情况下你只需要添加 `core` 即可,`resources` 会自动作为 API 引入。
你可以使用如下方式将此模块添加到你的项目中。
这是一个 Kotlin Multiplatform 依赖,你需要 `org.jetbrains.kotlin.multiplatform` 插件来应用相关依赖。
我们推荐使用 Kotlin DSL 作为 Gradle 构建脚本语言并推荐使用 [SweetDependency](https://github.com/HighCapable/SweetDependency) 来管理依赖。
### SweetDependency (推荐)
在你的项目 `SweetDependency` 配置文件中添加依赖。
```yaml
libraries:
com.highcapable.flexiui:
# commonMain
core:
version: +
resources:
version: +
# androidMain
core-android:
version-ref: <this>::core
resources-android:
version-ref: <this>::resources
# iosArm64Main
core-iosarm64:
version-ref: <this>::core
resources-iosarm64:
version-ref: <this>::resources
# iosX64Main
core-iosx64:
version-ref: <this>::core
resources-iosx64:
version-ref: <this>::resources
# iosSimulatorArm64Main
core-iossimulatorarm64:
version-ref: <this>::core
resources-iossimulatorarm64:
version-ref: <this>::resources
# desktopMain
core-desktop:
version-ref: <this>::core
resources-desktop:
version-ref: <this>::resources
```
在你的项目 `build.gradle.kts` 中配置依赖。
如果你在普通的项目中使用多平台依赖,你只需要按需部署对应平台后缀的依赖即可。
```kotlin
implementation(com.highcapable.flexiui.core.android)
implementation(com.highcapable.flexiui.core.iosarm64)
implementation(com.highcapable.flexiui.core.iosx64)
implementation(com.highcapable.flexiui.core.iossimulatorarm64)
implementation(com.highcapable.flexiui.core.desktop)
```
```kotlin
implementation(com.highcapable.flexiui.resources.android)
implementation(com.highcapable.flexiui.resources.iosarm64)
implementation(com.highcapable.flexiui.resources.iosx64)
implementation(com.highcapable.flexiui.resources.iossimulatorarm64)
implementation(com.highcapable.flexiui.resources.desktop)
```
如果你在多平台项目中使用多平台依赖,你需要在 `commonMain` 中添加 `core` 依赖。
```kotlin
kotlin {
sourceSets {
val commonMain by getting {
dependencies {
implementation(com.highcapable.flexiui.core)
implementation(com.highcapable.flexiui.resources)
}
}
}
}
```
### 传统方式
在你的项目 `build.gradle.kts` 中配置依赖。
如果你在普通的项目中使用多平台依赖,你只需要按需部署对应平台后缀的依赖即可。
```kotlin
implementation("com.highcapable.flexiui:core-android:<version>")
implementation("com.highcapable.flexiui:core-iosarm64:<version>")
implementation("com.highcapable.flexiui:core-iosx64:<version>")
implementation("com.highcapable.flexiui:core-iossimulatorarm64:<version>")
implementation("com.highcapable.flexiui:core-desktop:<version>")
```
```kotlin
implementation("com.highcapable.flexiui:resources-android:<version>")
implementation("com.highcapable.flexiui:resources-iosarm64:<version>")
implementation("com.highcapable.flexiui:resources-iosx64:<version>")
implementation("com.highcapable.flexiui:resources-iossimulatorarm64:<version>")
implementation("com.highcapable.flexiui:resources-desktop:<version>")
```
如果你在多平台项目中使用多平台依赖,你需要在 `commonMain` 中添加 `core` 依赖。
```kotlin
kotlin {
sourceSets {
val commonMain by getting {
dependencies {
implementation("com.highcapable.flexiui:core:<version>")
implementation("com.highcapable.flexiui:resources:<version>")
}
}
}
}
```
请将 `<version>` 修改为此页面顶部显示的版本。
## Demo
你可以在 [这里](https://github.com/BetterAndroid/FlexiUI/tree/compose/samples) 找到一些示例,通过查看对应的演示项目来更好地了解 Flexi UI 的使用方式。
## 基本用法
你可以通过 `FlexiTheme` 提供自定义的主题来初始化一个简单的应用程序。
它的用法与 `MaterialTheme` 基本保持一致。
> 示例如下
```kotlin
@Composable
fun MyApplicationTheme(content: @Composable () -> Unit) {
FlexiTheme {
content()
}
}
```
然后通过 `Scaffold` 来创建一个基本的页面。
> 示例如下
```kotlin
MyApplicationTheme {
Scaffold(
appBar = {
PrimaryAppBar(
title = { Text("My App") }
)
}
) { innerPadding ->
Box(
modifier = Modifier
.fillMaxSize()
.padding(innerPadding)
) {
Text("Hello World!")
}
}
}
```
## 样式介绍
Flexi UI 提供了 `Colors``Shapes``Typography` 以及 `Sizes` (实验性),你可以通过它们来修改所有组件的全局样式。
> 示例如下
```kotlin
FlexiTheme(
colors = FlexiTheme.colors.copy(
themePrimary = Color.Blue
)
) {
// ...
}
```
详情请参考 Flexi UI 的设计规范文档 (完善中)。
## 组件介绍
这里介绍了 Flexi UI 中目前提供的所有可用组件,你可以在下方每个组件中找到详细的使用方法。
### Scaffold
该板块完善中,敬请期待。
### Surface
该板块完善中,敬请期待。
### AreaBox
该板块完善中,敬请期待。
### ItemBox
该板块完善中,敬请期待。
### Icon
该板块完善中,敬请期待。
### Text
该板块完善中,敬请期待。
### TextField
该板块完善中,敬请期待。
### Button
该板块完善中,敬请期待。
### CheckBox
该板块完善中,敬请期待。
### RadioButton
该板块完善中,敬请期待。
### Switch
该板块完善中,敬请期待。
### Slider
该板块完善中,敬请期待。
### ProgressIndicator
该板块完善中,敬请期待。
### Dropdown
该板块完善中,敬请期待。
### Tab
该板块完善中,敬请期待。
### NavigationBar
该板块完善中,敬请期待。
### AppBar
该板块完善中,敬请期待。
### Dialog
该板块完善中,敬请期待。
### Interaction
该板块完善中,敬请期待。

283
docs/guide.md Normal file
View File

@@ -0,0 +1,283 @@
# Flexi UI Documentation (Jetpack Compose)
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.flexiui/core?logo=apachemaven&logoColor=orange&label=core)
![Maven Central](https://img.shields.io/maven-central/v/com.highcapable.flexiui/resources?logo=apachemaven&logoColor=orange&label=resources)
> ⚠️ Notice
>
> Flexi UI is still under development and testing, and the API may change before the `1.0.0` version is officially released.
>
> We are welcome you to make suggestions to us at [GitHub Issues](https://github.com/BetterAndroid/FlexiUI/issues).
Before you start using it, it is recommended that you read this document carefully so that you can better understand how it works and its functions.
You can use it together with [BetterAndroid](https://github.com/BetterAndroid/BetterAndroid) for better results.
## Configure Dependency
Flexi UI is divided into two modules: `core` and `resources`,
normally, you only need to add `core`, and `resources` will be automatically introduced as an API.
You can add this module to your project using the following method.
This is a Kotlin Multiplatform dependency, you need the `org.jetbrains.kotlin.multiplatform` plugin to apply the relevant dependencies.
We recommend using Kotlin DSL as the Gradle build script language and [SweetDependency](https://github.com/HighCapable/SweetDependency)
to manage dependencies.
### SweetDependency (Recommended)
Add dependencies to your project `SweetDependency` configuration file.
```yaml
libraries:
com.highcapable.flexiui:
# commonMain
core:
version: +
resources:
version: +
# androidMain
core-android:
version-ref: <this>::core
resources-android:
version-ref: <this>::resources
# iosArm64Main
core-iosarm64:
version-ref: <this>::core
resources-iosarm64:
version-ref: <this>::resources
# iosX64Main
core-iosx64:
version-ref: <this>::core
resources-iosx64:
version-ref: <this>::resources
# iosSimulatorArm64Main
core-iossimulatorarm64:
version-ref: <this>::core
resources-iossimulatorarm64:
version-ref: <this>::resources
# desktopMain
core-desktop:
version-ref: <this>::core
resources-desktop:
version-ref: <this>::resources
```
Configure dependencies in your project `build.gradle.kts`.
If you use multi-platform dependencies in a regular project, you only need to deploy the corresponding platform suffix dependencies as needed.
```kotlin
implementation(com.highcapable.flexiui.core.android)
implementation(com.highcapable.flexiui.core.iosarm64)
implementation(com.highcapable.flexiui.core.iosx64)
implementation(com.highcapable.flexiui.core.iossimulatorarm64)
implementation(com.highcapable.flexiui.core.desktop)
```
```kotlin
implementation(com.highcapable.flexiui.resources.android)
implementation(com.highcapable.flexiui.resources.iosarm64)
implementation(com.highcapable.flexiui.resources.iosx64)
implementation(com.highcapable.flexiui.resources.iossimulatorarm64)
implementation(com.highcapable.flexiui.resources.desktop)
```
If you use multi-platform dependencies in a multi-platform project, you need to add the `core` dependency in `commonMain`.
```kotlin
kotlin {
sourceSets {
val commonMain by getting {
dependencies {
implementation(com.highcapable.flexiui.core)
implementation(com.highcapable.flexiui.resources)
}
}
}
}
```
### Traditional Method
Configure dependencies in your project `build.gradle.kts`.
If you use multi-platform dependencies in a regular project, you only need to deploy the corresponding platform suffix dependencies as needed.
```kotlin
implementation("com.highcapable.flexiui:core-android:<version>")
implementation("com.highcapable.flexiui:core-iosarm64:<version>")
implementation("com.highcapable.flexiui:core-iosx64:<version>")
implementation("com.highcapable.flexiui:core-iossimulatorarm64:<version>")
implementation("com.highcapable.flexiui:core-desktop:<version>")
```
```kotlin
implementation("com.highcapable.flexiui:resources-android:<version>")
implementation("com.highcapable.flexiui:resources-iosarm64:<version>")
implementation("com.highcapable.flexiui:resources-iosx64:<version>")
implementation("com.highcapable.flexiui:resources-iossimulatorarm64:<version>")
implementation("com.highcapable.flexiui:resources-desktop:<version>")
```
If you use multi-platform dependencies in a multi-platform project, you need to add the `core` dependency in `commonMain`.
```kotlin
kotlin {
sourceSets {
val commonMain by getting {
dependencies {
implementation("com.highcapable.flexiui:core:<version>")
implementation("com.highcapable.flexiui:resources:<version>")
}
}
}
}
```
Please change `<version>` to the version displayed at the top of page.
## Demo
You can find some samples [here](https://github.com/BetterAndroid/FlexiUI/tree/compose/samples) to get a better understanding of how
Flexi UI is used by looking at the corresponding demo projects.
## Basic Usage
You can initialize a simple app by providing a custom theme through `FlexiTheme`.
Its usage is basically consistent with `MaterialTheme`.
> The following example
```kotlin
@Composable
fun MyApplicationTheme(content: @Composable () -> Unit) {
FlexiTheme {
content()
}
}
```
Then use `Scaffold` to create a basic page.
> The following example
```kotlin
MyApplicationTheme {
Scaffold(
appBar = {
PrimaryAppBar(
title = { Text("My App") }
)
}
) { innerPadding ->
Box(
modifier = Modifier
.fillMaxSize()
.padding(innerPadding)
) {
Text("Hello World!")
}
}
}
```
## Style Introduction
Flexi UI provides `Colors`, `Shapes`, `Typography` and `Sizes` (experimental) through which you can modify the global styles of all components.
> The following example
```kotlin
FlexiTheme(
colors = FlexiTheme.colors.copy(
themePrimary = Color.Blue
)
) {
// ...
}
```
For details, please refer to the Flexi UI design specification document (under development).
## Component Introduction
All available components currently provided in Flexi UI are introduced here, you can find detailed usage instructions for each component below.
### Scaffold
This section is under development, stay tuned.
### Surface
This section is under development, stay tuned.
### AreaBox
This section is under development, stay tuned.
### ItemBox
This section is under development, stay tuned.
### Icon
This section is under development, stay tuned.
### Text
This section is under development, stay tuned.
### TextField
This section is under development, stay tuned.
### Button
This section is under development, stay tuned.
### CheckBox
This section is under development, stay tuned.
### RadioButton
This section is under development, stay tuned.
### Switch
This section is under development, stay tuned.
### Slider
This section is under development, stay tuned.
### ProgressIndicator
This section is under development, stay tuned.
### Dropdown
This section is under development, stay tuned.
### Tab
This section is under development, stay tuned.
### NavigationBar
This section is under development, stay tuned.
### AppBar
This section is under development, stay tuned.
### Dialog
This section is under development, stay tuned.
### Interaction
This section is under development, stay tuned.