校務通系列介面與函式共用

長期校務通相關系列的app,介面與相關功能都極為相似,將相關的介面與函式庫,製作此套件以方便維護。

展示網頁

相關專案

套件使用要求

  • Flutter v1.20 以上

共用項目

Getting Started

pubspec.yaml 中加入 package

    # 官方多國語套件
    flutter_localizations:
        sdk: flutter
    ap_common: ^0.8.0

執行加入套件

  $ flutter package get

主題色設定

支援列表

  • 淺色主題
  • 深色主題

在 MaterialApp 上一層加入主題色模式(ThemeMode)設定 否則無法正常顯示
此功能只支援flutter v1.9 以上的SDK

    ThemeMode themeMode = ThemeMode.system;

    @override
      Widget build(BuildContext context) {
        return ApTheme(
            themeMode,
            child: MaterialApp(
              theme: ApTheme.light,
              darkTheme: ApTheme.dark,
              themeMode: themeMode,
            ),
        );
    }

多國語言支援列表

使用官方的 flutter_localization 實作,預設使用英文(en)

  • 繁體中文(zh-TW)
  • 英文(en)

MaterialApp 加入多國語言支援

    ThemeMode themeMode = ThemeMode.system;

    @override
      Widget build(BuildContext context) {
        return MaterialApp(
              // 在此設定使用的語言,否則會按照系統提供語言,若為不支援語言 預設為英文
              localeResolutionCallback:
                    (Locale locale, Iterable<Locale> supportedLocales) {
                  return locale;
                },
               localizationsDelegates: [
                const ApLocalizationsDelegate(),
              ],
              supportedLocales: [
                const Locale('en'), // English
                const Locale('zh', 'TW'), // Chinese
              ],
            );
    }

本地通知支援

使用 flutter_local_notification 實作

目前只支援 AndroidiOSmacOS 系統,並有以下限制

Android

需在原生專案中的 app/scr/main/AndroidManifest.xml

加入 RECEIVE_BOOT_COMPLETEDVIBRATE 權限

<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
<uses-permission android:name="android.permission.VIBRATE" />

確保App更新保持規劃通知保持運作,需加入

<receiver android:name="com.dexterous.flutterlocalnotifications.ScheduledNotificationBootReceiver">
    <intent-filter>
        <action android:name="android.intent.action.BOOT_COMPLETED"/>
        <action android:name="android.intent.action.MY_PACKAGE_REPLACED"/>
    </intent-filter>
</receiver>
<receiver android:name="com.dexterous.flutterlocalnotifications.ScheduledNotificationReceiver" />

更多 AndroidManifest.xml 設定 可參考

並在 app/scr/main/res/drawable 加入 ic_stat_name.png,此圖是在通知顯示時在狀態列(status bar)顯示的圖案

iOS

Runner 中的 AppDelegate.m/AppDelegate.swift

加入下列程式碼在 didFinishLaunchingWithOptions 方法下

Objective-C:

if (@available(iOS 10.0, *)) {
  [UNUserNotificationCenter currentNotificationCenter].delegate = (id<UNUserNotificationCenterDelegate>) self;
}
if(![[NSUserDefaults standardUserDefaults]objectForKey:@"Notification"]){
    [[UIApplication sharedApplication] cancelAllLocalNotifications];
    [[NSUserDefaults standardUserDefaults]setBool:YES forKey:@"Notification"];
}

Swift:

if #available(iOS 10.0, *) {
  UNUserNotificationCenter.current().delegate = self as? UNUserNotificationCenterDelegate
}
if(!UserDefaults.standard.bool(forKey: "Notification")) {
    UIApplication.shared.cancelAllLocalNotifications()
    UserDefaults.standard.set(true, forKey: "Notification")
}

開啟 XcodeRunner 中的 Signing & Capabilities 加入 Push Notification 的權限

課表加入行事曆App

Android

無須設定

iOS

ios/Runner/Info.plist dict 中加入

  <key>NSCalendarsUsageDescription</key>
	<string>Feature calendar would be add schedule to calendar app</string>

工具類

共用函式

showToast

顯示 Android 風格的 toast 提示字,使用 Package toast 實作

參數名稱型態描述
contextBuildContextFlutter Widget context
messageStringHeader點擊事件
gravityint顯示位置,預設為 Toast.Bottom

