Flr CLI
Flr (Flutter-R) CLI: A Flutter Resource Manager CLI TooL, which can help flutter developer to auto specify assets in pubspec.yaml and generate r.g.dart file after he changes the flutter project assets. With r.g.dart, flutter developer can apply the asset in code by referencing it's asset ID function.
๐ Read this in other languages: English, ็ฎไฝไธญๆ
Feature
- Support auto service that automatically specify assets in
pubspec.yamland generater.g.dartfile, which can be triggered manually or by monitoring asset changes - Support
R.x(such asR.image.test(),R.svg.test(width: 100, height: 100),R.txt.test_json()) code struct - Support for processing image assets (
.png,.jpg,.jpeg,.gif,.webp,.icon,.bmp,.wbmp,.svg) - Support for processing text assets (
.txt,.json,.yaml,.xml) - Support for processing font assets (
.ttf,.otf,.ttc) - Support for processing image asset variants
- Support for processing asset whichโs filename is bad:
- filename has illegal character (such as
blank,~,@,#) which is outside the range of valid characters (0-9,A-Z,a-z,_,+,-,.,ยท,!,@,&,$,๏ฟฅ) - filename begins with a number or character
_or character$
- filename has illegal character (such as
- Support for processing assets with the same filename but different path
- Support for processing multi projects (the main project and its sub projects in one workspace)
- Support for auto merging old asset specifications when specifying new assets
Install & Update Flr CLI
To install or update Flr, run sudo gem install flr
If you want to use Flr tool on the Windows system, you are strongly recommended to run it on WSL(Windows Subsystem for Linux) environment !!!
Uninstall Flr CLI
To uninstall Flr run sudo gem uninstall flr
Usage
-
Init your flutter project:
cd flutter_project_dir flr initThe
flr initcommand will check to see if the current project is a legal flutter project, add flr configuration and dependency r_dart_library intopubspec.yaml.Attention:
The Flutter SDK is currently in an unstable state, so if you get a build error of
r_dart_library, you can fix it by modify the dependent version ofr_dart_library.You can select the correct version of
r_dart_librarybased on this dependency relationship table. -
Open
pubspec.yamlfile, find the configuration item forFlr, and then configure the resource directories that needs to be scanned byFlrand configure the line length that is used to formatr.g.dart, such as:flr: core_version: 1.0.0 # config the line length that is used to format r.g.dart dartfmt_line_length: 80 # config the image and text resource directories that need to be scanned assets: - lib/assets/images - lib/assets/texts # config the font resource directories that need to be scanned fonts: - lib/assets/fonts
-
Scan assets, specify assets, and generate
r.g.dart:flr run
After run
flr runcommand,Flrwill scan the resource directories configured inpubspec.yaml, then specify scanned assets inpubspec.yaml, and generater.g.dartfile.If you want
Flrto do the above operations automatically every time a asset changes, you can run the commandFlr run --auto. ThenFlrwill launch a monitoring service that continuously monitors resource directories configured inpubspec.yaml. If the service detects any asset changes,Flrwill automatically scan the resource directories, then specify scanned assets in pubspec.yaml, and generate "r.g.dart" file.You can terminate this monitoring service by manually pressing
Ctrl-C.
Attention: all commands MUST be runned in your flutter project root directory.
Recommended Flutter Resource Structure
Flr the following flutter resource structure schemes:
-
scheme 1:
flutter_project_root_dir โโโ build โ โโโ .. โโโ lib โ โโโ assets โ โ โโโ images // image resource directory of all modules โ โ โ โโโ #{module} // image resource directory of a module โ โ โ โ โโโ #{main_image_asset} โ โ โ โ โโโ #{variant-dir} // image resource directory of a variant โ โ โ โ โ โโโ #{image_asset_variant} โ โ โ โ โ โ โ โโโ home // image resource directory of home module โ โ โ โ โโโ home_badge.svg โ โ โ โ โโโ home_icon.png โ โ โ โ โโโ 3.0x // image resource directory of a 3.0x-ratio-variant โ โ โ โ โ โโโ home_icon.png โ โ โ โ โ โ โโโ texts // text resource directory โ โ โ โ // (you can also break it down further by module) โ โ โ โโโ test.json โ โ โ โโโ test.yaml โ โ โ โ โ โ โโโ fonts // font resource directory of all font-families โ โ โ โโโ #{font-family} // font resource directory of a font-family โ โ โ โ โโโ #{font-family}-#{font_weight_or_style}.ttf โ โ โ โ โ โ โ โโโ Amiri // font resource directory of Amiri font-family โ โ โ โ โโโ Amiri-Regular.ttf โ โ โ โ โโโ Amiri-Bold.ttf โ โ โ โ โโโ Amiri-Italic.ttf โ โ โ โ โโโ Amiri-BoldItalic.ttf โ โโโ .. -
scheme 2:
flutter_project_root_dir โโโ build โ โโโ .. โโโ lib โ โโโ .. โโโ assets โ โโโ images // image resource directory of all modules โ โ โโโ #{module} // image resource directory of a module โ โ โ โโโ #{main_image_asset} โ โ โ โโโ #{variant-dir} // image resource directory of a variant โ โ โ โ โโโ #{image_asset_variant} โ โ โ โ โ โโโ home // image resource directory of home module โ โ โ โโโ home_badge.svg โ โ โ โโโ home_icon.png โ โ โ โโโ 3.0x // image resource directory of a 3.0x-ratio-variant โ โ โ โ โโโ home_icon.png โ โ โ โ โโโ texts // text resource directory โ โ โ // (you can also break it down further by module) โ โ โโโ test.json โ โ โโโ test.yaml โ โ โ โ โโโ fonts // font resource directory of all font-families โ โ โโโ #{font-family} // font resource directory of a font-family โ โ โ โโโ #{font-family}-#{font_weight_or_style}.ttf โ โ โ โ โ โโโ Amiri // font resource directory of Amiri font-family โ โ โ โโโ Amiri-Regular.ttf โ โ โ โโโ Amiri-Bold.ttf โ โ โ โโโ Amiri-Italic.ttf โ โ โ โโโ Amiri-BoldItalic.ttf โ โโโ ..
Big Attention, the resource structure in the root directory of the font resource MUST follow the structure described above: name the subdirectory with a font family name, and place the font resources of the font family in the subdirectory. Otherwise, Flr may not scan the font resource correctly.
r.g.dart
After you run flr run [--auto], Flr will scan the asset directories configured in pubspec.yaml, then specify scanned assets in pubspec.yaml, and generate r.g.dart file.
r.g.dart defines a asset access interface class: R, which allows flutter developer to apply the asset in code by referencing it's asset ID function, such as:
import 'package:flutter_r_demo/r.g.dart';
// test_sameName.png
var normalImageWidget = Image(
width: 200,
height: 120,
image: R.image.test_sameName(),
);
// test_sameName.gif
var gifImageWidget = Image(
image: R.mage.test_sameName_gif(),
);
// test.svg
var svgImageWidget = Image(
width: 100,
height: 100,
image: R.svg.test(width: 100, height: 100),
);
// test.json
var jsonString = await R.text.test_json();
// test.yaml
var yamlString = await R.text.test_yaml();
// Amiri Font Style
var amiriTextStyle = TextStyle(fontFamily: R.fontFamily.amiri);
_R_X class
r.g.dart defines several private _R_X asset management classes: _R_Image, _R_Svg, _R_Text, _R_FontFamily. These private asset management classes are used to manage the asset IDs of the respective asset types:
-
_R_Image: manage the asset IDs of non-svg type image assets (.png,.jpg,.jpeg,.gif,.webp,.icon,.bmp,.wbmp) -
_R_Svg: manage the asset IDs of svg type image assets -
_R_Text: manage the asset IDs of text assets (.txt,.json,.yaml,.xml) -
_R_FontFamily: manage the asset IDs of font assets (.ttf,.otf,.ttc)
R class and R.x struct
r.g.dart defines a asset access interface class: R, which is used to manage common information, aggregate the _R_X asset management classes, and implement R.x code struct:
/// This `R` class is generated and contains references to static asset resources.
class R {
/// package name: flutter_r_demo
static const package = "flutter_r_demo";
/// This `R.image` struct is generated, and contains static references to static non-svg type image asset resources.
static const image = _R_Image();
/// This `R.svg` struct is generated, and contains static references to static svg type image asset resources.
static const svg = _R_Svg();
/// This `R.text` struct is generated, and contains static references to static text asset resources.
static const text = _R_Text();
/// This `R.fontFamily` struct is generated, and contains static references to static font resources.
static const fontFamily = _R_FontFamily();
}Example
Here are some example demos to show how to use Flr tool in flutter project and show how to use R class in your code:
License
The gem is available as open source under the terms of the MIT License.