w_tools_ui 14.0.0
w_tools_ui: ^14.0.0 copied to clipboard
w_tools 的 UI 组件层:提供文本、图片、按钮、布局、导航与常用扩展,支持响应式尺寸、图片缓存与重试,帮助快速构建一致的界面。
14.0.0 #
Breaking #
WImage.source:删除;改为无名构造器WImage({required WImageSource source, ...})。 迁移只是WImage.source(→WImage(,source:/style:/options:/slots:参数与默认值不变。见docs/migrations/ui-14.0.md。
Changed #
- README 补充
WImageSource.file在 Web 上抛UnsupportedError。 - 测试稳定性 / 覆盖:图片宽度配方等待改为条件等待;补
WButtonTheme的outlined/text覆盖测试。无公开行为变化。
13.0.0 #
Breaking #
WButton.new:删除无名构造器;改用WButton.filled/.outlined/.text。WButton.variant/WButtonVariant:删除;按钮类型由命名的构造器决定。WButtonTheme.styleFor:删除;WButton内部按类型读取filled/outlined/text。WButtonTheme.new/WButtonTheme.danger/WButtonTheme.copyWith(danger:)/WButtonTheme.lerp的danger参数:删除;危险色用WButton.filled(style: AppButtons.danger(context))或style: FilledButton.styleFrom(...)表达,不再有全局 danger 槽。WScaffold.basic:删除;改用WScaffold(appBar: WAppBar(...))。WScaffold.title/WScaffold.titleWidget/WScaffold.leading/WScaffold.actions/WScaffold.onBack/WScaffold.automaticallyImplyLeading/WScaffold.centerTitle/WScaffold.appBarStyle/WScaffold.appBarBottom:删除(只服务.basic)。WScaffold只保留显式appBar与 body / 槽位。
Added #
WButton.filled/WButton.outlined/WButton.text:const命名构造器,分别渲染FilledButton/OutlinedButton/TextButton。WButtonTheme只保留filled/outlined/text三个类型槽。
Migration #
12.0.1 #
Changed #
- 文档注释:
.sp/WTextStyles的根装配位置改指WAppOptions.builder(配合w_tools_app4.0 删除插件包裹钩子)。
12.0.0 #
Added #
WButtonTheme:按钮四态(filled / outlined / text / danger)的 MaterialButtonStyleThemeExtension;未安装时按ColorScheme派生。WButtonVariant:filled/outlined/text/danger语义变体。WButton.semanticLabel/WButton.semanticHint/WButton.loadingLabel:替代WButtonSemantics;纯图标按钮仍要求语义标签。WColorExtension.fromCssHex/WColorExtension.toCssHex/WStringExtension.toCssColor:CSS / Figma 的RRGGBBAA字节序;fromHex/toHex仍是 Flutter 的AARRGGBB。
Breaking #
WNavController.new/WNavController.vsync:删除vsync参数与字段。选中态只维护currentIndex,不再持有动画资源,页面 State 不需要TickerProviderStateMixin。WNavController.dispose不再单独声明(继承ChangeNotifier)。WNavController.animation/WNavController.offset/WNavController.previousIndex/WNavController.indexIsChanging/WNavController.animateTo:删除。这些成员从未被WNavBar消费;切换直接赋值currentIndex,需要过渡动画时由页面自己绘制。WNavBar.new/WNavBar.style:删除style,改为直接接收decoration/padding(WNavBar.decoration/WNavBar.padding)。WScaffold.new/WScaffold.basic.new/WScaffold.underlayWidget:删除underlayWidget;背景叠层在页面层用Stack。WPressable.new/WPressable.hasChildSemanticsWhenDisabled:删除该参数;禁用时固定 保留 child 语义(原默认行为)。WNotificationListener.new/WNotificationListener.preventNotificationPropagation: 删除该参数;用onNotification返回true阻止冒泡。WImageErrorView.new/WImageErrorView.compact:删除compact参数;小尺寸由可用高度 自动降级(文案 / 操作按钮各有一个最小高度),不再需要第二套开关。WStep.new:构造函数恢复const;不再复制labels,由调用方保证列表不可变。WImageStyle.avatar/WImageStyle.thumbnail:删除;头像 / 缩略图直接用width+height(+borderRadius)。WButton.new/WButton.style/WButton.size/WButton.createState/WButton.contentBuilder/WButton.motion/WButton.semantics:WButton改为StatelessWidget并直接渲染 Material 按钮;size变为非空(默认 medium); 样式参数变成variant+style: ButtonStyle?,删除contentBuilder/motion/semantics(复杂内容用content,颜色由 Material 承接;无障碍用semanticLabel/semanticHint/loadingLabel)。WButtonStyle/WButtonStyleSet/WButtonMotion/WButtonSemantics/WButtonContentBuilder/WButtonResolvedStyle:删除;分别由 MaterialButtonStyle+WButtonTheme/WButtonVariant/ 直接参数替代。WNumFormatExtension(toThousandsSeparated/toCurrency/toPercent/toPercentWithFixed/toPadLeft):从 ui 删除,迁到w_tools_core3.2.0。WImageStyle.margin/WImageStyle.padding/WImageStyle.withoutMargin/WImageStyle.withoutPadding:删除;留白在外层包Padding/Container,width/height的尺寸语义与 Flutter 一致。WImage.new/WImage.source/WImage.controller:删除controller参数; 手动重试改用WImageSlots.errorWidgetBuilder的onRetry。WImageSlots.emptyBuilder/WImageSlots.progressBuilder/WImageSlots.showRetryButton/WImageSlots.retryLabel/WImageSlots.new: 删除;空 data / 加载中 / 等待重试统一走placeholderBuilder,错误走errorWidgetBuilder。WImageSlots.errorWidgetBuilder:签名增加VoidCallback onRetry第四参数 ((context, data, error, retry))。WImage._(WImage.source的实现构造):删除controller参数。WImageStyle.new/WImageStyle.copyWith:删除margin/padding参数。WImageSource.parse与各子类上的同签名成员(WNetworkImageSource.parse/WAssetImageSource.parse/WFileImageSource.parse/WBase64ImageSource.parse/WProviderImageSource.parse):删除;来源类型由调用方显式选择。WImageSource.asset与各子类上的同签名成员(WNetworkImageSource.asset/WAssetImageSource.asset/WFileImageSource.asset/WBase64ImageSource.asset/WProviderImageSource.asset)/WAssetImageSource.new/WAssetImageSource.prefix: 删除prefix参数;name改为完整资源路径。WAssets/WAssets.imagePath/WAssets.reset/WStringExtension.assetImagePath:删除;路径由WImageSource.asset('完整路径')显式传入。
Removed #
WTabBar/WTabBarStyle:MaterialTabBar的逐字参数镜像(22 个字段、零默认值); 直接用TabBar+TabBarTheme,noSplash用overlayColor+splashFactory。WImageController(含retry/state/isAttached与WImageController.dispose)与WImageLoadSnapshot:手动重试与状态观察已有errorWidgetBuilder的onRetry/WImage.onLoadStatusChanged/onProgress覆盖。WStepFlow:WStep的参数镜像(labels / style / 3 个 builder)+copyWith/build,与直接构造WStep等价;复用请复用参数本身。WNavBarStyle:只包decoration/padding两个字段,WNavBar直接接收。WGlobalKeyExtension/WGlobalKeyExtension.offset/WGlobalKeyExtension.rect:key.currentContext?.findRenderObject()+localToGlobal即可。WNumLayoutExtension.heightBox/WNumLayoutExtension.widthBox/WNumLayoutExtension.squareBox/WNumLayoutExtension.horizontalPadding/WNumLayoutExtension.verticalPadding/WNumLayoutExtension.borderRadius: 直接用SizedBox/EdgeInsets/BorderRadius构造(allPadding/borderSideOf保留)。WStringExtension.toInt/WStringExtension.toDouble/WStringExtension.toNum/WStringExtension.trimAll:直接用int.tryParse/double.tryParse/num.tryParse/replaceAll。WNumFormatExtension(toThousandsSeparated/toCurrency/toPercent/toPercentWithFixed/toPadLeft):迁到w_tools_core3.2.0;格式化与 UI 无关。WBoxDecorationExtension.withColor/WBoxDecorationExtension.withoutColor/WBoxDecorationExtension.withGradient/WBoxDecorationExtension.withoutGradient/WBoxDecorationExtension.withBorder/WBoxDecorationExtension.withoutBorder/WBoxDecorationExtension.withBorderRadius/WBoxDecorationExtension.withoutBorderRadius/WBoxDecorationExtension.withShadow/WBoxDecorationExtension.withoutShadow/WBoxDecorationExtension.withShape: 只保留withBackground(color / gradient 二选一,自动清空另一个)与circle; 其余字段直接传BoxDecoration构造器。
Fixed #
WScaffold.basic(title: '')不再静默丢失整条顶栏(含返回按钮);.basic一定渲染WAppBar,只有显式空title时不显示标题文本。WScaffold:删除重复两遍的includeStatusBar断言,以及构造函数已保证、永远为真的 「appBar 与 title 互斥」断言。WSelectableRow:删除只被透传、从未读取的滚动视图 key。
11.0.0 #
Added #
WNavDestination+WNavBar.destinations:底部导航的默认图标 / 文字项; 与itemBuilder二选一。WGradientCircularProgressIndicator.indeterminate:不确定进度(旋转弧段), 此时忽略value且语义不暴露百分比。WScaffold.basic:自动构建WAppBar的页面壳入口;WScaffold主构造器只保留 显式appBar与槽位。
Changed #
WScreen改为abstract final class:仍是静态命名空间,行为不变,只是禁止实例化 / 继承。
Breaking #
WButton.new/WBadge.new/WScaffold.new/WNavBar.new/WAppBarStyle.new/WAppBarStyle.copyWith/WTabBarStyle.new/WTabBarStyle.copyWith:10.3–10.5 引入的公开参数随 11.0.0 一起发布。直接调用源码兼容;把构造器 /copyWith作为函数值(tear-off)并显式声明旧签名时需要更新。WImageError.new/WListViewSliver.list/WListViewSliver.separated/WListViewSliver.grid/WListViewSliver.overlap:字段 / 参数改名导致的签名变化;WImageError仍是位置参数,WListViewSliver.keepAlive需要改成addAutomaticKeepAlives。WImageStyle.avatar/WImageStyle.copyWith/WImageStyle.borderRadius/WImageStyle.margin/WImageStyle.padding:几何类型放宽为BorderRadiusGeometry/EdgeInsetsGeometry;传BorderRadius/EdgeInsets的旧代码仍然兼容。WStep.new:构造时复制并冻结labels,因此不再是const构造器;const WStep(...)需要去掉const。WImageSlots.new:删除placeholder/emptyWidget/errorWidget固定 Widget 入口, 构造器签名变化;改用对应的*Builder。WNavBar.itemBuilder:类型改为可空,与新增的WNavBar.destinations二选一; 继续传itemBuilder的调用点不变,读取该字段的代码需要处理 null。WGradientCircularProgressIndicator.build:组件改为StatefulWidget, build 移到 State;不应直接调用组件的 build。WScaffold.new:title/titleWidget/leading/actions/onBack/appBarStyle/appBarBottom/automaticallyImplyLeading/centerTitle移到WScaffold.basic;主构造器只保留appBar与 body / 槽位。 旧WScaffold(title: ...)改为WScaffold.basic(title: ...)。
Removed #
WClipRRect:FlutterClipRRect的纯别名,默认值完全一致;圆角裁剪直接用ClipRRect。WNavBar.onItemTap:用onBeforeTap(FutureOr<bool>)。notifyScrollPercentage:内部实现细节,直接读ScrollNotification.metrics。WTextStyleExtension:直接用 FlutterTextStyle.copyWith。WUiWidgetExtension:合并到WWidgetExtension,toPressable方法仍在。WImageError.data:改名sourceValue(值相等 /toString同步)。WImageSlots.placeholder/WImageSlots.emptyWidget/WImageSlots.errorWidget: 删除固定 Widget 入口,统一用对应的*Builder。WImageSlots.validate:slots 不再有互斥字段,校验方法随之删除。WListViewSliver.keepAlive:改名addAutomaticKeepAlives,与 Flutter 语义对齐。WButtonStyles:合并到WButtonStyleSet.of(context)。WImageFrame:不再从 barrel 导出(图片装饰由WImageStyle负责)。WWidgetExtension.withHorizontalPadding/WWidgetExtension.withVerticalPadding/WWidgetExtension.withLeftPadding/WWidgetExtension.withRightPadding/WWidgetExtension.withTopPadding/WWidgetExtension.withBottomPadding:改用 FlutterPadding。WWidgetExtension.withBottomBarSpaceOf:改名withBottomSafeSpaceOf。WNumExtension:拆分为WNumLayoutExtension(布局糖)与WNumFormatExtension(数字格式化)。WScreen._:改为abstract final class后不再需要私有构造器。 迁移见docs/migrations/ui-11.0.md。
10.5.0 #
Breaking #
WAppBarStyle.copyWith增加leadingWidth/actionsPadding/boxShadow命名参数。WTabBarStyle.copyWith增加indicatorAnimation/mouseCursor/enableFeedback/splashBorderRadius命名参数(含 10.3.0 引入的颜色 / padding / textScaler 参数)。 两处直接调用源码兼容;把方法作为函数值(tear-off)并显式声明旧签名时需要更新。
Added #
WAppBarStyle.leadingWidth/actionsPadding/boxShadow:控制顶栏两侧布局与阴影 (自绘顶栏没有 Material elevation,阴影显式用boxShadow)。WBadge.offset(含WBadge.count/WBadge.dot):在position基础上额外位移。WTabBarStyle.indicatorAnimation/mouseCursor/enableFeedback/splashBorderRadius:补齐TabBar的交互类参数。WScaffold.bottomNavigationBarSafeArea:给非WNavBar的底栏包SafeArea。WButton.tooltip/isSelected:图标按钮提示与 toggle 语义(进入Semantics.selected)。
Tests #
- 新增值对象非 const 相等测试,覆盖
WAppBarStyle/WButtonStyle/WTabBarStyle/WStepStyle/WBadgeStyle/WImageStyle/WImageLoadOptions/WImageSlots等。
10.4.0 #
Breaking #
WTabBarStyle.new/WTabBarStyle.copyWith:10.3.0 增加的labelColor/unselectedLabelColor/labelPadding/indicatorPadding/textScaler仍随本版发布。 直接调用源码兼容;把copyWith作为函数值(tear-off)并显式声明旧签名时需要更新。
Added #
WScaffold透传drawer/endDrawer/bottomSheet/persistentFooterButtons/extendBody,需要这些槽位时不必改用原生Scaffold。WNavBar.onBeforeTap:FutureOr<bool> Function(int)?,返回false阻止切换; 同步 / 异步都支持。
Changed #
WTabBarStyle补齐标签颜色 / 布局参数(10.3.0 引入,随 10.4.0 一起发布)。
Deprecated #
WNavBar.onItemTap:改用onBeforeTap,remove-in: 11.0.0。
10.3.0 #
Breaking #
WTabBarStyle.copyWith增加labelColor/unselectedLabelColor/labelPadding/indicatorPadding/textScaler命名参数。直接调用源码兼容;把该方法作为函数值 (tear-off)并显式声明旧签名时需要更新。
Added #
WText.rich:富文本入口,子TextSpan可混排样式,同时复用variant/WTextStyles、maxLines/overflow/textScaler等排版参数。WTabBarStyle.labelColor/unselectedLabelColor/labelPadding/indicatorPadding/textScaler:补齐TabBar最常用的标签颜色与布局参数。WBadge.count(count:, maxCount:)/WBadge.dot():数量角标(超限显示maxCount+)与圆点角标。WNavBar.safeArea:默认true,自动避开底部 home indicator;外层已包SafeArea时传false。
Changed #
WActionRow/WSelectableRow:不同高度的子项改为垂直居中(原Wrap默认顶部对齐)。WButtonStyle.filled:未传foregroundColor时按背景亮度自动选黑 / 白,避免深色背景文字不可读。WImageStyle.copyWith:设置width/height且未显式传aspectRatio时清空比例, 修复WImageStyle.cover().square(40)触发断言的问题。
Fixed #
WImageLoadOptions补齐==/hashCode;WImage.didUpdateWidget不再因非 const options 每次重建都丢弃 gapless 上一帧。WImageController.dispose后重复释放 /retry是安全的空操作。WImageSlots合并结果不再同时保留 builder 与固定 Widget,维持自身互斥约定。WGlobalKeyExtension.offset()在组件尚未布局时返回 null,与rect()一致。
Deprecated #
notifyScrollPercentage:内部实现细节,remove-in: 11.0.0;请直接读ScrollNotification.metrics。
10.2.0 #
Added #
WIconText.custom:接收任意Widget图标(SVG / 资源图 / 品牌图标),复用行盒中点对齐、 gap / offset / 语义与文本样式;不引入flutter_svg依赖。
10.1.0 #
Added #
WImageError.localizedMessage(BuildContext):按当前Locale返回图片错误文案 (zh 中文 / 其他英文);message继续作为固定中文诊断文案。
10.0.0 #
Breaking #
- 删除全局
WScreen.w/h/sp与WScreen.delegateWidth/delegateHeight/delegateFont/reset;WScreen.of不再回退全局 delegate,统一用WScreenScopeWScreen.of(context).w/h/sp。
Removed #
WScreen.w、WScreen.h、WScreen.sp、WScreen.delegateWidth、WScreen.delegateHeight、WScreen.delegateFont、WScreen.reset。WNumExtension.borderSide;改用borderSideOf(context)。
9.0.0 #
Breaking #
WImageStyle.copyWith的参数从Object?改为具体类型;null表示保留字段。 清空可空字段改用withoutWidth/withoutHeight/withoutAspectRatio/withoutBorderRadius/withoutBorder/withoutBoxShadow/withoutMargin/withoutPadding/withoutSemanticLabel。WImageLoadOptions.copyWith的memCacheWidth/memCacheHeight改为int?;null表示保留。清空解码尺寸改用withoutMemCacheWidth/withoutMemCacheHeight。
Added #
WIconText:图标 + 文字一行,内部用WidgetSpan+PlaceholderAlignment.middle对齐行盒中点,替代手写Row + Icon + Text;支持variant/style/color、gap、iconSize(默认随textScaler缩放)、iconOffset、maxLines/overflow、semanticsLabel。WBadge.semanticLabel:给角标提供读屏上下文(如「3 条未读」);提供后气泡内容 不再单独朗读,child 的语义保持不变。WWidgetExtension.withStartPadding/withEndPadding:跟随Directionality的侧边距;withLeftPadding/withRightPadding继续表示物理方向。WScreenScope:在子树内注入宽度 / 高度 / 字体缩放,替代全局 delegate。WScreenData.w/h/sp:从WScreen.of(context)直接取缩放后的值;WScreenData构造器新增可选 scaler 字段(默认恒等)。
Changed #
WSelectableRow内部改用WPressable:增加按压 / hover 反馈与点击光标;外层仍是Semantics(button: true, selected: ...)。WButton的 loading 语义增加liveRegion:loading 切换时由读屏播报WButtonSemantics.loadingLabel。WButton(icon:, label:)内部改用WIconText的行盒中点对齐;补按钮四态 golden。- 内置文案按
Locale:WButtonSemantics.loadingLabel/WImageErrorView.retryLabel默认改为空字符串(空 = 按 Locale 取内置文案,zh 中文 / 其他英文);WImageErrorView的错误文案同步本地化;WImageError.message仍为固定中文。 WImageError/WTextStyles/WButtonResolvedStyle增加值相等;文档移除 8.0 已删除的badges引用、修正 example README 的topRight/ config 残留,并补充中文默认文案说明。
Removed #
WImageErrorKind.empty:空 data 从 8.1 起不再产生该错误,继续用WImageSlots.emptyWidget/emptyBuilder。
Deprecated(10.0 移除) #
WScreen.w/h/sp与WScreen.delegateWidth/delegateHeight/delegateFont: 改用WScreenScope+WScreen.of(context).w/h/sp;WScreen.of在无 scope 时回退旧 delegate。WNumExtension.borderSide:改用borderSideOf(context)跟随ColorScheme.outline。
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