📚 读书打卡小程序

一个基于 Taro + React + TypeScript 开发的读书打卡微信小程序，帮助用户记录阅读进度、管理书架、追踪阅读习惯。

✨ 功能特性

📖 扫码录书：通过扫描ISBN条形码快速添加图书
📚 书架管理：管理个人书籍收藏，支持多种视图模式
📝 阅读记录：记录每日阅读时长和进度
📊 统计分析：查看阅读数据统计和趋势
👤 个人中心：管理个人信息和偏好设置

🛠️ 技术栈

框架: Taro 4.1.6 - 多端统一开发框架
UI 库: React 18
语言: TypeScript
样式: Sass/SCSS
构建工具: Vite
包管理: pnpm
代码规范:
- ESLint - 代码检查
- Stylelint - 样式检查
- Commitlint - 提交信息规范
- Husky + lint-staged - Git hooks

📁 项目结构

reading-records-miniapp/
├── src/
│   ├── app.config.ts          # 应用配置
│   ├── app.scss              # 全局样式
│   ├── app.ts                # 应用入口
│   ├── assets/               # 静态资源
│   │   └── images/          # 图片资源
│   ├── components/          # 公共组件
│   │   └── BookDetailModal/ # 图书详情弹窗
│   ├── pages/               # 页面
│   │   ├── index/          # 首页
│   │   ├── books/          # 书架
│   │   ├── records/        # 记录
│   │   └── mine/           # 我的
│   ├── services/           # API 服务
│   │   ├── book.ts        # 图书相关 API
│   │   └── storage.ts     # 本地存储
│   ├── styles/            # 样式文件
│   │   ├── _variables.scss # 变量定义
│   │   └── _shared.scss   # 公共样式
│   └── types/             # 类型定义
│       └── book.ts        # 图书相关类型
├── config/                # 配置文件
│   ├── dev.ts            # 开发环境配置
│   ├── prod.ts           # 生产环境配置
│   └── index.ts          # 配置入口
├── dist/                 # 编译输出目录
├── babel.config.js       # Babel 配置
├── tsconfig.json        # TypeScript 配置
├── stylelint.config.mjs # Stylelint 配置
├── commitlint.config.mjs # Commitlint 配置
├── project.config.json  # 微信小程序配置
└── package.json         # 项目依赖

🚀 快速开始

环境要求

Node.js >= 18.x
pnpm >= 10.x
微信开发者工具

安装依赖

# 使用 pnpm 安装依赖
pnpm install

开发调试

# 微信小程序
pnpm dev:weapp

# H5
pnpm dev:h5

# 支付宝小程序
pnpm dev:alipay

# 百度小程序
pnpm dev:swan

# 字节跳动小程序
pnpm dev:tt

# QQ 小程序
pnpm dev:qq

构建打包

# 构建微信小程序
pnpm build:weapp

# 构建 H5
pnpm build:h5

⚙️ 配置说明

ISBN API 配置

本项目使用 ISBN.work 图书信息查询 API，需要配置 AppKey：

前往 ISBN.work 官网
注册并登录账号
获取 AppKey
在环境变量中配置：

# 设置环境变量
export TARO_APP_ISBN_APP_KEY='您的AppKey'

或在项目的 config/dev.ts 和 config/prod.ts 中配置：

env: {
  TARO_APP_ISBN_APP_KEY: '您的AppKey'
}

微信小程序配置

使用微信开发者工具打开项目根目录
修改 project.config.json 中的 appid 为你的小程序 AppID
配置合法域名（在微信公众平台设置）：
- API 域名需要添加到请求合法域名列表
- 图片域名需要添加到 downloadFile 合法域名列表

📦 数据结构

BookInfo - 图书信息

interface BookInfo {
  isbn: string          // ISBN 号
  title: string         // 书名
  author: string        // 作者
  publisher?: string    // 出版社
  publishDate?: string  // 出版日期
  publishPlace?: string // 出版地
  price?: string        // 价格
  cover?: string        // 封面图片
  summary?: string      // 内容简介
  pages?: number        // 页数
  category?: string     // 分类
  clcCode?: string      // 中图分类号
  binding?: string      // 装帧
  language?: string     // 语言
  format?: string       // 开本
  edition?: string      // 版次
  words?: string        // 字数
}

