Flutter macOS UI风格插件macos_ui的使用

macos_ui 是一个Flutter插件，它提供了一系列符合macOS设计语言的组件和主题。本文将详细介绍如何使用macos_ui创建具有macOS风格的应用程序，并提供一个完整的示例代码。

插件简介

• 交互式小部件画廊：https://macosui.github.io/macos_ui/#/
• 文档和教程：https://macosui.dev

使用注意事项

Flutter版本

macos_ui基于Flutter的stable通道开发，建议您在stable通道上构建应用程序以确保最佳的开发体验。

平台兼容性

虽然macos_ui可以在任何Flutter支持的平台上运行，但其效果最佳是在macOS上。某些特性（如窗口工具栏样式、颜色选择器等）依赖于macOS的原生代码，因此在其他平台上可能无法正常工作。

弹出框和窗口调整大小

由于当前Flutter不允许UI元素超出窗口边界，弹出框会受到可用空间的限制。因此，在工具栏中使用如ToolBarPopupButton等创建弹出框的小部件时，应避免将应用窗口调整到小于最大弹出框高度。

示例代码

以下是一个完整的示例，展示了如何使用macos_ui构建一个具有侧边栏、搜索框和多个页面切换功能的应用程序：

import 'dart:io';

import 'package:flutter/material.dart';
import 'package:flutter/foundation.dart';
import 'package:macos_ui/macos_ui.dart';

/// 初始化并设置macOS窗口样式
Future<void> _configureMacosWindowUtils() async {
  const config = MacosWindowUtilsConfig(
    toolbarStyle: NSWindowToolbarStyle.unified,
  );
  await config.apply();
}

void main() async {
  if (!kIsWeb && Platform.isMacOS) {
    await _configureMacosWindowUtils();
  }

  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return MacosApp(
      title: 'macOS UI Example',
      themeMode: ThemeMode.system,
      home: const HomePage(),
    );
  }
}

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

  @override
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  int pageIndex = 0;
  final searchFieldController = TextEditingController();

  @override
  Widget build(BuildContext context) {
    return PlatformMenuBar(
      menus: menuBarItems(),
      child: MacosWindow(
        sidebar: Sidebar(
          top: MacosSearchField(
            placeholder: 'Search',
            controller: searchFieldController,
            onResultSelected: (result) {
              setState(() {
                pageIndex = ['Buttons', 'Indicators', 'Fields', 'Colors'].indexOf(result.searchKey);
                searchFieldController.clear();
              });
            },
            results: const [
              SearchResultItem('Buttons'),
              SearchResultItem('Indicators'),
              SearchResultItem('Fields'),
              SearchResultItem('Colors'),
            ],
          ),
          minWidth: 200,
          builder: (context, scrollController) {
            return SidebarItems(
              currentIndex: pageIndex,
              onChanged: (i) {
                setState(() => pageIndex = i);
              },
              scrollController: scrollController,
              itemSize: SidebarItemSize.large,
              items: const [
                SidebarItem(
                  label: Text('Buttons'),
                ),
                SidebarItem(
                  label: Text('Indicators'),
                ),
                SidebarItem(
                  label: Text('Fields'),
                ),
                SidebarItem(
                  label: Text('Colors'),
                ),
              ],
            );
          },
        ),
        child: IndexedStack(
          index: pageIndex,
          children: const [
            ButtonsPage(),
            IndicatorsPage(),
            FieldsPage(),
            ColorsPage(),
          ],
        ),
      ),
    );
  }
}

// 模拟页面内容
class ButtonsPage extends StatelessWidget {
  const ButtonsPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Center(child: Text('Buttons Page'));
  }
}

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

  @override
  Widget build(BuildContext context) {
    return Center(child: Text('Indicators Page'));
  }
}

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

  @override
  Widget build(BuildContext context) {
    return Center(child: Text('Fields Page'));
  }
}

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

  @override
  Widget build(BuildContext context) {
    return Center(child: Text('Colors Page'));
  }
}

主要组件介绍

MacosWindow

MacosWindow是构建macOS风格布局的基础框架。它支持左侧的Sidebar、顶部的TitleBar以及主内容区域。

Sidebar

Sidebar用于导航和快速访问应用程序的主要内容集合。可以通过MacosWindow.sidebar属性放置在左侧，或通过MacosWindow.endSidebar属性放置在右侧。

MacosScaffold

MacosScaffold类似于页面的概念，包含工具栏和子组件。可以将其与CupertinoTabView结合使用，以便更好地管理导航。

ToolBar

ToolBar提供了对常用命令和功能的便捷访问。每个工具栏项都应该有一个对应的菜单栏命令。

SliverToolBar

SliverToolBar是ToolBar的一个变体，适用于可滚动的小部件，如CustomScrollView和NestedScrollView。

MacosListTile

MacosListTile模仿了Flutter Material库中的ListTile，用于显示列表项。

MacosTabView

MacosTabView用于创建多页面界面，允许用户在不同页面之间切换。

Icons

MacosIcon是一种图标小部件，遵循MacosTheme，可以像普通图标一样使用。

Buttons

包括多种类型的按钮，如MacosCheckbox、HelpButton、RadioButton、PulldownButton、PopupButton、PushButton、MacosSwitch和MacosSegmentedControl。

Dialogs and Sheets

MacosAlertDialog和MacosSheet分别用于创建对话框和表单。

Fields

MacosTextField和MacosSearchField分别用于创建文本输入框和搜索框。

Labels

MacosTooltip用于为屏幕上的元素添加简短描述。

Indicators

ProgressCircle和ProgressBar用于表示进度；CapacityIndicator、RatingIndicator用于表示容量和评分。

Selectors

MacosDatePicker、MacosTimePicker和MacosColorWell分别用于选择日期、时间和颜色。

总结

通过上述内容，您可以快速上手macos_ui插件，构建出具有macOS风格的Flutter应用程序。更多详细信息和高级用法，请参考官方文档和示例项目。