pushCupertinoStyle

Cupertino 風格開啟頁面

參數名稱型態描述
contextBuildContextFlutter Widget context
pageWidget開啟頁面

handleDioError

處理 Dio 套件中的錯誤,並以 showToast 顯示相關提示字

參數名稱型態描述
contextBuildContextFlutter Widget context
dioErrorDioErrorDio 錯誤類別
gravityinttoast 顯示位置

launchUrl

開啟 URL,以 url_launcher 實作

參數名稱型態描述
urlStringURL

callPhone

播打電話,會將#xxx(yyy)格式更改成tel:xxx,yyy,以 url_launcher 實作

參數名稱型態描述
urlStringURL

shareTo

呼叫原生分享功能,分享格式 ${分享內容}\n\nSend from ${App名稱} ${作業系統名稱},以 share 實作

參數名稱型態描述
contentString分享內容

launchFbFansPage

開啟 Facebook 粉絲專頁,會先以 app link 方式開啟,失敗才會以瀏覽器開啟,以 url_launcher 實作

參數名稱型態描述
contextBuildContextFlutter Widget context
fansPageIdString粉絲專頁 id

showAppReviewDialog

詢問是否評分,同意並呼叫 openAppReview 開啟原生評分功能

參數名稱型態描述
contextBuildContextFlutter Widget context
defaultUrlString無原生API則開啟網址

openAppReview

開啟原生評分功能,若無原生API則開啟 defaultUrl,以 in_app_review 呼叫原生評分功能,以 url_launcher 開啟連結

參數名稱型態描述
defaultUrlString無原生API則開啟網址

Notification 工具

//TODO 文件

Dialog 工具

showDefault

開啟簡易的一般對話框

參數名稱型態描述
contextBuildContextFlutter Widget context
titleString標題
contentString內容

showAnnouncementRule

開啟最新消息規則

參數名稱型態描述
contextBuildContextFlutter Widget context
onRightButtonClickFunction點擊 聯絡粉專 事件

showNewVersionContent

開啟新版本資訊,利用 versionInfo 中的 code 計算目前版本號,Android 為 Version Code,iOS 和 macOS 為 Builder Number,若超過版本號,則判斷 versionInfo 中的 isForceUpdate 是否強制更新開啟新版本資訊

參數名稱型態描述
contextBuildContextFlutter Widget context
versionInfoVersionInfo版本資訊
appNameStringApp 名稱
iOSAppIdStringiOS App Id
defaultUrlString若無法開啟商店平台(Play Store 或 Apple Store),則開啟此網址

VersionInfo

參數名稱型態描述
codeint版本號,Android 為 Version Code,iOS 和 macOS 為 Builder Number
isForceUpdateVersionInfo是否強制更新
contentString更新內容

SharePreferences 工具

封裝 Flutter 官方維護的 shared_preferences

widgets

此項目必須加入主題色設定,否則會無法正常使用

抽屜 ApDrawer

提供校務通v3風格抽屜,Flutter 原生的 Drawer 封裝
另提供

  • DrawerItem
  • DrawerSubItem
drawing
參數名稱型態描述
userInfoUserInfo使用者資訊,會在Header顯示 照片名字學號
onTapHeaderFunctionHeader點擊事件
imageAssetFunctionHeader 右邊的圖片,使用 Asset Image 載入
widgetsList抽屜主體的Widget List,屬於Flutter原生API
imageHeroTagStringHeader中的圖片支援Flutter Hero,可自訂 Tag 對應畫面的tag,預設為 tag_student_picture
displayPicturebool是否顯示照片,true時顯示 ApIcon 中的 person

網路圖片 ApNetworkImage

由 Plugin CachedNetworkImage 封裝,此套件因為在未支援平台會錯誤,故此封裝

參數名稱型態描述
urlString圖片來源網址

一般對話框 DefaultDialog

提供校務通v3風格對話框,使用 Flutter 官方的 AlertDialog 封裝

drawing
參數名稱型態描述
titleString對話框標題
contentWidgetWidget對話框內容的 Widget
actionTextString按鍵的文字
actionFunctionFunction按鍵點擊事件

選項對話框中選項 DialogOption

