# PlayAndroid

**Repository Path**: pengyoucongcode/PlayAndroid

## Basic Information

- **Project Name**: PlayAndroid
- **Description**: 项目化的安卓开发体验，采用 Jetpack Compose 进行开发，适合初学者进行学习和体验
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-04-08
- **Last Updated**: 2024-04-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: JetpackCompose, Android, Kotlin, UI, APP

## README

# PlayAndroid

## 整体介绍
本项目为 Android 开发实践项目，编程难度为中下，适合学习完 Android 基础后的新手进行完整项目的开发体验。
本项目使用的 SDK 版本为 34 即 Android 14.0，以 Kotlin 为开发语言，
采用结合了链式调用和函数式声明的 Jetpack Compose UI 框架，并采用时下流行的 MVVM(Model-View-ViewModel)设计模式。

本项目实现的功能为从指定网站上加载数据，并在指定页面中进行呈现。因为数据是动态加载的，
故而本项目的许多页面不支持在 Android Studio 中进行预览，
需要部署到真机或模拟器中才能观察，因此，建议调试本项目的初学者，
先准备好一台 SDK 版本不低于 24 即 Android 7 的手机或模拟器。

## 项目结构说明
### 1、整体结构
![alt 项目目录结构](./doc/img01.png) 本项目的整体目录结构如上所示， 项目的全部代码主要存放于 `app/src/main/java` 中，而所使用到的图片等资源文件则存放在
`app/src/main/res` 中， 而 `app/src/main/AndroidManifest.xml` 中主要设置应用相关的信息。

对于AndroidManifest.xml， 如果你选择自己手动抄写，一定不要漏了关键的两项，
即申请网络权限的 `<uses-permission android:name="android.permission.INTERNET" />`,
和 Application 标签中的 `android:name=".App"`。漏了第一项，会导致应用无法联网而不能正常运行；漏了第二项会导致
`dataSources` 没有被初始化，进而导致应用奔溃。

对于 res 目录下的东西，可以随着代码的编写逐项添加，也可以换成你自己喜欢的图标资源。

对于 java 目录下的代码文件，原则上，建议逐行编写，这样才是完整的 Android 应用开发体验。

### 2、com.pyc.playandroid 目录说明
java 目录下的结构，如下图所示：

![alt java目录的结构](./doc/img02.png)

有四个子目录和四个 Kotlin 脚本。先对四个 Kotlin 脚本进行说明：
- MainActivity：设置起始页的应用入口文件
- App: 对 `dataSources` 进行初始化
- Nav：实现应用底部导航栏并注册页面路由，由 MainActivity 的 onCreate 方法进行载入
- Play：是一个获取登录状态的接口

而四个目录分别为 `controller`、`data`、`logic` 和 `ui`，下面一一说明：
#### 2.1、controller 目录
该目录下面，只有一个 `PlayActions` 类，供全局调用，实现文章详情页的加载。
#### 2.2、data 目录
该目录的内容稍多，如下所示：
![alt data目录详情](./doc/img03.png)

该目录下的内容都是一些数据类，即 Kotlin 中的 data class，对应着 MVVM 中的第一个 M 即 Model，
而之所以都以 Bean 结尾，是因为我习惯了 Java 的命名习惯，你可以按照自己的习惯进行改名。
每个数据类的详情，还请浏览对应的源码，这里不过多展开。

#### 2.3、logic 目录
![alt logic 目录详情](./doc/logic.png)

logic 目录的详情如上图所示，一共有 5 个子目录：
- network：实现网络请求，加载文章数据
- repository：充当数据中间层，向外提供数据访问接口，实现数据与视图的解耦
- state：存放状态类，状态用于控制视图页面的渲染行为
- utils：工具集，存放提供必要辅助功能的工具类
- viewModel： 存放一个个具体的 ViewModel

在本项目中，network 中的相关实现，充当了数据源的作用，因此，建议你直接复制代码，避免手敲出错导致文章数据加载失败。

#### 2.4、ui 目录
该目录存放的是视图层的实现代码，即用户直接看到的应用页面的实现，其结构详情如下：

![alt ui 目录详情](./doc/ui.png)

如上所示，共有 4 个子目录：
- main：实现起始页的视图
- page：实现各个具体的应用页面
- theme：存放应用主题相关的代码，如颜色、形状等
- view：实现可复用的页面组件，如 topAppBar

