Flutter古兰经API集成插件lamsz_quran_api的使用

关于Lamsz Quran API

Lamsz Quran API 是一个混合离线和云端的古兰经API，提供了创建Flutter古兰经应用程序的基本功能。为了保持包尽可能小，它采用了混合模式。

功能

Lamsz Quran API 提供了以下功能：

• 获取章节列表，包括名称、拉丁名称、节数、章节类型（麦加/麦地那）、来自mp3quran.net的音频URL。
• 根据名称关键字过滤章节列表。
• 获取单章内容。
• 获取单节内容。
• 获取节的翻译（英语/印尼语/马来语）。
• 获取节的音译（英语/印尼语）。
• 获取基于翻译语言的节注释。

安装

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

dependencies:
  lamsz_quran_api:

在需要使用的文件中导入包：

import 'package:lamsz_quran_api/lamsz_quran_api.dart';

使用方法

获取章节列表

返回包含所有章节及其详细信息的古兰经数据。 示例：

getSurahList();

返回结果示例：

{
    "surah": [
        {
            "id": 1,
            "name_arabic": "الفاتحة",
            "name_latin": "Al Fatihah",
            "asma": "الفاتحة",
            "ayah": 7,
            "type": "Makkiyah",
            "transliteration": "Al Fatihah",
            "audio": "https://server8.mp3quran.net/afs/001.mp3"
        },
        // ...
    ]
}

搜索章节

可以通过章节名称关键字来过滤章节列表。 示例：

searchSurah('Fatihah');

返回结果与获取章节列表相同。

获取单章数据

返回章节名称、章节内容、翻译及音译等信息。 示例：

getSurahData(
  surahNumber: 1,
  translationLang: 'bahasa',
  transliterationLang: 'bahasa',
  tafseer: 'jalalayn'
);

返回结果示例：

{
    "id": 1,
    "name": "الفاتحة",
    "remark": "...",
    "translationLang": "bahasa",
    "transliterationLang": "bahasa",
    "tafseer": "jalalayn",
    "aya": [
        {
            "id": 1,
            "arabic_index": "\u0661",
            "arabic": "بِسْمِ ٱللَّهِ ٱلرَّحْمَـٰنِ ٱلرَّحِيمِ",
            "translation": "Dengan menyebut nama Allah Yang Maha Pengasih lagi Maha Penyayang.",
            "transliteration": "...",
            "tafseer": ""
        },
        // ...
    ]
}

获取单节数据

返回节编号、阿拉伯文文本、翻译、音译等信息。 示例：

getAya(
  surahNumber: 1,
  aya: 1,
  translationLang: 'english',
  transliterationLang: 'english',
  tafseer: 'shaheehinter'
);

返回结果示例：

{
    "id": 1,
    "arabic_index": "\u0661",
    "arabic": "بِسْمِ ٱللَّهِ ٱلرَّحْمَـٰنِ ٱلرَّحِيمِ",
    "translation": "In the name of Allah, the Most Gracious, the Most Merciful.",
    "transliteration": "...",
    "tafseer": "..."
}

示例应用

下面是一个简单的示例应用，展示如何使用Lamsz Quran API：

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

void main() {
  runApp(const MyApp());
}

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

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      title: 'Lamsz Quran Demo',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: const MyHomePage(title: 'Quran App'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({Key? key, required this.title}) : super(key: key);

  final String title;

  [@override](/user/override)
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  var surahData = SurahContentModel();
  var surahListData = <SurahHeaderModel>[];
  var aya11 = Aya();
  var defaultLang = 'bahasa';
  var defaultSurah = 1;
  var defaultAyah = 1;
  var withTransliteration = true;
  var withTafseer = true;
  var withTranslation = true;
  var tafseer = {'bahasa': 'jalalayn', 'english': 'shaheehinter'};

  loadSurah(String translationLang) async {
    var surah = await getSurahData(
        surahNumber: defaultSurah,
        translationLang: withTranslation ? translationLang : null,
        transliterationLang: withTransliteration ? translationLang : null,
        tafseer: withTafseer ? tafseer[defaultLang] : null);
    var surahList = await getSurahList();
    var aya = await getAyaData(
        surahNumber: defaultSurah,
        ayaNumber: defaultAyah,
        translationLang: withTranslation ? translationLang : null,
        transliterationLang: withTransliteration ? translationLang : null,
        tafseer: withTafseer ? tafseer[defaultLang] : null);
    setState(() {
      surahData = surah;
      surahListData = surahList;
      aya11 = aya;
    });
  }

  [@override](/user/override)
  void initState() {
    loadSurah(defaultLang);
    super.initState();
  }

  // ... (其他方法如changeLang, changeSurah等)

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text(widget.title)),
      body: Column(
        children: [
          Expanded(
            flex: 1,
            child: SingleChildScrollView(
              scrollDirection: Axis.horizontal,
              child: Row(
                children: [
                  TextButton(onPressed: changeLang, child: const Text('Change Language')),
                  TextButton(onPressed: changeSurah, child: const Text('Change Surah')),
                  TextButton(onPressed: changeAya, child: const Text('Change Aya')),
                  TextButton(
                      onPressed: toggleTranslation,
                      child: Text('Translation ${withTranslation ? "ON" : "OFF"}')),
                  TextButton(
                      onPressed: toggleTransliteration,
                      child: Text('Transliteration ${withTransliteration ? "ON" : "OFF"}')),
                  TextButton(
                      onPressed: toggleTafseer,
                      child: Text('Tafseer ${withTafseer ? "ON" : "OFF"}')),
                ],
              ),
            ),
          ),
          Expanded(
            flex: 3,
            child: Column(
              children: [
                const Text('getSurahList()'),
                Expanded(
                  child: SizedBox(
                    height: 200,
                    child: ListView.builder(
                        controller: ScrollController(),
                        itemCount: surahListData.length,
                        itemBuilder: (context, i) {
                          return Padding(
                            padding: const EdgeInsets.only(top: 8.0, bottom: 8.0, left: 3.0, right: 3.0),
                            child: ListTile(
                              leading: Text(surahListData[i].arabicIndex),
                              title: Text(surahListData[i].toString(), textAlign: TextAlign.start),
                            ),
                          );
                        }),
                  ),
                ),
              ],
            ),
          ),
          Expanded(
            flex: 3,
            child: Column(
              children: [
                Text("getSurahData(surahNumber: $defaultSurah, translationLang: $defaultLang)"),
                Text('Surah : ${surahData.name ?? ''}'),
                Expanded(
                  child: SizedBox(
                    height: 200,
                    child: ListView.builder(
                        controller: ScrollController(),
                        itemCount: (surahData.aya ?? []).length,
                        itemBuilder: (context, i) {
                          return Padding(
                            padding: const EdgeInsets.only(top: 8.0, bottom: 8.0, left: 3.0, right: 3.0),
                            child: ListTile(
                              leading: Text(surahData.aya![i].arabicIndex),
                              title: Text(
                                '${surahData.aya![i].toString()}\n surahNameTranslation: ${surahData.nameTranslation ?? ""}',
                                textAlign: TextAlign.start,
                              ),
                            ),
                          );
                        }),
                  ),
                ),
              ],
            ),
          ),
          Expanded(
            flex: 2,
            child: SingleChildScrollView(
              child: Column(
                children: [
                  Text("""getAyaData(surahNumber: $defaultSurah, ayaNumber: $defaultAyah,
                      translationLang: $defaultLang );"""),
                  Text(aya11.toString()),
                ],
              ),
            ),
          ),
        ],
      ),
    );
  }
}