對話框 SimpleOptionDialog 使用的選項,也可 自訂Dialog 使用它

參數名稱型態描述
textString內容文字
checkbool是否顯示打勾的圖示
onPressedFunction點擊事件

頁面提示 HintContent

提供校務通v3風格的提示內容

drawing
參數名稱型態描述
iconIconData圖示
contentString內容文字

選項選擇器 ItemPiccker

SimpleOptionDialog 功能整合至一個元件,點擊時會顯示 SimpleOptionDialog

drawing
參數名稱型態描述
itemsList選項列表,純文字顯示
dialogTitleStringSimpleOptionDialog 的標題
currentIndexint目前的選項的索引值
onSelectedFunction(int index)SimpleOptionDialog 點擊事件,回傳索引值

選項對話框 SimpleOptionDialog

提供選項對話框,項目以 DialogOption 顯示,透過 index 顯示目前選取的項目

drawing
參數名稱型態描述
titleString標題
itemsList選項列表,純文字顯示
indexint目前的選項的索引值
onSelectedFunction(int index)點擊事件,回傳索引值

進度對話框 ProgressDialog

參數名稱型態描述
contentString內容文字

設定頁元件 SettingPageWidget

提供校務通設定頁通常會使用到的元件

drawing

SettingTitle

設定頁小標題

參數名稱型態描述
textString內容文字

SettingSwitch

設定頁的 Switch 元件,使用 Flutter 中的 SwitchListTile 封裝

設定頁小標題

參數名稱型態描述
textString內容文字
subTextString內容文字說明
valuebool是否開啟
onChangedString點擊事件

SettingItem

設定頁的項目元件,使用 Flutter 中的 ListTile 封裝

設定頁小標題

參數名稱型態描述
textString內容文字
subTextString內容文字說明
onTapString點擊事件

CheckCourseNotifyItem

目前上課提醒的封裝元件,顯示目前上課提醒的項目,使用 SettingItem 封裝

設定頁小標題

參數名稱型態描述

是或否對話框 YesNoDialog

提供校務通v3風格對話框,使用 Flutter 官方的 AlertDialog 封裝

drawing
參數名稱型態描述
titleString對話框標題
contentWidgetWidget對話框內容的 Widget
contentWidgetPaddingWidget對話框內容的 Widget 的內縮間距
leftActionTextString左邊按鍵的文字
rightActionTextString右邊按鍵的文字
leftActionFunctionFunction左邊按鍵點擊事件
rightActionFunctionFunction右邊按鍵點擊事件

Pages

此項目必須加入多國語言設定,否則會無法正常使用

關於我們 AboutUsPage

提供校務通系列的歷任作者及社群介紹,可在此頁面放置自己專案的License,期望您使用這份套件時可以加入此頁面,以及PR這個頁面加入您的資訊,我會同步到所有校務通專案中

drawing drawing drawing
參數名稱型態描述
assetImageString頂端 Header 的圖片,採Asset Image 載入
fbFanPageUrlStringFacebook 粉絲專頁網址
fbFanPageIdStringFacebook 粉絲專頁id,點擊facebook logo時優先以 app link 的方法開啟
githubUrlStringGitHub 網址
githubNameStringGitHub 的 username 或 Oraganization GitHub logo時優先以 app link 的方法開啟
emailString聯絡 email
appLicenseStringApp的License
actionsList右上角的元件列表,為Flutter Scaffold原生的API
logEventFunction(String name, String value)可搜集使用者行為的事件
setCurrentScreenFunction可搜集目前畫面的事件

開放原始碼 OpenSourcePage

列出校務通系統有使用到的開放原始碼的License

最新消息詳細資訊 AnnouncementContentPage

最新消息詳細資訊,採用頁面顯示

手機介面

drawing

平板 or 桌面版介面

drawing
參數名稱型態描述
announcementAnnouncement最新消息
logEventFunction(String name, String value)可搜集使用者行為的事件
setCurrentScreenFunction可搜集目前畫面的事件

Scaffold

首頁骨架 ScoreScaffold

