Flutter巴西地理位置插件brazilian_locations的使用

概述

本插件由Guilherme Queiroz开发，旨在帮助开发者在Flutter应用中展示巴西各州和城市的列表。通过使用该插件，您可以构建高度可定制的输入组件，这是设计师在Figma中难以实现的。

Flutter Brazilian Locations

如何使用

要使用此插件，请将其添加到您的pubspec.yaml文件中作为依赖项：

dependencies:
  brazilian_locations: ^x.y.z

然后，在您的代码中导入并使用插件：

import 'package:brazilian_locations/brazilian_locations.dart';

以下是一个简单的示例代码：

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

void main() async {
  // 确保在任何异步操作之前初始化小部件绑定。
  WidgetsFlutterBinding.ensureInitialized();

  /// 可选地初始化BrazilianLocations
  /// - 这一步设置Hive并加载缓存数据。
  /// - 通过在此处进行初始化，您可以避免首次加载时显示空或无响应的下拉框，特别是如果需要从API获取数据。
  /// - [可选] 如果您希望以不同的方式处理数据加载，可以跳过此初始化步骤，但可能会导致小部件首次出现时填充下拉框时有轻微延迟。
  await BrazilianLocations.initialize();

  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: MyHomePage(),
    );
  }
}

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

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  String stateValue = "";
  String cityValue = "";
  String address = "";

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('巴西地理位置'),
      ),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          children: [
            const SizedBox(height: 16),

            /// 添加BrazilianLocations小部件到应用中
            BrazilianLocations(
              /// 启用/禁用州下拉菜单 [可选参数]
              showStates: true,

              /// 启用/禁用城市下拉菜单 [可选参数]
              showCities: true,

              /// 下拉框装饰来样式化您的下拉选择器 [可选参数] (与disabledDropdownDecoration一起使用)
              dropdownDecoration: BoxDecoration(
                borderRadius: const BorderRadius.all(Radius.circular(4)),
                color: Colors.white,
                border: Border.all(color: Colors.grey.shade400, width: 1),
              ),

              /// 禁用的下拉框装饰来样式化您的下拉选择器 [可选参数] (与禁用的dropdownDecoration一起使用)
              disabledDropdownDecoration: BoxDecoration(
                borderRadius: const BorderRadius.all(Radius.circular(4)),
                color: Colors.grey.shade300,
                border: Border.all(color: Colors.grey.shade400, width: 1),
              ),

              /// 下拉搜索字段的占位符
              stateSearchPlaceholder: "Estado",
              citySearchPlaceholder: "City",

              /// 下拉菜单标签
              stateDropdownLabel: "Estado",
              cityDropdownLabel: "City",

              /// 选定项目的样式 [可选参数]
              selectedItemStyle: const TextStyle(
                color: Colors.black,
                fontSize: 16,
              ),

              /// 下拉对话框标题样式 [可选参数]
              dropdownHeadingStyle: const TextStyle(
                  color: Colors.black,
                  fontSize: 18,
                  fontWeight: FontWeight.bold),

              /// 下拉对话框项目样式 [可选参数]
              dropdownItemStyle: const TextStyle(
                color: Colors.black,
                fontSize: 16,
              ),

              /// 对话框框的圆角 [可选参数]
              dropdownDialogRadius: 8.0,

              /// 搜索栏圆角 [可选参数]
              searchBarRadius: 8.0,

              /// 状态下拉菜单选择时触发
              onStateChanged: (value) {
                if (value != null) {
                  setState(() {
                    /// 将值存储在状态变量中
                    stateValue = value;
                  });
                }
              },

              /// 城市下拉菜单选择时触发
              onCityChanged: (value) {
                if (value != null) {
                  setState(() {
                    /// 将值存储在城市变量中
                    cityValue = value;
                  });
                }
              },
            ),

            /// 在文本小部件中打印新选择的状态和城市
            TextButton(
              onPressed: () {
                setState(() => address = "$cityValue, $stateValue");
              },
              child: const Text("打印数据"),
            ),
            Text(address),
          ],
        ),
      ),
    );
  }
}

缓存服务

该插件现在包含一个缓存服务，该服务使用Hive存储从IBGE API检索的数据，从而加快后续应用启动时的加载时间。

可选初始化

您可以选择在运行应用之前初始化缓存服务，以确保数据预先加载且用户交互时下拉菜单已准备好。

示例：

void main() async {
  /// 可选地初始化BrazilianLocations
  /// - 初始化Hive并加载缓存数据。
  /// - 确保首次应用加载时下拉菜单已填充并响应。
  await BrazilianLocations.initialize();

  runApp(const MyApp());
}