w_tools_ui 10.2.0
w_tools_ui: ^10.2.0 copied to clipboard
w_tools 的 UI 组件层:提供文本、图片、按钮、布局、导航与常用扩展,支持响应式尺寸、图片缓存与重试,帮助快速构建一致的界面。
w_tools_ui #
w_tools_ui 是 w_tools 的 UI 组件层,提供通用组件、布局、导航、扩展与屏幕适配工具。
文档分工:本文负责安装 / 快速开始 / 常用配方;模块边界、设计取舍与反例见
docs/modules/ui_module.md。
特性 #
- 通用组件:
WText/WImage/WButton/WBadge等 - 布局组件:
WScaffold/WAppBar/WListView/WStep - 导航组件:
WNavBar/WNavController/WTabBar - 扩展方法:颜色、字符串、数字、TextStyle、Widget、BoxDecoration 等
- 屏幕适配:
WScreen、间距与尺寸工具
安装 #
dependencies:
w_tools_ui: ^10.2.0
本包最低要求 Flutter 3.38.0。
依赖与平台 #
- 直接第三方依赖只有
cached_network_image(约束^3.3.1)。 - 它会传递带入
flutter_cache_manager、path_provider、sqflite、octo_image、rxdart、uuid等;移动 / 桌面用path_provider+sqflite做磁盘缓存, Web 走cached_network_image_web。 asset/file/base64/provider来源不经过网络缓存,但依赖仍在 pub 层, 不能靠“只用 asset 图”裁掉插件注册。- 已有
ImageProvider用WImageSource.provider接管加载。是否拆分缓存依赖见 ADR-0008。
快速开始 #
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)),
),
options: const WImageLoadOptions(memCacheWidth: 800),
);
所有来源统一走 WImage.source + WImageSource。
空 data('' / 纯空白)表示「没有配图」,不是加载失败:默认渲染中性 empty 占位,
不会触发 errorWidgetBuilder,也不会回调 onLoadStatusChanged(failed)。需要自定义时用
WImageSlots(emptyWidget: ...) 或 emptyBuilder: ...;要区分「空」和「加载失败」就在这里分支。
内置 loading / retry / 图片错误文案按当前 Locale 取中文或英文;
WButtonSemantics.loadingLabel / WImageSlots.retryLabel 传非空字符串可覆盖。
WImageError.message 是固定中文诊断文案(日志 / toString());UI 里用
error.localizedMessage(context) 跟随当前 Locale。
WImage不会自动给尺寸:没有width/height/aspectRatio时,必须由父级 (SizedBox/Expanded/AspectRatio)约束;否则在Row/Column/ListView里加载前占位是 0 尺寸,表现为空白(debug 下会打印提示)。注意
width + BoxFit.fitWidth不会确定高度;仍要补height、aspectRatio或让父级 在高度轴有界。aspectRatio不能和固定width/height同时设置:固定宽度 + 比例时用 父级AspectRatio,或只给aspectRatio。debug 提示会带脱敏 source,并按 source + 轴去重。
入口选择 #
| 场景 | 入口 |
|---|---|
| 已知网络 / 资源 / 文件 / Base64 | WImageSource.network/asset/file/base64 |
任意 ImageProvider / 内存字节 |
WImageSource.provider / ImageProvider + MemoryImage |
| 动态字符串,需要自动判定 | WImageSource.parse + WImage.source |
| 需要加载行为 | options: WImageLoadOptions(...) |
| 需要单图占位/错误/进度/重试 UI | slots: WImageSlots(...) |
| 没有配图 / 空 data | slots: WImageSlots(emptyWidget: ...) |
| 需要视觉样式 | style: WImageStyle(...) |
| 需要 App 级默认占位/错误/进度 | WImageTheme(slots: WImageSlots(...)) |
| 需要预加载 | await WImageSource.resolve(...) + precacheImage |
| 需要手动重试/状态 | controller: WImageController() |
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),
options: const WImageLoadOptions(memCacheWidth: 240, memCacheHeight: 240),
)
WImage.source(
source: WImageSource.network(url),
slots: const WImageSlots(showRetryButton: true),
)
WImage.source(source: WImageSource.asset('logo.png', prefix: true))
WImage.source(source: WImageSource.provider(MemoryImage(bytes)))
App 级默认占位只装一次:
WImageTheme(
slots: WImageSlots(
placeholderBuilder: (context, data) => const Center(child: CircularProgressIndicator()),
errorWidgetBuilder: (context, data, error) => const Icon(Icons.broken_image),
),
child: app,
)
预加载要与 WImage 使用同一套尺寸规则:
final provider = await WImageSource.network(url).resolve(memCacheWidth: 240);
await precacheImage(provider, context);
手动重试/状态监听:
final controller = WImageController();
WImage.source(
source: WImageSource.network(url),
controller: controller,
slots: const WImageSlots(showRetryButton: true),
);
controller.state.addListener(() => debugPrint('${controller.state.value.status}'));
// controller.dispose();
WImageStyle.width/height 只约束图片内容;padding / margin 会加在总尺寸上
(width: 10 + padding: 5 → 总尺寸 20),这一点与 Container 不同。
WImageStyle 也提供预设与链式糖:
WImageStyle.avatar(40)
WImageStyle.thumbnail(80)
WImageStyle.cover(aspectRatio: 16 / 9, radius: 12)
const WImageStyle().square(40).rounded(20)
宽度铺满 + 高度上限 #
宽度铺满、高度不超过 maxHeight,超出部分按 alignment 保留上 / 中 / 下。不需要新 API:
ConstrainedBox + fitWidth 就够了。
ConstrainedBox(
constraints: const BoxConstraints(maxHeight: 240),
child: WImage.source(
source: WImageSource.parse(url),
style: const WImageStyle(
width: double.infinity, // 必须:宽度要是紧约束,否则夹高时会被缩窄
fit: BoxFit.fitWidth,
alignment: Alignment.center, // topCenter 保上 / center 保中 / bottomCenter 保下
),
),
)
- 按宽度算出的高度 ≤
maxHeight时,与普通fitWidth完全一致; - 超过时盒子固定在
maxHeight,fitWidth会裁源图,alignment的 y 分量决定保留哪一段 (x 分量不起作用,宽度总是铺满); - 不要再给
style.height:固定高度会让上面的第一种情况也变成固定盒子; - 宽度约束不紧时(例如放在
Column里),图片会按原图宽度走,甚至被maxHeight缩窄, 所以显式写width: double.infinity或让父级给紧宽度;宽度无界时(Row/ 水平列表) 先给有界宽度,否则铺不满; - 加载前占位高度是 0,解码后才会展开;要避免跳动,优先在能拿到宽高时用
aspectRatio+cover在数据层夹比例,或先放一个已知高度的占位。
可运行示例见 example/lib/recipes_page.dart。
完整的网络、资源、Base64、进度、重试、主题与预加载示例见
example/。
10.0 迁移见
docs/migrations/ui-10.0.md; 9.0 迁移见docs/migrations/ui-9.0.md; 8.0 迁移见docs/migrations/ui-8.0.md; 7.0 迁移见docs/migrations/ui-7.0.md; 历史迁移见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)。
图标 + 文字一行:
WIconText(icon: Icons.star, text: '收藏');
WIconText(icon: Icons.location_on, text: '上海市', variant: WTextVariant.caption);
WIconText.custom(icon: SvgPicture.asset('assets/star.svg'), text: '收藏'); // 任意 Widget
不要用 Row + Icon + Text 手拼;中文行盒会让图标看起来偏高。需要按品牌字体微调时传
iconOffset,间距用 gap。
按钮与点击 #
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: ...,
);
// 自定义顶栏:WAppBar 或其他 PreferredSizeWidget(Material AppBar / SliverAppBar)
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));
WBadge(semanticLabel: '3 条未读', badgeContent: const Text('3'), child: const Icon(Icons.notifications));
WClipRRect(borderRadius: BorderRadius.circular(12), child: image);
WActionRow(children: [WButton(...), WButton(...)]);
状态与反馈 #
WGradientCircularProgressIndicator(radius: 24, value: 0.6, colors: const [Colors.indigo, Colors.lightBlue]);
WKeepAliveWrapper(child: item);
WNotificationListener<ScrollNotification>(
onNotificationPercentage: (p) { ... },
child: list,
)
导航 #
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(
style: const WNavBarStyle(),
controller: _controller,
itemBuilder: (context, index, selected) => Text('Tab $index'),
);
}
}
WNavController 需要页面 State 提供 vsync,并由调用方 dispose。
顶部 tab:
DefaultTabController(
length: 2,
child: Column(
children: [
WTabBar(
style: const WTabBarStyle(),
tabs: const [Text('全部'), Text('已完成')],
),
const Expanded(
child: TabBarView(
children: [Text('全部内容'), Text('已完成内容')],
),
),
],
),
)
WTabBar 不自带 controller,需要 DefaultTabController 或显式 TabController。
默认 overlay / 水波纹跟 TabBarTheme;要关闭灰色按压块 + ripple,用
WTabBarStyle.noSplash,或分别设置 overlayColor: Colors.transparent /
splashFactory: NoSplash.splashFactory。默认值不强制透明,避免覆盖 Material 主题。
扩展方法 #
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();
card.withStartPadding(8).withEndPadding(4); // 跟随 Directionality
2.borderSideOf(context); // 跟随 ColorScheme.outline(borderSide 已弃用)
const BoxDecoration()
.withColor(Colors.white)
.withBorderRadius(BorderRadius.circular(8));
扩展方法随 package:w_tools_ui/w_tools_ui.dart 一起导入。
工具 #
final screen = WScreen.of(context);
screen.w(16);
screen.h(24);
screen.sp(14);
WAssets.imagePath = 'assets/icons/';
'logo.png'.assetImagePath;
WScreen 无 scope / delegate 时返回原始值;需要 ScreenUtil 时在 App 根节点注入
WScreenScope:
WScreenScope(
widthScaler: (v) => ScreenUtil().setWidth(v),
heightScaler: (v) => ScreenUtil().setHeight(v),
fontScaler: (v) => ScreenUtil().setSp(v),
child: app,
);
10.0 起静态 WScreen.w/h/sp 与 WScreen.delegate* 已删除;
统一用 WScreenScope + WScreen.of(context)。
主要 API #
| 能力 | 入口 |
|---|---|
| 文本 / 图片 | WText / WImage |
| 按钮 / 点击 | WButton / WPressable |
| 徽标 / 横向操作 | WBadge / WActionRow / WSelectableRow |
| 裁剪 | WClipRRect |
| 加载指示 | WGradientCircularProgressIndicator |
| 列表保活 | WKeepAliveWrapper |
| 滚动通知 | WNotificationListener |
| 布局 | WScaffold / WAppBar / WListView |
| 导航 | WNavBar / WNavController / WTabBar |
| 屏幕工具 | WScreen / WScreenScope |
| 资源 | WAssets |
| 扩展 | WColorExtension / WImageStyleExtension / WStringExtension / WNumExtension / WWidgetExtension / WBoxDecorationExtension |
完整构造参数与成员见 pub.dev API 文档
或 packages/ui/lib 源码;模块边界与设计取舍见 docs/modules/ui_module.md。
License #
MIT