提供校務通首頁(Home Page)骨架

  • 支援響應式介面
    • shortestSide >= 680 會開啟平板模式
    • 平板模式開啟時 BottomNavigationBar 會隱藏
    • 平板模式開啟時 Scaffold 中的 最新消息BottomNavigationBar 會被 content 設定的 Widget 取代,目的是可實作不跳頁顯示內容,詳細可參考 example
  • 正中間由 announcements 顯示輪播資訊
  • 可註冊 HomePageScaffoldState 存取 Snacker Bar 的行為,詳細可參考 example

手機介面

drawing

平板 or 桌面版介面

drawing
參數名稱型態描述
stateCourseState必要欄位,總共有 loading finish error empty offlineEmpty custom 的狀態,只有finish才會顯示課表介面,其餘都是顯示錯誤狀況
titleStringScaffold 標題
announcementsList最新消息列表
isLoginbool控制下方的Snacker Bar是否顯示要登入
actionsList在右上角可顯示元件列表,為Flutter Scaffold原生的API
onTabTappedFunction(int index)底下BottomNavigationBar點擊時的事件,回傳點擊的索引值
bottomNavigationBarItemsList底下BottomNavigationBar的元素,為Flutter Scaffold原生的API
drawerWidget左方的抽屜(Drawer)元件,為Flutter Scaffold原生的API
contentWidget使用平板介面時,右方會顯示Content的內容,null時則顯示首頁
actionsList右上角的元件列表,為Flutter Scaffold原生的API
floatingActionButtonWidgetMaterial Design 的 FloatingActionButton 位置放的元件,為Flutter Scaffold原生的API
onImageTappedFunction(Announcement announcement)點擊最新消息的圖片事件,回傳Announcement
autoPlayFunction是否自動輪播最新消息,預設值為 true
autoPlayDurationbool最新消息自動輪播的時間間距,預設值為 5秒

AnnouncementData

參數名稱型態描述
dataList最新消息列表

Announcement

參數名稱型態描述
titleString標題
idDate最新消息id
nextIdLocation下一個最新消息id
lastIdint最後一個最新消息的id
weightint權重 HomeScaffold 會從權重大的排序顯示
imgUrlint圖片網址
urlint連結
descriptionint描述 會在 AnnouncementContentPage 顯示
publishTimeint發布時間,格式 YYYY-MM-DDTHH:mm::ss
expireTimeint過期時間 HomeScaffold 會讓超過此時間的最新消息不顯示,格式 YYYY-MM-DDTHH:mm::ss

課表骨架 CourseScaffold

提供顯示課表(Course Table)骨架,另將課表CourseContent與課程列表CourseList另拆成兩個Widget

  • 支援響應式介面
    • longestSide >= 880 顯示平板模式
  • 支援上課通知 (Android & iOS & MacOS)
  • 將課表加入至行事曆App (Android & iOS)
  • 提供學期列表的區域,預設只提供學期資料SemesterData,即可使用相關的 Callback
  • CourseContent中的顏色由CourseData中的updateIndex() 找出該課堂在 CourseList 的索引值決定,順序為Material Design的500系列顏色

手機介面

drawing

平板 or 桌面版介面

drawing
參數名稱型態描述
stateCourseState必要欄位,總共有 loading finish error empty offlineEmpty custom 的狀態,只有finish才會顯示課表介面,其餘都是顯示錯誤狀況
customStateHintStringstatecustom 時,會顯示此字串
titleStringScaffold 標題
courseDataSourseData課表資料,會利用其中的 課表CourseContent與課程列表CourseList顯示
itemPickerWidget使用自訂元件實作學期選擇器,itemPickersemesterData 擇一使用
semesterDataList學期列表
onSelectFunction(int index)學期列表點擊事件,回傳semesterData的索引值,semesterData 不為 Null 時才有效
isShowSearchButtonString是否顯示搜尋按鍵,預設值為 true
onSearchButtonClickFunction搜尋按鍵點擊事件
onRefreshFunction下拉更新事件
actionsList右上角的元件
customHintString學期選擇器與課表中間的提示字
enableNotifyControlbool是否顯示上課通知按鍵,預設值為 true
notifyDataFunction上課通知資料
autoNotifySavebool是否自動儲存上課更新資料,預設值為 true
onNotifyClickFunction上課通知按鍵點擊事件
courseNotifySaveKeyStringautoNotifySave有開啟,儲存的Preference key
enableAddToCalendarbool是否顯示課表加入行事曆按鍵,預設值為 true
androidResourceIconStringAndroid的原生資源圖示

