Parchment README

项目的 README,来自 github.com/AhmadHassan-BTed/Parchment。合并为一个 markdown 文件:README.md。

Parchment

A Soulful PDF Reading Experience for Android

CI License Android Kotlin Maintainer


Reading is a sacred act of connection.
Parchment was engineered to remove the digital friction between the reader and the text.
It brings the warmth of physical paper to the precision of modern Android engineering.

Explore Architecture • View Roadmap • Contribute


The Vision

Digital PDF readers often feel cold and industrial. Parchment, envisioned and engineered by Ahmad Hassan (B-Ted), prioritizes the human element. By utilizing a "Warm Paper" design system and a gesture-driven interface, it replicates the focused, undistracted environment of a physical library.


Feature Ecosystem

Feature Technical Implementation Human Value
Warm Aesthetic Custom HSL-tailored Design System Reduces digital eye strain
Parchment Engine Android PdfRenderer + 2× Super-sampling Keeps text crisp at any zoom level
Interactive TOC Flexible TocItem Model Quick, outline-based navigation
Smart HUD Auto-hiding gesture-aware UI Maximum immersion, zero clutter
Fluid Navigation LazyColumn + Haptic Feedback loops Tactile sense of progress
Persistence Synchronized SharedPreferences layer Never lose your place in a text

Architecture Overview

The system is built on a strict Modular Layered Architecture. This ensures 100% cohesion and zero coupling between the rendering engine and the data source.

graph TD
    subgraph Presentation_Layer [UI & Presentation]
        Main[MainActivity] --> Viewer[PdfViewerScreen]
        Viewer --> Comp[Extracted UI Modules]
        Comp --> Tokens[Design Tokens]
    end

    subgraph Domain_Layer [Business Logic]
        Viewer --> Repo[BookRepository]
        Viewer --> Prefs[ReadingPreferences]
    end

    subgraph Data_Layer [Resources]
        Repo --> Config[BookConfig Model]
        Config --> Assets[PDF Assets]
    end

    style Presentation_Layer fill:#F8F1E4,stroke:#8B6914,stroke-width:2px
    style Domain_Layer fill:#F0E8D8,stroke:#6B5E4F,stroke-width:2px
    style Data_Layer fill:#E8DFCC,stroke:#5A6340,stroke-width:2px

Request & Data Flow

When a reader opens a book, the following lifecycle is executed to ensure a sub-100ms "Time to First Page."

Page Rendering Lifecycle

sequenceDiagram
    participant U as User
    participant V as ViewerScreen
    participant Util as PdfUtils
    participant R as PdfRenderer
    participant P as PdfPageRenderer

    U->>V: Selects Book
    V->>Util: Request FileDescriptor
    Util->>Util: Copy Asset to Cache (if needed)
    Util-->>V: Return Descriptor
    V->>R: Initialize Native Engine
    V->>P: Render Page 0..N
    loop Synchronized Rendering
        P->>R: openPage(index)
        R-->>P: Render Bitmap (2x Res)
        P->>P: Apply Night Mode Filter
    end
    P-->>U: Display Fluid Page

Repository Structure

The project is structured to favor feature-first discovery. Contributors can locate logic within seconds.

root/
├── .github/                # CI/CD Workflows & Templates
├── app/
│   ├── src/
│   │   ├── main/
│   │   │   ├── assets/     # Bundled PDF documents
│   │   │   └── java/ted/parchment/reader/
│   │   │       ├── data/   # Models, Prefs, Repositories
│   │   │       ├── ui/     # Themed screens & components
│   │   │       └── utils/  # Hardware/File IO Utilities
│   └── build.gradle.kts    # Modular build config
├── docs/                   # Architectural deep-dives
└── README.md               # You are here

Technical Pipeline

Build & Deployment

The project utilizes a professional GitHub Actions pipeline for every commit to ensure structural integrity.

graph LR
    Push[Push/PR] --> Lint[Linting Check]
    Lint --> Build[Debug Build]
    Build --> Test[Unit Tests]
    Test --> Result{Success?}
    Result -- Yes --> Merge[Ready to Merge]
    Result -- No --> Fix[Notify Maintainer]

Development Workflow

New contributions are welcomed. The repository is maintained with a high bar for engineering standards.

1. Development Setup
  • IDE: Android Studio Ladybug+
  • JDK: 17
  • SDK: 36 (target), 28 (min)
  • Commands:
    ./gradlew assembleDebug  # Build
    ./gradlew test           # Verify
    
2. Module Relationship Guide
Module Responsibility
PdfViewerScreen Orchestrates navigation and HUD states
VerticalZoomBar Custom Canvas-based scaling controller
PdfPageRenderer Native-to-Bitmap bridge with memory management
BookRepository Single source of truth for all book metadata

Acknowledgments & Ethics

Parchment is an original work by Ahmad Hassan (B-Ted).
It is built with a commitment to privacy:


Built for the love of reading.
Engineered by Ahmad Hassan (B-Ted)

Parchment (AhmadHassan-BTed/Parchment)

正在搜索数据库…

这是什么?Parchment 是一款用 Kotlin 和 Jetpack Compose 构建的原生 Android PDF 阅读器。它的设计风格温暖、接近纸张质感,阅读体验以手势操作为主,而不是冷冰冰的工业化界面。
我要怎样才能在自己的设备上运行它?需要从源代码自行构建:在 Android Studio 中克隆代码仓库并打开,确保已安装 JDK 17 和 Android SDK 36,然后在模拟器或真机上运行应用。
构建它需要先安装什么?构建项目需要 Android Studio Ladybug 或更新版本、JDK 17,以及作为目标版本的 Android SDK 36(最低 SDK 28)。
这个应用会追踪我的阅读数据,或把数据发送到别处吗?不会。Parchment 完全不发起网络请求,也没有分析或遥测功能,所以你的阅读记录会完全保留在自己的设备上。
PDF 渲染为什么既快又清晰?它使用 Android 原生的 PdfRenderer,并结合 2 倍超采样,让文字在任何缩放比例下都保持清晰。目标是打开书籍时,“首页显示时间”低于 100 毫秒。
代码库是怎么组织的?它遵循严格的模块化分层架构,目的是让渲染引擎和数据层完全解耦,方便贡献者快速找到对应的逻辑。
我能通过目录在 PDF 中快速跳转吗?可以。应用提供了交互式目录,基于灵活的 TocItem 模型实现,便于按大纲快速导航。
大小
67.2 MB
星标
3.6K
更新
提交Nov 10
时长
6个月
提交 · 90 天