設定頁元件 SettingPageWidget

使用時必須先完成

• 主題色設定
• 多國語言設定

提供校務通設定頁通常會使用到的元件，v3 全面改用 Material Design 3 的 colorScheme 取得主題色彩。

SettingTitle

設定頁小標題，支援選用的前置圖示。

參數名稱	型態	描述
text	String	內容文字
icon	IconData?	前置圖示，null 時不顯示

SettingCard

卡片式設定容器，子項之間自動加入分隔線。提供圓角邊框與主題色描邊的外觀。

參數名稱	型態	描述
children	List<Widget>	卡片內的子元件列表

SettingSwitch

設定頁的 Switch 元件，自訂實作的開關元件，左側可選擇性顯示圖示。

參數名稱	型態	描述
text	String	內容文字
subText	String	內容文字說明
value	bool	是否開啟
onChanged	void Function(bool)	狀態變更事件
icon	IconData?	前置圖示，null 時不顯示

SettingItem

設定頁的項目元件，自訂實作的列表項目，右側帶有 chevron 圖示。

參數名稱	型態	描述
text	String	內容文字
subText	String	內容文字說明
onTap	Function()	點擊事件

CheckCourseNotifyItem

使用時必須先完成

• NotificationUtils 設定
• Preference 設定

目前上課提醒的封裝元件，顯示目前上課提醒的項目，是 SettingItem 封裝的元件

參數名稱	型態	描述

ClearAllNotifyItem

使用時必須先完成

• NotificationUtils 設定
• Preference 設定

點擊取消所有上課提醒的項目的封裝元件，是 SettingItem 封裝的元件

參數名稱	型態	描述
tag	String	自訂 tag 並使用 CourseNotifyData.load(tag) 載入對應資料

ChangeLanguageItem

使用時必須先完成

• Preference 設定

選擇目前的語言，並透過 Preferences 儲存到 ApConstants.prefLanguageCode，對應編號可參考 ApSupportLanguageConstants，依序為 系統語言、英文、繁體中文

並會使用 AnalyticsUtils 分析紀錄

• 當點擊時，紀錄事件 language_setting_click
• 修改成功，紀錄事件 change_language 並儲存語言代號 code
• 設定使用者屬性 language

參數名稱	型態	描述
onChange	Function(Locale)	當修改成功時會回傳 Locale
textList	List<String>	語言列表預設使用 ApLocalizations 定義的

ChangeThemeModeItem

使用時必須先完成

• Preference 設定

選擇目前的主題，使用 ThemeMode 所定義的索引順序，並透過 Preferences 儲存到 ApConstants.prefThemeModeIndex，依序為 系統主題、淺色、深色

並會使用 AnalyticsUtils 分析紀錄

• 當點擊時，紀錄事件 theme_mode_setting_click
• 修改成功，紀錄事件 change_theme 並儲存主題代號 code
• 設定使用者屬性 theme

參數名稱	型態	描述
onChange	Function(ThemeMode)	當修改成功時會回傳 ThemeMode
textList	List<String>	主題列表預設使用 ApLocalizations 定義的

ChangeThemeColorItem

使用時必須先完成

• Preference 設定

選擇目前的主題色彩，此元件會開啟 ColorPickerDialog，讓使用者可以選擇預設好的色彩或是使用調色盤自由選擇 HSVColor，並透過 Preferences 儲存到 ApConstants.prefThemeColorIndex (針對預設色彩索引) 與 ApConstants.prefCustomThemeColor (針對自訂色彩)。

支援設定：

• 預設色彩：透過 PresetColorGrid 元件從 ApTheme.themeColors 中讀取並作為快速選擇面板。
• 自訂色彩：透過 ColorSlider 元件提供 Hue, Saturation, Value 滑桿調色，支援即時預覽十六進位色碼。

參數名稱	型態	描述
onChange	Function(Color)	當修改成功時會回傳選取的 Color

ColorSlider

從 ColorPickerDialog 中提取出的獨立元件，提供帶漸層背景的 HSV 滑桿。

參數名稱	型態	描述
label	String	滑桿標籤文字
gradientColors	List<Color>	漸層背景色列表
value	double	目前數值
onChanged	ValueChanged<double>	數值變更回呼
min	double	最小值，預設為 0
max	double	最大值，預設為 1

PresetColorGrid

從 ColorPickerDialog 中提取出的獨立元件，顯示 ApTheme.themeColors 定義的預設色彩格子供快速選擇。

參數名稱	型態	描述
onColorSelected	ValueChanged<Color>	當使用者選取顏色時的回呼

ChangeIconStyleItem

使用時必須先完成

• Preference 設定

選擇 ApIcon 的風格，使用 ApIcon 所定義的順序，並透過 Preferences 儲存到 ApConstants.prefIconStyleCode，依序為 filled、outlined

此元件修改成功時會自動設定 ApIcon

並會使用 AnalyticsUtils 分析紀錄

• 當點擊時，紀錄事件 icon_style_setting_click
• 修改成功，紀錄事件 change_icon_style 並儲存圖案風格代號 code

參數名稱	型態	描述
onChange	Function(String)	當修改成功時會回傳圖案代號
textList	List<String>	主題列表預設使用 ApLocalizations 定義的