Flutter TOML解析插件toml.dart的使用

介绍

toml.dart 是一个为Dart语言实现的TOML解析器和编码器。它支持TOML规范版本1.0.0，并且可以方便地在Flutter项目中加载、解析、解码以及编码TOML格式的配置文件。

安装

首先，在你的pubspec.yaml文件中添加toml依赖：

dependencies:
  toml: ^0.16.0

然后运行以下命令来获取依赖项：

flutter pub get

使用方法

加载TOML文件

你可以通过TomlDocument.load方法从文件系统或HTTP加载TOML文件。下面是一个简单的例子，展示如何异步加载名为config.toml的文件：

import 'package:toml/toml.dart';

void main() async {
  try {
    var document = await TomlDocument.load('assets/config.toml');
    print('Configuration loaded successfully.');
  } catch (e) {
    print('Failed to load configuration: $e');
  }
}

注意：当代码在浏览器环境中运行时，将使用HTTP请求加载配置文件；而在Dart VM或原生应用中，则会直接从本地文件系统读取。

解析TOML字符串

如果你已经有了TOML格式的字符串内容，可以直接调用TomlDocument.parse来进行解析：

void main() {
  String contents = '''
  title = "TOML Example"

  [database]
  server = "192.168.1.1"
  ports = [ 8001, 8001, 8002 ]
  connection_max = 5000
  enabled = true
  ''';
  
  try {
    var document = TomlDocument.parse(contents);
    print('Parsed TOML document.');
  } catch (e) {
    print('Failed to parse TOML string: $e');
  }
}

解码TOML文档

一旦有了TomlDocument对象，就可以将其转换成Map形式以方便访问数据：

void main() {
  String contents = '''
  title = "TOML Example"

  [database]
  server = "192.168.1.1"
  ports = [ 8001, 8001, 8002 ]
  connection_max = 5000
  enabled = true
  ''';

  try {
    var document = TomlDocument.parse(contents);
    var config = document.toMap();
    print('Decoded configuration: ${config['database']['server']}');
  } catch (e) {
    print('Failed to decode TOML document: $e');
  }
}

编码TOML文档

你也可以将一个Map对象编码成TOML格式的字符串：

void main() {
  Map<String, dynamic> data = {
    'title': 'TOML Example',
    'database': {
      'server': '192.168.1.1',
      'ports': [8001, 8001, 8002],
      'connection_max': 5000,
      'enabled': true,
    },
  };

  try {
    var document = TomlDocument.fromMap(data);
    String tomlString = document.toString();
    print('Encoded TOML string:\n$tomlString');
  } catch (e) {
    print('Failed to encode TOML document: $e');
  }
}

数据结构映射

• 表（Table）和内联表（Inline Table）：TOML中的表格会被表示为嵌套的Map<String, dynamic>。
• 数组（Array）和表数组（Array of Tables）：所有类型的数组都会被转换为List。
• 字符串（String）：所有字符串类型都将被转换为Dart的String。
• 整数（Integer）：根据平台的不同，整数可能被表示为int或BigInt。
• 浮点数（Float）：浮点数被表示为double。
• 布尔值（Boolean）：布尔值对应于Dart的bool类型。
• 带偏移的时间戳（Offset Date-Time）：由TomlOffsetDateTime类表示，并可转换为DateTime对象。
• 本地时间戳（Local Date-Time）：由TomlLocalDateTime类表示。
• 日期（Local Date）：由TomlLocalDate类表示。
• 时间（Local Time）：由TomlLocalTime类表示。

示例代码

这里提供一个完整的Flutter示例，展示如何从assets中读取TOML文件并解析其内容：

import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:toml/toml.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('TOML Example')),
        body: FutureBuilder<Map<String, dynamic>>(
          future: _loadAndParseToml(),
          builder: (context, snapshot) {
            if (snapshot.connectionState == ConnectionState.done) {
              if (snapshot.hasError) {
                return Center(child: Text('Error: ${snapshot.error}'));
              }
              final config = snapshot.data!;
              return ListView(
                children: [
                  ListTile(
                    title: Text('Title'),
                    subtitle: Text(config['title']),
                  ),
                  ListTile(
                    title: Text('Server'),
                    subtitle: Text(config['database']['server']),
                  ),
                  // Add more ListTiles as needed...
                ],
              );
            } else {
              return Center(child: CircularProgressIndicator());
            }
          },
        ),
      ),
    );
  }

  Future<Map<String, dynamic>> _loadAndParseToml() async {
    String tomlContent = await DefaultAssetBundle.of(context).loadString('assets/config.toml');
    var document = TomlDocument.parse(tomlContent);
    return document.toMap();
  }
}

此示例展示了如何在一个Flutter应用程序中加载assets目录下的config.toml文件，并将其内容显示出来。请确保在pubspec.yaml中正确配置了assets路径。

结论

toml.dart 提供了一种简单而强大的方式来处理TOML格式的数据，无论是用于读取配置文件还是生成配置文件都非常适用。希望这篇文章能帮助你更好地理解和使用这个库。如果有任何问题或者需要进一步的帮助，请随时提问！