macos_ui
Version 2.1.0
顫動的小部件和主題實現當前的MacOS設計語言。
在https://macosui.github.io/macos_ui/#/上在線查看我們的交互式小部件畫廊
可以在https://macosui.dev上找到指南，codelabs和其他文檔
macos_ui是針對Flutter的stable頻道開發的。為了確保macos_ui獲得平穩的開發體驗，您應該在Flutter的stable頻道上構建應用程序。
pub.dev顯示macos_ui僅支持MacOS。這是因為macos_ui調用了一些本機代碼，因此將MACOS指定為pubspec.yaml文件中的插件平台。
macos_ui從技術上講， MacOS_UI將在任何撲面支持的平台上工作，但是您將在MacOS上獲得最佳結果。不能保證非麥克斯平台支持。
由於調用本機代碼， macos_ui的功能將在MACOS以外的其他平台上工作。
macos_window_utils有關的任何東西MacosColors.controlAccentColor()函數MacosColorWell小部件由於此時Flutter不允許UI元素溢出窗口的邊界，因此將彈出窗口限制在可用空間上。
因此，如果您使用的是在工具欄中創建彈出鍵的小部件，例如ToolBarPopupButton ，則應避免允許將應用程序窗口調整到最高彈出窗口高度以下。
macos_ui歡迎貢獻！有關更多信息，請參見CONTRIBUTING.md 。
MacosWindow是MacOS風格佈局的基本框架。
它支撐左側的Sidebar ，頂部是一個可選的TitleBar ，其餘的窗口通常用MacosScaffold填充。
MacosWindowScope提供了MacosWindow的範圍。可以用MacosWindowScope.of(context).toggleSidebar()切換側欄。請注意，您必須將MacosScaffold包裹在Builder小部件中，以使其正常工作。
側欄啟用應用程序導航，並可以快速訪問應用程序中的頂級內容。
側邊欄可能放在應用程序的左側或右側。要在左側放置一個側邊欄，請使用MacosWindow.sidebar屬性。要將側邊欄放在右側，請使用MacosWindow.endSidebar屬性。
示例用法：
int pageIndex = 0 ;
...
MacosWindow (
sidebar : Sidebar (
minWidth : 200 ,
builder : (context, scrollController) {
return SidebarItems (
currentIndex : pageIndex,
scrollController : scrollController,
itemSize : SidebarItemSize .large,
onChanged : (i) {
setState (() => pageIndex = i);
},
items : const [
SidebarItem (
label : Text ( 'Page One' ),
),
SidebarItem (
label : Text ( 'Page Two' ),
),
],
);
},
),
endSidebar : Sidebar (
startWidth : 200 ,
minWidth : 200 ,
maxWidth : 300 ,
shownByDefault : false ,
builder : (context, _) {
return const Center (
child : Text ( 'End Sidebar' ),
);
},
),
), MacosScaffold是您可能稱為“頁面”的。
腳手架具有toolbar財產和children財產。 children接受ContentArea小部件和多個ResizablePane小部件。要捕捉導航或腳手架下方的路線，請考慮將MacosScaffold包裹在CupertinoTabView中。通過這樣做， MacosScaffold內部的導航將在MacosScaffold區域內顯示，而不是覆蓋整個窗口。要將路線推出包裹在CupertinoTabView中的MacosScaffold ，請使用root Navigator Navigator.of(context, rootNavigator: true)
有關自定義和ToolBar示例的文檔。
Big Sur（MacOS 11）引入了MacOS應用程序的新外觀。為了匹配您的Flutter應用程序中的外觀，MACOS_UI依賴Macos_window_utils，這需要最小MACOS部署目標為10.14.6。因此，請確保使用XCode打開項目的macos/Runner.xcworkspace文件夾，然後搜索Runner.xcodeproj 。轉到Info > Deployment Target ，並將macOS Deployment Target設置為10.14.6或更高。然後，打開項目的Podfile （如果沒有在Xcode中顯示，則可以通過VS代碼在項目的macos目錄中找到它），並將第一行中的最小部署版本設置為10.14.6或更高版本：
platform :osx , '10.14.6'您可能還需要在Xcode中打開應用程序的Runner.xcodeproj ，並在此處設置最小部署版本。
現在，將您的窗口配置在main()內部（）內：
/// This method initializes macos_window_utils and styles the window.
Future < void > _configureMacosWindowUtils () async {
const config = MacosWindowUtilsConfig (
toolbarStyle : NSWindowToolbarStyle .unified,
);
await config. apply ();
}
void main () async {
await _configureMacosWindowUtils ();
runApp ( const YourAppHere ());
}請注意，如果您在MacosWindow中使用標題欄（ TitleBar ），則應將窗口的toolbarStyle設置為NSWindowToolbarStyle.expanded ，以便正確地對齊，最小化，Zoom窗口窗口按鈕：
Future < void > _configureMacosWindowUtils () async {
const config = MacosWindowUtilsConfig (
toolbarStyle : NSWindowToolbarStyle .expanded,
);
await config. apply ();
}在任何其他情況下，您都應將其保留為NSWindowToolbarStyle.unified 。
在MacosScaffold中創建工具欄。該工具欄出現在MACOS應用程序的標題欄（如果存在）下方，或使用其title屬性集成。
工具欄可方便訪問常用命令和功能（工具欄項目）。應用程序的不同路線可能具有不同的工具欄。
工具欄項目包括ToolBarIconButton ， ToolBarPulldownButton和ToolBarSpacer窗口小部件，應通過items屬性提供。每個工具欄項目的操作也應作為您應用程序的菜單欄命令提供。
工具欄看起來最好，最容易理解它們包含相同類型的元素時（因此要么為每個工具欄項目使用標籤）。
您可以使用ToolBarSpacer小部件來設置不同工具欄操作的分組。
一個示例工具欄是：
ToolBar (
title : const Text ( 'Untitled Document' ),
titleWidth : 200.0 ,
leading : MacosBackButton (
onPressed : () => debugPrint ( 'click' ),
fillColor : Colors .transparent,
),
actions : [
ToolBarIconButton (
label : "Add" ,
icon : const MacosIcon (
CupertinoIcons .add_circled,
),
onPressed : () => debugPrint ( "Add..." ),
showLabel : true ,
),
const ToolBarSpacer (),
ToolBarIconButton (
label : "Delete" ,
icon : const MacosIcon (
CupertinoIcons .trash,
),
onPressed : () => debugPrint ( "Delete" ),
showLabel : false ,
),
ToolBarPullDownButton (
label : "Actions" ,
icon : CupertinoIcons .ellipsis_circle,
items : [
MacosPulldownMenuItem (
label : "New Folder" ,
title : const Text ( "New Folder" ),
onTap : () => debugPrint ( "Creating new folder..." ),
),
MacosPulldownMenuItem (
label : "Open" ,
title : const Text ( "Open" ),
onTap : () => debugPrint ( "Opening..." ),
),
],
),
]
),這構建了這個簡單的工具欄：
其他工具欄示例：
您還可以創建自己的CustomToolbarItem ，以在工具欄中包含任何類型的小部件：
// Add a grey vertical line as a custom toolbar item:
CustomToolbarItem (
inToolbarBuilder : (context) => Padding (
padding : const EdgeInsets . all ( 8.0 ),
child : Container (color : Colors .grey, width : 1 , height : 30 ),
),
inOverflowedBuilder : (context) =>
Container (color : Colors .grey, width : 30 , height : 1 ),
),SliverToolBar SliverToolbar是標準ToolBar的變體，關鍵區別在於（顧名思義），它與諸如CustomScrollView和NestedScrollView之類的可滾動小部件兼容。 SliverToolBar上還有三個其他屬性：
pinned ，這確定工具欄在滾動時是否應保持可見floating ，這確定工具欄是否應在使用開始向上滾動後是否可以看到opacity ，管理工具欄的半透明效果該小部件使開發人員能夠實現Apple App Store中看到的工具欄行為。
示例用法：
return CustomScrollView (
controller : scrollController,
slivers : [
SliverToolBar (
title : const Text ( 'SliverToolbar' ),
pinned : true ,
toolbarOpacity : 0.75 ,
),
// Other slivers below
],
);一個旨在近似flutter材料庫中的ListTile小部件的小部件。
示例用法：
MacosListTile (
leading : const Icon ( CupertinoIcons .lightbulb),
title : Text (
'A robust library of Flutter components for macOS' ,
style : MacosTheme . of (context).typography.headline,
),
subtitle : Text (
'Create native looking macOS applications using Flutter' ,
style : MacosTheme . of (context).typography.subheadline. copyWith (
color : MacosColors .systemGrayColor,
),
),
),一次顯示一個頁面的乘法接口。必須在StatefulWidget使用。
您可以使用position屬性控制選項卡的放置。
用法：
final _controller = MacosTabController (
initialIndex : 0 ,
length : 3 ,
);
...
MacosTabView (
controller : _controller,
tabs : const [
MacosTab (
label : 'Tab 1' ,
),
MacosTab (
label : 'Tab 2' ,
),
MacosTab (
label : 'Tab 3' ,
),
],
children : const [
Center (
child : Text ( 'Tab 1' ),
),
Center (
child : Text ( 'Tab 2' ),
),
Center (
child : Text ( 'Tab 3' ),
),
],
),
MacosIcon在各個方面都與常規Icon相同，但一個例外 - 它尊重MacosTheme 。以相同的方式使用它，您將是常規圖標：
MacosIcon (
CupertinoIcons .add,
// color: CupertinoColors.activeBlue.color,
// size: 20,
),複選框是一種按鈕，可讓用戶在兩個相反的狀態，操作或值之間進行選擇。當其中包含一個選中標記時，請考慮選定的複選框。除非在清單中出現，否則幾乎總是隨後是標題。了解更多
| 未選中 | 檢查 | 混合 |
|---|---|---|
這是如何創建基本複選框的示例：
bool selected = false ;
MacosCheckbox (
value : selected,
onChanged : (value) {
setState (() => selected = value);
},
)要在mixed狀態下製作複選框，請將value設置為null 。
在視圖中顯示一個幫助按鈕，並在單擊時打開特定的幫助文檔。所有幫助按鈕都是圓形的，始終尺寸的按鈕，其中包含問號圖標。了解更多
這是如何創建幫助按鈕的一個示例：
HelpButton (
onPressed : () {
print ( 'pressed help button' ),
},
)您可以使用HelpButtonTheme自定義“幫助”按鈕外觀和行為，但是Apple不建議更改幫助按鈕的外觀。
單選按鈕是一個小的圓形按鈕，然後是標題。無線電按鈕通常以兩到五個組的組為組，為用戶提供了一組相關但相互排斥的選擇。單選按鈕的狀態在（填充圓圈）或關閉（一個空圓圈）上。了解更多
這是如何創建基本廣播按鈕的示例：
bool selected = false ;
MacosRadioButton (
value : selected,
onChanged : (value) {
setState (() => selected = value);
},
),下拉按鈕（通常稱為下拉菜單）是一種彈出按鈕，當單擊時，將顯示包含選擇列表的菜單。菜單出現在按鈕下方。一旦在屏幕上顯示菜單後，它將保持打開狀態，直到用戶選擇菜單項，單擊菜單外，切換到另一個應用程序或退出應用程序。或直到系統顯示警報。了解更多
使用下拉按鈕顯示命令列表。下拉按鈕可以顯示title或icon來描述按鈕菜單的內容。如果使用圖標，請確保它清楚地傳達了按鈕的目的。
如果items為null，則將禁用該按鈕（灰色）。
必須提供title或icon ，以顯示為下拉按鈕的標題，但同時又不同時顯示。
菜單也可以使用UP/DOWN鍵和帶有返回鍵的操作導航。
它也可以通過工具欄上ToolBarPulldownButton欄出現在工具欄中。
| 黑暗主題 | 光主題 |
|---|---|
這是如何創建基本下拉按鈕的示例：
MacosPulldownButton (
title : "Actions" ,
// Or provide an icon to use as title:
// icon: CupertinoIcons.ellipsis_circle,
items : [
MacosPulldownMenuItem (
title : const Text ( 'Save' ),
onTap : () => debugPrint ( "Saving..." ),
),
MacosPulldownMenuItem (
title : const Text ( 'Save as...' ),
onTap : () => debugPrint ( "Opening Save As dialog..." ),
),
const MacosPulldownMenuDivider (),
MacosPulldownMenuItem (
enabled : false ,
title : const Text ( 'Export' ),
onTap : () => debugPrint ( "Exporting" ),
),
],
),彈出按鈕（通常稱為彈出菜單）是一種按鈕，當單擊時，它顯示一個包含相互排斥選擇列表的菜單。菜單出現在按鈕頂部。像其他類型的菜單一樣，彈出式按鈕的菜單可以包括分離器和符號等符號。顯示菜單後，它保持打開狀態，直到用戶選擇菜單項，單擊菜單外，切換到另一個應用程序或退出應用程序。或直到系統顯示警報。了解更多
MacosPopupButton的類型T是每個彈出菜單項代表的值的類型。給定菜單中的所有條目必須表示具有一致類型的值。通常，使用enum 。項目中的每個MacosPopupMenuItem必須專門使用相同類型的參數。
onChanged回調應更新定義彈出菜單值的狀態變量。它還應該調用State.setState用新值重建彈出按鈕。
當有可用菜單約束中無法顯示的菜單項時，在打開菜單的頂部或底部顯示了一個鏡頭，以表明有些項目當前不可見。
菜單也可以使用上/下鍵和帶有返回鍵的項目導航。
| 黑暗主題 | 光主題 |
|---|---|
這是如何創建基本彈出按鈕的示例：
String popupValue = 'One' ;
MacosPopupButton < String >(
value : popupValue,
onChanged : ( String ? newValue) {
setState (() {
popupValue = newValue ! ;
});
},
items : < String > [ 'One' , 'Two' , 'Three' , 'Four' ]
. map < MacosPopupMenuItem < String >>(( String value) {
return MacosPopupMenuItem < String >(
value : value,
child : Text (value),
);
}). toList (),
),按鈕是MacOS中的標準按鈕類型。按鈕包含文本（不是圖標），並且通常打開一個單獨的窗口，對話框或應用程序，以便用戶可以完成任務。了解更多
| 黑暗主題 | 光主題 |
|---|---|
請注意，本機按鈕可以用作僅文本的樣式，具有圖標或僅圖標的文本。當前，支持僅文本按鈕。要創建一個僅圖標按鈕，請使用MacosIconButton窗口小部件。
這是如何創建基本按鈕的示例：
PushButton (
child : Text ( 'button' ),
controlSize : ControlSize .regular,
onPressed : () {
print ( 'button pressed' );
},
),開關（也稱為切換）是一個控件，該控件在兩個相互排他性狀態之間提供了二進制選擇。一個開關顯示，當可見重音顏色以及開關顯示無色時，它正在打開。
可以將ContolSize Enum傳遞到size屬性以控制開關的大小。 MacosSwitch支持以下控制大小：
minismallregular| 離開 | 在 |
|---|---|
這是如何創建基本切換開關的示例：
bool switchValue = false ;
MacosSwitch (
value : switchValue,
onChanged : (value) {
setState (() => switchValue = value);
},
),在此處了解有關開關的更多信息。
在單個水平組中顯示一個或多個導航選項卡。由MacosTabView使用，用於在標籤欄的不同選項卡之間導航。
該小部件的典型用法是通過MacosTabView來控制其孩子的導航。您無需使用MacosTabView來指定MacosSegmentedControl ，因為它是由該小部件構建的。
用法：
showMacosAlertDialog (
context : context,
builder : (_) => MacosAlertDialog (
appIcon : FlutterLogo (size : 64 ),
title : Text (
'Alert Dialog with Primary Action' ,
style : MacosTheme . of (context).typography.headline,
),
message : Text (
'This is an alert dialog with a primary action and no secondary action' ,
textAlign : TextAlign .center,
style : MacosTypography . of (context).headline,
),
primaryButton : PushButton (
controlSize : ControlSize .large,
child : Text ( 'Primary' ),
onPressed : () {},
),
),
);用法：
showMacosSheet (
context : context,
builder : (_) => const MacosuiSheet (),
);文本字段是用戶進入或編輯一條或多個文本的矩形區域。文本字段可以包含普通或樣式的文本。
這是如何創建基本文本字段的示例：
MacosTextField (
placeholder : 'Type some text here' ,
)搜索字段是優化的文本字段樣式，用於在大量值集合中執行基於文本的搜索。
當用戶開始鍵入搜索字段時，可選結果的列表將顯示在下面（或更高）的字段中。
| 黑暗主題 | 光主題 |
|---|---|
這是如何創建搜索字段的示例：
MacosSearchField (
placeholder : 'Search for a country...' ,
results : countries. map ((e) => SearchResultItem (e)). toList (),
onResultSelected : (resultItem) {
debugPrint (resultItem.searchKey);
},
)檢查examples/fields_page以獲取更多示例。
標籤是屏幕上元素所做的簡短描述。
Tooltips簡潔地描述瞭如何使用控件，而無需將人們的注意力轉移到主要界面。當用戶將指針定位在控件上幾秒鐘時，幫助標籤出現。工具提示保持10秒鐘，或直到指針遠離控件。
| 黑暗主題 | 光主題 |
|---|---|
要創建工具提示，請在MacosTooltip上包裝任何小部件：
MacosTooltip (
message : 'This is a tooltip' ,
child : Text ( 'Hover or long press to show a tooltip' ),
),您可以通過自定義主題的TooltipTheme來自定義工具提示。工具提示會自動適應其環境，響應觸摸和指針事件。要使用工具欄項目使用工具提示，請為其提供tooltipMessage屬性屬性。
不要讓人們坐在靜態屏幕上，等待您的應用程序加載內容或執行冗長的數據處理操作。使用進度指標讓人們知道您的應用程序尚未停滯，並讓他們了解他們將等待多長時間。
進度指標具有兩種不同的樣式：
人們不會與進度指標互動；但是，它們通常伴隨著一個按鈕，用於取消相應的操作。了解更多
可以確定的或不確定的ProgressCircle 。
| 確定進度圈子 | 不確定的進度圓圈 |
|---|---|
這是如何創建不確定進度圈子的一個示例：
ProgressCircle (
value : null ,
),您可以為value提供非零值以確定進度圈子。
ProgressBar只能確定。
這是如何創建確定進度標準的一個示例：
ProgressBar (
value : 30 ,
)級別指示燈以圖形方式表示數字值範圍內的特定值。它類似於目的的滑塊，但更多的視覺效果，並且不包含選擇值的獨特控件，但是支持在級別指示器上單擊和拖動以選擇一個值以選擇一個值。級別指示器還可以包括刻度標記，從而使用戶輕鬆地查明該範圍內的特定值。有三種不同的指標樣式，每種樣式具有不同的外觀，用於交流能力，評級和相關性。
容量指標說明了與有限容量有關的當前水平。傳達磁盤和電池使用等因素時，通常會使用容量指標。了解更多
這是如何創建交互式連續容量指標的一個示例：
double value = 30 ;
CapacityIndicator (
value : value,
discrete : false ,
onChanged : (v) {
setState (() => value = v);
},
),您可以將discrete設置為true ，以使其成為離散的容量指示器。
滑塊是一個控制，使人們可以通過移動滑塊拇指從連續或離散的值範圍中選擇值。
| 連續的 | 離散的 |
|---|---|
| 水平滑塊，可以選擇最小值和最大值之間的任何值連續值 | 水平滑塊只能選擇最小和最大之間的離散值。通常顯示刻度標記以提供上下文。 |
這是如何創建交互式連續滑塊的一個示例：
double value = 0.5 ;
MacosSlider (
value : value,
onChanged : (v) {
setState (() => value = v);
},
),評分指標使用一系列水平佈置的圖形符號來傳達排名級別。默認符號是恆星。
評分指示燈不顯示部分符號 - 它的值是捨入的，以僅顯示完整的符號。在評分指示器中，符號總是相同的距離，並且不要擴展或收縮以適合控件。了解更多
這是如何創建交互式評級指標的示例：
double value = 3 ;
RatingIndicator (
amount : 5 ,
value : value,
onChanged : (v) {
setState (() => value = v);
}
)讓用戶選擇一個日期。
MacosDatePickers有三種樣式：
textual ：僅使用文本的日期選擇器，用戶必須選擇日期，月或年，並使用Caret-Control按鈕來更改值。當您的應用中的空間受到限制時，這很有用。graphical ：用戶可以在類似日曆的接口中導航以選擇日期的視覺日期選擇器。combined ：提供textual和graphical接口。 PICKER的本地化由weekdayAbbreviations和monthAbbreviations參數（例如標準localizations.narrowWeekdays()以符合Apple的規格）。
weekdayAbbreviations應該是7個琴弦的清單，一周中的每一天，從周日開始monthAbbreviations應該是12個字符串的列表，一年中的每個月為1月。您還可以定義dateFormat以更改文本接口中顯示日期的方式。它需要一串令牌（不敏感），並用相應的值代替它們。支持以下令牌：
D ：月中的一天（1-31）DD ：月中的一天（01-31）M ：一年中的月份（1-12）MM ：一年中的月份（01-12）YYYY ：年（0000-9999）/ ， - ， . ）默認格式為M/D/YYYY 。
示例用法：
MacosDatePicker (
onDateChanged : (date) => debugPrint ( '$ date ' ),
),讓用戶選擇時間。
MacosTimePickers有三種樣式：
textual ：僅使用文本的時間選擇器，用戶必須選擇小時或分鐘，並使用Caret-Control按鈕來更改值。當您的應用中的空間受到限制時，這很有用。graphical ：視覺時間選擇器，用戶可以在其中移動類似時鐘的接口的手來選擇時間。combined ：提供textual和graphical接口。示例用法：
MacosTimePicker (
onTimeChanged : (time) => debugPrint ( '$ time ' ),
),讓用戶可以通過本機MacOS顏色選擇器選擇顏色。
您可以選擇使用ColorPickerMode枚舉來啟動選擇器的模式。默認值是ColorPickerMode.wheel
這個小部件將在MacOS以外的平台上不起作用！
示例用法：
MacosColorWell (
onColorSelected : (color) => debugPrint ( '$ color ' ),
),