ReadingProgress - 阅读进度

interface ReadingProgress {
  bookId: string        // 图书 ID
  currentChapter: number // 当前章节
  totalChapters: number  // 总章节数
  progress: number       // 进度百分比 (0-100)
  lastReadTime: string   // 最后阅读时间
  todayReadTime: number  // 今日阅读时长（分钟）
}

ReadingRecord - 阅读记录

interface ReadingRecord {
  id: string            // 记录 ID
  bookId: string        // 图书 ID
  bookTitle: string     // 书名
  bookAuthor: string    // 作者
  chapter: number       // 章节
  chapterTitle?: string // 章节标题
  readTime: number      // 阅读时长（分钟）
  date: string          // 日期
  timestamp: number     // 时间戳
}

📝 开发规范

Git 提交规范

本项目使用 Commitlint 规范提交信息，格式如下：

<type>(<scope>): <subject>

# 示例
feat(books): 添加书籍详情弹窗
fix(records): 修复阅读记录日期显示问题
docs(readme): 更新项目文档

类型说明：

feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 重构
perf: 性能优化
test: 测试相关
chore: 构建/工具相关

代码规范

使用 ESLint 进行代码检查
使用 Stylelint 进行样式检查
提交前会自动运行 lint-staged 进行代码检查

📖 API 服务

图书服务 (book.ts)

// 扫码并获取图书信息（推荐）
const bookInfo = await scanAndGetBookInfo()

// 根据 ISBN 查询图书信息
const bookInfo = await getBookInfoByISBN('9787532776825')

存储服务 (storage.ts)

提供本地数据存储功能，包括图书、阅读记录等数据的持久化。

🎨 样式主题

项目支持自定义主题色，主要配置在 src/styles/_variables.scss:

$primary-color: #0c8918;    // 主题绿色
$text-color: #333333;       // 主文字颜色
$bg-color: #f5f5f5;        // 背景色
// ... 更多变量

🔧 常见问题

1. 扫码功能无法使用

扫码功能仅在微信小程序真机环境下可用，开发工具中无法测试。请使用真机预览功能进行测试。

2. 图片无法显示

微信小程序要求所有网络资源必须使用 HTTPS 协议。项目已自动将 API 返回的 HTTP 图片链接转换为 HTTPS。

3. API 请求失败

请检查：

AppKey 是否配置正确
API 是否有调用次数限制（可登录 PC 端网站领取免费次数）
网络请求域名 https://data.isbn.work 是否已添加到微信公众平台的合法域名列表

📄 文档资源

项目包含以下详细文档：

API_INTEGRATION.md - API 集成说明
BOOKS_VIEW_MODES.md - 书架视图模式
HTTPS_CONVERSION.md - HTTPS 转换说明
INTERACTION_FLOW.md - 交互流程设计
SASS_MODERNIZATION.md - Sass 现代化改造
THEME_UPDATE.md - 主题更新说明
src/services/README.md - 服务模块详细说明

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'feat: Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
提交 Pull Request

📜 许可证

MIT License

👨‍💻 微信小程序

若愚读书打卡

⭐️ 如果这个项目对你有帮助，欢迎 Star 支持！

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
.husky		.husky
config		config
src		src
types		types
.editorconfig		.editorconfig
.eslintrc		.eslintrc
.gitignore		.gitignore
API_INTEGRATION.md		API_INTEGRATION.md
BOOKS_VIEW_MODES.md		BOOKS_VIEW_MODES.md
HTTPS_CONVERSION.md		HTTPS_CONVERSION.md
INTERACTION_FLOW.md		INTERACTION_FLOW.md
README.md		README.md
babel.config.js		babel.config.js
commitlint.config.mjs		commitlint.config.mjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
project.config.json		project.config.json
stylelint.config.mjs		stylelint.config.mjs
tsconfig.json		tsconfig.json

pengxiaohua/reading-records-miniapp

Folders and files

Latest commit

History

Repository files navigation