w_tools_ui 6.0.1
w_tools_ui: ^6.0.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 - 扩展方法:颜色、字符串、数字、Row / Column、TextStyle、Widget、BoxDecoration 等
- 屏幕适配:
WScreen、间距与尺寸工具
安装 #
dependencies:
w_tools_ui: ^6.0.0
本包最低要求 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(
body: Column(
children: const [
WAppBar(title: 'Demo'),
Expanded(
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。
入口选择 #
| 场景 | 入口 |
|---|---|
| 已知网络 / 资源 / 文件 / 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/。
导航 #
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/heightBox/widthBox/squareBox已在 5.0 删除; 直接用SizedBox/EdgeInsets。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。
主要 API #
| 能力 | 入口 |
|---|---|
| 文本 / 图片 | WText / WImage |
| 按钮 / 徽标 | WButton / WBadge / WActionRow / WSelectableRow |
| 裁剪 | WClipRRect |
| 加载指示 | WGradientCircularProgressIndicator |
| 列表保活 | WKeepAliveWrapper |
| 滚动通知 | WNotificationListenerBuilder |
| 布局 | WScaffold / WAppBar / WListView |
| 导航 | WNavBar / WNavController / WTabBar |
| 屏幕工具 | WScreen |
| 资源 | WAssets |
| 扩展 | WHexColor / WStringExtension / WNumExtension / WWidgetExtension / WBoxDecorationExtension |
License #
MIT