CourseData

參數名稱型態描述
coursesList課表詳細資訊列表,課程列表 CourseList 會使用到此部分
courseTablesCourseTable課表內容 CourseContent 會使用到此部分

CourseDetail

此類別會影響課程列表中的介面

drawing
參數名稱型態描述
codeString課程代碼
titleString課程名稱
classNameString課程班級
groupString課程分組
unitsString學分數
hoursString上課時數(單位:小時)
requiredString課程類型,選修、必修等等,右上角藍字
timesString上課節次
locationLocation上課位置
instructorsList授課老師

Coursetables

參數名稱型態描述
mondayList星期一的課程
tuesdayList星期二的課程
wednesdayList星期三的課程
thursdayList星期四的課程
fridayList星期五的課程
saturdayList星期六的課程
sundayList星期日的課程
timeCodesList所有節次

Course

drawing
參數名稱型態描述
titleString課程名稱
dateDate上課時間
locationLocation上課位置
detailIndexint對應CourseDetail的索引值
instructorsList授課老師

Date

參數名稱型態描述
startTimeString開始時間,格式 HH:mm
endTimeString結束時間,格式 HH:mm
sectionString節次,對應 CourseTable 中的 timeCodes

成績骨架 ScoreScaffold

提供顯示成績(Score)骨架,顯示 ScoreData 中的成績列表List<Score>資訊

  • 支援響應式介面
    • longestSide >= 880 顯示平板模式
    • 平板模式時,列表於詳細資訊會水平顯示
  • 提供學期列表的區域,預設只提供學期資料SemesterData,即可使用相關的 Callback

手機介面

drawing

平板 or 桌面版介面

drawing
參數名稱型態描述
stateScoreState必要欄位,總共有 loading finish error empty offlineEmpty custom 的狀態,只有finish才會顯示課表介面,其餘都是顯示錯誤狀況
customStateHintStringstatecustom 時,會顯示此字串
titleStringScaffold 標題
scoreDataScoreData成績資料,會利用其中的 List<Score> 顯示成績
itemPickerWidget使用自訂元件實作學期選擇器,itemPickersemesterData 擇一使用
semesterDataSemesterData學期列表
onSelectFunction(int index)學期列表點擊事件,回傳semesterData的索引值,semesterData 不為 Null 時才有效
isShowSearchButtonString是否顯示搜尋按鍵,預設值為 true
onSearchButtonClickFunction搜尋按鍵點擊事件
onRefreshFunction下拉更新事件
actionsList右上角的元件
customHintString學期選擇器與課表中間的提示字
middleTitleString成績列表第一列的標題,預設為 ApLocalizationsmidtermScore
finalTitleString成績列表第二列的標題,預設為 ApLocalizationsfinalScore
middleScoreBuilderWidget Function(int index)成績列表第一列Builder,Null時預設顯示為 Score 參數中的 midtermScore
finalScoreBuilderWidget Function(int index)成績列表第二列Builder,Null時預設顯示為 Score 參數中的 finalScore
detailsList第二區塊,列表顯示其中的資訊

登入骨架 LoginScaffold

提供校務通v3版本登入頁面骨架

  • 支援響應式介面
    • 利用手機水平與垂直顯示區隔,水平模式視為平板模式
    • 平板模式時,Logo 與 forms 會水平顯示
  • forms 會包裝在 Flutter v1.20 支援的 AutofillGroup 使區塊內的TextFeild 支援自動填入(Autofill)
  • 提供校務通風格的元件
    • ApButton : RaisedButton封裝
    • ApFlatButton : FlatButton封裝
    • ApTextFeild : TextFeild封裝
    • ApCheckBox : CheckBox封裝

手機介面

drawing

平板 or 桌面版介面 or 手機水平模式

drawing
參數名稱型態描述
logoSourceString必要欄位,Logo的來源,由 loginMode 決定Logo顯示方式
formList必要欄位,骨架正中間的表單資訊,採自由實作
logoModeLogoModeLogoMode,logoMode 為 text時顯示 logoSource 的資訊,logoMode 為 image 時載入 logoSource 路徑的 asset image
enableKeyboardDoneButtonbool是否顯示鍵盤完成按鍵,會顯示在虛擬鍵盤正上方

