Skip to main content

w_tools_ui 11.0.0 copy "w_tools_ui: ^11.0.0" to clipboard
w_tools_ui: ^11.0.0 copied to clipboard

w_tools 的 UI 组件层:提供文本、图片、按钮、布局、导航与常用扩展,支持响应式尺寸、图片缓存与重试,帮助快速构建一致的界面。

w_tools_ui #

pub package License: MIT

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: ^11.0.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.basic(
      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(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(emptyBuilder: ...)
需要视觉样式 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)
WImageStyle.cover().square(40) // 设置 width/height 时自动清空 aspectRatio

宽度铺满 + 高度上限 #

宽度铺满、高度不超过 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()]),
);
WText.rich(
  textSpan: TextSpan(
    text: '¥128',
    children: [TextSpan(text: ' 起', style: TextStyle(fontSize: 12))],
  ),
  variant: WTextVariant.price,
);

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: WButtonStyleSet.of(context).primary, onTap: add);
WButton(icon: Icons.favorite, tooltip: '收藏', isSelected: true, onTap: toggle);
WPressable(onTap: openDetail, child: card); // 任意 child,无 button 语义

任意 child / 卡片点击用 WPressable;需要键盘、最小点击区域或 button 语义时用 WButton。 图标按钮用 tooltip;toggle 按钮用 isSelected(进入 Semantics.selected)。 WButtonStyle.filled 未传 foregroundColor 时按背景亮度自动选黑 / 白。

页面骨架与布局 #

WScaffold.basic(
  title: '首页',
  actions: [IconButton(onPressed: ..., icon: const Icon(Icons.search))],
  floatingActionButton: FloatingActionButton(onPressed: ..., child: const Icon(Icons.add)),
  drawer: Drawer(...),        // drawer / endDrawer / bottomSheet / footer 均透传
  bottomSheet: ...,
  body: ...,
);

// 自定义顶栏:WAppBar 或其他 PreferredSizeWidget(Material AppBar / SliverAppBar)
WScaffold(appBar: WAppBar(title: '详情'), body: ...);

// 底栏不是 WNavBar 时:WScaffold(bottomNavigationBarSafeArea: true, ...)

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.count(count: 120, maxCount: 99, child: const Icon(Icons.notifications));
WBadge.dot(child: const Icon(Icons.notifications));
WBadge(offset: const Offset(4, -4), badgeContent: const Text('3'), child: const Icon(Icons.notifications));
WBadge(semanticLabel: '3 条未读', badgeContent: const Text('3'), child: const Icon(Icons.notifications));
WClipRRect 已删除;圆角裁剪直接用 Flutter 原生 `ClipRRect`:
ClipRRect(borderRadius: BorderRadius.circular(12), child: image);
WActionRow(children: [WButton(...), WButton(...)]);

状态与反馈 #

WGradientCircularProgressIndicator(radius: 24, value: 0.6, colors: const [Colors.indigo, Colors.lightBlue]);
WGradientCircularProgressIndicator(radius: 24, indeterminate: true, 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,
      onBeforeTap: (index) async => true, // 返回 false 阻止切换
      itemBuilder: (context, index, selected) => Text('Tab $index'),
    );
  }
}

WNavController 需要页面 State 提供 vsync,并由调用方 dispose。 WNavBar 默认 safeArea: true,会避开底部 home indicator;已在外层包 SafeArea 时传 safeArea: false。切换前拦截用 onBeforeTap(FutureOr<bool>)。 默认 item 可传 destinations: [WNavDestination(...)];完全自定义用 itemBuilder。

顶部 tab:

DefaultTabController(
  length: 2,
  child: Column(
    children: [
      WTabBar(
        style: const WTabBarStyle(
          labelColor: Colors.indigo,
          enableFeedback: false,
          indicatorAnimation: TabIndicatorAnimation.elastic,
        ),
        tabs: const [Text('全部'), Text('已完成')],
      ),
      const Expanded(
        child: TabBarView(
          children: [Text('全部内容'), Text('已完成内容')],
        ),
      ),
    ],
  ),
)

WTabBar 不自带 controller,需要 DefaultTabController 或显式 TabController。 WTabBarStyle 支持 labelColor / unselectedLabelColor / labelPadding / indicatorPadding / textScaler;默认 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 无 WScreenScope 时返回原始值;需要 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
裁剪 Flutter 原生 ClipRRect(WClipRRect 已删除)
加载指示 WGradientCircularProgressIndicator
列表保活 WKeepAliveWrapper
滚动通知 WNotificationListener
布局 WScaffold / WAppBar / WListView
导航 WNavBar / WNavController / WTabBar
屏幕工具 WScreen / WScreenScope
资源 WAssets
扩展 WColorExtension / WImageStyleExtension / WStringExtension / WNumLayoutExtension / WNumFormatExtension / WWidgetExtension / WBoxDecorationExtension

完整构造参数与成员见 pub.dev API 文档 或 packages/ui/lib 源码;模块边界与设计取舍见 docs/modules/ui_module.md。

License #

MIT

0
likes
115
points
2.23k
downloads

Documentation

API reference

Publisher

unverified uploader

Weekly Downloads

w_tools 的 UI 组件层:提供文本、图片、按钮、布局、导航与常用扩展,支持响应式尺寸、图片缓存与重试,帮助快速构建一致的界面。

Homepage
Repository (GitHub)
View/report issues
Contributing

Topics

#flutter #ui #widget #components

License

MIT (license)

Dependencies

cached_network_image, flutter

More

Packages that depend on w_tools_ui