如果，你所计划从事的是 Android UI 相关的岗位，那么整个 ui 目录下的代码，都应该手动敲一遍，
在敲的过程中积累应用页面的布局经验、交互经验等等；反之，如果你想从事 Android 应用后台相关的岗位，
那么前面的 logic 目录中的代码就应该仔细地手敲。

ui 中的四个目录，需要继续展开详细说明的为 `page` 目录，下面便就此展开说明：
##### page 目录
首先，看一下这个承担着用户直接看到的页面的实现的 page 目录下，都有什么内容：

![alt page 目录详情](./doc/page.png)

如上所示，page 下有 6 个子目录：
- article：存放文章详情页面的相关实现代码
- home：存放应用首页的相关实现代码
- login：存放登录页面的相关实现代码
- mine：存放“我的”页面的相关实现代码
- official：存放 official 页面的相关实现代码
- project：存放 Project 页面的相关实现代码

而更详细的信息，还请浏览具体的源码文件，下面只针对页面的加载顺序进行说明：
### 3、应用页面加载顺序说明
> 受 Nav.kt 的控制，应用一开始会先装载 ui/main/MainPage，而该 MainPage 会加载一个有着四个 Tab 项的底部导航栏，
> 该底部导航栏实现 Home 页、Project 页、Official 页和 Mine 页的跳转，而 Home 页是应用一打开就加载进来的。
> > 在 Homepage 中，从上到下依次加载页面标题、滚动播放的 banner 和支持上下滑动与打开动作的文章列表，
> > 这些文章列表由 ArticleListPaging 实现，而通过点击文章列表项进入的文章详情页，则是由 ArticlePage 加载。

> 单击 MainPage 加载的底部导航栏的 Project 项，就会进入 Project 页面，该页面由 ProjectPage(即ArticleListPage) 加载
> > ProjectPage 和 OfficialPage 实际上和 ArticleListPage 的完全一样，只不过使用的数据不同。因而，在手机上运行时，
> > ProjectPage 和 OfficialPage 的页面布局是相互一致的，从上到下依次为页面标题、可左右滑动的 TopBar 与显示有图片
> > 和文章标题和文章来源信息的文章列表，而列表项都是支持打开动作的。

> 单击 MainPage 加载的底部导航栏的 Mine 项，就会进入 "我的"页，该页面由位于 MinePage.kt 中的 ProfilePage 加载，
> > ProfilePage 从上到下依次加载越三分之一屏幕宽的图片、一个指示登录状态的文本和前往登录页的按钮，
> > 以及一个可以跳转到相关博客平台作者主页的列表项，这里的博客地址，可以在 UserInfoFields.kt 中进行修改。

## 编码指导
本项目虽然不复杂，但也不简单，诸多文件中有的是被调用的，有的是调用别的，所以，如果没有给一个编码顺序的说明，
就会出现某个源码文件编写到一半只能加个 TODO 标志后，转而去编写所依赖的代码文件，体验不是很好。

根据上面介绍的目录结构，我建议你首先去编写 data 中的代码，因为 data 中存放的都是 data class，没有依赖他人。

接着编写 logic 目录中的代码，而其中又以先编写 utils 中的代码为最推荐的顺序，其次是编写 logic/state 中的代码并以
TextFieldState 为最先，而 repository 目录下的代码依赖 network 目录下的代码，因此，
network 必须先于 repository 完成。 logic 中 viewModel 中的代码，放在整个 logic 的最后。

这时候，可以回过头来将 controller 中的 PlayAction 写好，之后便可以开始编写 ui 目录下的代码。在 ui 目录中，
view 目录下面的代码拥有最高的编写优先级，因为里面存放了可以复用的代码，接着 theme 目录（建议直接拷贝），
然后是 page 目录中的代码。

page 目录下，以子目录为划分，先编写哪一个都可以，只是在具体的子目录中，
避开先编写 ProjectPage、OfficialPage、MinePage、Login、HomePage ArticlePage 和 ArticleListPage，
因为这些文件中的代码都依赖了其他文件中的代码。

整体上的编码顺序，就是上面所描述的，而更具体的，还请通过阅读代码进行确定，总而言之，建议开始编写第一行代码之前，
先看一下后面的代码有无未实现的依赖，若有就应该放弃先写。

## 使用说明
将本项目的所有文件下载到本地后，若想直接体验一番的，可以用 Android Studio 打开。 Android Studio 中的 Gradle
会根据项目中的 gradle 脚本进行编译和下载相关依赖包，无需过多操作。待编译完成之后，执行找一个符合本项目最低 
Android SDK 版本要求的物理机或模拟器，便能够部署和运行应用。