Flutter古兰经阅读插件flutter_quran的使用

Flutter古兰经阅读插件flutter_quran的使用

简介

flutter_quran 是一个用于在Flutter应用中集成古兰经阅读功能的插件。它允许用户在没有网络连接的情况下离线查看古兰经，并提供了多种功能，如浏览所有页面、保存用户的最后阅读位置、搜索文本、导航到特定章节或页码等。

主要特性

• 查看麦地那版本的古兰经页面：提供与麦地那版古兰经一致的页面布局。
• 保存用户的最后阅读页面：自动记录用户上次阅读的页面。
• 搜索古兰经中的任何文本：支持全文搜索功能。
• 导航到任意页面：用户可以快速跳转到指定页码。
• 获取并导航到任意章节（Jozz）：提供章节列表并支持直接跳转。
• 获取并导航到任意分段（Hizb）：提供分段列表并支持直接跳转。
• 获取并导航到任意章（Surah）：提供章列表并支持直接跳转。
• 添加、移除和导航到书签：用户可以标记重要内容并快速返回。

快速开始

1. 添加依赖

在 pubspec.yaml 文件中添加 flutter_quran 依赖：

dependencies:
  flutter_quran: ^0.0.2

2. 导入插件

在 Dart 文件中导入 flutter_quran：

import 'package:flutter_quran/flutter_quran.dart';

3. 初始化插件

在应用启动时初始化 flutter_quran：

void main() {
  runApp(
    MaterialApp(
      home: MyApp(),
    ),
  );
}

class MyApp extends StatefulWidget {
  [@override](/user/override)
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  [@override](/user/override)
  void initState() {
    super.initState();
    // 初始化插件
    FlutterQuran().init();
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      body: FlutterQuranScreen(),
    );
  }
}

使用示例

基本古兰经界面

你可以直接使用 FlutterQuranScreen 来显示古兰经页面：

Scaffold(
  body: FlutterQuranScreen(),
)

你也可以通过传递一些参数来自定义界面，例如添加应用栏和监听页面变化：

FlutterQuranScreen(
  appBar: AppBar(
    title: Text('古兰经'),
    actions: [
      Padding(
        padding: const EdgeInsetsDirectional.only(end: 22.0),
        child: GestureDetector(
          onTap: () => Navigator.of(context).push(
            MaterialPageRoute(builder: (ctx) => SearchScreen()),
          ),
          child: Icon(Icons.search),
        ),
      ),
    ],
  ),
  onPageChanged: (int pageIndex) {
    print("Page changed: $pageIndex");
  },
)

获取古兰经的相关数据

flutter_quran 提供了许多实用工具来获取古兰经的数据，例如章节、分段、书签等。

获取所有章节（Jozz）、分段（Hizb）和章（Surah）

final jozzs = FlutterQuran().getAllJozzs();  // 获取所有章节
final hizbs = FlutterQuran().getAllHizbs();  // 获取所有分段
final surahs = FlutterQuran().getAllSurahs(); // 获取所有章

获取特定章的完整数据

final surah = FlutterQuran().getSurah(1);  // 获取第1章（如：开端章）

书签功能

你可以添加、设置、移除、获取和导航到书签。

// 初始化时设置书签
FlutterQuran().init(userBookmarks: [
  Bookmark(id: 0, colorCode: Colors.red.value, name: "Red Bookmark")
]);

// 获取已使用的书签
final usedBookmarks = FlutterQuran().getUsedBookmarks();

// 设置书签
FlutterQuran().setBookmark(ayahId: 24, page: 4, bookmarkId: 0);

// 移除书签
FlutterQuran().removeBookmark(bookmarkId: 0);

// 导航到书签
FlutterQuran().navigateToBookmark(bookmark);

搜索功能

你可以通过 TextField 实现搜索功能，实时查找古兰经中的文本。

TextField(
  onChanged: (txt) {
    final _ayahs = FlutterQuran().search(txt);
    setState(() {
      ayahs = [..._ayahs];
    });
  },
  decoration: InputDecoration(
    border: OutlineInputBorder(borderSide: BorderSide(color: Colors.black)),
    hintText: '搜索',
  ),
)

导航功能

你可以通过以下方法导航到特定的章节、页码、分段、书签等：

FlutterQuran().navigateToAyah(ayah);       // 导航到特定经文
FlutterQuran().navigateToPage(1);          // 导航到第1页
FlutterQuran().navigateToJozz(1);          // 导航到第1章节
FlutterQuran().navigateToHizb(1);          // 导航到第1分段
FlutterQuran().navigateToSurah(1);         // 导航到第1章
FlutterQuran().navigateToBookmark(bookmark); // 导航到书签

使用古兰经样式

如果你需要使用古兰经的样式，可以通过 hafsStyle 获取：

FlutterQuran().hafsStyle;

示例图片

以下是使用 flutter_quran 插件生成的一些界面截图：

完整示例代码

以下是一个完整的示例代码，展示了如何使用 flutter_quran 插件创建一个简单的古兰经阅读应用：

import 'package:flutter/material.dart';
import 'package:flutter_quran/flutter_quran.dart';

void main() {
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(
        primaryColor: Colors.blue,
      ),
      home: const MyApp(),
    ),
  );
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  [@override](/user/override)
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  [@override](/user/override)
  void initState() {
    super.initState();
    // 初始化插件
    FlutterQuran().init();
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('古兰经阅读器'),
        actions: [
          Padding(
            padding: const EdgeInsetsDirectional.only(end: 22.0),
            child: GestureDetector(
              onTap: () => Navigator.of(context).push(
                MaterialPageRoute(builder: (ctx) => SearchScreen()),
              ),
              child: Icon(Icons.search),
            ),
          ),
        ],
      ),
      body: FlutterQuranScreen(
        onPageChanged: (int pageIndex) {
          print("Page changed: $pageIndex");
        },
      ),
    );
  }
}

class SearchScreen extends StatelessWidget {
  final TextEditingController _controller = TextEditingController();
  List<Ayah> ayahs = [];

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('搜索'),
      ),
      body: Column(
        children: [
          TextField(
            controller: _controller,
            onChanged: (txt) {
              final _ayahs = FlutterQuran().search(txt);
              setState(() {
                ayahs = [..._ayahs];
              });
            },
            decoration: InputDecoration(
              border: OutlineInputBorder(borderSide: BorderSide(color: Colors.black)),
              hintText: '搜索',
            ),
          ),
          Expanded(
            child: ListView.builder(
              itemCount: ayahs.length,
              itemBuilder: (context, index) {
                final ayah = ayahs[index];
                return ListTile(
                  title: Text(ayah.text),
                  subtitle: Text('章: ${ayah.surah.name}, 经文: ${ayah.numberInSurah}'),
                );
              },
            ),
          ),
        ],
      ),
    );
  }
}