147 lines
6.8 KiB
Markdown
147 lines
6.8 KiB
Markdown
# TVBox-Swift
|
||
|
||
|
||
|
||
|
||
|
||
**TVBox-Swift** 是一套基于原生 Swift & SwiftUI 构建的跨平台多媒体应用核心工程。它同时支持 macOS 和 iOS 设备，致力于在双端提供无缝、现代且极其流畅的视听体验。
|
||
|
||
## ✨ 核心特性
|
||
|
||
- 🎯 **真正的原生跨平台 (Native Cross-platform)**
|
||
- 基于最新的 SwiftUI 和 SwiftData，一套代码覆盖 macOS (14.0+) 与 iOS (17.0+)。
|
||
- 高度针对多端设备的特定交互形式进行原生级适配与优化。
|
||
- 🎨 **前沿的 UI 视觉 (Modern UI & Glassmorphism)**
|
||
- 全新的毛玻璃 (Glassmorphism) 视觉设计体系。
|
||
- 精美流畅的重构动画与微交互，从列表到播放页全系更新。
|
||
- 原生级体验的暗黑模式 (Dark Mode) 全方位支持。
|
||
- 🧩 **全方位的媒体功能栈 (Media Stack)**
|
||
- **点播中心 (VOD Center):** 整合了智能资源检索、卡片化视觉呈现与多级详情页。
|
||
- *生态支持:* 原生支持解析主流的 CMS JSON/XML 数据源接口 (`type=0`, `type=1`)。
|
||
- *暂不支持:* 由于 iOS/macOS 平台原生限制与环境安全，内核未集成基于 Java 引擎或 Rhino 逻辑层，**不支持** `type=3` (Spider / Jar) 等依赖动态脚本执行的复杂爬虫源。
|
||
- **直播支持 (Live):** 稳定的流媒体播放基础构件支持。
|
||
- **内容枢纽 (Content Hub):** 便捷的搜索、智能历史记录流、一键收藏管理。
|
||
- ⚙️ **健壮的业务底层 (Robust Foundation)**
|
||
- **持久化:** 基于苹果全新 `SwiftData` 技术的现代化缓存与本地数据存储模块。
|
||
- **数据层:** 兼容性极强的网络接口解析引擎，支持非标准的 JSON/XML 接口容错处理与数据清洗。
|
||
|
||
## 🛠 技术栈
|
||
|
||
* **语言**: Swift 5.9
|
||
* **UI 框架**: SwiftUI
|
||
* **数据持久化**: SwiftData
|
||
* **工程化管理**: XcodeGen (>= 2.35)
|
||
|
||
---
|
||
|
||
## 🔍 与安卓参考版差异
|
||
|
||
以下差异基于当前仓库代码：
|
||
|
||
1. **源类型支持范围不同**
|
||
- Swift 版支持 `type=0/1/4`（XML/JSON/Remote）。
|
||
- Swift 版暂不支持 `type=3 (JAR/Spider)` 动态脚本源。
|
||
2. **配置兼容能力不同**
|
||
- 安卓版支持加密配置解密、`clan://`、相对路径修复、独立直播配置加载等。
|
||
- Swift 版当前为常规 URL 拉取 + 注释容错解析。
|
||
3. **解析链路能力不同**
|
||
- 安卓版支持嗅探/解析切换、规则引擎与相关过滤策略。
|
||
- Swift 版当前仅解析并展示解析器配置数量，未接入完整播放解析链路。
|
||
4. **播放器能力不同**
|
||
- 安卓版支持系统/IJK/EXO/外部播放器等多模式。
|
||
- Swift 版当前支持系统 `AVPlayer` 与 `VLCKit`（iOS/macOS）双引擎切换，IJK/EXO/外部播放器仍未接入。
|
||
5. **字幕体系不同**
|
||
- 安卓版支持字幕搜索、本地字幕、样式/延迟调节、内嵌轨道等。
|
||
- Swift 版当前尚未接入完整字幕功能。
|
||
6. **直播高级能力不同**
|
||
- 安卓版支持 EPG、回看/时移、分组密码、直播设置分组等。
|
||
- Swift 版当前已支持基础直播分组与线路切换，EPG 仍为简化实现。
|
||
7. **筛选与检索形态不同**
|
||
- 安卓版具备分类筛选、快速搜索、复选搜索等界面与交互。
|
||
- Swift 版当前为基础搜索与分类浏览。
|
||
8. **远程控制与推送不同**
|
||
- 安卓版具备本地控制服务与推送/遥控相关能力。
|
||
- Swift 版当前未提供该能力。
|
||
9. **设置项覆盖度不同**
|
||
- 安卓版设置项更细（DoH、渲染/缩放、历史条数、M3U8 净化、备份恢复等）。
|
||
- Swift 版当前保留核心常用设置。
|
||
10. **收藏入口闭环不同**
|
||
- 安卓版详情页支持直接加入/取消收藏。
|
||
- Swift 版目前提供收藏页与收藏数据模型，但详情页收藏入口待完善。
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
本项目的主 Xcode 工程文件并未直接包含在仓库代码中，以保证干净的源码树并降低拉取冲突风险。您需要通过 `XcodeGen` 生成配置文件。
|
||
|
||
### 1. 环境准备
|
||
确保您的设备已安装以下必备组件：
|
||
* **macOS** (最新版本)
|
||
* **Xcode 15.0** 或以上版本
|
||
* **Homebrew** (用于安装命令行工具)
|
||
|
||
安装工程生成器 `XcodeGen`:
|
||
```bash
|
||
brew install xcodegen
|
||
```
|
||
|
||
### 2. 生成 Xcode 工程
|
||
在终端进入本项目的根目录，执行以下命令以生成 `tvbox.xcodeproj` 文件：
|
||
```bash
|
||
xcodegen generate
|
||
```
|
||
|
||
### 3. 构建与运行
|
||
打开刚刚使用 XcodeGen 生成的 `tvbox.xcodeproj`：
|
||
- 选择合适的 Scheme (`tvbox` 对应 iOS, `tvbox-macOS` 对应 macOS)。
|
||
- 直接在设备或模拟器真机上 `Command + R` 进行编译与运行调试。
|
||
|
||
---
|
||
|
||
## 📦 macOS 独立打包
|
||
|
||
项目已内置自动化打包脚本 `package_mac.sh`。当您需要分发 macOS 版本时，直接运行即可自动清理缓存、构建并生成免安装的 `.dmg` 拖拽式安装包。
|
||
|
||
```bash
|
||
chmod +x package_mac.sh
|
||
./package_mac.sh
|
||
```
|
||
|
||
> **成功输出提示:** `✅ 打包完成！生成文件: TVBox-macOS.dmg`
|
||
|
||
---
|
||
|
||
## 📂 简明目录结构
|
||
|
||
```text
|
||
├── tvbox
|
||
│ ├── Models/ # 数据模型定义
|
||
│ ├── ViewModels/ # 业务逻辑与状态管理 (MVVM)
|
||
│ ├── Views/ # 所有的 SwiftUI 原生视图组件
|
||
│ ├── Services/ # 网络层、配置解析层等外部服务交互
|
||
│ ├── Persistence/ # 数据库 (SwiftData) 配置与读写管理
|
||
│ ├── Utils/ # 通用的帮助类与扩展函数
|
||
│ └── Assets.xcassets # 资源文件集、图标与预设全局色彩 (AccentColor)
|
||
├── project.yml # XcodeGen 的工程模板描述文件
|
||
├── package_mac.sh # macOS DMG 打包脚本
|
||
└── process_icon.py # 图片转换脚本套件
|
||
```
|
||
|
||
---
|
||
|
||
## 📜 开源协议
|
||
|
||
本项目采用 [MIT License](./LICENSE) 开源发布。
|
||
|
||
---
|
||
|
||
## ⚠️ 开源免责声明 (Disclaimer)
|
||
|
||
**本项目仅供编程技术交流、学习 Swift 与 SwiftUI 原生应用开发原理之目的。**
|
||
|
||
1. 开发者不对本项目代码产生的任何直接或间接后果负责。
|
||
2. 本项目**不提供、不内置、不分发**任何形式的具体影视资源、播放源配置接口（如接口 URL、JSON 规则等）。
|
||
3. 使用本项目所导致的所有合法性与知识产权纠纷（包括但不限于使用者自行导入第三方规则/接口而引发的版权问题），由使用者自行承担全部法律责任。
|
||
4. 本应用旨在作为一个本地多媒体客户端工具框架进行技术探讨，任何以此框架衍生的商业化产品与违法行为均与原作者无关。如果您下载、安装、编译或使用了本项目，即代表您理解并完全接受本免责声明之所有条款。
|