圖片瀏覽器骨架 ImageViewerScaffold

以 Package photo_view 封裝的圖片瀏覽器,可設定複數的圖片,透過TabBarView瀏覽,若 imageViewers 的數量為1時則不顯示Tab

參數名稱型態描述
titleStringScaffold 標題
imageViewersList圖片瀏覽器物件,載入assetName的圖片
actionsList右上角的元件列表,為Flutter Scaffold原生的API

PDF骨架 PdfScaffold

以 Plugin native_pdf_view 封裝的PDF瀏覽器,只支援Android iOS Web macOS 平台

手機介面,不包含 AppBarBottomNavigationBar 的區塊

drawing
參數名稱型態描述
byteListUint8ListPDF 的 Raw Data

使用者資訊骨架 UserInfoScaffold

提供使用者資訊骨架

  • 可點擊右上角的icon,切換顯示Qr Code 或 Bar Code
  • Qr Code 或 Bar Code 顯示時內容是學號
  • 部分欄位為 Null 時則不顯示

手機介面

drawing drawing
參數名稱型態描述
userInfoUserInfo使用者資訊物件
heroTagString照片的 Hero Tag,預設為 tag_student_picture
actionsList右上角的元件列表,為Flutter Scaffold原生的API
onRefreshFuture Function()下拉更新事件,需回傳更新後的使用者資訊
enableBarCodebool是否顯示Bar Code

UserInfo

參數名稱型態描述
educationSystemString學制
departmentString科系
classNameString班級名稱
idString學號
nameString名字
pictureUrlString照片網址,但 UserInfoScaffold 不使用此載入圖片
emailString電子信箱
pictureBytesUint8List照片Raw Data,UserInfoScaffold 使用此載入圖片

校園最新消息骨架 NotificationScaffold

提供校園最新消息列表的骨架

  • 點擊時會開啟 Notification 中的 link 設定的連結
  • 長按時會啟動原生的分享功能,使用 share 實作
  • 此骨架沒有使用Scaffold包裝

手機介面,不包含 AppBarBottomNavigationBar 的區塊

drawing
參數名稱型態描述
stateNotificationState必要欄位,總共有 loading finish error empty offlineEmpty 的狀態,只有finish才會顯示,其餘都是顯示錯誤狀況
notificationListList校園最新消息列表
onRefreshFunction下拉更新事件
onLoadingMoreFunction滾動最底事件
logEventFunction(String name, String value)可搜集使用者行為的事件
setCurrentScreenFunction可搜集目前畫面的事件

Notifications

參數名稱型態描述
linkString連結
infoInfo校園最新消息資訊

Info

參數名稱型態描述
idStringid
titleString標題
deparmentString發布處室
dateString日期 格式 YYYY-MM-DD

學校電話骨架 PhoneScaffold

提供電話列表的骨架

  • 點擊會撥打PhoneModel 中的 number
  • 此骨架沒有使用Scaffold包裝
  • PhoneModel 中的 numberNull 時則作為標題區隔

手機介面,不包含 AppBarBottomNavigationBar 的區塊

drawing
參數名稱型態描述
stateNotificationState必要欄位,總共有 loading finish error 的狀態,只有finish才會顯示,其餘都是顯示錯誤狀況
notificationListList電話列表
logEventFunction(String name, String value)可搜集使用者行為的事件
setCurrentScreenFunction可搜集目前畫面的事件

PhoneModel

參數名稱型態描述
nameString名稱
numberString電話號碼

Libraries

about_us_page
analytics_utils
announcement_content_page
announcement_data
ap_assets
ap_colors
ap_common
ap_constants
ap_drawer
ap_icon
ap_localizations
ap_network_image
ap_support_language
ap_theme
ap_utils
course_data
course_notify_data
course_scaffold
default_dialog
dialog_option
dialog_utils
general_callback
general_response
github_helper
hint_content
home_page_scaffold
image_viewer_scaffold
item_picker
login_scaffold
notification_data
notification_scaffold
notification_utils
open_source_page
option_dialog
pdf_scaffold
phone_model
phone_scaffold
preferences
progress_dialog
score_data
score_scaffold
semester_data
setting_page_widgets
time_code
user_info
user_info_scaffold
version_info
yes_no_dialog