这是indexloc提供的服务,不要输入任何密码

ky_guide 0.1.0 copy "ky_guide: ^0.1.0" to clipboard
ky_guide: ^0.1.0 copied to clipboard

Guide feauture guide

ky_guide Guide #

pub package style: very good analysis License: MIT

A comprehensive and customizable onboarding system for Flutter applications that guides users through new features using beautiful overlays and tooltips.

✨ Features #

  • 🎯 Target Any Widget - Highlight any existing widget in your app
  • 🎨 Highly Customizable - Custom colors, content, and styling
  • 📱 Responsive Design - Automatically adapts to different screen sizes
  • 🔄 Smart Positioning - Tooltips position themselves optimally
  • ⏭️ Skip Functionality - Users can skip onboarding anytime
  • 🎭 Beautiful Animations - Smooth transitions between steps
  • 🧩 Easy Integration - Works with existing apps without major changes
  • 🚀 Lightweight - Minimal performance impact

📱 Screenshots #

Welcome Step Feature Highlight Custom Content
Welcome Feature Custom

🚀 Getting Started #

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  ky_guide: ^0.1.0

Then run:

flutter pub get

Import #

import 'package:ky_guide/ky_guide.dart';

💡 Quick Start #

1. Create an GuideController #

class MyHomePage extends StatefulWidget {
  @override
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  final GuideController _GuideController = GuideController();
}

2. Wrap Target Widgets #

// Create GlobalKeys for your target widgets
final GlobalKey _fabKey = GlobalKey();
final GlobalKey _menuKey = GlobalKey();

// Wrap widgets you want to highlight
GuideTarget(
  onboardingKey: _fabKey,
  child: FloatingActionButton(
    onPressed: () {},
    child: Icon(Icons.add),
  ),
)

3. Create Guide Steps #

void _startGuide() {
  final steps = [
    GuideStep(
      targetKey: _fabKey,
      title: 'Create New Items',
      description: 'Tap this button to create new content.',
    ),
    GuideStep(
      targetKey: _menuKey,
      title: 'Access Menu',
      description: 'Find more options in this menu.',
      backgroundColor: Colors.blue.shade50,
    ),
  ];

  _GuideController.startGuide(steps);
}

4. Start Guide #

@override
void initState() {
  super.initState();
  
  // Start onboarding after first frame
  WidgetsBinding.instance.addPostFrameCallback((_) {
    _startGuide();
  });
}

🎨 Customization #

Custom Step Content #

GuideStep(
  targetKey: _buttonKey,
  title: 'Pro Feature',
  description: 'This is a premium feature.',
  customContent: Container(
    padding: EdgeInsets.all(12),
    decoration: BoxDecoration(
      color: Colors.amber.shade100,
      borderRadius: BorderRadius.circular(8),
    ),
    child: Row(
      children: [
        Icon(Icons.star, color: Colors.amber),
        SizedBox(width: 8),
        Text('Unlock with Pro!'),
      ],
    ),
  ),
  backgroundColor: Colors.white,
  showSkipButton: false, // Force users to see this step
)

Styling Options #

GuideStep(
  targetKey: _targetKey,
  title: 'Custom Style',
  description: 'This step has custom styling.',
  tooltipPadding: EdgeInsets.all(20),
  backgroundColor: Colors.deepPurple.shade50,
  borderRadius: 12.0,
)

🎮 Controller Methods #

Method Description
startGuide(List<GuideStep> steps) Start onboarding with given steps
nextStep() Move to next step
previousStep() Move to previous step
skipGuide() Skip entire onboarding
finishGuide() Complete onboarding

🎯 GuideStep Properties #

Property Type Default Description
targetKey GlobalKey Required Key of widget to highlight
title String Required Title text
description String Required Description text
customContent Widget? null Additional custom content
tooltipPadding EdgeInsets EdgeInsets.all(16) Tooltip padding
backgroundColor Color? null Tooltip background color
borderRadius double 8.0 Highlight border radius
showSkipButton bool true Show/hide skip button

🔧 Advanced Usage #

Listen to Guide State #

_GuideController.addListener(() {
  if (!_GuideController.isActive) {
    print('Guide completed!');
    // Save completion state, show celebration, etc.
  }
});

Conditional Steps #

void _createConditionalGuide() {
  List<GuideStep> steps = [
    // Always show welcome
    GuideStep(
      targetKey: _welcomeKey,
      title: 'Welcome!',
      description: 'Let\'s get started.',
    ),
  ];

  // Add premium feature step only for pro users
  if (user.isPro) {
    steps.add(GuideStep(
      targetKey: _proFeatureKey,
      title: 'Pro Feature',
      description: 'This is available for pro users.',
    ));
  }

  _GuideController.startGuide(steps);
}

Multiple Guide Flows #

class GuideManager {
  static const String FIRST_LAUNCH = 'first_launch';
  static const String NEW_FEATURE = 'new_feature_v2';
  
  static void showAppropriateGuide(BuildContext context) {
    final prefs = SharedPreferences.getInstance();
    
    if (!prefs.getBool(FIRST_LAUNCH, false)) {
      _showFirstLaunchGuide();
      prefs.setBool(FIRST_LAUNCH, true);
    } else if (!prefs.getBool(NEW_FEATURE, false)) {
      _showNewFeatureGuide();
      prefs.setBool(NEW_FEATURE, true);
    }
  }
}

