# capacitor-react-base-app

**Repository Path**: majy89/capacitor-react-base-app

## Basic Information

- **Project Name**: capacitor-react-base-app
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Lemon Editor TV

## 项目简介

本项目是一个面向电视大屏场景的应用前端工程骨架，用于后续开发电视端 App。

当前项目的目标不是提供完整业务，而是提供一套已经打通的基础开发底座，包括：

- 基于 `React + TypeScript + Vite` 的前端开发体验
- 基于 `Ionic React` 的页面容器和 UI 组件体系
- 基于 `Capacitor` 的 Android 原生壳集成能力
- 适合电视大屏的首页、设置页和基础路由结构
- 后续扩展遥控器焦点导航、设备能力、原生桥接的起点

简而言之，这个仓库是一个“电视端 App 起步工程”。

## 当前项目能做什么

当前仓库已经具备以下能力：

- 提供一个电视端风格的首页 `/home`
- 提供一个设置页 `/settings`
- 支持通过浏览器本地调试页面
- 支持通过 `Capacitor` 同步到 Android 工程
- 支持在 Android Studio 中运行 Android App
- 提供基础的类型检查、Lint 和单元测试能力

当前还没有接入后端 API，也没有实现完整的电视遥控器焦点系统，后续可继续扩展。

## 技术栈

当前实际使用的技术栈如下：

- 前端框架：`React 18`
- 语言：`TypeScript`
- 构建工具：`Vite 6`
- UI 框架：`Ionic React 8`
- 路由：`@ionic/react-router + react-router-dom 5`
- 原生容器：`Capacitor 7`
- Android 平台：`@capacitor/android`
- 测试：`Vitest + Testing Library`
- 样式：`CSS + Tailwind 工具链`

关键配置文件：

- 前端入口：`src/main.tsx`
- 应用路由：`src/App.tsx`
- 首页：`src/pages/Home.tsx`
- 设置页：`src/pages/Settings.tsx`
- Capacitor 配置：`capacitor.config.ts`

## 目录说明

主要目录约定如下：

```text
.
├─ src/
│  ├─ pages/          页面级组件
│  ├─ components/     可复用组件
│  ├─ hooks/          自定义 Hook
│  ├─ utils/          工具函数
│  └─ test/           测试初始化文件
├─ android/           Capacitor 生成的 Android 工程
├─ dist/              前端构建产物
├─ .trae/documents/   项目需求与技术文档
├─ capacitor.config.ts
└─ package.json
```

## 路由说明

当前已经实现的页面路由如下：

- `/home`：电视端首页
- `/settings`：设置页
- `/`：默认重定向到 `/home`

## 如何启动项目

### 1. 安装依赖

当前命令以 `npm` 为准：

```bash
npm install
```

### 2. 本地浏览器调试

```bash
npm run dev
```

启动后通过 Vite 本地地址访问项目，适合先调页面布局、样式和基础逻辑。

### 3. 构建前端产物

```bash
npm run build
```

构建结果会输出到 `dist/` 目录。

### 4. 同步到 Android 工程

```bash
npx cap sync android
```

或者：

```bash
npm run cap:sync
```

这个步骤会把 `dist/` 中的前端资源同步到 `android/` 工程中。

### 5. 打开 Android 工程

```bash
npx cap open android
```

如果本地没有配置 `cap open`，也可以直接用 Android Studio 打开：

```text
android/
```

### 6. 在 Android Studio 中运行

用 Android Studio 打开 `android/` 目录后：

- 等待 Gradle 同步完成
- 选择模拟器或真机
- 点击 `Run`

## 常用命令

```bash
npm run dev         # 启动前端开发服务器
npm run build       # 构建生产包
npm run preview     # 预览构建结果
npm run check       # TypeScript 类型检查
npm run lint        # ESLint 检查
npm run test        # 运行单元测试
npm run cap:sync    # 同步前端资源到 Capacitor 平台工程
npm run cap:android # 添加 Android 平台
```

## 当前开发运行环境

以下是当前项目在本地开发过程中已经验证过的运行环境信息：

- 操作系统：`Windows`
- Node.js：`v23.11.1`
- npm：`10.9.2`
- Java 命令行环境：`JDK 17`
- Android Studio 运行 Android 工程时建议使用：`JDK 21`

说明：

- 前端开发、构建、测试在当前 `Node.js + npm` 环境下可以正常运行。
- Android 工程在 Android Studio 中运行时，建议将 `Gradle JDK` 设置为 `Embedded JDK 21` 或其他 `JDK 21`。
- 如果命令行执行 `./gradlew installDebug` 报 `无效的源发行版：21`，通常说明当前终端的 Java 版本不是 `21`。

## 当前已验证状态

截至目前，项目已验证通过的内容包括：

- `npm install`
- `npm run check`
- `npm run build`
- `npm run test`
- `npx cap sync android`
- Android Studio 启动 App 并正常渲染页面

## 当前页面状态

当前页面主要用于工程初始化验证和后续开发占位：

- 首页：展示项目名称、技术栈说明、平台状态、后续开发入口
- 设置页：展示运行平台、运行模式和应用标识

这些页面的重点是验证工程链路已经打通，而不是承载最终业务。

## 后续开发建议

如果后续继续沿着电视端 App 方向开发，建议优先补齐：

- 遥控器方向键和焦点管理
- TV 卡片组件和焦点态样式规范
- Android TV 专用清单和启动配置
- 页面模块拆分和状态管理
- API 接入层与环境配置
- 真机和 TV 模拟器适配

## 补充说明

- 项目最初是作为电视端应用骨架初始化，后续已将 `Ionic` 升级到更适合当前 `Vite + Capacitor` 组合的版本。
- 如果后续要调整包管理器，请团队统一 `npm / pnpm` 策略后再改动，避免锁文件混乱。
- `.trae/documents/` 目录中保留了项目初始需求与技术文档，可作为后续接手参考。
- gradle官网下载不了，用腾讯镜像源 distributionUrl=https\://mirrors.cloud.tencent.com/gradle//gradle-8.11.1-bin.zip