Flutter项目规范
app项目文件目录分布
以坎德拉环卫app为例
├─android flutter构建后的android项目app
├─ios flutter构建后的ios项目app
├─assets app项目中的资源文件(图片、字体、数据格式...)
├─build.sh 打包上传蒲公英/testFlight的运行脚本
├─pubspec.yaml 项目中的依赖包名称+版本,资源文件路径的引入
├─network
| ├─environment 环境常量配置、切换不同的运行环境逻辑
| ├─http 网络相关的请求、响应结果归类、异常请求后的逻辑处理、url请求路径等
| ├─interceptor 网络拦截器,用于断网的提示、或token过期的逻辑处理
| ├─token 登录有效的token逻辑处理
├─lib 业务源代码文件目录
| ├─main_stag.dart app入口,可以构建予发布环境下的包
| ├─main.dart app入口,可以构建生产环境下的包
| ├─routes.dart 路由文件
| ├─utils 工具目录
| | ├─base_data.dart 一些枚举和基础功能,TODO:详细的模块区分和解耦
...
| ├─main app的视图主框架结构
| ├─pages 页面视图
| | ├─device
| | | ├─bean 自定义的封装后的网络对象
| | | ├─page.dart 视图页面绘制 (view)
| | | ├─logic.dart 页面中的业务逻辑处理(viewModel)
| | | ├─state.dart 页面中的数据状态 (model)
| | | ├─service.dart 网络接口请求返回自定义对象
| | | ├─lib.dart 文件的导出
...
| ├─common
| | ├─widgets 公用视图组件
| | ├─lang 国际化
| | | ├─trahslations.dart
| | | ├─zow_en.json
| | | └zow_zh.json
| | ├─icons 图标
| | | └zow_icons.dart
...
部分代码说明
高德地图组件
Widget build(BuildContext context) {
return GetBuilder<AmapLogic>(
builder: (AmapLogic logic) {
return AMapWidget(
privacyStatement: AMapPrivacyStatement(
hasAgree: true,
hasContains: true,
hasShow: true,
),
apiKey: state.aMapApiKey,
customStyleOptions: state.customStyleOptions,
scaleEnabled: false,
tiltGesturesEnabled: false,
zoomGesturesEnabled: !MainState.instance.currentPark.showCircleWidget,
buildingsEnabled: false,
myLocationStyleOptions: MyLocationStyleOptions(
true,
circleFillColor: AppColors.transparentColor,
circleStrokeWidth: 0,
),
markers: logic.createMarkers(state.markerPoints, context: context),
polygons: state.polygons,
polylines: logic.createPolyline(state.polylineModels),
initialCameraPosition: state.cameraPosition,
onLocationChanged: (AMapLocation location) {
if (canLocation) {
logic.userLocation(location);
}
},
onMapCreated: (AMapController controller) {
if (onMapCreated != null) {
onMapCreated(controller);
}
},
onTap: (argument) => logic.userTouchMap(argument),
);
},
);
}
创建高德地图,并根据数据绘制锚点、区域、路线等。
/// 地图显示清扫区域名称
createAndShowAreaMarker(String index, LatLng latLng, {String areaId}) async {
Uint8List byteDatas = await widgetToImage(
Container(
child: Stack(
children: [
SizedBox(
width: 175.w,
height: 110.h,
child: AppIcons.loadIcon(AppIcons.zoneImg),
),
Container(
width: 175.w,
margin: EdgeInsets.only(top: 20.h),
child: Text(
'区域' + index,
style: TextStyle(
color: AppColors.textPrimaryColor,
fontSize: 35,
fontWeight: FontWeight.bold,
),
textAlign: TextAlign.center,
),
)
],
),
),
);
BitmapDescriptor bitmapDescriptor = BitmapDescriptor.fromBytes(byteDatas);
PointModel markerModel = PointModel.createAreaMarkerPoint(
latLng,
bitmapDescriptor,
areaId: areaId,
);
state.markerPoints.add(markerModel);
update();
return markerModel;
}
根据数字container
动态的生成BitmapDescriptor
,从而可以显示清扫区域锚点。
Future<Uint8List> widgetToImage(Widget widget,
{Alignment alignment = Alignment.center,
Size size = const Size(double.maxFinite, double.maxFinite),
double devicePixelRatio = 1.0,
double pixelRatio = 1.0}) async {
RenderRepaintBoundary repaintBoundary = RenderRepaintBoundary();
RenderView renderView = RenderView(
child: RenderPositionedBox(alignment: alignment, child: repaintBoundary),
configuration: ViewConfiguration(
size: size,
devicePixelRatio: devicePixelRatio,
),
window: ui.window,
);
PipelineOwner pipelineOwner = PipelineOwner();
pipelineOwner.rootNode = renderView;
renderView.prepareInitialFrame();
BuildOwner buildOwner = BuildOwner(focusManager: FocusManager());
RenderObjectToWidgetElement rootElement = RenderObjectToWidgetAdapter(
container: repaintBoundary,
child: Directionality(
textDirection: TextDirection.ltr,
child: widget,
),
).attachToRenderTree(buildOwner);
buildOwner.buildScope(rootElement);
buildOwner.finalizeTree();
pipelineOwner.flushLayout();
pipelineOwner.flushCompositingBits();
pipelineOwner.flushPaint();
ui.Image image = await repaintBoundary.toImage(pixelRatio: pixelRatio);
ByteData byteData = await image.toByteData(format: ui.ImageByteFormat.png);
Uint8List pngBytes = byteData.buffer.asUint8List();
return pngBytes;
}
根据高德地图组建动态的返回gps
logic.initLocationCallBack(locationCallback: (AMapLocation location) {
LatLng w84 = GpsUtil.gcj02_To_Gps84(location.latLng.latitude, location.latLng.longitude);
Position position = Position(
longitude: w84.longitude,
latitude: w84.latitude,
timestamp: DateTime.now(),
accuracy: 0.0,
altitude: location.altitude,
heading: 0.0,
speed: 0.0,
speedAccuracy: 0,
);
state.positionList.add(position);
}
}
)
当然需要设置canLocation
AmapCustomWidget(
onMapCreated: (controller) {
logic.state.mapController = controller;
logic.deviceLocationInMap();
},
canLocation: true,
)
代码规范
标识符三种类型
大驼峰
类、枚举、 typedef
和类型参数
class SliderMenu { ... }
class HttpRequest { ... }
typedef Predicate = bool Function<T>(T value);
包括用于元数据注释的类
class Foo {
const Foo([arg]);
}
@Foo(anArg)
class A { ... }
@Foo()
class B { ... }
使用小写加下划线来命名库和源文件
library peg_parser.source_scanner;
import 'file_system.dart';
import 'slider_menu.dart';
不推荐如下写法:
library pegparser.SourceScanner;
import 'file-system.dart';
import 'SliderMenu.dart';
使用小写加下划线来命名导入前缀
import 'dart:math' as math;
import 'package:angular_components/angular_components' as angular_components;
import 'package:js/js.dart' as js;
不推荐如下写法:
import 'dart:math' as Math;
import 'package:angular_components/angular_components' as angularComponents;
import 'package:js/js.dart' as JS;
使用小驼峰法命名其他标识符
var item;
HttpRequest httpRequest;
void align(bool clearItems) { ... }
优先使用小驼峰法作为常量命名
const pi = 3.14;
const defaultTimeout = 1000;
final urlScheme = RegExp('^([a-z]+):');
class Dice {
static final numberGenerator = Random();
}
不推荐如下写法:
const PI = 3.14;
const DefaultTimeout = 1000;
final URL_SCHEME = RegExp('^([a-z]+):');
class Dice {
static final NUMBER_GENERATOR = Random();
}
不使用前缀字母
因为Dart可以告诉您声明的类型、范围、可变性和其他属性,所以没有理由将这些属性编码为标识符名称。
defaultTimeout
不推荐如下写法:
kDefaultTimeout
排序
为了使你的文件前言保持整洁,我们有规定的命令,指示应该出现在其中。每个“部分”应该用空行分隔。
在其他引入之前引入所需的 dart
库
import 'dart:async';
import 'dart:html';
import 'package:bar/bar.dart';
import 'package:foo/foo.dart';
在相对引入之前先引入在包中的库
import 'package:bar/bar.dart';
import 'package:foo/foo.dart';
import 'util.dart';
第三方包的导入先于其他包
import 'package:bar/bar.dart';
import 'package:foo/foo.dart';
import 'package:my_package/util.dart';
在所有导入之后,在单独的部分中指定导出
import 'src/error.dart';
import 'src/foo_bar.dart';
export 'src/error.dart';
不推荐如下写法:
import 'src/error.dart';
export 'src/error.dart';
import 'src/foo_bar.dart';
所有流控制结构,请使用大括号
这样做可以避免悬浮的 else
问题
if (isWeekDay) {
print('Bike to work!');
} else {
print('Go dancing or read a book!');
}
例外
一个 if
语句没有 else
子句,其中整个 if
语句和 then
主体都适合一行。
在这种情况下,如果你喜欢的话,你可以去掉大括号
if (arg == null) return defaultValue;
如果流程体超出了一行需要分划请使用大括号:
if (overflowChars != other.overflowChars) {
return overflowChars < other.overflowChars;
}
不推荐如下写法:
if (overflowChars != other.overflowChars)
return overflowChars < other.overflowChars;
注释
要像句子一样格式化
除非是区分大小写的标识符,否则第一个单词要大写。以句号结尾(或“!”或“?”)。
对于所有的注释都是如此: doc
注释、内联内容,甚至 TODOs
。即使是一个句子片段。
greet(name) {
// Assume we have a valid name.
print('Hi, $name!');
}
不推荐如下写法:
greet(name) {
/* Assume we have a valid name. */
print('Hi, $name!');
}
可以使用块注释( /…/
)临时注释掉一段代码,但是所有其他注释都应该使用 //
Doc
注释
使用文档 ///
注释来记录成员和类型。
使用 doc
注释而不是常规注释,可以让 dartdoc
找到并生成文档。
/// The number of characters in this chunk when unsplit.
int get length => ...
由于历史原因,达特茅斯学院支持道格评论的两种语法: ///
(“ C#
风格”)和 /**…* /
(“ JavaDoc
风格”)。我们更喜欢 因 ///
为它更紧凑。 /*
和 /
在多行文档注释中添加两个无内容的行。在某些情况下,语法 ///
也更容易阅读,例如文档注释包含使用*标记列表项的项目符号列表。
考虑为私有 api
编写文档注释
Doc
注释并不仅仅针对库的公共 API
的外部使用者。它们还有助于理解从库的其他部分调用的私有成员
用一句话总结开始 doc
注释
以简短的、以用户为中心的描述开始你的文档注释,以句号结尾。
/// Deletes the file at [path] from the file system.
void delete(String path) { ... }
不推荐如下写法:
/// Depending on the state of the file system and the user's permissions,
/// certain operations may or may not be possible. If there is no file at
/// [path] or it can't be accessed, this function throws either [IOError]
/// or [PermissionError], respectively. Otherwise, this deletes the file.
void delete(String path) { ... }
“ doc
注释”的第一句话分隔成自己的段落
在第一个句子之后添加一个空行,把它分成自己的段落
/// Deletes the file at [path].
///
/// Throws an [IOError] if the file could not be found. Throws a
/// [PermissionError] if the file is present but could not be deleted.
void delete(String path) { ... }
Flutter_Go
使用参考
库的引用
flutter go
中,导入 lib
下文件库,统一指定包名,避免过多的 ../../
package:flutter_go/
字符串的使用
使用相邻字符串连接字符串文字
如果有两个字符串字面值(不是值,而是实际引用的字面值),则不需要使用 +
连接它们。就像在 C
和中, c++
简单地把它们放在一起就能做到。这是创建一个长字符串很好的方法但是不适用于单独一行。
raiseAlarm(
'ERROR: Parts of the spaceship are on fire. Other '
'parts are overrun by martians. Unclear which are which.'
);
不推荐如下写法:
raiseAlarm(
'ERROR: Parts of the spaceship are on fire. Other ' + 'parts are overrun by martians. Unclear which are which.'
);
优先使用模板字符串
'Hello, $name! You are ${year - birth} years old.';
####在不需要的时候,避免使用花括号
'Hi, $name!'
"Wear your wildest $decade's outfit."
不推荐如下写法:
'Hello, ' + name + '! You are ' + (year - birth).toString() + ' y...';
不推荐如下写法:
'Hi, ${name}!' "Wear your wildest ${decade}'s outfit."
集合
尽可能使用集合字面量
如果要创建一个不可增长的列表,或者其他一些自定义集合类型,那么无论如何,都要使用构造函数。
var points = [];
var addresses = {};
var lines = <Lines>[];
不推荐如下写法:
var points = List();
var addresses = Map();
不要使用.length查看集合是否为空
if (lunchBox.isEmpty) return 'so hungry...';
if (words.isNotEmpty) return words.join(' ');
不推荐如下写法:
if (lunchBox.length == 0) return 'so hungry...';
if (!words.isEmpty) return words.join(' ');
考虑使用高阶方法转换序列
如果有一个集合,并且希望从中生成一个新的修改后的集合,那么使用.map()
、.where()
和Iterable
上的其他方便的方法通常更短,也更具有声明性
var aquaticNames = animals .where((animal) => animal.isAquatic) .map((animal) => animal.name);
避免使用带有函数字面量的Iterable.forEach()
在Dart
中,如果你想遍历一个序列,惯用的方法是使用循环。
for (var person in people) { ... }
不推荐如下写法:
people.forEach((person) { ... });
不要使用List.from()
,除非打算更改结果的类型
给定一个迭代,有两种明显的方法可以生成包含相同元素的新列表
var copy1 = iterable.toList();
var copy2 = List.from(iterable);
明显的区别是第一个比较短。重要的区别是第一个保留了原始对象的类型参数
// Creates a List<int>:
var iterable = [1, 2, 3];
// Prints "List<int>":
print(iterable.toList().runtimeType);
// Creates a List<int>:
var iterable = [1, 2, 3];
// Prints "List<dynamic>":
print(List.from(iterable).runtimeType);
参数的使用
使用=
将命名参数与其默认值分割开
由于遗留原因,Dart
均允许:
和=
作为指定参数的默认值分隔符。为了与可选的位置参数保持一致,使用=
。
void insert(Object item, {int at = 0}) { ... }
不推荐如下写法:
void insert(Object item, {int at: 0}) { ... }
不要使用显式默认值null
如果参数是可选的,但没有给它一个默认值,则语言隐式地使用null
作为默认值,因此不需要编写它
void error([String message]) {
stderr.write(message ?? '\n');
}
不推荐如下写法:
void error([String message = null]) {
stderr.write(message ?? '\n');
}
变量
不要显式地将变量初始化为空
在Dart
中,未显式初始化的变量或字段自动被初始化为null
。不要多余赋值null
int _nextId;
class LazyId {
int _id;
int get id {
if (_nextId == null) _nextId = 0;
if (_id == null) _id = _nextId++;
return _id;
}
}
不推荐如下写法:
int _nextId = null;
class LazyId {
int _id = null;
int get id {
if (_nextId == null) _nextId = 0;
if (_id == null) _id = _nextId++;
return _id;
}
}
避免储存你能计算的东西
在设计类时,您通常希望将多个视图公开到相同的底层状态。通常你会看到在构造函数中计算所有视图的代码,然后存储它们:
应该避免的写法:
class Circle {
num radius;
num area;
num circumference;
Circle(num radius)
: radius = radius,
area = pi * radius * radius,
circumference = pi * 2.0 * radius;
}
如上代码问题:
- 浪费内存
- 缓存的问题是无效——如何知道何时缓存过期需要重新计算?
推荐的写法如下:
class Circle {
num radius;
Circle(this.radius);
num get area => pi * radius * radius;
num get circumference => pi * 2.0 * radius;
}
类成员
不要把不必要地将字段包装在getter
和setter
中
不推荐如下写法:
class Box {
var _contents;
get contents => _contents;
set contents(value) {
_contents = value;
}
}
优先使用final
字段来创建只读属性
尤其对于 StatelessWidget
在不需要的时候不要用this
不推荐如下写法:
class Box {
var value;
void clear() {
this.update(null);
}
void update(value) {
this.value = value;
}
}
推荐如下写法:
class Box {
var value;
void clear() {
update(null);
}
void update(value) {
this.value = value;
}
}
构造函数
尽可能使用初始化的形式
不推荐如下写法:
class Point {
num x, y;
Point(num x, num y) {
this.x = x;
this.y = y;
}
}
推荐如下写法:
class Point {
num x, y;
Point(this.x, this.y);
}
不要使用new
Dart2
使new
关键字可选
推荐写法:
Widget build(BuildContext context) {
return Row(
children: [
RaisedButton(
child: Text('Increment'),
),
Text('Click!'),
],
);
}
不推荐如下写法:
Widget build(BuildContext context) {
return new Row(
children: [
new RaisedButton(
child: Text('Increment'),
),
new Text('Click!'),
],
);
}
异步
优先使用async/await
代替原始的futures
async/await
语法提高了可读性,允许你在异步代码中使用所有Dart
控制流结构。
Future<int> countActivePlayers(String teamName) async {
try {
var team = await downloadTeam(teamName);
if (team == null) return 0;
var players = await team.roster;
return players.where((player) => player.isActive).length;
} catch (e) {
log.error(e);
return 0;
}
}
当异步没有任何用处时,不要使用它
如果可以在不改变函数行为的情况下省略异步,那么就这样做。
Future afterTwoThings(Future first, Future second) {
return Future.wait([first, second]);
}
不推荐写法:
Future afterTwoThings(Future first, Future second) async {
return Future.wait([first, second]);
}
转载自:https://juejin.cn/post/7241399184594731064