🧪 Testing #

import 'package:flutter_test/flutter_test.dart';
import 'package:ky_guide/ky_guide.dart';

void main() {
  group('GuideController', () {
    late GuideController controller;

    setUp(() {
      controller = GuideController();
    });

    test('should start with inactive state', () {
      expect(controller.isActive, false);
      expect(controller.currentStep, 0);
    });

    test('should activate when starting onboarding', () {
      final steps = [
        GuideStep(
          targetKey: GlobalKey(),
          title: 'Test',
          description: 'Test description',
        ),
      ];
      
      controller.startGuide(steps);
      expect(controller.isActive, true);
    });
  });
}

🤝 Contributing #

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup #

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Add tests for your changes
  5. Ensure tests pass (flutter test)
  6. Commit your changes (git commit -m 'Add amazing feature')
  7. Push to the branch (git push origin feature/amazing-feature)
  8. Open a Pull Request

📋 Requirements #

  • Flutter SDK: >=3.0.0 <4.0.0
  • Dart SDK: >=2.17.0 <4.0.0

🐛 Issues #

If you encounter any issues, please file them on the GitHub issue tracker.

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments #

  • Inspired by various onboarding libraries across different platforms
  • Thanks to the Flutter community for feedback and contributions
  • Special thanks to all contributors

Made with ❤️ by [Your Name]


---

## 📄 CHANGELOG.md

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.0.0] - 2024-06-12

### 🎉 Initial Release

#### Added
- ✨ Complete onboarding system with overlay and tooltips
- 🎯 `GuideController` for managing onboarding flow
- 📝 `GuideStep` model for defining onboarding steps
- 🎨 `GuideTarget` widget for marking target elements
- 🔄 Navigation between steps (next, previous, skip, finish)
- 📱 Responsive tooltip positioning
- 🎨 Customizable styling (colors, padding, border radius)
- 📖 Custom content support for steps
- ⏭️ Configurable skip button per step
- 🌗 Dark overlay with spotlight effect on target widgets
- 📚 Comprehensive API documentation
- 🧪 Example implementation
- 🔧 TypeScript-like documentation with examples

#### Features
- **Smart Positioning**: Tooltips automatically position above or below targets
- **Customizable Content**: Add custom widgets to any step
- **Skip Functionality**: Allow users to skip onboarding entirely
- **Step Control**: Navigate forward, backward, or jump to finish
- **Responsive Design**: Works on all screen sizes
- **Easy Integration**: Minimal code changes to existing apps
- **Performance Optimized**: Efficient overlay rendering and updates

#### Developer Experience
- 📖 Complete API documentation with examples
- 🎯 Type-safe implementation
- 🧩 Easy integration with existing Flutter apps
- 🔧 Highly customizable and extensible
- 📱 Works with any existing Flutter widgets

### 📋 Requirements
- Flutter: `>=3.0.0 <4.0.0`
- Dart: `>=2.17.0 <4.0.0`

### 🔗 Links
- [Documentation](https://pub.dev/documentation/ky_guide/latest/)
- [Example](https://pub.dev/packages/ky_guide/example)
- [GitHub Repository](https://github.com/bhangun/ky_guide)

---

## [Unreleased]

### 🚧 Planned Features
- 🎥 Animation customization options
- 🎵 Sound effects support
- 📊 Analytics integration
- 🌍 Internationalization support
- 🎨 More built-in tooltip themes
- 📱 Platform-specific adaptations
- 🔄 Gesture-based navigation
- 💾 Automatic progress persistence

### 🐛 Known Issues
- None currently reported

---

## Release Notes Format

Each release follows this structure:

### [Version] - Date

#### Added ✨
- New features and capabilities

#### Changed 🔄
- Changes to existing functionality

#### Deprecated ⚠️
- Features marked for removal

#### Removed 🗑️
- Removed features

#### Fixed 🐛
- Bug fixes and corrections

#### Security 🔒
- Security-related changes

---

**Note**: This project follows [Semantic Versioning](https://semver.org/). Given a version number MAJOR.MINOR.PATCH:
- **MAJOR** version changes for incompatible API changes
- **MINOR** version changes for backward-compatible functionality additions  
- **PATCH** version changes for backward-compatible bug fixes

🚀 Publishing Checklist #

Before publishing to pub.dev, ensure:

  • ❌ All files are in correct directory structure
  • pubspec.yaml has correct version and metadata
  • ❌ README.md is comprehensive with examples
  • ❌ CHANGELOG.md documents all changes
  • ❌ LICENSE file is included
  • ❌ Tests are written and passing
  • ❌ Documentation is complete
  • ❌ Example app works correctly
  • ❌ No sensitive information in code
  • ❌ Package analysis passes (dart pub publish --dry-run)

📦 Publishing Command #

# Dry run to check for issues
dart pub publish --dry-run

# Publish to pub.dev
dart pub publish

This package is now ready for publication to pub.dev with all the necessary files, documentation, and structure!

0
likes
150
points
24
downloads

Publisher

unverified uploader

Weekly Downloads

Guide feauture guide

Homepage

Topics

#onboarding #tutorial #guide #introduction #showcase

Documentation

API reference

Funding

Consider supporting this project:

github.com
buymeacoffee.com

License

MIT (license)

Dependencies

flutter

More

Packages that depend on ky_guide