Flutter自定义组件插件 pal_widgets 的使用

pal_widgets 是一个用于增强Flutter应用中引导页（onboarding）功能的插件。它提供了多种引导小部件，可以让你的应用更容易上手。

安装插件

在你的 pubspec.yaml 文件中添加以下依赖：

dependencies:
  pal_widgets: ^0.3.0

然后运行 flutter pub get 来安装该插件。

列表中的助手（Helpers）

使用 AnchoredHelper

AnchoredHelper 受Google引导页启发，能够围绕你想要突出显示的小部件创建一个覆盖层，并在其上方显示消息和按钮。

示例代码

首先，在你的页面或应用根部嵌入 HelperOrchestrator 小部件。

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

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

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: HelperOrchestrator(
        child: MyHomePage(title: 'Flutter Demo Home Page'),
      ),
    );
  }
}

接下来，给需要作为锚点的小部件设置一个key。

Text(
  '$_counter',
  key: HelperOrchestrator.of(context).generateKey('text1'),
),

现在，你可以创建并显示一个 AnchoredHelper：

final helper = AnchoredHelper(
  title: const Text('Title lorem pitume'),
  description: const Text('Lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum'),
  bgColor: Colors.blue,
  leftBtnText: const Text('cancel'),
  rightBtnText: const Text('Ok, understood'),
  onError: () => print("widget not found"),
  positivBtnStyle: helperOutlineBtnStyle,
  negativeBtnStyle: helperOutlineBtnStyle,
  onLeftBtnTap: () => HelperOrchestrator.of(context).hideHelper(),
  onRightTap: () => HelperOrchestrator.of(context).hideHelper(),
  onTapAnchor: () => HelperOrchestrator.of(context).hideHelper(),
);

// 显示带有'text1'键的锚定助手
HelperOrchestrator.of(context).showAnchoredHelper('text1', helper);

属性说明

• title：标题文本。
• description：描述文本。
• bgColor：背景颜色（必填项）。
• leftBtnText：左侧按钮文本。
• rightBtnText：右侧按钮文本。
• onLeftBtnTap：左侧按钮点击事件。
• onRightTap：右侧按钮点击事件。
• onError：错误处理函数。
• leftBtnStyle：左侧按钮样式。
• rightBtnStyle：右侧按钮样式。
• onTapAnchor：点击锚点时的动作。
• widgetFactory：创建锚定助手的工厂方法，默认是 AnchoredCircleHoleHelper.anchorFactory，也可以选择 AnchoredRectHoleHelper.anchorFactory。

演示完整Demo

下面是一个完整的演示示例：

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

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

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: const HelperOrchestrator(
        child: MyHomePage(title: 'Flutter Demo Home Page'),
      ),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({Key? key, required this.title}) : super(key: key);

  final String title;

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

class _MyHomePageState extends State<MyHomePage> {
  int _counter = 0;

  void _incrementCounter() {
    setState(() {
      _counter++;
    });
  }

  ButtonStyle get helperOutlineBtnStyle => OutlinedButton.styleFrom(
        padding: const EdgeInsets.all(12),
        textStyle: const TextStyle(color: Colors.white, fontSize: 18),
        side: const BorderSide(width: 1.0, style: BorderStyle.solid, color: Colors.white),
        shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(8.0)),
      );

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            const Text('You have pushed the button this many times:'),
            Text(
              '$_counter',
              style: const TextStyle(color: Colors.blue, fontSize: 32),
            ),
            Text(
              'test widget helper',
              key: HelperOrchestrator.of(context).generateKey('text2'),
            ),
            const SizedBox(height: 21),
            OutlinedButton(
              onPressed: () {
                HelperOrchestrator.of(context).showAnchoredHelper('btn', helper);
              },
              child: const Text('push me 2'),
              key: HelperOrchestrator.of(context).generateKey('btn'),
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ),
    );
  }

  AnchoredHelper get helper => AnchoredHelper(
        title: const Text(
          'Push to increment',
          textAlign: TextAlign.center,
          style: TextStyle(color: Colors.white, fontSize: 32),
        ),
        description: const Text(
          'Tap on this button to increment the flutter demo counter',
          textAlign: TextAlign.center,
          style: TextStyle(color: Colors.white, fontSize: 21),
        ),
        bgColor: Colors.blue,
        rightBtnStyle: helperOutlineBtnStyle,
        leftBtnStyle: helperOutlineBtnStyle,
        onTapAnchor: () => HelperOrchestrator.of(context).hideHelper(),
        widgetFactory: AnchoredCircleHoleHelper.anchorFactory,
      );
}

这样，你就完成了一个简单的Flutter应用，它使用了 pal_widgets 插件来实现用户引导功能。