w_tools_ui 8.2.0
w_tools_ui: ^8.2.0 copied to clipboard
w_tools 的 UI 组件层:提供文本、图片、按钮、布局、导航与常用扩展,支持响应式尺寸、图片缓存与重试,帮助快速构建一致的界面。
8.2.0 #
Breaking #
WTabBarStyle.copyWith签名新增可选splashFactory:源码兼容,旧调用不需要改; 公开 API 快照把方法签名变化视为 Breaking。
Added #
WTabBarStyle.splashFactory/WTabBarStyle.noSplash:可显式关闭 tab 的 overlay 与水波纹; 默认仍交给TabBarTheme,不强制透明。
Changed #
WImage无尺寸提示带脱敏后的 source,并按 source + 轴去重;避免同一张图在测试 / 多个实例里反复刷屏。补充width + fitWidth仍需要 height / aspectRatio / 有界父级的文档。
8.1.0 #
8.0.0 #
Breaking #
- 删除
WNavBarConfig/WTabBarConfig/WBadgeConfig/WClipRRectConfig:统一用WNavBarStyle/WTabBarStyle与直接字段;WTabBar/WNavBar只接受style。 WBadge改用自有WBadgePosition/WBadgeStyle,不再转出badges包的BadgePosition/BadgeStyle;默认背景 / 前景改为ColorScheme.error/onError,badgeContent为空或showBadge: false时只渲染 child。WButtonStyle不再承载motion/semantics,改由WButton(motion:, semantics:); 删除WButtonMetrics与WButtonStyle.metrics。- 删除
WButtonEffectType,统一用WPressEffect;WButtonMotion.effect类型随之改变。 WButtonStyles.of返回WButtonStyleSet,不再返回匿名 record。- 删除
WNotificationListenerBuilder,统一用WNotificationListener。 WStepStyle.resolve返回WStepColors;WStep默认语义标签改为"<label> (<current>/<total>)",不再写死英文 "Step X of Y"。WPressable.excludeChildSemanticsWhenDisabled更名hasChildSemanticsWhenDisabled, 默认 true(与旧默认行为一致)。WAppBarStyle.copyWith/WStepStyle.copyWith改为传 null 表示保留,不再能清空字段。WScaffold未显式设置标题样式时优先WTextStyles.title(未安装时仍是titleLarge)。
成员级(逐条):
WClipRRect.config删除;WClipRRectConfig类型删除。WNavBar.config/WTabBar.config删除;WTabBar.style改为非空并使用默认值。WTabBarStyle.toConfig删除。WButtonStyle.filled/WButtonStyle.outlined/WButtonStyle.text去掉motion/semantics参数。WButtonStyle.motion/WButtonStyle.semantics/WButtonStyle.metrics删除。WPressable.new的excludeChildSemanticsWhenDisabled更名hasChildSemanticsWhenDisabled。WWidgetExtension.withBottomBarSpace/WWidgetExtension.withTopSafeSpace删除。WBadge.config/WBadge.badgeStyle/WBadge.position改为 8.0 自有类型或删除。WButton.debugStyleResolutionCount删除。WButtonMotion.new/WButtonMotion.copyWith的effect类型改为WPressEffect。WButtonStyle.copyWith去掉motion/semantics参数。WButtonSize.copyWith改为传 null 表示保留,不再使用_unset哨兵。WClipRRect.new/WNavBar.new/WActionRow.createState随构造 / 继承变化调整。
Removed #
WNavBarConfig、WTabBarConfig、WBadgeConfig、WClipRRectConfigWButtonMetrics、WButtonEffectType、WNotificationListenerBuilderbadges依赖与 barrel 里的BadgePosition/BadgeStyle转出
Added #
WButtonStyleSet、WStepColors、WBadgeStyle、WBadgePositionWButton.motion/WButton.semanticsWAppBarStyle.withBackground/WAppBarStyle.withoutBackground:在纯色与渐变之间安全切换WTabBarStyle.copyWith与WTabBarStyle值相等WScreenData值相等
Changed #
- README / example / catalog / AGENTS 模板全部切到
style与自有类型。 WImage的 provider cache key 只随来源变化(解码尺寸仍由ResizeImage统一应用)。WImageLoadOptions文件更名image_load_options.dart;WImageSlots/WImageTheme拆到独立文件(公开 API 不变)。
7.0.0 #
Breaking #
WImageLoadConfig更名WImageLoadOptions;同时把占位 / 错误 / 进度 / 重试 UI 拆到WImageSlots,Options 只保留解码、重试与 gapless 行为。WImageDefaultsScope(defaults: WImageLoadConfig(...))→WImageTheme(slots: WImageSlots(...)); 作用域只承载 UI 插槽,不再静默忽略重试/解码配置。- 删除
WImage.type/WImage.data(改用image.source.type/image.source.raw)。 - 删除
WImageStyle.merge(无法区分“未设置”和默认值,且无内部调用方);用copyWith。 WImageController.state改为非空,WImageLoadStatus新增idle,WImageLoadSnapshot.status不再可空; controller 增加dispose()。aspectRatio不能再与固定width/height同时设置。WImage.source只接受options:;7.0 重构期间新增的config:兼容别名未发布,直接删除。- 删除未使用的
WImageSlots.isEmpty。 - 扩展改名:
WImageStyleX→WImageStyleExtension、WHexColor→WColorExtension、WTextStylesThemeData→WThemeDataExtension;WNotificationListenerBuilderExtension删除。 WStepStyle.completedColor/currentColor/upcomingColor改为可空;未显式设置时 分别取ColorScheme.primary/primary/outline(6.1.1 默认是Colors.blue/Colors.grey)。WGradientCircularProgressIndicator.backgroundColor改为可空;未设置时取ColorScheme.surfaceContainerHighest(6.1.1 固定为0xFFEEEEEE)。WNavBar.config改为可空(默认不再注入const WNavBarConfig());读取.config的代码 需要处理 null,或改用style:。WScaffold.appBar类型从WAppBar?放宽为PreferredSizeWidget?;读取.appBar并依赖WAppBar类型的代码需要显式收窄。
Added #
WImageSource.resolve(...):生成与 WImage 一致尺寸规则的 provider,配合precacheImage。WImageProgress.isComplete/WImageProgress.complete():完成不再伪造 1/1 字节。WImageTheme/WImageSlots公开类型;WImageSlots同时支持固定 Widget、showRetryButton/retryLabel;新的WImageTheme只承载 slots, 与 4.x 已删除的同名类型语义不同。gaplessPlayback现在真正保留上一帧。WNavBarStyle/WTabBarStyle;WNavBar/WTabBar新增style:(config:仍是兼容入口)。WStepStyle.resolve(ColorScheme),把完成 / 当前 / 未开始颜色解析集中到一处。WNotificationListener<T>声明式滚动通知 / 百分比监听;旧WNotificationListenerBuilder仍是兼容入口。WButtonMetrics:WButtonStyle的布局 / 尺寸子集,支持fromStyle/applyTo/WButtonStyle.metrics。WBadge直接传position/showBadge/badgeStyle;WClipRRect直接传borderRadius。WButtonSize.name改为可选,省略时为空字符串;自定义尺寸不再强制命名。WWidgetExtension.withTopSafeSpaceOf/withBottomBarSpaceOf,读取当前MediaQuery。WNumExtension.borderSideOf(context)(主题 outline)与WBoxDecorationExtension.withBackground(...)。WScreen.reset()/WAssets.reset()(测试隔离用)。
Fixed #
borderRadius + border的边框改为绘制在图片之上,不再被图片盖住。aspectRatio作用在图片内容上,padding/margin 在外层。WImageStyle实现==/hashCode,避免相同样式被误判为变化。- build 期状态通知延后到 post-frame,外部监听器
setState不再崩溃。 - 相同进度只回调一次;progress-only 变化不再重建 WImage 子树。
onProgress完成回调、retryDelayMs实际延迟、尺寸提示的重复/单轴漏报修正。- 默认占位/错误占位改为从
ColorScheme派生,深色主题不再出现亮灰块。 WImageErrorView小尺寸优先保留重试按钮;160×90 等常见尺寸可操作。
Changed #
appbar.dart/tab_bar.dart拆出 style / config;list_view.dart的 sliver 拆为 part 文件。step.dart拆为step_types/step_style/step_flow;row_actions.dart拆为action_row/selectable_row。WImage内部拆出 provider 工厂、slots 合并 / 构建、Base64 解码、尺寸提示与 source 构建;WImageState从 526 行降到约 335 行,公开行为不变。WButton增加debugStyleResolutionCount(@visibleForTesting),用于验证样式缓存命中。WTabBar未配置overlayColor时不再强制透明,交给TabBarTheme/ Material 默认。WButtonStyle/WButtonMotion/WButtonSemantics/WAppBarStyle/WStepStyle支持值相等。WButton样式解析按 Theme 实例命中缓存,避免每次 build 计算ThemeData深哈希。
Deprecated #
WNotificationListenerBuilder(用WNotificationListener,8.0 移除)。WClipRRect.config/WBadge.config/withTopSafeSpace/withBottomBarSpace(8.0 移除)。
6.1.1 #
Fixed #
- 补齐 6.1.0 发布归档遗漏的示例与 README 同步:新增 6 个二级页,
Playground 代码面板改用
WImage.source,并补充 WText / WPressable / 布局 / 状态章节。
6.1.0 #
Added #
WImage在没有width/height/aspectRatio且父级约束无界时,debug 下输出一次性提示 (加载前占位为 0 尺寸,会表现为空白);release 无行为变化。
Changed #
WStepStyle.copyWith/WButtonSize.copyWith支持传null清空可空字段 (与 ADR-0004 的哨兵约定一致;数值字段仍接受int字面量)。
Fixed #
WBadge的badgeContent为空时不再断言崩溃,改为不渲染徽章。- README 安装约束同步为
^6.1.0,并补充WImage尺寸要求。
6.0.0 #
Removed #
- 移除
WImage(data:)/WImage.network/asset/file/base64/provider/memory。 - 移除
String.toImage/toAssetImage/toBase64Image/toFileImage/toNetworkImage。 - 统一使用
WImage.source(source: WImageSource...);迁移见docs/migrations/ui-6.0.md。
5.1.0 #
Deprecated #
WImage(data:)与WImage.network/asset/file/base64/provider/memory标记 deprecated, 统一迁移到WImage.source(WImageSource...);计划在 ui 6.0 移除。
5.0.1 #
5.0.0 #
Removed #
WRowButtons/WRowButtonsController:用WActionRow/WSelectableRow。WImage.avatar/thumbnail/cover/assetImage:用WImage+WImageStyle。WImageCachePolicy:直接配置PaintingBinding.instance.imageCache。WImageConfigtypedef:用WImageLoadConfig。WImageDefaults:用WImageDefaultsScope。- 7 个
WImage*Error子类:用WImageError.kind。 WRow/WColumn/WPadding/WSizeBox:用 Flutter 原生布局组件。WButtonStyles.primary/secondary/text/danger:用WButtonStyles.of(context)。
Changed(破坏性) #
WTabBarConfig/WBadgeConfig/WClipRRectConfig改为不可变:setter / 链式方法移除, 用const构造、factory 或copyWith。WClipRRectConfig.borderRadiusAll(12)→WClipRRectConfig.all(12)。
4.7.1 #
- 内部重构:
image.dart(846 行)拆为image.dart+image_state.dart(part,公开 API 不变)。
4.7.0 #
Changed #
WClipRRect/WBadge/WTabBar/WNavBar的config改为可选;省略时使用默认配置, 只传child/tabs/badgeContent即可渲染。
4.6.0 #
4.5.0 #
4.4.0 #
4.3.0 #
4.2.0 #
Changed #
WImageConfig更名WImageLoadConfig(字段不变);旧名保留为弃用 typedef,5.0 移除。WImageError新增kind(WImageErrorKind);7 个错误子类弃用(5.0 移除)。
4.1.0 #
Changed #
WImageLoader/WImageLoadSnapshot不再从公共 barrel 导出(内部实现);测试改用 src 导入。WImageCachePolicy弃用(5.0 移除):直接配置PaintingBinding.instance.imageCache。
4.0.0 #
Breaking #
WButton未传style时默认使用WButtonStyles.of(context).primary,颜色来自ColorScheme(primary/onPrimary、error/onError、outline);不再使用写死的#3949AB/#D32F2F。依赖旧默认色的页面请显式传WButtonStyle。WButtonStyles.primary/secondary/text/danger静态预设弃用(5.0 移除), 改用WButtonStyles.of(context)。
Added #
WButtonStyles.of(context):按ThemeData缓存的主题派生样式组。
3.2.0 #
Added #
WTextStyles.toTextTheme():把 11 个语义角色写进 MaterialTextTheme,每个角色占一个独立槽位;未涉及的槽位保留传入的TextTheme。ThemeData.withWTextStyles():一次装好TextTheme与 ThemeExtension。form / toast / async 只读Theme.of(context).textTheme,因此不需要依赖 w_tools_ui 就能跟随品牌排版。
Changed #
toTextTheme/fromTextTheme按 Material 的消费点映射:body同时写bodyLarge(输入框)与bodyMedium(正文),number不投影(避免表单输入变成数字样式);price从「等于 title」改为headlineSmall,bodyStrong改为titleMedium。依赖兜底样式的页面外观会略有变化。WTextStyles.of的兜底样式按TextTheme实例缓存(Expando),不再每次 build 重建 11 个TextStyle。
3.1.0 #
Changed #
WAppBar的图标改为IconTheme.merge:默认不再丢失ThemeData.iconTheme(此前会回落到黑色);标题按style.titleStyle→AppBarTheme.titleTextStyle→TextTheme.titleLarge回退,不再显示为正文样式。WImage.avatar/thumbnail/cover的style改为与预设合并(原来整体替换):显式字段覆盖预设,尺寸 / 圆角不再被静默丢掉;正方形预设只覆盖宽度时仍保持正方形。- 新增
WImageStyle.merge。
Fixed #
WImage.thumbnail的解码上限按合并后的尺寸推导,只覆盖宽度时不再沿用旧宽度的缓存尺寸。
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