Flutter进度条展示插件primer_progress_bar的使用

插件简介

primer_progress_bar 是一个基于 GitHub Primer Design System 的非官方 Flutter 进度条实现。它提供了丰富的自定义选项，可以轻松地在应用程序中创建美观且功能强大的进度条。

版本信息

• 最新版本: 0.4.0（要求Flutter SDK版本3.16.0或更高）
• 旧版本: 如果您使用的是较旧的SDK，请使用版本0.3.0或更低版本。

安装

要使用 primer_progress_bar，请将以下内容添加到您的 pubspec.yaml 文件中：

dependencies:
  primer_progress_bar: ^0.4.0

或者，您可以直接通过命令行安装：

flutter pub add primer_progress_bar

使用示例

下面是一个完整的示例代码，展示了如何使用 primer_progress_bar 创建一个包含多个段落的进度条，并允许用户交互调整显示的段落数量、是否限制图例行数等。

示例代码

import 'dart:math';
import 'package:flutter/material.dart';
import 'package:primer_progress_bar/primer_progress_bar.dart';

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

final themeMode = ValueNotifier(Brightness.light);

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

  @override
  Widget build(BuildContext context) {
    return ValueListenableBuilder(
      valueListenable: themeMode,
      builder: (context, brightness, _) {
        return MaterialApp(
          theme: ThemeData(
            useMaterial3: true,
            brightness: brightness,
          ),
          home: const Home(),
        );
      },
    );
  }
}

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

  @override
  State<Home> createState() => _HomeState();
}

class _HomeState extends State<Home> {
  final segments = const [
    Segment(
      color: Colors.green,
      value: 24,
      label: Text("Dart"),
      valueLabel: Text("24%"),
    ),
    Segment(
      color: Colors.lime,
      value: 11,
      label: Text("CSS"),
      valueLabel: Text("11%"),
    ),
    Segment(
      color: Colors.purple,
      value: 9,
      label: Text("HTML"),
      valueLabel: Text("9%"),
    ),
    Segment(
      color: Colors.lightBlue,
      value: 6,
      label: Text("Typescript"),
      valueLabel: Text("6%"),
    ),
    Segment(
      color: Colors.orange,
      value: 4,
      label: Text("Javascript"),
      valueLabel: Text("4%"),
    ),
    Segment(
      color: Colors.grey,
      value: 4,
      label: Text("Shell"),
      valueLabel: Text("4%"),
    ),
    Segment(
      color: Colors.indigo,
      value: 4,
      label: Text("Java"),
      valueLabel: Text("4%"),
    ),
    Segment(
      color: Colors.red,
      value: 4,
      label: Text("Objective-C"),
      valueLabel: Text("4%"),
    ),
    Segment(
      color: Colors.teal,
      value: 2,
      label: Text("Rust"),
      valueLabel: Text("2%"),
    ),
    Segment(
      color: Colors.brown,
      value: 2,
      label: Text("Swift"),
      valueLabel: Text("2%"),
    ),
  ];

  late final maxTotalValue = segments.fold(0, (acc, seg) => acc + seg.value);
  late int displaySegmentCount = segments.length ~/ 2;
  late double sliderValue = segments.length / 2;
  bool alwaysFillBar = false;
  bool limitLegendLines = false;

  @override
  Widget build(BuildContext context) {
    final progressBar = PrimerProgressBar(
      segments: segments.take(displaySegmentCount).toList(),
      maxTotalValue: alwaysFillBar ? null : maxTotalValue,
      legendStyle: limitLegendLines
          ? const SegmentedBarLegendStyle(maxLines: 2)
          : const SegmentedBarLegendStyle(maxLines: null),
      legendEllipsisBuilder: (truncatedItemCount) {
        final value = segments
            .skip(displaySegmentCount - truncatedItemCount)
            .take(truncatedItemCount)
            .fold(0, (accValue, segment) => accValue + segment.value);
        return LegendItem(
          segment: Segment(
            value: value,
            color: Colors.grey,
            label: const Text("Other"),
            valueLabel: Text("$value%"),
          ),
        );
      },
    );

    final options = [
      SwitchListTile(
        title: const Text("Dark Theme"),
        value: themeMode.value == Brightness.dark,
        onChanged: (turnedOn) {
          setState(() {
            themeMode.value = turnedOn ? Brightness.dark : Brightness.light;
          });
        },
      ),
      SwitchListTile(
        title: const Text("Always fill the entire bar"),
        value: alwaysFillBar,
        onChanged: (turnedOn) {
          setState(() => alwaysFillBar = turnedOn);
        },
      ),
      SwitchListTile(
        title: const Text("Limit the legend lines"),
        value: limitLegendLines,
        onChanged: (turnedOn) {
          setState(() => limitLegendLines = turnedOn);
        },
      ),
    ];

    final slider = SizedBox(
      height: 56,
      child: Slider(
        value: sliderValue,
        min: 0,
        max: segments.length.toDouble(),
        divisions: segments.length,
        label: "$displaySegmentCount segment(s)",
        onChanged: (value) {
          setState(() {
            sliderValue = value;
            displaySegmentCount = value.round();
          });
        },
      ),
    );

    final body = Padding(
      padding: const EdgeInsets.all(20),
      child: Column(
        children: [
          Expanded(
            child: Center(
              child: progressBar,
            ),
          ),
          ...options,
        ],
      ),
    );

    const minBodyHeight = 400.0;
    final bodyContainer = LayoutBuilder(
      builder: (context, constraints) {
        return SingleChildScrollView(
          child: ConstrainedBox(
            constraints: BoxConstraints(
              minHeight: minBodyHeight,
              maxHeight: max(constraints.maxHeight, minBodyHeight),
            ),
            child: body,
          ),
        );
      },
    );

    return Scaffold(
      appBar: AppBar(),
      extendBodyBehindAppBar: true,
      body: SafeArea(
        top: false,
        bottom: false,
        child: bodyContainer,
      ),
      bottomNavigationBar: BottomAppBar(
        child: slider,
      ),
    );
  }
}

关键特性

段落定义

每个段落由 Segment 类表示，包括颜色、值和标签：

Segment(
  color: Colors.green,
  value: 24,
  label: Text("Dart"),
  valueLabel: Text("24%"),
);

进度条配置

通过 PrimerProgressBar 小部件配置进度条，支持以下参数：

• segments: 段落列表。
• maxTotalValue: 总值，用于计算各段的比例，默认为所有段的值之和。
• legendStyle: 图例样式，可限制图例行数。
• legendEllipsisBuilder: 当图例超出限制时，生成“其他”项的回调函数。

样式定制

可以通过 SegmentedBarStyle, SegmentedBarLegendStyle, 和 LegendItemStyle 来定制进度条的外观。

总结

primer_progress_bar 提供了一个灵活且易于使用的API来创建复杂的进度条组件。无论是在简单的应用还是复杂的数据可视化场景中，它都能很好地满足需求。希望这个指南能帮助你快速上手并充分利用这个强大的工具！