w_tools_ui 6.1.1
w_tools_ui: ^6.1.1 copied to clipboard
w_tools 的 UI 组件层:提供文本、图片、按钮、布局、导航与常用扩展,支持响应式尺寸、图片缓存与重试,帮助快速构建一致的界面。
w_tools_ui #
w_tools_ui 是 w_tools 的 UI 组件层,提供通用组件、布局、导航、扩展与屏幕适配工具。
特性 #
- 通用组件:
WText/WImage/WButton/WBadge等 - 布局组件:
WScaffold/WAppBar/WListView/WStep - 导航组件:
WNavBar/WNavController/WTabBar - 扩展方法:颜色、字符串、数字、TextStyle、Widget、BoxDecoration 等
- 屏幕适配:
WScreen、间距与尺寸工具
安装 #
dependencies:
w_tools_ui: ^6.1.1
本包最低要求 Flutter 3.38.0。
快速开始 #
import 'package:w_tools_ui/w_tools_ui.dart';
class DemoPage extends StatelessWidget {
const DemoPage({super.key});
@override
Widget build(BuildContext context) {
return WScaffold(
title: 'Demo',
body: const Center(
child: WText(
text: 'Hello w_tools_ui',
variant: WTextVariant.body,
),
),
);
}
}
WImage 快速示例 #
import 'package:w_tools_ui/w_tools_ui.dart';
WImage.source(
source: WImageSource.network('https://example.com/cover.jpg'),
style: const WImageStyle(
aspectRatio: 16 / 9,
fit: BoxFit.cover,
borderRadius: BorderRadius.all(Radius.circular(12)),
),
config: const WImageLoadConfig(memCacheWidth: 800),
);
所有来源统一走 WImage.source + WImageSource。
WImage不会自动给尺寸:没有width/height/aspectRatio时,必须由父级 (SizedBox/Expanded/AspectRatio)约束;否则在Row/Column/ListView里加载前占位是 0 尺寸,表现为空白(debug 下会打印提示)。
入口选择 #
| 场景 | 入口 |
|---|---|
| 已知网络 / 资源 / 文件 / Base64 | WImageSource.network/asset/file/base64 |
任意 ImageProvider / 内存字节 |
WImageSource.provider / ImageProvider + MemoryImage |
| 动态字符串,需要自动判定 | WImageSource.parse + WImage.source |
| 需要加载配置 | config: WImageLoadConfig(...) |
| 需要视觉样式 | style: WImageStyle(...) |
WImageSource.asset(name) 默认 不拼 WAssets.imagePath;
需要自动拼前缀时用 WImageSource.asset(name, prefix: true)。
常用配方 #
WImage.source(source: WImageSource.parse(url), style: WImageStyle.avatar(40))
WImage.source(
source: WImageSource.parse(url),
style: WImageStyle.thumbnail(80),
config: const WImageLoadConfig(memCacheWidth: 240, memCacheHeight: 240),
)
WImage.source(
source: WImageSource.network(url),
config: const WImageLoadConfig(showRetryButton: true),
)
WImage.source(source: WImageSource.asset('logo.png', prefix: true))
WImage.source(source: WImageSource.provider(MemoryImage(bytes)))
WImageStyle 也提供预设与链式糖:
WImageStyle.avatar(40)
WImageStyle.thumbnail(80)
WImageStyle.cover(aspectRatio: 16 / 9, radius: 12)
const WImageStyle().square(40).rounded(20)
完整的网络、资源、Base64、进度、重试、主题与预加载示例见
example/。
历史迁移见
docs/migrations/。
文本 #
WText(text: '标题', variant: WTextVariant.title);
WText(text: '正文', variant: WTextVariant.body, maxLines: 2, overflow: TextOverflow.ellipsis);
WText(
text: '价格',
variant: WTextVariant.price,
style: const TextStyle(fontFeatures: [FontFeature.tabularFigures()]),
);
11 个 variant:display/headline/title/price/body/bodyStrong/number/caption/label/button/badge。
品牌样式在主题构建处装一次:
final base = ThemeData(colorScheme: scheme, useMaterial3: true);
theme: base.withWTextStyles(WTextStyles.fromTextTheme(base.textTheme)),
WTextConfig 已移除;局部只覆盖需要的字段(style/color/maxLines/overflow/textScaler)。
按钮与点击 #
WButton(label: '保存', onTap: save);
WButton(label: '提交', loading: true, enabled: false, onTap: submit);
WButton(icon: Icons.add, label: '新增', style: WButtonStyles.of(context).primary, onTap: add);
WPressable(onTap: openDetail, child: card); // 任意 child,无 button 语义
任意 child / 卡片点击用 WPressable;需要键盘、最小点击区域或 button 语义时用 WButton。
页面骨架与布局 #
WScaffold(
title: '首页',
actions: [IconButton(onPressed: ..., icon: const Icon(Icons.search))],
floatingActionButton: FloatingActionButton(onPressed: ..., child: const Icon(Icons.add)),
body: ...,
);
// 自定义顶栏
WScaffold(appBar: WAppBar(title: '详情'), body: ...);
WStep(labels: const ['下单', '付款', '完成'], current: 2);
列表:
WListView(sliver: WListViewSliver.list(itemCount: n, itemBuilder: ...));
WListView(sliver: WListViewSliver.separated(itemCount: n, itemBuilder: ..., separatorBuilder: ...));
WListView(sliver: WListViewSliver.grid(itemCount: n, gridDelegate: ..., itemBuilder: ...));
WListView(sliver: WListViewSliver.overlap(itemCount: n, itemExtent: 80, overlap: 24, itemBuilder: ...));
角标 / 裁剪 / 横向操作:
WBadge(badgeContent: const Text('3'), child: const Icon(Icons.notifications));
WClipRRect(config: const WClipRRectConfig.all(12), child: image);
WActionRow(children: [WButton(...), WButton(...)]);
状态与反馈 #
WGradientCircularProgressIndicator(radius: 24, value: 0.6, colors: const [Colors.indigo, Colors.lightBlue]);
WKeepAliveWrapper(child: item);
WNotificationListenerBuilder<ScrollNotification>(child: list)
..onNotificationPercentage((p) { ... })
..build();
导航 #
class _NavDemoState extends State<NavDemo> {
late final _controller = WNavController(length: 3, vsync: this);
@override
void dispose() {
_controller.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return WNavBar(
config: const WNavBarConfig(),
controller: _controller,
itemBuilder: (context, index, selected) => Text('Tab $index'),
);
}
}
WNavController 需要页面 State 提供 vsync,并由调用方 dispose。
顶部 tab:
DefaultTabController(
length: 2,
child: Column(
children: [
WTabBar(
config: WTabBarConfig(),
tabs: const [Text('全部'), Text('已完成')],
),
const Expanded(
child: TabBarView(
children: [Text('全部内容'), Text('已完成内容')],
),
),
],
),
)
WTabBar 不自带 controller,需要 DefaultTabController 或显式 TabController。
扩展方法 #
WSizeBox/WPadding/WRow/WColumn已在 5.0 删除,直接用 Flutter 原生组件;heightBox/widthBox/squareBox仍保留,是SizedBox的简写;allPadding用于需要EdgeInsets值的场景。
const SizedBox(height: 16);
16.allPadding; // EdgeInsets.all(16)
1234.toThousandsSeparated; // 1,234
1234.56.toCurrency(symbol: '¥'); // ¥1,234.56
0.125.toPercent; // 12.5%
'#FF5733'.toColor();
const BoxDecoration()
.withColor(Colors.white)
.withBorderRadius(BorderRadius.circular(8));
扩展方法随 package:w_tools_ui/w_tools_ui.dart 一起导入。
工具 #
WScreen.w(16);
WScreen.h(24);
WScreen.sp(14);
WAssets.imagePath = 'assets/icons/';
'logo.png'.assetImagePath;
WScreen 无 delegate 时返回原始值;需要 ScreenUtil 时注入 delegate:
WScreen.delegateWidth = (v) => ScreenUtil().setWidth(v);
WScreen.delegateHeight = (v) => ScreenUtil().setHeight(v);
WScreen.delegateFont = (v) => ScreenUtil().setSp(v);
主要 API #
| 能力 | 入口 |
|---|---|
| 文本 / 图片 | WText / WImage |
| 按钮 / 点击 | WButton / WPressable |
| 徽标 / 横向操作 | WBadge / WActionRow / WSelectableRow |
| 裁剪 | WClipRRect |
| 加载指示 | WGradientCircularProgressIndicator |
| 列表保活 | WKeepAliveWrapper |
| 滚动通知 | WNotificationListenerBuilder |
| 布局 | WScaffold / WAppBar / WListView |
| 导航 | WNavBar / WNavController / WTabBar |
| 屏幕工具 | WScreen |
| 资源 | WAssets |
| 扩展 | WHexColor / WStringExtension / WNumExtension / WWidgetExtension / WBoxDecorationExtension |
License #
MIT