diff --git a/README-zh-CN.md b/README-zh-CN.md index a31a624..b585de4 100644 --- a/README-zh-CN.md +++ b/README-zh-CN.md @@ -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) | 简体中文 | LOGO | [BetterAndroid](https://github.com/BetterAndroid) | |---------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------| 这个项目属于上述组织,**点击上方链接关注这个组织**,发现更多好项目。 -## 开发进行中说明 +## 开始使用 -> **Warning** -> 该项目仍处于开发的早期阶段,所有 API 都有可能发生重大变化。 -> -> 该项目正式发布后,将会推送代码从 `compose-dev` 到 `compose` 分支。 +[点击这里](docs/guide-zh-CN.md) 查看使用文档。 -你可以随时为此分支贡献你的代码 (如果可能) 以更快地完善这个项目。 +## 更新日志 + +[点击这里](docs/changelog-zh-CN.md) 查看历史更新日志。 + +## 项目推广 + + +
+

嘿,还请君留步!👋

+

这里有 Android 开发工具、UI 设计、Gradle 插件、Xposed 模块和实用软件等相关项目。

+

如果下方的项目能为你提供帮助,不妨为我点个 star 吧!

+

所有项目免费、开源,遵循对应开源许可协议。

+

→ 查看更多关于我的项目,请点击这里 ←

+
## 第三方开源使用声明 diff --git a/README.md b/README.md index 85ff932..e95f981 100644 --- a/README.md +++ b/README.md @@ -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) | 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 + + +
+

Hey, please stay! 👋

+

Here are related projects such as Android development tools, UI design, Gradle plugins, Xposed Modules and practical software.

+

If the project below can help you, please give me a star!

+

All projects are free, open source, and follow the corresponding open source license agreement.

+

→ To see more about my projects, please click here ←

+
## Third-Party Open Source Usage Statement diff --git a/docs/changelog-zh-CN.md b/docs/changelog-zh-CN.md new file mode 100644 index 0000000..01839bd --- /dev/null +++ b/docs/changelog-zh-CN.md @@ -0,0 +1,13 @@ +# 更新日志 + +## core + +### 0.1.0-alpha01 | 2024.01.11 + +- 首个版本提交至 Maven + +## resources + +### 0.1.0-alpha01 | 2024.01.11 + +- 首个版本提交至 Maven \ No newline at end of file diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..94f915f --- /dev/null +++ b/docs/changelog.md @@ -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 \ No newline at end of file diff --git a/docs/guide-zh-CN.md b/docs/guide-zh-CN.md new file mode 100644 index 0000000..f78cb19 --- /dev/null +++ b/docs/guide-zh-CN.md @@ -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: ::core + resources-android: + version-ref: ::resources + # iosArm64Main + core-iosarm64: + version-ref: ::core + resources-iosarm64: + version-ref: ::resources + # iosX64Main + core-iosx64: + version-ref: ::core + resources-iosx64: + version-ref: ::resources + # iosSimulatorArm64Main + core-iossimulatorarm64: + version-ref: ::core + resources-iossimulatorarm64: + version-ref: ::resources + # desktopMain + core-desktop: + version-ref: ::core + resources-desktop: + version-ref: ::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:") +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:") + } + } + } +} +``` + +请将 `` 修改为此页面顶部显示的版本。 + +## 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 + +该板块完善中,敬请期待。 \ No newline at end of file diff --git a/docs/guide.md b/docs/guide.md new file mode 100644 index 0000000..9fda82d --- /dev/null +++ b/docs/guide.md @@ -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: ::core + resources-android: + version-ref: ::resources + # iosArm64Main + core-iosarm64: + version-ref: ::core + resources-iosarm64: + version-ref: ::resources + # iosX64Main + core-iosx64: + version-ref: ::core + resources-iosx64: + version-ref: ::resources + # iosSimulatorArm64Main + core-iossimulatorarm64: + version-ref: ::core + resources-iossimulatorarm64: + version-ref: ::resources + # desktopMain + core-desktop: + version-ref: ::core + resources-desktop: + version-ref: ::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:") +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:") + } + } + } +} +``` + +Please change `` 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. \ No newline at end of file