w_tools_ui 3.0.0
w_tools_ui: ^3.0.0 copied to clipboard
w_tools 的 UI 组件层:提供文本、图片、按钮、布局、导航与常用扩展,支持响应式尺寸、图片缓存与重试,帮助快速构建一致的界面。
Changelog #
3.0.0 #
Fixed #
WImageLoader.dispose会清除排队中的重试状态;新增 retry 配置变化 / dispose 测试。WImageLoader在失败后修改 retry 配置时保留已有 error,避免 failed 状态变成无错误;补对应测试。GlobalKey扩展在非RenderBox上返回 null;HexColor.fromHex拒绝多个#;toPadLeft校验负数长度。
Changed #
- 移除已废弃的
Widget.withBottomSpace,改用withBottomPadding。 - 移除
WRow.iconWithText(与图标 + 文字光学对齐规范冲突)。 WSizeBox.size的child改为命名参数,与其他WSizeBox方法一致。WBadgeConfig增加showBadge()/isShown/badgeStyle();WClipRRect增加clipBehavior;WGradientCircularProgressIndicator增加semanticsLabel、colors/stops 校验与列表比较。WNotificationListenerBuilder.setPreventNotificationPropagation重命名为preventNotificationPropagation,并增加preventsPropagation只读 getter。- 移除
WKeepAliveWrapper.onDeactivated/onRevive:AutomaticKeepAlive下滚动保活不会触发这些 State 生命周期回调,保留会误导。 WGradientCircularProgressIndicator语义进度与绘制进度统一 clamp;WBadge显示徽章时断言badgeContent非空。WBadge在 build 时再次校验badgeContent,并防止空角标;WGradientCircularProgressIndicator增加value.isFinite断言与非有限数兜底。WRowButtonsController删除未使用的scrollThreshold;相同索引不再重复通知;补充 controller dispose 顺序文档。WRowButtonsController首次布局自动居中initialIndex,新增ensureVisible;overScroll增加非负断言;onCanTap文档说明应为轻量纯函数。WRowButtons初始居中现在尊重scrollToCenter;显式ensureVisible不受该开关限制。WRowButtonsController.selectedIndexNotifier改为只读ValueListenable<int?>,避免外部直接写 value 导致索引不同步。- 重命名:
num.toThousand→num.toThousandsSeparated;Widget.withBottomSafeSpace→Widget.withBottomBarSpace(后者明确是底部导航栏空间,不是系统 safe area);WScreen.bottomBarHeight→WScreen.bottomSafeAreaHeight。 - Navigation 加固:
WNavController.currentIndex会停止进行中的动画并在 dispose 后安全返回;WNavBar增加 button/selected 语义;WTabBar改为无状态并支持overlayColor。
Removed #
- 移除
WImagePreloader;WImage使用 FlutterImageCache,预加载用precacheImage。 - 移除
WRichText/WRichTextConfig;多色 / 多字重 / 可点击片段统一使用 FlutterText.rich+WTextStyles。 - 移除
WTextConfig与WText.config;WText统一使用WTextVariant/WTextStyles,局部覆盖用style/color;有字体信息时自动生成 strut。
2.1.0 #
- 新增
WTextVariant/WTextStyles:语义文字样式与ThemeExtension; WText增加variant、style、color、maxLines、softWrap、textScaler等参数;WTextConfig保留兼容。
2.0.0 #
Added #
WListViewSliver增加emptyFill,显式控制空态是否填满视口;shrinkWrap: true时必须为 false。WBoxDecorationExtension:withGradient/withShadow/withBorder/withBorderRadius/withColor及对应without.../circle。WGradients:vertical / horizontal / diagonal / radial 方向预设。WShadows:none / card / elevated / floating 中性阴影预设。withShadow复制为不可变列表;WGradients校验 colors/stops。toCurrency负数符号改为-$1,234.56;toPadLeft负数补零保留符号;toPercent整数结果不再带.0。HexColor.fromHex忽略前后空格;trimAll正则简化。- 删除
WImageExtension;图片预加载用precacheImage。 withIntrinsicHeight合并到WWidgetExtension,删除 Row/Column 专用扩展。withBottomSpace标记废弃,改用withBottomPadding。- 删除
WStrutStyleExtension与WUiTextStyleExtension.fromConfig;使用WTextConfig.toTextStyle()/toStrutStyle()。 WWidgetExtension.withDecoration:给 Widget 包一层DecoratedBox。
Breaking #
WStepConfig删除;WStep改为current(1 基)+labels+WStepState+WStepStyle,新增可复用WStepFlow,并支持semanticLabelBuilder。WListView拆为WListView+WListViewSliver:前者只负责独立滚动,后者只提供 sliver,可直接嵌入 SmartRefresher / NestedScrollView;删除WListViewConfig、buildByList、itemBuilderByT;重叠改为WListViewSliver.overlap的正向overlap。- 删除
WContainer/WContainerConfig;盒子直接用Container+BoxDecoration。 - 删除
WWidgetExtension.withContainer;WWidgetExtension只保留间距、展开和点击糖。 WNavBarConfig.containerConfig改为decoration+padding。- 旧的可变
WImageConfig/WImageConfigBuild删除;WImageStyle改为不可变视觉样式。 WImageConfigBuild扩展删除;用WImage.source/WImage.network/asset/file/base64。toImage(config:)改为toImage(style:);placeholder/errorWidget改为构造参数。WImage.onLoadProgress、progressIndicatorBuilder、cacheEnabled、fitCenter、size均已删除。WImageCacheManager改名WImagePreloader(3.0 已移除);WImageGlobalConfig拆为WImageDefaultsScope+WImageCachePolicy。WImageTheme/WImageThemeData改为WImageDefaultsScope/WImageDefaults; 默认占位/错误/进度统一为 builder。WImageStyle拆为视觉WImageStyle+ 加载WImageConfig;WImage/ 所有命名构造新增config参数,style不再包含 retry / placeholder / memCache / gaplessPlayback。WAppBarConfig/WScaffoldConfig删除;WAppBar改为显式WAppBarStyle+ leading/title/actions/bottom。WScaffold改为页面壳:title/actions 自动生成默认WAppBar,新增appBar覆盖、bottomNavigationBar、floatingActionButton、resizeToAvoidBottomInset。WScaffold的 PreferredSize 只包含 toolbar + bottom,状态栏由 WAppBar 绘制,避免重复;appBarBottom会触发默认 AppBar;WAppBarStyle增加 copyWith / validate。WScaffold.appBar覆盖只要求 WAppBar 包含状态栏;WAppBar 自身的 leading/centerTitle 不受限制, 但 WScaffold 上的同名参数必须保持默认。WAppBar 移除未使用的totalHeight; WAppBarStyle 的 backgroundColor/gradient 改为二选一。WScaffold安全区改用 MediaQuery;onBack优先于 automaticallyImplyLeading; 空字符串 title 不再创建默认 AppBar。WAppBarStyle.titleSpacing增加非负校验;补 appBarBottom + 状态栏高度测试。WAppBar默认包含状态栏背景;不再提供WAppBarPreferred/WTopBar。WButtonConfig/ 配置缓存 /WButtonThemeData删除;WButton改用显式WButtonStyle。WButton.enabled/loading改为组件参数。WButton删除任意child;改用content/contentBuilder,任意区域点击用WPressable。WButton删除shake、onSecondaryTap、onTapDown/Up/Cancel、onFocusChange/onHover、onPressedChanged、tooltip、enableFeedback、behavior、sizeName。WButton所有命名工厂(primary/secondary/text/danger)删除;统一用WButton(style: ...)。- 项目样式通过
AppButtons/WButtonStyle显式传入;WButtonStyles.primary仅作 fallback。 WButtonStyle的effect/pressedOpacity/pressedScale/animationDuration/curve/semanticLabel/ semanticHint/loadingLabel移到WButtonMotion/WButtonSemantics。WButtonStyle不再依赖WContainerConfig/WTextConfig;改为显式backgroundColor/gradient/border/borderRadius/boxShadow/padding/foregroundColor/textStyle。- 颜色/边框/阴影/文字改为
WidgetStateProperty,WButton解析为WButtonResolvedStyle; 支持 disabled/pressed/hovered/focused 状态组合。使用 disabled 状态色时需将disabledOpacity设为 1,避免双重禁用效果。 WButtonResolvedStyle暴露不可变states,contentBuilder可按状态改变内容结构。- 示例
AppButtons.primary改为WidgetStateProperty状态样式,示例页新增第 12 节演示。 WButton要求可交互按钮至少提供onTap/onLongPress,并让指针回调在禁用中不再触发; release 下没有回调时按 disabled 渲染;无onLongPress时不再安装长按识别器,避免延迟普通点击。- 只有
onLongPress时不启用键盘焦点,避免出现可聚焦但 Enter/Space 无响应的按钮。 withBackgroundColor同时清空gradient,避免背景色被渐变覆盖。WPressable保持纯指针点击,不参与键盘焦点;键盘操作统一用WButton。WPressable禁用时重置按下态;没有onTap/onLongPress时不再安装手势或 click cursor; 增加动画参数断言。WPressable回调增加_actionable守卫,禁用中手势不会触发 onTap/onLongPress。WPressable默认只阻断指针,不清理 child 的交互语义;可选excludeChildSemanticsWhenDisabled在禁用时排除 child 语义。- 增加
withBackgroundColor/withForegroundColor/withBorder/withBoxShadow/withTextStyle静态覆盖便利方法,以及withoutDecoration/withoutBorder/withoutBoxShadow/withoutTextStyle/withoutText/withoutForegroundColor/withoutFocusColor/withoutHoverColor。 withoutTextStyle只清 textStyle;同时清 textStyle 和 foregroundColor 用withoutText。Widget.toButton(config:)/toButton(style:)改为Widget.toPressable(...)。
Added #
- 新架构入口:
WImage.source(source:, style:)、sealedWImageSource、不可变WImageStyle、WImageFrame、WImageDefaultsScope。 - 场景预设:
WImage.avatar/WImage.thumbnail/WImage.cover/WImage.assetImage/WImage.memory/WImage.provider,以及WImageStyle.avatar/thumbnail/cover。 WImageStyle链式糖:square()/rounded()。WImageConfig(showRetryButton: true)+WImageErrorView内置错误/重试视图; 小尺寸自动只显示图标。WImageProviderError:provider/memory解码失败的错误类型。WImageDefaults.progressBuilder。WImageSource.parse保留字符串自动判定;WImage(data:, style:)与命名构造作为便利入口。WImageController.state:ValueListenable<WImageLoadSnapshot>(status/progress/attempt/error/retryScheduled)。WImageLoadSnapshot实现==/hashCode,emit()相同快照不重复通知。WImageCachePolicy:进程级ImageCache预算;WImageDefaultsScope管默认占位/错误/进度。- 重试定时器、错误分类、进度上报与状态去重移入
WImageLoader;WImage的 State 只做构建/渲染。 - 网络路径统一为
CachedNetworkImageProvider+Image,进度改用ImageChunkEvent; 磁盘缓存仍走cached_network_image。 String.toImage增加key/style/config/type/semanticLabel/controller/onProgress参数;style/config不可变,不会被修改。- 新增
String.toAssetImage({prefix})/toBase64Image()/toFileImage()/toNetworkImage()。 WImage默认构造支持显式type,与命名构造一致。WButtonStyle拆分为视觉WButtonStyle+ 动效WButtonMotion+ 语义WButtonSemantics;WButtonStyles.primary/secondary/text/danger预设保留。WButton支持label/icon/content/contentBuilder;复杂内容保留 button 语义、 loading、键盘和点击区域。WButton保留loading、loadingBuilder、focusNode、autofocus、semanticLabel、 48×48 hit target、focus/hover overlay、禁用隔离。WButtonSize支持lineHeight/letterSpacing,默认 small/medium/large 视觉高度 32/40/48, 实际 hit target 保持 48。- 新增
WButtonStyle.filled/outlined/text工厂。 - 新增
WPressable:任意 child 点击 + opacity/scale,不声明 button 语义、不负责样式/loading/最小区域。 button.dart拆出 content / effect / tap target 三个 part 文件。
Changed #
String.toImage的尺寸优先级改为显式width/height优先,size仅作 fallback。- 网络图的进度改由
Image.loadingBuilder的ImageChunkEvent上报。 WImage相关源码集中到lib/src/components/common/image/,导入路径统一为package:w_tools_ui/src/components/common/image/image.dart。
Fixed #
WImageLoader在completed/failed后忽略迟到的进度/markLoading/错误,完成时取消已排队的重试,beginAttempt清空旧进度。- 迟到的
loadingBuilder/errorBuilder不再覆盖已完成的图片;style 变化会清空上一帧缓存。 WImageController.state首次绑定后保持稳定,WImage 卸载后仍可安全移除监听。data:/file:前缀改为大小写不敏感(DATA:/FILE:)。showRetryButton只对网络/provider/文件错误显示重试,空数据/Base64/asset/unsupported 不显示。WImageErrorView的尺寸完全交给LayoutBuilder判断;compact/showAction仅作为显式覆盖参数。WImage.provider/WImage.memory复用 provider,避免每次 build 重新解析。WImageController同时绑定多个 WImage 时在 debug 下断言;WImageFrame渲染时复制boxShadow为不可变快照。WImage的key之前没有传给StatefulWidget,导致所有构造方式的key实际失效。- 修改
retryCount/retryDelay时会取消已排队的重试。 - 网络图的
completed状态改为在首帧到达时上报。 borderRadius现在同时作用于border与boxShadow。WImageStyle.validate()/WImageConfig.validate()在构造、更新、build 时复用;aspectRatio与固定宽高冲突时 debug assert。- 每个
WImage缓存 provider,避免每次 build 重新创建CachedNetworkImageProvider/AssetImage/FileImage。 WImagePreloader与WImageCachePolicy解耦(缓存预算只作用于 FlutterImageCache)。
1.1.0 #
说明:本版本删除了公开组件
WNetworkImageWithRetry。按 semver 这应当作为 2.0.0 发布; 发布时没有外部使用者,因此未回滚、也未提供兼容垫片。自 1.1.0 起该组件不再存在, 后续破坏性变更会按 major 发布。
Added #
WImage.network/WImage.asset/WImage.file/WImage.base64命名构造: 跳过字符串嗅探,类型确定,也不会因为 asset 名长得像 URL 而走错分支。WImageProgress+WImage.onProgress+WImageConfig.progressBuilder: 进度回调不再暴露cached_network_image的DownloadProgress。WImageError(sealed)与 6 个子类型(空数据 / 网络 / 资产 / Base64 / 文件 / 不支持平台):errorWidgetBuilder的第三个参数声明为WImageError(以前是dynamic),可以直接is分支。error.data统一为调用方传给WImage的原始data(网络错误以前给的是规范化后的 URL)。WImageConfig.memCacheWidth/memCacheHeight:限制解码尺寸(物理像素), 网络、资产、文件、Base64 全路径生效;列表缩略图必传。WImageConfig.aspectRatio:图片与占位符按固定宽高比布局,加载前后尺寸一致、列表不跳版。- 常用参数:
semanticLabel、excludeFromSemantics、gaplessPlayback、filterQuality、alignment、httpHeaders、cacheKey。 WImageConfig的配置项都是公开字段,可以直接读写(测试/调试不必再反查组件树);placeholder/errorWidget是只写的固定 Widget 便捷 setter,读回用对应的 builder 字段。WImageController:新增手动重试入口retry()(网络 / 资产 / 文件 / Base64 都有效), 可在错误占位里放"重试"按钮,不必再销毁重建。- 重试策略:只对
5xx/408/429/ 连接级失败重试,4xx直接失败; 间隔改为指数退避 + 抖动(上限 30s),避免同屏多图同时重试。
Changed #
- 资产图片统一走
Image.asset+ FlutterImageCache:支持 2x/3x 变体与package:资产, 不再额外缓存一份原始字节;WImageCacheManager因此不再被WImage使用(保留给预加载/统计)。 WImageGlobalConfig.maxCacheSize/maxCacheMemory现在同步到 FlutterImageCache(maximumSize/maximumSizeBytes),asset 与网络共用同一份缓存预算。- 网络图片只剩一条渲染路径:
WImage内部直接构建CachedNetworkImage, 重试/进度/状态都在自己的 State 里处理,不再经过额外的包装组件。 - 类型判定只在
initState/didUpdateWidget计算一次,去掉跨实例的全局类型缓存。 - Base64 解码后 ≤64KB 在主 isolate 解码(按 Base64 文本长度估算),超过才用
compute。 - 平台条件导入改用
dart.library.io判断,WASM 构建不再误编译dart:io。 WImageGlobalConfig.maxCacheSize默认值改为 1000,与 FlutterImageCache保持一致。- 进度换算(
DownloadProgress→WImageProgress)改为内部函数,WImageProgress.fromDownloadProgress不再暴露第三方类型。 WImageConfig/ 图片类型拆到独立文件;build/buildFilePath/buildBase64改为WImageConfigBuild扩展(通过image.dart导出,调用方式不变)。
Fixed #
data:前缀剥离只认data:image/:data:application/octet-stream;base64,...会被整串丢进base64Decode而失败。//开头的协议相对地址被判成网络图后没有补https:,请求必然失败。- 类型判定用 trim 后的值、但 asset/file/base64 分支仍用原始串:带空白的路径会加载失败。
- 文件图片忽略
memCacheWidth/memCacheHeight。 - 状态/进度回调的 post-frame 没有判断
mounted,组件已卸载仍会回调。 WImageConfig.buildBase64(裸串)会被判定成 asset(现在走显式构造)。- 重试不再对
404/403等永久失败生效,也不会让错误占位延迟retryCount × retryDelay才出现。 - 重试间隔固定、无抖动的问题(同屏图片会同步重试)。
- 状态去重与进度上报原本在网络路径重复实现一份,现在只剩一处,并补上了网络路径测试。
Removed #
WNetworkImageWithRetry:重试已内联到WImage,不再保留独立的公共组件。 迁移:WNetworkImageWithRetry(imageUrl: url, retryCount: 3, ...)→WImage.network(url, config: WImageConfig()..retryCount = 3); 需要手动重试时用WImageController。
Deprecated #
WImageConfig.cacheEnabled:资产图片已统一走 FlutterImageCache,该开关不再生效。WImageConfig.fitCenter():等价于fitContain(),将在 2.0 移除。
1.0.0 #
首次发布。
- 新增通用组件:
WText/WImage/WButton/WBadge/WNetworkImageWithRetry/WRowButtons等 - 新增布局组件:
WScaffold/WAppBar/WContainer/WListView/WStep - 新增导航组件:
WNavBar/WNavController/WTabs - 新增颜色、字符串、数字、Row / Column、TextStyle、Widget 等扩展
- 新增屏幕适配与间距工具:
WScreen/WSizeBox/WPadding/WAssets/WImageCacheManager - 最低要求 Flutter 3.27.0
WListView保留cacheExtent(Flutter 3.44 起标记 deprecated)以兼容 3.27–3.43