From 80261f376b427fa477c35113fbc8c040fa94e599 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=20v?= Date: Thu, 17 Aug 2023 10:35:04 +0800 Subject: [PATCH] perf: add dart doc (#483) * perf: add dart doc * perf: add dart doc * fix: issue #482 --- lib/src/components/appraise/brn_appraise.dart | 2 +- .../appraise/brn_flutter_gif_image.dart | 1 - .../brn_progress_bar_chart.dart | 2 +- .../charts/broken_line/brn_line_painter.dart | 18 ++++++++---- .../broken_line/brn_line_y_painter.dart | 1 + .../components/dialog/brn_share_dialog.dart | 1 - .../components/dialog/brn_single_select.dart | 2 -- .../items/general/brn_radio_input_item.dart | 1 - .../gallery/page/brn_gallery_detail_page.dart | 2 +- lib/src/components/guide/brn_tip_widget.dart | 24 +++++++++++++-- .../noticebar/brn_marquee_text.dart | 4 +-- .../picker/base/brn_picker_title.dart | 1 - .../brn_multi_column_picker.dart | 2 +- .../brn_multi_select_data.dart | 10 +++++-- .../date_picker/brn_time_widget.dart | 1 + .../brn_time_range_side_widget.dart | 1 - .../components/popup/brn_measure_size.dart | 3 +- .../components/popup/brn_overlay_window.dart | 3 ++ .../components/rating/brn_rating_star.dart | 1 + .../scroll_anchor/brn_scroll_anchor_tab.dart | 29 ++++++++++++------- .../selectcity/brn_base_azlistview_page.dart | 19 ++++++------ .../selectcity/brn_select_city_model.dart | 2 ++ .../bean/brn_selection_common_entity.dart | 25 ++++++++++++++++ .../selection/brn_flat_selection.dart | 1 - .../selection/brn_selection_util.dart | 3 +- .../selection/brn_selection_view.dart | 1 + .../selection/brn_simple_selection.dart | 1 + .../brn_flat_selection_controller.dart | 4 ++- .../brn_selection_view_controller.dart | 25 ++++++++++++++-- ...selection_view_date_picker_controller.dart | 7 ++++- .../converter/brn_selection_converter.dart | 6 ++++ .../widget/brn_layer_more_selection_page.dart | 6 ++-- .../widget/brn_selection_animate_widget.dart | 7 +++++ .../brn_selection_common_item_widget.dart | 20 +++++++++++++ .../brn_selection_date_range_item_widget.dart | 9 ++++++ ...n_selection_datepicker_animate_widget.dart | 7 +++++ .../widget/brn_selection_list_widget.dart | 13 +++++++++ .../brn_selection_menu_item_widget.dart | 10 +++++++ .../widget/brn_selection_menu_widget.dart | 12 ++++++++ ...brn_selection_range_input_item_widget.dart | 9 ++++++ .../brn_selection_range_tag_widget.dart | 17 +++++++++-- .../widget/brn_selection_range_widget.dart | 21 +++++++++++--- .../brn_selection_single_list_widget.dart | 17 +++++++++++ .../switch/brn_switch_button_base.dart | 4 +++ .../components/tabbar/normal/brn_tab_bar.dart | 22 +++++++------- .../tabbar/normal/brn_tabbar_controller.dart | 6 ++++ lib/src/components/tag/brn_state_tag.dart | 5 +++- .../tag/tagview/brn_delete_tag.dart | 4 +-- .../tag/tagview/brn_select_tag.dart | 2 +- lib/src/utils/brn_multi_click_util.dart | 4 +++ lib/src/utils/brn_rich_text.dart | 24 ++++++++++----- lib/src/utils/brn_text_util.dart | 1 + lib/src/utils/brn_tools.dart | 24 +++++++-------- lib/src/utils/css/brn_core_funtion.dart | 6 +++- 54 files changed, 354 insertions(+), 99 deletions(-) diff --git a/lib/src/components/appraise/brn_appraise.dart b/lib/src/components/appraise/brn_appraise.dart index 2fe209b4..81730803 100644 --- a/lib/src/components/appraise/brn_appraise.dart +++ b/lib/src/components/appraise/brn_appraise.dart @@ -225,7 +225,7 @@ class _BrnAppraiseState extends State { Widget _confirmButton() { if (widget.config.showConfirmButton) { return Padding( - padding: EdgeInsets.symmetric(horizontal: 16), + padding: EdgeInsets.symmetric(vertical: 16), child: BrnBigMainButton( title: widget.config.confirmButtonText ?? BrnIntl.of(context).localizedResource.submit, isEnable: _enable ?? _appraiseIndex != -1, diff --git a/lib/src/components/appraise/brn_flutter_gif_image.dart b/lib/src/components/appraise/brn_flutter_gif_image.dart index cc83efe4..757825ca 100644 --- a/lib/src/components/appraise/brn_flutter_gif_image.dart +++ b/lib/src/components/appraise/brn_flutter_gif_image.dart @@ -8,7 +8,6 @@ import 'package:flutter/widgets.dart'; /// 参考来自github：https://github.com/peng8350/flutter_gifimage /// 感谢 Jpeng class GifImage extends StatefulWidget { - /// final VoidCallback? onFetchCompleted; final AnimationController controller; final ImageProvider image; diff --git a/lib/src/components/charts/brn_progress_bar_chart/brn_progress_bar_chart.dart b/lib/src/components/charts/brn_progress_bar_chart/brn_progress_bar_chart.dart index 8b5275f4..1ff4caaa 100644 --- a/lib/src/components/charts/brn_progress_bar_chart/brn_progress_bar_chart.dart +++ b/lib/src/components/charts/brn_progress_bar_chart/brn_progress_bar_chart.dart @@ -4,7 +4,7 @@ import 'package:flutter/material.dart'; /// BrnProgressBarChart /// 柱形数据图表 /// 展示一组或者多组数据，方便数据的查看以及对比 -/// ignore: must_be_immutable +// ignore: must_be_immutable class BrnProgressBarChart extends StatefulWidget { /// 图表最小宽度，默认0 final double minWidth; diff --git a/lib/src/components/charts/broken_line/brn_line_painter.dart b/lib/src/components/charts/broken_line/brn_line_painter.dart index e680f2f9..bdf07306 100644 --- a/lib/src/components/charts/broken_line/brn_line_painter.dart +++ b/lib/src/components/charts/broken_line/brn_line_painter.dart @@ -7,6 +7,7 @@ import 'package:bruno/src/theme/brn_theme_configurator.dart'; import 'package:flutter/material.dart'; import 'package:path_drawing/path_drawing.dart'; +/// 折线图 刻度线、X/Y 轴绘制类 class BrnLinePainter extends BrnBasePainter { final int lineSelectIndex; final int pointSelectIndex; @@ -47,10 +48,13 @@ class BrnLinePainter extends BrnBasePainter { /// 绘制线条的参数内容 List lines; + /// 是否展示 X、Y 轴刻度文本 bool isShowXText, isShowYText; + /// 是否展示 X轴刻度 final bool isShowXDial; + /// 是否展示选中点对应的 X、Y 辅助虚线 final bool showPointDashLine; /// 默认的边距 @@ -111,10 +115,12 @@ class BrnLinePainter extends BrnBasePainter { assert(yDialMax > yDialMin, "yDialMax 应该大于 yDialMin"); } + /// 返回选中的点 Point selectedPoint(int lineIndex, int pointIndex) { return _linePointPositions[lineIndex][pointIndex]; } + /// 根据点击的位置和 point 的 index，遍历寻找出所属的 Line int lineIndexCompute(Offset offset, int pointIndex) { int index = -1; double margin = 15; @@ -540,7 +546,7 @@ class BrnLinePainter extends BrnBasePainter { style: item.points[i].pointTextStyle), textDirection: TextDirection.ltr) ..layout(); - double adjustOffset = isAdjustPosition(lineIndex, + double adjustOffset = _isAdjustPosition(lineIndex, _linePointPositions[lineIndex][i], _linePointPositions) ? (20 - tpX.height) : -20; @@ -559,9 +565,10 @@ class BrnLinePainter extends BrnBasePainter { } } - bool isAdjustPosition( + /// 是否需要调整位置 + bool _isAdjustPosition( int lineIndex, Point currentPoint, List>> lines) { - List> sameXPoints = getSameXValuePoints(currentPoint, lines); + List> sameXPoints = _getSameXValuePoints(currentPoint, lines); if (sameXPoints.isNotEmpty) { if (currentPoint.distanceTo(sameXPoints[0]) == 0) { return lineIndex > 0; @@ -572,7 +579,8 @@ class BrnLinePainter extends BrnBasePainter { return false; } - List> getSameXValuePoints( + /// 获取相同x值的点 + List> _getSameXValuePoints( Point currentPoint, List>> lines) { List> sameXPoints = []; for (int lineIndex = 0; lineIndex < lines.length; lineIndex++) { @@ -588,7 +596,7 @@ class BrnLinePainter extends BrnBasePainter { } } -//绘制图表的计算之后的结果模型集 +/// 绘制图表的计算之后的结果模型集 class LineCanvasModel { final List paths; final Color pathColor; diff --git a/lib/src/components/charts/broken_line/brn_line_y_painter.dart b/lib/src/components/charts/broken_line/brn_line_y_painter.dart index 712d2c87..ebc85c0d 100644 --- a/lib/src/components/charts/broken_line/brn_line_y_painter.dart +++ b/lib/src/components/charts/broken_line/brn_line_y_painter.dart @@ -48,6 +48,7 @@ class BrnLineYPainter extends BrnBasePainter { /// 绘制线条的参数内容 List lines; + /// 是否展示 X、Y 轴刻度文本 bool isShowXDialText, isShowYDialText; double? selectX; diff --git a/lib/src/components/dialog/brn_share_dialog.dart b/lib/src/components/dialog/brn_share_dialog.dart index 1ca9ba1e..87d25c31 100644 --- a/lib/src/components/dialog/brn_share_dialog.dart +++ b/lib/src/components/dialog/brn_share_dialog.dart @@ -27,7 +27,6 @@ typedef BrnShareDialogGetCustomShareItemIcon = Widget? Function(int index); /// 可自定义分享弹框标题文案 /// 可自定义分享弹框辅助信息 /// 可自定义文案和分享渠道中间的分割线内文案 -/// // ignore: must_be_immutable class BrnShareDialog extends StatelessWidget { final BuildContext context; diff --git a/lib/src/components/dialog/brn_single_select.dart b/lib/src/components/dialog/brn_single_select.dart index 7882c580..3a4b549e 100644 --- a/lib/src/components/dialog/brn_single_select.dart +++ b/lib/src/components/dialog/brn_single_select.dart @@ -94,9 +94,7 @@ class BrnSingleSelectDialog extends Dialog { } } -/// /// 单选列表弹框 widget -/// // ignore: must_be_immutable class BrnSingleSelectDialogWidget extends StatefulWidget { final bool isClose; diff --git a/lib/src/components/form/items/general/brn_radio_input_item.dart b/lib/src/components/form/items/general/brn_radio_input_item.dart index 3cec458e..5d22c767 100644 --- a/lib/src/components/form/items/general/brn_radio_input_item.dart +++ b/lib/src/components/form/items/general/brn_radio_input_item.dart @@ -14,7 +14,6 @@ import 'package:flutter/material.dart'; /// 包括"标题"、"副标题"、"错误信息提示"、"必填项提示"、"添加/删除按钮"、"消息提示"、 /// "单选项"等元素 /// - // ignore: must_be_immutable class BrnRadioInputFormItem extends StatefulWidget { /// 录入项的唯一标识，主要用于录入类型页面框架中 diff --git a/lib/src/components/gallery/page/brn_gallery_detail_page.dart b/lib/src/components/gallery/page/brn_gallery_detail_page.dart index f7999967..2b73feec 100644 --- a/lib/src/components/gallery/page/brn_gallery_detail_page.dart +++ b/lib/src/components/gallery/page/brn_gallery_detail_page.dart @@ -17,7 +17,7 @@ import 'package:flutter/material.dart'; /// 组件提供了（列表页<-->详情页）这种交互模式的骨架， /// 适用于查看图片，视频 PDF 等场景。 /// 默认只实现了图片的查看，如果想要扩展视频或者pdf自行扩展配置接口可实现。 -/// ignore: must_be_immutable +// ignore: must_be_immutable class BrnGalleryDetailPage extends StatefulWidget { /// 该交互下所有 item 的配置集合 final List allConfig; diff --git a/lib/src/components/guide/brn_tip_widget.dart b/lib/src/components/guide/brn_tip_widget.dart index 58b84d71..f1d69d3f 100644 --- a/lib/src/components/guide/brn_tip_widget.dart +++ b/lib/src/components/guide/brn_tip_widget.dart @@ -6,26 +6,46 @@ import 'package:bruno/src/theme/brn_theme_configurator.dart'; import 'package:bruno/src/utils/brn_tools.dart'; import 'package:flutter/material.dart'; +/// 引导组件试，[force] 有蒙层遮挡，[soft] 无蒙层遮挡 enum GuideMode { force, soft } /// 默认的引导组件包含，强和弱两种交互模式 class BrnTipInfoWidget extends StatelessWidget { + + /// 引导组件的方向 final GuideDirection direction; + + /// 关闭按钮的回调 final void Function()? onClose; + + /// 下一步按钮的回调 final void Function()? onNext; + + /// 跳过按钮的回调 final void Function()? onSkip; + /// 引导组件的宽度 final double width; + + /// 引导组件的高度 final double? height; + + /// 引导组件的内容 final BrnTipInfoBean info; + + /// 引导模式 final GuideMode mode; - /// Which guide page is currently displayed, starting from 0 + /// 当前的引导步数 final int currentStepIndex; - /// Total number of guide pages + /// 引导步数 final int stepCount; + + /// 箭头距离指示的边距 final double? arrowPadding; + + /// 【下一步】的文案 final String? nextTip; const BrnTipInfoWidget( diff --git a/lib/src/components/noticebar/brn_marquee_text.dart b/lib/src/components/noticebar/brn_marquee_text.dart index 758830ff..dcb35c1a 100644 --- a/lib/src/components/noticebar/brn_marquee_text.dart +++ b/lib/src/components/noticebar/brn_marquee_text.dart @@ -22,9 +22,7 @@ class BrnMarqueeText extends StatefulWidget { final int timerRest; /// 尽量设置宽高，自动算宽|高受布局影响较大 - double width; - - double height; + double width, height; BrnMarqueeText({ required this.text, diff --git a/lib/src/components/picker/base/brn_picker_title.dart b/lib/src/components/picker/base/brn_picker_title.dart index 787457b8..fe7e3520 100755 --- a/lib/src/components/picker/base/brn_picker_title.dart +++ b/lib/src/components/picker/base/brn_picker_title.dart @@ -7,7 +7,6 @@ import 'package:bruno/src/theme/brn_theme.dart'; import 'package:flutter/material.dart'; /// DatePicker's title widget. - // ignore: must_be_immutable class BrnPickerTitle extends StatelessWidget { final BrnPickerTitleConfig pickerTitleConfig; diff --git a/lib/src/components/picker/multi_range_picker/brn_multi_column_picker.dart b/lib/src/components/picker/multi_range_picker/brn_multi_column_picker.dart index 2e0b11a6..c6298ad6 100644 --- a/lib/src/components/picker/multi_range_picker/brn_multi_column_picker.dart +++ b/lib/src/components/picker/multi_range_picker/brn_multi_column_picker.dart @@ -29,7 +29,7 @@ typedef BrnOnPickerConfirm = void Function(Map> re /// 从屏幕下方弹起的多级筛选选择器 /// 可设置筛项的层级、多选、单选等筛选相关功能 -/// ignore: must_be_immutable +// ignore: must_be_immutable class BrnMultiColumnPicker extends StatefulWidget { /// 筛选数据源 final BrnPickerEntity entity; diff --git a/lib/src/components/picker/multi_select_bottom_picker/brn_multi_select_data.dart b/lib/src/components/picker/multi_select_bottom_picker/brn_multi_select_data.dart index 6748fa66..d159b6b3 100644 --- a/lib/src/components/picker/multi_select_bottom_picker/brn_multi_select_data.dart +++ b/lib/src/components/picker/multi_select_bottom_picker/brn_multi_select_data.dart @@ -1,9 +1,13 @@ +/// 底部多选 Picker 数据类 class BrnMultiSelectBottomPickerItem { - String code; //选项编号 + /// 选项编号 + String code; - String content; //选项内容 + /// 选项内容 + String content; - bool isChecked; //是否选中 + /// 是否选中 + bool isChecked; BrnMultiSelectBottomPickerItem(this.code, this.content, {this.isChecked = false}); diff --git a/lib/src/components/picker/time_picker/date_picker/brn_time_widget.dart b/lib/src/components/picker/time_picker/date_picker/brn_time_widget.dart index f7eee310..081662d9 100755 --- a/lib/src/components/picker/time_picker/date_picker/brn_time_widget.dart +++ b/lib/src/components/picker/time_picker/date_picker/brn_time_widget.dart @@ -12,6 +12,7 @@ import 'package:flutter/material.dart'; enum ColumnType { hour, minute, second } +/// BrnTimeWidget widget. Can display time picker // ignore: must_be_immutable class BrnTimeWidget extends StatefulWidget { BrnTimeWidget({ diff --git a/lib/src/components/picker/time_picker/date_range_picker/brn_time_range_side_widget.dart b/lib/src/components/picker/time_picker/date_range_picker/brn_time_range_side_widget.dart index fc276d99..563109ef 100755 --- a/lib/src/components/picker/time_picker/date_range_picker/brn_time_range_side_widget.dart +++ b/lib/src/components/picker/time_picker/date_range_picker/brn_time_range_side_widget.dart @@ -7,7 +7,6 @@ import 'package:bruno/src/theme/brn_theme.dart'; import 'package:flutter/material.dart'; /// TimeRangeSidePicker widget. - // ignore: must_be_immutable class BrnTimeRangeSideWidget extends StatefulWidget { /// 可选最小时间 diff --git a/lib/src/components/popup/brn_measure_size.dart b/lib/src/components/popup/brn_measure_size.dart index e154fc71..45d4dd90 100644 --- a/lib/src/components/popup/brn_measure_size.dart +++ b/lib/src/components/popup/brn_measure_size.dart @@ -4,7 +4,7 @@ import 'package:flutter/rendering.dart'; typedef OnWidgetSizeChange = void Function(Size size); -/// 描述: 计算 Widget 宽高的工具类。 +/// 监听 Widget 宽高的工具类。 class MeasureSizeRenderObject extends RenderProxyBox { Size? oldSize; final OnWidgetSizeChange onChange; @@ -29,6 +29,7 @@ class MeasureSizeRenderObject extends RenderProxyBox { } } +/// 监听 Widget 宽高变化的工具类 class MeasureSize extends SingleChildRenderObjectWidget { final OnWidgetSizeChange onChange; diff --git a/lib/src/components/popup/brn_overlay_window.dart b/lib/src/components/popup/brn_overlay_window.dart index 3ef39de2..c5705d18 100644 --- a/lib/src/components/popup/brn_overlay_window.dart +++ b/lib/src/components/popup/brn_overlay_window.dart @@ -236,6 +236,7 @@ class _BrnOverlayWindowState extends State { } } +/// [OverlayWindow] 组件展示隐藏控制器 class BrnOverlayController { OverlayEntry? _entry; @@ -246,6 +247,7 @@ class BrnOverlayController { BrnOverlayController._(this.context, this._entry); + /// 显示OverlayWindow showOverlay() { if (_entry != null) { Overlay.of(context).insert(_entry!); @@ -253,6 +255,7 @@ class BrnOverlayController { } } + /// 移除OverlayWindow void removeOverlay() { _entry?.remove(); _entry = null; diff --git a/lib/src/components/rating/brn_rating_star.dart b/lib/src/components/rating/brn_rating_star.dart index 605121f4..fcdf0f25 100644 --- a/lib/src/components/rating/brn_rating_star.dart +++ b/lib/src/components/rating/brn_rating_star.dart @@ -6,6 +6,7 @@ import 'package:flutter/material.dart'; /// state，[RatingState] 星星状态 typedef BrnRatingStarBuilder = Widget Function(RatingState state); +/// 星星状态 enum RatingState { /// 半颗 half, diff --git a/lib/src/components/scroll_anchor/brn_scroll_anchor_tab.dart b/lib/src/components/scroll_anchor/brn_scroll_anchor_tab.dart index 37e370b0..cffcb6c0 100644 --- a/lib/src/components/scroll_anchor/brn_scroll_anchor_tab.dart +++ b/lib/src/components/scroll_anchor/brn_scroll_anchor_tab.dart @@ -10,14 +10,21 @@ typedef AnchorTabWidgetIndexedBuilder = Widget Function(BuildContext context, in /// 构建指定索引的Tab typedef AnchorTabIndexedBuilder = BadgeTab Function(BuildContext context, int index); +/// 滑动锚点组件 class BrnAnchorTab extends StatefulWidget { - // TabBar的样式 + /// TabBar的样式 final BrnAnchorTabBarStyle tabBarStyle; + + /// 构建指定索引的Widget final AnchorTabWidgetIndexedBuilder? widgetIndexedBuilder; + + /// 构建指定索引的Tab final AnchorTabIndexedBuilder tabIndexedBuilder; + + /// Tab与内容之间的分割线 final Widget? tabDivider; - //设置tab与widget的个数 + /// 设置tab与widget的个数 final int itemCount; BrnAnchorTab( @@ -33,28 +40,28 @@ class BrnAnchorTab extends StatefulWidget { class _BrnScrollAnchorTabWidgetState extends State with SingleTickerProviderStateMixin { - //用于控制 滑动 + /// 用于控制 滑动 late ScrollController _scrollController; - //用于控制tab + /// 用于控制tab late TabController _tabController; - //滑动组件的 key + /// 滑动组件的 key late GlobalKey _key; - //当前选中的索引 + /// 当前选中的索引 int currentIndex = 0; - //滑动组件的元素的key + /// 滑动组件的元素的key late List _bodyKeyList; - //每个元素在滑动组件中的位置 + /// 每个元素在滑动组件中的位置 late List _cardOffsetList; - //是否点击滑动 + /// 是否点击滑动 bool tab = false; - //滑动组件在屏幕的位置 + /// 滑动组件在屏幕的位置 double listDy = 0; @override @@ -207,7 +214,7 @@ class _BrnScrollAnchorTabWidgetState extends State } } - //根据偏移量 确定tab索引 + /// 根据偏移量 确定tab索引 int createIndex(double offset) { int index = widget.itemCount - 1; for (int i = 0; i < widget.itemCount - 1; i++) { diff --git a/lib/src/components/selectcity/brn_base_azlistview_page.dart b/lib/src/components/selectcity/brn_base_azlistview_page.dart index 03d23313..b38a72bd 100644 --- a/lib/src/components/selectcity/brn_base_azlistview_page.dart +++ b/lib/src/components/selectcity/brn_base_azlistview_page.dart @@ -7,37 +7,38 @@ import 'package:bruno/src/components/selectcity/brn_az_listview.dart'; import 'package:flutter/material.dart'; import 'package:lpinyin/lpinyin.dart'; -//带右侧定位器的list页面 +/// 带右侧定位器的list页面 abstract class BaseAZListViewPage extends StatefulWidget { @override _BaseAZListViewPageState createState() => _BaseAZListViewPageState(); - //设置页面的title + /// 设置页面的title PreferredSizeWidget createAppBar(); - //设置页面的数据源 + /// 设置页面的数据源 Future createFuture(); - //从数据源中提取列表 + /// 从数据源中提取列表 List pickListFromData(data); - //列表的widget + /// 列表的widget Widget buildItemWidget(ISuspensionBean item); - //悬浮的widget + /// 悬浮的widget Widget buildSuspensionWidget(String? tag); + /// 顶部展示的数据 List getTopData() { return []; } - //item的高度 默认50 + /// item的高度 默认50 double getItemHeight() => 50.0; - //悬浮的条目的高度 + /// 悬浮的条目的高度 double getSuspensionHeight() => 46.0; - //每个modal 对应的 tag，默认是拼音来设置 + /// 每个modal 对应的 tag，默认是拼音来设置 String createTagByModal(ISuspensionBean bean) { if (bean.name.isNotEmpty) { String pinyin = PinyinHelper.getPinyinE(bean.name); diff --git a/lib/src/components/selectcity/brn_select_city_model.dart b/lib/src/components/selectcity/brn_select_city_model.dart index d80b5ebc..8a40e95b 100644 --- a/lib/src/components/selectcity/brn_select_city_model.dart +++ b/lib/src/components/selectcity/brn_select_city_model.dart @@ -1,5 +1,6 @@ import 'package:bruno/src/components/selectcity/brn_az_common.dart'; +/// 城市选择数据类 class BrnSelectCityModel extends ISuspensionBean { /// 城市名称 @@ -11,6 +12,7 @@ class BrnSelectCityModel extends ISuspensionBean { /// 拼音 String? namePinyin; + /// 城市 name 对应的锚点 tag String tag = ""; /// 城市编码 diff --git a/lib/src/components/selection/bean/brn_selection_common_entity.dart b/lib/src/components/selection/bean/brn_selection_common_entity.dart index 1b71d5ac..403a81f2 100644 --- a/lib/src/components/selection/bean/brn_selection_common_entity.dart +++ b/lib/src/components/selection/bean/brn_selection_common_entity.dart @@ -3,6 +3,7 @@ import 'package:bruno/src/components/selection/brn_selection_util.dart'; import 'package:bruno/src/constants/brn_constants.dart'; import 'package:bruno/src/utils/brn_tools.dart'; +/// 筛选组件支持的筛选类型 enum BrnSelectionFilterType { /// 未设置 none, @@ -50,6 +51,7 @@ enum BrnSelectionWindowType { range, } +/// 筛选组件使用的数据结构 class BrnSelectionEntity { /// 类型 是单选、复选还是有自定义输入 String? type; @@ -258,6 +260,7 @@ class BrnSelectionEntity { } } + /// 根据 [showType] 解析出对应的 [BrnSelectionWindowType]， 默认为 [BrnSelectionWindowType.list] BrnSelectionWindowType parserShowType(String? showType) { if (showType == "list") { return BrnSelectionWindowType.list; @@ -267,6 +270,7 @@ class BrnSelectionEntity { return BrnSelectionWindowType.list; } + /// 根据 [type] 解析出对应的 [BrnSelectionFilterType], 默认为 [BrnSelectionFilterType.none] BrnSelectionFilterType parserFilterTypeWithType(String? type) { if (type == 'unlimit') { return BrnSelectionFilterType.unLimit; @@ -294,6 +298,7 @@ class BrnSelectionEntity { return BrnSelectionFilterType.none; } + /// 清空子节点的选中状态 void clearChildSelection() { if (children.isNotEmpty) { for (BrnSelectionEntity entity in children) { @@ -311,6 +316,7 @@ class BrnSelectionEntity { } } + /// 获取当前节点的所有选中的子节点 List selectedLastColumnList() { List list = []; if (this.children.isNotEmpty) { @@ -341,6 +347,7 @@ class BrnSelectionEntity { return list; } + /// 获取当前节点的所有选中的子节点, 不包含【不限】节点 List selectedListWithoutUnlimit() { List selected = selectedList(); return selected @@ -360,6 +367,7 @@ class BrnSelectionEntity { .toList(); } + /// 获取当前节点的所有选中的子节点，支持 more 类型 List selectedList() { if (BrnSelectionFilterType.more == this.filterType) { return this.selectedLastColumnList(); @@ -386,6 +394,7 @@ class BrnSelectionEntity { } } + /// 获取当前节点的所有选中的子节点 List allSelectedList() { List results = []; List firstColumn = @@ -408,14 +417,17 @@ class BrnSelectionEntity { return results; } + /// 获取当前节点对应根节点，返回根节点最后一级选中的子节点的数量 int getLimitedRootSelectedChildCount() { return getSelectedChildCount(getRootEntity(this)); } + /// 获取当前节点对应根节点，可选择的最大选中数量 int getLimitedRootMaxSelectedCount() { return getRootEntity(this).maxSelectedCount; } + /// 获取当前节点对应根节点 BrnSelectionEntity getRootEntity(BrnSelectionEntity rootEntity) { if (rootEntity.parent == null || rootEntity.parent!.maxSelectedCount == @@ -477,6 +489,7 @@ class BrnSelectionEntity { return filterType == BrnSelectionFilterType.unLimit; } + /// 递归清空选中状态 void clearSelectedEntity() { List tmp = []; BrnSelectionEntity node = this; @@ -490,6 +503,10 @@ class BrnSelectionEntity { } } + /// 返回当前节点所有不是以下类型的子节点 + /// [BrnSelectionFilterType.range] + /// [BrnSelectionFilterType.dateRange] + /// [BrnSelectionFilterType.dateRangeCalendar] List currentTagListForEntity() { List list = []; children.forEach((data) { @@ -502,6 +519,7 @@ class BrnSelectionEntity { return list; } + /// 根据是否展开，返回对应数量的子节点 List currentShowTagByExpanded(bool isExpanded) { List all = currentTagListForEntity(); return isExpanded ? all : all.sublist(0, currentDefaultTagCountForEntity()); @@ -528,6 +546,10 @@ class BrnSelectionEntity { return defaultShowCount; } + /// 返回当前节点下所有以下类型的子节点 + /// [BrnSelectionFilterType.range] + /// [BrnSelectionFilterType.dateRange] + /// [BrnSelectionFilterType.dateRangeCalendar] List currentRangeListForEntity() { List list = []; children.forEach((data) { @@ -540,6 +562,7 @@ class BrnSelectionEntity { return list; } + /// 校验 range 类型的数据是否合法 bool isValidRange() { if (this.filterType == BrnSelectionFilterType.range || this.filterType == BrnSelectionFilterType.dateRange || @@ -583,10 +606,12 @@ class BrnSelectionEntity { return true; } + /// 反选 void reverseSelected() { this.isSelected = !isSelected; } + /// 获取第一个选中的子节点的下标 int getFirstSelectedChildIndex() { return children.indexWhere((data) { return data.isSelected; diff --git a/lib/src/components/selection/brn_flat_selection.dart b/lib/src/components/selection/brn_flat_selection.dart index 0721a30d..8f06e6c8 100644 --- a/lib/src/components/selection/brn_flat_selection.dart +++ b/lib/src/components/selection/brn_flat_selection.dart @@ -15,7 +15,6 @@ import 'package:flutter/material.dart'; /// 支持tag 、输入 、range、选择等类型混合一级筛选 /// 也可支持点击选项跳转二级页面 - // ignore: must_be_immutable class BrnFlatSelection extends StatefulWidget { /// 筛选原始数据 diff --git a/lib/src/components/selection/brn_selection_util.dart b/lib/src/components/selection/brn_selection_util.dart index ae759f18..d3cc19c1 100644 --- a/lib/src/components/selection/brn_selection_util.dart +++ b/lib/src/components/selection/brn_selection_util.dart @@ -5,6 +5,7 @@ const double DESIGN_SELECTION_HEIGHT = 268; const double DESIGN_BOTTOM_HEIGHT = 82; const double DESIGN_SCREEN_HEIGHT = 812; +/// 筛选组件工具类 class BrnSelectionUtil { /// 处理兄弟结点为未选中状态，将自己置为选中状态 static void processBrotherItemSelectStatus( @@ -137,7 +138,7 @@ class BrnSelectionUtil { entity.getLimitedRootMaxSelectedCount(); } -//设置数据为未选中状态 + /// 设置数据为未选中状态 static void resetSelectionDatas(BrnSelectionEntity entity) { entity.isSelected = false; entity.customMap = Map(); diff --git a/lib/src/components/selection/brn_selection_view.dart b/lib/src/components/selection/brn_selection_view.dart index 905e71f0..7764067b 100644 --- a/lib/src/components/selection/brn_selection_view.dart +++ b/lib/src/components/selection/brn_selection_view.dart @@ -80,6 +80,7 @@ typedef OnDefaultParamsPrepared = void Function( const BrnSelectionConverterDelegate _defaultConverter = const DefaultSelectionConverter(); +/// 筛选组件 // ignore: must_be_immutable class BrnSelectionView extends StatefulWidget { final BrnSelectionConverterDelegate selectionConverterDelegate; diff --git a/lib/src/components/selection/brn_simple_selection.dart b/lib/src/components/selection/brn_simple_selection.dart index 79ecbd97..39670aaa 100644 --- a/lib/src/components/selection/brn_simple_selection.dart +++ b/lib/src/components/selection/brn_simple_selection.dart @@ -10,6 +10,7 @@ typedef BrnSimpleSelectionOnSelectionChanged = void Function( const String _defaultMenuKey = "defaultMenuKey"; +/// 简单筛选，基于 BrnSelectionView 实现 // ignore: must_be_immutable class BrnSimpleSelection extends StatefulWidget { /// 标题文案 diff --git a/lib/src/components/selection/controller/brn_flat_selection_controller.dart b/lib/src/components/selection/controller/brn_flat_selection_controller.dart index 522c3eb1..d6621924 100644 --- a/lib/src/components/selection/controller/brn_flat_selection_controller.dart +++ b/lib/src/components/selection/controller/brn_flat_selection_controller.dart @@ -1,12 +1,12 @@ import 'package:flutter/material.dart'; /// 区间+输入混合一级筛选Controller - class BrnFlatSelectionController extends ChangeNotifier { bool isResetSelectedOptions = false; bool isCancelSelectedOptions = false; bool isConfirmSelectedOptions = false; + /// 控制重置点击事件 void resetSelectedOptions() { isResetSelectedOptions = true; isCancelSelectedOptions = false; @@ -14,6 +14,7 @@ class BrnFlatSelectionController extends ChangeNotifier { notifyListeners(); } + /// 控制取消点击事件 void cancelSelectedOptions() { isResetSelectedOptions = false; isCancelSelectedOptions = true; @@ -21,6 +22,7 @@ class BrnFlatSelectionController extends ChangeNotifier { notifyListeners(); } + /// 控制确认点击事件 void confirmSelectedOptions() { isResetSelectedOptions = false; isCancelSelectedOptions = false; diff --git a/lib/src/components/selection/controller/brn_selection_view_controller.dart b/lib/src/components/selection/controller/brn_selection_view_controller.dart index 1da1450c..c14cca90 100644 --- a/lib/src/components/selection/controller/brn_selection_view_controller.dart +++ b/lib/src/components/selection/controller/brn_selection_view_controller.dart @@ -1,25 +1,37 @@ import 'package:bruno/src/utils/brn_event_bus.dart'; import 'package:flutter/material.dart'; + class BrnSelectionListViewController extends ChangeNotifier { + + /// 菜单索引 int menuIndex; - bool isShow; //是否显示下拉筛选列表 - double? listViewTop; //下拉筛选列表顶部坐标 + /// 是否显示下拉筛选列表 + bool isShow; + + /// 下拉筛选列表顶部坐标 + double? listViewTop; + + /// 屏幕高度，暂时没用到 double? screenHeight; - OverlayEntry? entry; //显示下拉筛选列表的图层 + + /// 显示下拉筛选列表的图层 + OverlayEntry? entry; BrnSelectionListViewController({ this.menuIndex = -1, this.isShow = false, }); + /// 显示下拉筛选列表 void show(int index) { isShow = true; menuIndex = index; notifyListeners(); } + /// 隐藏下拉筛选列表 void hide() { isShow = false; entry?.remove(); @@ -28,18 +40,25 @@ class BrnSelectionListViewController extends ChangeNotifier { } } +/// 筛选控制器 class BrnSelectionViewController { + + /// 关闭筛选弹窗 void closeSelectionView() { EventBus.instance.fire(CloseSelectionViewEvent()); } + /// 主动刷新 menu 菜单标题 void refreshSelectionTitle() { EventBus.instance.fire(RefreshMenuTitleEvent()); } } +/// 筛选事件 abstract class BaseSelectionEvent {} +/// 刷新菜单标题事件 class RefreshMenuTitleEvent extends BaseSelectionEvent {} +/// 关闭筛选弹窗事件 class CloseSelectionViewEvent extends BaseSelectionEvent {} diff --git a/lib/src/components/selection/controller/brn_selection_view_date_picker_controller.dart b/lib/src/components/selection/controller/brn_selection_view_date_picker_controller.dart index 092bcfd5..f42b8938 100644 --- a/lib/src/components/selection/controller/brn_selection_view_date_picker_controller.dart +++ b/lib/src/components/selection/controller/brn_selection_view_date_picker_controller.dart @@ -1,7 +1,12 @@ import 'package:flutter/material.dart'; +/// 日期选择器动画控制器 class BrnSelectionDatePickerController extends ChangeNotifier { - bool isShow; //是否显示下拉筛选列表 + + /// 是否显示下拉筛选列表 + bool isShow; + + /// OverlayEntry 用于展示隐藏子组件 OverlayEntry? entry; BrnSelectionDatePickerController({ diff --git a/lib/src/components/selection/converter/brn_selection_converter.dart b/lib/src/components/selection/converter/brn_selection_converter.dart index 6957b473..9403b129 100644 --- a/lib/src/components/selection/converter/brn_selection_converter.dart +++ b/lib/src/components/selection/converter/brn_selection_converter.dart @@ -2,12 +2,14 @@ import 'package:bruno/src/components/selection/bean/brn_selection_common_entity. import 'package:bruno/src/components/selection/brn_selection_util.dart'; import 'package:bruno/src/utils/brn_tools.dart'; +/// 筛选项数据转换器，用于将统一的数据结构转换为用户需要的数据结构 abstract class BrnSelectionConverterDelegate { /// 统一的数据结构 转换为 用户需要的数据结构，并通过 [BrnSelectionOnSelectionChanged] 回传给用户使用。 Map convertSelectedData( List selectedResults); } +/// 默认的筛选项数据转换器 class DefaultSelectionConverter implements BrnSelectionConverterDelegate { const DefaultSelectionConverter(); @@ -18,6 +20,7 @@ class DefaultSelectionConverter implements BrnSelectionConverterDelegate { } } +/// 默认的【更多】筛选项数据转换器 class DefaultMoreSelectionConverter implements BrnSelectionConverterDelegate { const DefaultMoreSelectionConverter(); @@ -28,6 +31,7 @@ class DefaultMoreSelectionConverter implements BrnSelectionConverterDelegate { } } +/// 默认的【快捷筛选】筛选项数据转换器 class DefaultSelectionQuickFilterConverter implements BrnSelectionConverterDelegate { const DefaultSelectionQuickFilterConverter(); @@ -48,6 +52,7 @@ Map getSelectionParamsWithConfigChild( return getSelectionParams(selectedResults); } +/// 根据传入的原始数据，返回用户选中的筛选数据 Map getSelectionParams( List? selectedResults) { Map params = Map(); @@ -91,6 +96,7 @@ Map getSelectionParams( return params; } +/// 获取当前选中项中用户选择的筛选数据 Map getCurrentSelectionEntityParams( BrnSelectionEntity selectionEntity) { Map params = Map(); diff --git a/lib/src/components/selection/widget/brn_layer_more_selection_page.dart b/lib/src/components/selection/widget/brn_layer_more_selection_page.dart index 11d7d667..c1d1da88 100644 --- a/lib/src/components/selection/widget/brn_layer_more_selection_page.dart +++ b/lib/src/components/selection/widget/brn_layer_more_selection_page.dart @@ -261,7 +261,7 @@ class _BrnLayerMoreSelectionPageState extends State ); } - //清空 + /// 清空 Widget _buildBottomBtn() { return Align( alignment: Alignment.bottomLeft, @@ -470,8 +470,8 @@ class _BrnLayerMoreSelectionPageState extends State } } - //初始化二级的选中（小白楼） - //规则：如果二级没有选中的，那么 选中二级的不限 + /// 初始化二级的选中（小白楼） + /// 规则：如果二级没有选中的，那么 选中二级的不限 void setInitialSecondShowingItem(BrnSelectionEntity currentFirstEntity) { //设置初始化的二级筛选条件 -1没有 int secondIndex = currentFirstEntity.getFirstSelectedChildIndex(); diff --git a/lib/src/components/selection/widget/brn_selection_animate_widget.dart b/lib/src/components/selection/widget/brn_selection_animate_widget.dart index c83821de..436239c0 100644 --- a/lib/src/components/selection/widget/brn_selection_animate_widget.dart +++ b/lib/src/components/selection/widget/brn_selection_animate_widget.dart @@ -1,9 +1,16 @@ import 'package:bruno/src/components/selection/controller/brn_selection_view_controller.dart'; import 'package:flutter/material.dart'; +/// 筛选动画展示隐藏组件 class BrnSelectionAnimationWidget extends StatefulWidget { + + /// 用于展示隐藏控制器 final BrnSelectionListViewController controller; + + /// 子组件 final Widget view; + + /// 动画时长 final int animationMilliseconds; const BrnSelectionAnimationWidget({ diff --git a/lib/src/components/selection/widget/brn_selection_common_item_widget.dart b/lib/src/components/selection/widget/brn_selection_common_item_widget.dart index b512dfc5..ec2109c7 100644 --- a/lib/src/components/selection/widget/brn_selection_common_item_widget.dart +++ b/lib/src/components/selection/widget/brn_selection_common_item_widget.dart @@ -6,16 +6,31 @@ import 'package:bruno/src/utils/brn_tools.dart'; import 'package:bruno/src/utils/css/brn_css_2_text.dart'; import 'package:flutter/material.dart'; +/// [BrnSelectionSingleListWidget] 子组件中的单项 class BrnSelectionCommonItemWidget extends StatelessWidget { + + /// 单项数据 final BrnSelectionEntity item; + + /// 背景色 final Color? backgroundColor; + + /// 选中项背景色 final Color? selectedBackgroundColor; + + /// 是否当前焦点 final bool isCurrentFocused; + + /// 是否是第一级 final bool isFirstLevel; + + /// 是否是多选列表类型 final bool isMoreSelectionListType; + /// 单选回调 final ValueChanged? itemSelectFunction; + /// 主题配置 final BrnSelectionConfig? themeData; BrnSelectionCommonItemWidget({ @@ -103,6 +118,7 @@ class BrnSelectionCommonItemWidget extends StatelessWidget { ); } + /// 获取当前节点的背景色 Color? getItemBGColor() { if (isCurrentFocused) { return this.selectedBackgroundColor; @@ -111,6 +127,7 @@ class BrnSelectionCommonItemWidget extends StatelessWidget { } } + /// 是否高亮 bool isHighLight(BrnSelectionEntity item) { if (item.isInLastLevel()) { if (item.isUnLimit()) { @@ -123,6 +140,7 @@ class BrnSelectionCommonItemWidget extends StatelessWidget { } } + /// 是否加粗 bool isBold(BrnSelectionEntity item) { if (isHighLight(item)) { return true; @@ -131,6 +149,7 @@ class BrnSelectionCommonItemWidget extends StatelessWidget { } } + /// 获取当前节点的文本样式 TextStyle? getItemTextStyle() { if (isHighLight(item)) { return themeData?.itemSelectedTextStyle.generateTextStyle(); @@ -140,6 +159,7 @@ class BrnSelectionCommonItemWidget extends StatelessWidget { return themeData?.itemNormalTextStyle.generateTextStyle(); } + /// 获取当前节点的子节点中，选中的数量 String getSelectedItemCount(BrnSelectionEntity item) { String itemCount = ""; if ((BrnSelectionUtil.getTotalLevel(item) < 3 || !isFirstLevel) && diff --git a/lib/src/components/selection/widget/brn_selection_date_range_item_widget.dart b/lib/src/components/selection/widget/brn_selection_date_range_item_widget.dart index 3c6caf74..e0b09880 100644 --- a/lib/src/components/selection/widget/brn_selection_date_range_item_widget.dart +++ b/lib/src/components/selection/widget/brn_selection_date_range_item_widget.dart @@ -12,8 +12,11 @@ import 'package:flutter/services.dart'; const String _defaultDateFormat = 'yyyy年MM月dd日'; +/// 日期范围选择，筛选组件的子组件 // ignore: must_be_immutable class BrnSelectionDateRangeItemWidget extends StatefulWidget { + + /// 筛选数据 final BrnSelectionEntity item; /// 输入框显示文字大小 @@ -25,11 +28,16 @@ class BrnSelectionDateRangeItemWidget extends StatefulWidget { /// 日期格式 final String dateFormat; + /// 最小日期输入框控制器 final TextEditingController minTextEditingController; + + /// 最大日期输入框控制器 final TextEditingController maxTextEditingController; + /// 选择日期时的点击事件 final VoidCallback? onTapped; + /// 主题配置 BrnSelectionConfig themeData; BrnSelectionDateRangeItemWidget( @@ -245,6 +253,7 @@ class _BrnSelectionDateRangeItemWidgetState }); } + /// 关闭选择弹窗 void closeSelectionPopupWindow() { if (_datePickerController.isShow) { _datePickerController.hide(); diff --git a/lib/src/components/selection/widget/brn_selection_datepicker_animate_widget.dart b/lib/src/components/selection/widget/brn_selection_datepicker_animate_widget.dart index 7143ccc0..3807792c 100644 --- a/lib/src/components/selection/widget/brn_selection_datepicker_animate_widget.dart +++ b/lib/src/components/selection/widget/brn_selection_datepicker_animate_widget.dart @@ -1,9 +1,16 @@ import 'package:bruno/src/components/selection/controller/brn_selection_view_date_picker_controller.dart'; import 'package:flutter/material.dart'; +/// 日期选择器动画组件 class BrnSelectionDatePickerAnimationWidget extends StatefulWidget { + + /// 用于展示隐藏控制器 final BrnSelectionDatePickerController controller; + + /// 子组件 final Widget view; + + /// 动画时长 final int animationMilliseconds; const BrnSelectionDatePickerAnimationWidget( diff --git a/lib/src/components/selection/widget/brn_selection_list_widget.dart b/lib/src/components/selection/widget/brn_selection_list_widget.dart index a10d45fa..efc7a305 100644 --- a/lib/src/components/selection/widget/brn_selection_list_widget.dart +++ b/lib/src/components/selection/widget/brn_selection_list_widget.dart @@ -14,13 +14,26 @@ import 'package:flutter/material.dart'; typedef SingleListItemSelect = void Function( int listIndex, int index, BrnSelectionEntity entity); +/// 多列数据选择子组件，内部包含多个 BrnSelectionSingleListWidget // ignore: must_be_immutable class BrnListSelectionGroupWidget extends StatefulWidget { + + /// 筛选数据 final BrnSelectionEntity entity; + + /// 最大高度 final double maxContentHeight; + + /// 是否显示选中数量 final bool showSelectedCount; + + /// 背景点击回调 final VoidCallback? bgClickFunction; + + /// 点击确认按钮回调 final BrnOnRangeSelectionConfirm? onSelectionConfirm; + + /// 主题配置 BrnSelectionConfig themeData; BrnListSelectionGroupWidget({ diff --git a/lib/src/components/selection/widget/brn_selection_menu_item_widget.dart b/lib/src/components/selection/widget/brn_selection_menu_item_widget.dart index bae2214f..3e348bc7 100644 --- a/lib/src/components/selection/widget/brn_selection_menu_item_widget.dart +++ b/lib/src/components/selection/widget/brn_selection_menu_item_widget.dart @@ -3,13 +3,23 @@ import 'package:bruno/src/theme/configs/brn_selection_config.dart'; import 'package:bruno/src/utils/brn_tools.dart'; import 'package:flutter/material.dart'; +/// 筛选菜单项 // ignore: must_be_immutable class BrnSelectionMenuItemWidget extends StatelessWidget { + + /// 菜单项标题 final String title; + + /// 是否高亮 final bool isHighLight; + + /// 是否选中 final bool active; + + /// 点击事件 final VoidCallback? itemClickFunction; + /// 主题配置 BrnSelectionConfig themeData; BrnSelectionMenuItemWidget( diff --git a/lib/src/components/selection/widget/brn_selection_menu_widget.dart b/lib/src/components/selection/widget/brn_selection_menu_widget.dart index 239c9227..13d7ec93 100644 --- a/lib/src/components/selection/widget/brn_selection_menu_widget.dart +++ b/lib/src/components/selection/widget/brn_selection_menu_widget.dart @@ -20,13 +20,24 @@ typedef BrnOnMenuItemClick = bool Function(int index); typedef BrnOnRangeSelectionConfirm = void Function(BrnSelectionEntity results, int firstIndex, int secondIndex, int thirdIndex); +/// 筛选菜单子组件 class BrnSelectionMenuWidget extends StatefulWidget { + /// 筛选菜单数据 final List data; final BuildContext context; + + /// 筛选菜单高度 final double height; + /// 筛选菜单宽度 final double? width; + + /// 确认回调 final BrnOnRangeSelectionConfirm? onConfirm; + + /// 筛选菜单项点击回调 final BrnOnMenuItemClick? onMenuItemClick; + + /// 每行的 tag 数，用于子组件配置 final BrnConfigTagCountPerRow? configRowCount; ///筛选所在列表的外部列表滚动需要收起筛选，此处为最外层列表，有点恶心，但是暂时只想到这个方法，有更好方式的一定要告诉我 @@ -35,6 +46,7 @@ class BrnSelectionMenuWidget extends StatefulWidget { ///指定筛选固定的相对于屏幕的顶部距离，默认null不指定 final double? constantTop; + /// 筛选菜单主题 final BrnSelectionConfig themeData; BrnSelectionMenuWidget( diff --git a/lib/src/components/selection/widget/brn_selection_range_input_item_widget.dart b/lib/src/components/selection/widget/brn_selection_range_input_item_widget.dart index 80c03e99..a604a693 100644 --- a/lib/src/components/selection/widget/brn_selection_range_input_item_widget.dart +++ b/lib/src/components/selection/widget/brn_selection_range_input_item_widget.dart @@ -10,17 +10,26 @@ typedef RangeChangedCallback = void Function(String minInput, String maxInput); /// 清空自定义范围输入框焦点的事件类 class ClearSelectionFocusEvent {} +/// 筛选的范围输入子组件 class BrnSelectionRangeItemWidget extends StatefulWidget { final BrnSelectionEntity item; + /// 范围输入框的回调 final RangeChangedCallback? onRangeChanged; + + /// 输入框焦点的回调 final ValueChanged? onFocusChanged; + /// 是否清空输入框的文本 final bool isShouldClearText; + /// 最小值输入框的控制器 final TextEditingController minTextEditingController; + + /// 最大值输入框的控制器 final TextEditingController maxTextEditingController; + /// 主题配置 final BrnSelectionConfig themeData; BrnSelectionRangeItemWidget({ diff --git a/lib/src/components/selection/widget/brn_selection_range_tag_widget.dart b/lib/src/components/selection/widget/brn_selection_range_tag_widget.dart index 12368acc..ed4edcd1 100644 --- a/lib/src/components/selection/widget/brn_selection_range_tag_widget.dart +++ b/lib/src/components/selection/widget/brn_selection_range_tag_widget.dart @@ -11,21 +11,32 @@ import 'package:flutter/material.dart'; /// 描述: 多选 tag 组件 /// /// /// /// /// /// /// /// /// / class BrnSelectionRangeTagWidget extends StatefulWidget { - //tag 显示的文本 + /// tag 显示的文本 @required final List tagFilterList; - //初始选中的 Index 列表 + /// 初始选中的 Index 列表 final List? initSelectStatus; - //选择tag的回调 + /// 选择tag的回调 final void Function(int, bool)? onSelect; + + /// tag 之间的间距 final double spacing; + + /// tag 之间的垂直间距 final double verticalSpacing; + + /// tag 的宽度 final int tagWidth; + + /// tag 的高度 final double tagHeight; + + /// 初始选择的焦点位置 final int initFocusedIndex; + /// 主题配置 final BrnSelectionConfig themeData; BrnSelectionRangeTagWidget( diff --git a/lib/src/components/selection/widget/brn_selection_range_widget.dart b/lib/src/components/selection/widget/brn_selection_range_widget.dart index a37d3df0..d1d8cc89 100644 --- a/lib/src/components/selection/widget/brn_selection_range_widget.dart +++ b/lib/src/components/selection/widget/brn_selection_range_widget.dart @@ -19,17 +19,30 @@ import 'package:bruno/src/utils/brn_text_util.dart'; import 'package:bruno/src/utils/brn_tools.dart'; import 'package:flutter/material.dart'; +/// 范围选择子组件 class BrnRangeSelectionGroupWidget extends StatefulWidget { + /// 根节点的筛选数据 final BrnSelectionEntity entity; + + /// 最大高度 final double maxContentHeight; + + /// 是否显示选中数量 final bool showSelectedCount; + + /// 背景点击事件 final VoidCallback? bgClickFunction; + + /// 确认按钮点击事件 final BrnOnRangeSelectionConfirm? onSelectionConfirm; + /// 每行 tag 数 final int? rowCount; + /// 顶部间距 final double marginTop; + /// 主题配置 final BrnSelectionConfig themeData; BrnRangeSelectionGroupWidget( @@ -453,7 +466,7 @@ class _BrnRangeSelectionGroupWidgetState }); } - // 初始化数据 + /// 初始化数据 void _initData() { // 生成筛选节点树 _originalSelectedItemsList = widget.entity.selectedList(); @@ -471,7 +484,7 @@ class _BrnRangeSelectionGroupWidgetState _refreshDataSource(); } - // 设置默认无选中项的时候默认选择index + /// 设置默认无选中项的时候默认选择index void _configDefaultInitSelectIndex() { _firstIndex = _secondIndex = -1; } @@ -503,7 +516,7 @@ class _BrnRangeSelectionGroupWidgetState }); } - // 刷新3个ListView的数据源 + /// 刷新3个ListView的数据源 void _refreshDataSource() { _firstList = widget.entity.children; if (_firstIndex >= 0 && _firstList.length > _firstIndex) { @@ -541,7 +554,7 @@ class _BrnRangeSelectionGroupWidgetState } } - //设置数据为未选中状态 + /// 设置数据为未选中状态 void _resetSelectionDatas(BrnSelectionEntity entity) { entity.isSelected = false; entity.customMap = Map(); diff --git a/lib/src/components/selection/widget/brn_selection_single_list_widget.dart b/lib/src/components/selection/widget/brn_selection_single_list_widget.dart index d943790a..7df6471d 100644 --- a/lib/src/components/selection/widget/brn_selection_single_list_widget.dart +++ b/lib/src/components/selection/widget/brn_selection_single_list_widget.dart @@ -7,20 +7,36 @@ import 'package:bruno/src/l10n/brn_intl.dart'; import 'package:bruno/src/theme/configs/brn_selection_config.dart'; import 'package:flutter/material.dart'; +/// 单列选择子组件 // ignore: must_be_immutable class BrnSelectionSingleListWidget extends StatefulWidget { late List _selectedItems; + + /// 当前选择的项 late int currentListIndex; + /// 筛选数据 List items; + + /// 占父容器宽度的比例 int flex; + + /// 焦点位置 int focusedIndex; + + /// 最大高度 double maxHeight; + /// 背景色 Color? backgroundColor; + + /// 选中项背景色 Color? selectedBackgroundColor; + + /// 单选回调 SingleListItemSelect? singleListItemSelect; + /// 主题配置 BrnSelectionConfig themeData; BrnSelectionSingleListWidget({ @@ -203,6 +219,7 @@ class _BrnSelectionSingleListWidgetState } } + /// 根据父子层级数据，配置节点选中状态 void configMultiLevelList( BrnSelectionEntity selectedEntity, int currentListIndex) { /// 选中【不限】清除同一级别其他的状态 diff --git a/lib/src/components/switch/brn_switch_button_base.dart b/lib/src/components/switch/brn_switch_button_base.dart index 3e2a3bf7..d007b7e9 100644 --- a/lib/src/components/switch/brn_switch_button_base.dart +++ b/lib/src/components/switch/brn_switch_button_base.dart @@ -13,12 +13,16 @@ class BrnBaseSwitchButton extends StatelessWidget { /// can click final bool enabled; + /// Called when the user toggles the switch on or off. final ValueChanged? onChanged; + /// The color to use when this switch is off. final Color borderColor; + /// The color to use on the track. final Color? trackColor; + /// The color to use on the thumb. final Color thumbColor; const BrnBaseSwitchButton({ diff --git a/lib/src/components/tabbar/normal/brn_tab_bar.dart b/lib/src/components/tabbar/normal/brn_tab_bar.dart index 667dbd67..279ae75b 100644 --- a/lib/src/components/tabbar/normal/brn_tab_bar.dart +++ b/lib/src/components/tabbar/normal/brn_tab_bar.dart @@ -332,7 +332,8 @@ class BrnTabBarState extends State { ); } - // 更新选中tab的小红点状态 + /// 更新选中tab的小红点状态 + /// [index] tab索引 void refreshBadgeState(int index) { setState(() { BadgeTab badgeTab = widget.tabs![index]; @@ -375,7 +376,7 @@ class BrnTabBarState extends State { return widgets; } - // 原始的自适应的tab样式 + /// 原始的自适应的tab样式 Widget _wrapOriginWidget( BadgeTab badgeTab, bool lastElement, bool isScrollable) { var _contentWidget = LayoutBuilder(builder: (context, constraints) { @@ -443,7 +444,7 @@ class BrnTabBarState extends State { ); } - // 定制的等分tab样式 + /// 定制的等分tab样式 Widget _wrapAverageWidget( BadgeTab badgeTab, double? minWidth, bool lastElement) { return LayoutBuilder(builder: (context, constraints) { @@ -509,7 +510,7 @@ class BrnTabBarState extends State { }); } - // 计算小红点尺寸相关参数 + /// 计算小红点尺寸相关参数 void caculateBadgeParams(BadgeTab badgeTab, BoxConstraints constraints) { _paddingTop = -5.0; @@ -580,7 +581,7 @@ class BrnTabBarState extends State { } } - // 展开更多 + /// 展开更多 void showMoreWindow(BuildContext context) { final RenderBox dropDownItemRenderBox = context.findRenderObject() as RenderBox; @@ -661,7 +662,7 @@ class BrnTabBarState extends State { } } -// 更多弹框样式 +/// 更多弹框样式 // ignore: must_be_immutable class _TabBarOverlayWidget extends StatefulWidget { List? tabs; @@ -711,7 +712,7 @@ class _TabBarOverlayWidgetState extends State<_TabBarOverlayWidget> { return createMoreWindowView(); } - // 展开更多弹框样式 + /// 展开更多弹框样式 Widget createMoreWindowView() { return MeasureSize( onChange: (size) { @@ -828,19 +829,16 @@ class _TabBarOverlayWidgetState extends State<_TabBarOverlayWidget> { } } +/// BrnTabBar tab 的展示配置 class BadgeTab { BadgeTab( - {this.key, - this.text, + {this.text, this.badgeNum, this.topText, this.badgeText, this.showRedBadge = false, this.isAutoDismiss = true}); - @Deprecated('无效参数，预计两个版本后删除') - final Key? key; - /// Tab文本 final String? text; diff --git a/lib/src/components/tabbar/normal/brn_tabbar_controller.dart b/lib/src/components/tabbar/normal/brn_tabbar_controller.dart index b0337c54..e3423763 100644 --- a/lib/src/components/tabbar/normal/brn_tabbar_controller.dart +++ b/lib/src/components/tabbar/normal/brn_tabbar_controller.dart @@ -30,22 +30,27 @@ class BrnTabbarController extends ChangeNotifier { /// int selectIndex = 0; + /// 设置选中的位置 + /// [index] 选中的位置 void setSelectIndex(int index) { selectIndex = index; notifyListeners(); } + /// 设置更多选项弹出 void show() { isShow = true; notifyListeners(); } + /// 设置更多选项隐藏 void hide() { isShow = false; notifyListeners(); } } +/// 关闭更多弹框事件 class CloseWindowEvent { bool? isShow = false; @@ -75,6 +80,7 @@ class BrnCloseWindowController { isShow = state; } + /// 关闭 "更多" 弹框 void closeMoreWindow() { _closeController.add(CloseWindowEvent()); } diff --git a/lib/src/components/tag/brn_state_tag.dart b/lib/src/components/tag/brn_state_tag.dart index 83ade3d5..f2bde4df 100644 --- a/lib/src/components/tag/brn_state_tag.dart +++ b/lib/src/components/tag/brn_state_tag.dart @@ -19,7 +19,8 @@ class BrnStateTag extends StatelessWidget { final Color? backgroundColor; final Color? textColor; - //默认为等待状态,黄色 + /// 状态标签是反应状态的形式，根据不同的[tagState]呈现不同的背景色和文字颜色 + /// 默认为等待状态, 黄色 const BrnStateTag({ Key? key, required this.tagText, @@ -39,6 +40,8 @@ class BrnStateTag extends StatelessWidget { ); } + /// 根据状态获取背景色 + /// [state] 状态, 默认为 waiting Color getTagColor(TagState state) { switch (state) { case TagState.invalidate: diff --git a/lib/src/components/tag/tagview/brn_delete_tag.dart b/lib/src/components/tag/tagview/brn_delete_tag.dart index 8f58885b..4c9dc12b 100644 --- a/lib/src/components/tag/tagview/brn_delete_tag.dart +++ b/lib/src/components/tag/tagview/brn_delete_tag.dart @@ -8,7 +8,7 @@ import 'package:flutter/material.dart'; /// 可以外部主动添加和删除标签 /// 宽高间距可设置 /// 支持标签数量的增删 -/// ignore: must_be_immutable +// ignore: must_be_immutable class BrnDeleteTag extends StatefulWidget { /// 初始传入的标签，当传入controller的时候，应把初始标签放入controller的构造中 final List? tags; @@ -173,7 +173,7 @@ class _BrnDeleteTagState extends State { } /// 标签具体子项，配置属性可参考 [BrnDeleteTag] -/// ignore: must_be_immutable +// ignore: must_be_immutable class DeleteTagItemWidget extends StatelessWidget { final int index; final String title; diff --git a/lib/src/components/tag/tagview/brn_select_tag.dart b/lib/src/components/tag/tagview/brn_select_tag.dart index c55ee652..e2be73ec 100644 --- a/lib/src/components/tag/tagview/brn_select_tag.dart +++ b/lib/src/components/tag/tagview/brn_select_tag.dart @@ -10,7 +10,7 @@ import 'package:flutter/material.dart'; /// 支持定宽和非定宽 /// 宽高间距可设置 /// 支持单选和多选 -/// ignore: must_be_immutable +// ignore: must_be_immutable class BrnSelectTag extends StatefulWidget { /// 展示的标签列表 final List tags; diff --git a/lib/src/utils/brn_multi_click_util.dart b/lib/src/utils/brn_multi_click_util.dart index b2d6f36b..1565c0cb 100644 --- a/lib/src/utils/brn_multi_click_util.dart +++ b/lib/src/utils/brn_multi_click_util.dart @@ -1,8 +1,12 @@ + +/// 防止多次点击工具类 class BrnMultiClickUtils { const BrnMultiClickUtils._(); static DateTime? _lastClickTime; + /// 判断是否是多次点击 + /// [intervalMilliseconds] 间隔时间，单位毫秒，默认500毫秒 static bool isMultiClick({int intervalMilliseconds = 500}) { if (_lastClickTime == null || DateTime.now().difference(_lastClickTime!) > diff --git a/lib/src/utils/brn_rich_text.dart b/lib/src/utils/brn_rich_text.dart index 8f2d5018..790ef841 100644 --- a/lib/src/utils/brn_rich_text.dart +++ b/lib/src/utils/brn_rich_text.dart @@ -14,10 +14,13 @@ class BrnRichTextGenerator { TextOverflow? _overflow; /// 添加超链接部分的文案 - /// text 是显示的文案 - /// url 是超链接的 url - /// fontsize 是显示大小 - /// richTextLinkClick 是超链接点击的回调 + /// [text] 显示的文案 + /// [url] 超链接的 url + /// [textStyle] 文案的样式 + /// [linkColor] 超链接的颜色 + /// [fontSize] 显示大小 + /// [fontWeight] 字体粗细 + /// [richTextLinkClick] 超链接点击的回调 BrnRichTextGenerator addTextWithLink( String text, { String? url, @@ -52,8 +55,11 @@ class BrnRichTextGenerator { } /// 添加自定义文案 - /// fontsize 是文案大小 默认是16 - /// color 是文案的颜色 默认是深黑色 + /// [text] 显示的文案 + /// [textStyle] 文案的样式 + /// [fontWeight] 字体的粗细 默认是 normal + /// [fontSize] 文案大小 默认是16 + /// [color] 文案的颜色 默认是深黑色 BrnRichTextGenerator addText( String text, { TextStyle? textStyle, @@ -79,7 +85,8 @@ class BrnRichTextGenerator { return this; } - /// 添加Icon + /// [icon] 图标 + /// [alignment] 图标的对齐方式 默认是顶部对齐 BrnRichTextGenerator addIcon( Widget? icon, { PlaceholderAlignment? alignment, @@ -101,7 +108,7 @@ class BrnRichTextGenerator { return this; } - /// 设置最多文案显示几行 默认是100行 + /// 设置文案溢出的样式 BrnRichTextGenerator setTextOverflow(TextOverflow overflow) { _overflow = overflow; return this; @@ -122,6 +129,7 @@ class BrnRichTextGenerator { ); } + /// 清空文案 void clear() { _spanList.clear(); } diff --git a/lib/src/utils/brn_text_util.dart b/lib/src/utils/brn_text_util.dart index 18cb2692..b6ce36d9 100644 --- a/lib/src/utils/brn_text_util.dart +++ b/lib/src/utils/brn_text_util.dart @@ -1,6 +1,7 @@ import 'package:bruno/src/utils/brn_tools.dart'; import 'package:flutter/widgets.dart'; +/// 文本工具类 class BrnTextUtil { const BrnTextUtil._(); diff --git a/lib/src/utils/brn_tools.dart b/lib/src/utils/brn_tools.dart index 332d318c..18f0e5b7 100644 --- a/lib/src/utils/brn_tools.dart +++ b/lib/src/utils/brn_tools.dart @@ -3,10 +3,13 @@ import 'package:bruno/src/theme/brn_theme_configurator.dart'; import 'package:bruno/src/theme/configs/brn_common_config.dart'; import 'package:flutter/material.dart'; +/// 图片加载工具类 class BrunoTools { const BrunoTools._(); /// 将 icon 根据主题色变色后返回 + /// [assetFilePath] assets 资源文件路径 + /// [configId] 主题配置id static Image getAssetImageWithBandColor( String assetFilePath, { String configId = GLOBAL_CONFIG_ID, @@ -21,6 +24,8 @@ class BrunoTools { } /// 将 icon 根据传入颜色变后返回 + /// [assetFilePath] assets 资源文件路径 + /// [color] 图片着色 static Image getAssetImageWithColor(String assetFilePath, Color? color) { if (!assetFilePath.startsWith('assets')) { assetFilePath = 'assets/$assetFilePath'; @@ -34,8 +39,8 @@ class BrunoTools { } /// [assetFilePath] assets 资源文件路径 - /// [package] 访问某个 package 里的资源，这里默认为 'bruno' - /// [scale] 与所用的 png 资源是 icon_2x.png (scale=2.0)，icon_3x.png(scale=3.0) + /// [fit] 图片剪裁模式 + /// [gaplessPlayback] 当图像提供程序更改时，是继续显示旧映像（true），还是暂时显示空白（false）。 static Image getAssetImage( String assetFilePath, { BoxFit? fit, @@ -53,6 +58,7 @@ class BrunoTools { ); } + /// [assetFilePath] assets 资源文件路径，使用默认 scale static Image getAssetScaleImage(String assetFilePath) { if (!assetFilePath.startsWith('assets')) { assetFilePath = 'assets/$assetFilePath'; @@ -63,6 +69,10 @@ class BrunoTools { ); } + /// [assetFilePath] assets 资源文件路径 + /// [w] 图片宽度 + /// [h] 图片高度， + /// [color] 图片着色 static Image getAssetSizeImage( String assetFilePath, double w, @@ -128,14 +138,4 @@ class BrunoTools { } return obj == null; } - - /// 去掉最后一位小数 -//static double formatNumRemoveLastNum(double num){ -// int count = num.toString().length - num.toString().lastIndexOf('.') - 1; -// if(count >1){ -// -// } -// String numStr = num.toString(); -// return numStr.substring(numStr.length-1); -//} } diff --git a/lib/src/utils/css/brn_core_funtion.dart b/lib/src/utils/css/brn_core_funtion.dart index 1622288f..a214c913 100644 --- a/lib/src/utils/css/brn_core_funtion.dart +++ b/lib/src/utils/css/brn_core_funtion.dart @@ -7,8 +7,12 @@ import 'package:xml/xml_events.dart' as xml; /// 超链接的点击回调 typedef BrnHyperLinkCallback = void Function(String text, String? url); -/// 用于将标签转为 style +/// 用于将 HTML 标签转为 style class BrnConvert { + + /// [cssContent] 带有html 标签文本 + /// [linkCallBack] 超链接的点击回调 + /// [defaultStyle] 外部传入的默认文本样式 BrnConvert( String cssContent, { BrnHyperLinkCallback? linkCallBack,