前端UI组件移动开发小程序【免费下载链接】wot-design-uni一个基于Vue3TS开发的uni-app组件库提供70高质量组件支持暗黑模式、国际化和自定义主题。项目地址https://gitcode.com/gh_mirrors/wo/wot-design-uni点击查看免费下载wd-badge是 wot-design-uni基于 Vue3 TypeScript 的 uni-app 组件库中用于在按钮、图标、文字旁展示数字或状态标记的基础组件。本文以官方组件文档 badge.md 为主线完整覆盖其基础用法、背景色定制、最大值、0 值展示、自定义内容与点状标注等全部示例并结合组件源码 wd-badge.vue、属性定义 types.ts 与样式 index.scss深入讲解每一项参数在底层的实际行为帮助你在使用中快速定位「为什么角标没显示」「为什么 max 不生效」这类问题。组件定位与默认插槽结构官方文档对 Badge 的定义是出现在按钮、图标旁的数字或状态标记典型场景是展示未读消息数量、新内容提示new/hot 标签以及需要关注的红点。从源码结构看组件模板非常简洁根节点是一个view默认插槽slot承载被标记的内容按钮、图标或文字徽标本体.wd-badge__content则是通过绝对定位悬浮在插槽内容右上角的独立viewtemplate view :class[wd-badge, customClass] :stylecustomStyle slot/slot view v-ifshouldShowBadge :class[wd-badge__content, is-fixed, type ? wd-badge__content-- type : , isDot ? is-dot : ] :stylecontentStyle {{ content }} /view /view /template对应地样式文件 index.scss 中根节点.wd-badge为position: relative; display: inline-block而徽标内容.is-fixed通过position: absolute; top: 0; right: 0; transform: translateY(-50%) translateX(50%)固定锚定在容器的右上角——这正是文档中所有示例徽标都出现在按钮右上角的布局原理。另外组件声明中带有virtualHost: true与styleIsolation: shared选项从源码结构看这是针对小程序端虚拟节点与样式隔离的适配使custom-class等外部样式类能够正常穿透生效。基础用法用 v-model 展示数字或字符串文档「基础用法」一节给出了最典型的未读消息场景wd-badge modelValue12 wd-button sizesmall评论/wd-button /wd-badge wd-badge modelValue12px wd-button sizesmall评论/wd-button /wd-badge第二个示例中modelValue12px直接原样渲染12px文本说明modelValue并不限定必须是「纯数字」而是接受Number或String。这一点可以在属性定义中得到印证types.ts 中modelValue使用的是公共的numericProp其定义为[Number, String]见 props.ts 第 5 行即同时接受数字与字符串两种类型。需要注意一个细节文档示例使用modelValue12这种字符串写法此时它不会被max属性参与比较后文「最大值」一节会展开。若希望徽标按数字逻辑如触发max截断工作应绑定响应式变量:modelValue12。仓库中的演示页 badge/Index.vue 正是使用:modelValue12的绑定方式。修改背景色type、bg-color 与 custom-class文档「修改背景色」一节提供了三种自定义角标外观的手段预设type、自定义bg-color以及通过custom-class定义整体样式wd-badge custom-classbadge modelValue3 bg-colorpink wd-button sizesmall回复/wd-button /wd-badge wd-badge custom-classbadge modelValue1 typeprimary wd-button sizesmall评论/wd-button /wd-badge wd-badge custom-classbadge modelValue2 typewarning wd-button sizesmall回复/wd-button /wd-badge wd-badge custom-classbadge modelValue1 typesuccess wd-button sizesmall评论/wd-button /wd-badge wd-badge custom-classbadge modelValue2 typeinfo wd-button sizesmall回复/wd-button /wd-badge配套的布局样式与 演示页 中的写法一致:deep(.badge) { margin: 0 30px 20px 0; display: inline-block; }三种手段在源码中的落地方式各不相同type模板中根据type值拼接修饰类wd-badge__content--primary等样式文件通过each $type in (primary, success, warning, info, danger)循环为每种类型分别指定background-color。其默认色值来自设计变量 variable.scss第 120~131 行全部以--wot-badge-*CSS 变量形式暴露--wot-badge-bg默认危险色、--wot-badge-primary、--wot-badge-success、--wot-badge-warning、--wot-badge-danger、--wot-badge-info、--wot-badge-color文字默认#fff、--wot-badge-fs字号默认12px、--wot-badge-height高度默认16px、--wot-badge-dot-size红点大小默认6px、--wot-badge-border边框默认2px solid #fff等。因此除了五个预设类型外你也可以全局覆盖--wot-badge-bg等 CSS 变量来自定义徽标主题。bg-color不走类名而是由contentStyle计算属性直接写入内联样式style.backgroundColor props.bgColor优先级高于type类名设置的背景色。单测用例「自定义背景颜色」wd-badge.test.ts 第 84~98 行验证了传入bgColor: #f50后节点 style 中会包含background-color:。custom-class作用于根节点对应.wd-badge适合调整角标整体的外边距、间距与块级形态如文档中margin: 0 30px 20px 0的横向排布。注意参数命名模板属性写作bg-colorkebab-case而 types.ts 中的 props 字段名为bgColorhidden/is-dot/show-zero同理模板中用连字符写法即可。最大值 max超过阈值显示「{max}」文档「最大值」一节由max属性定义它接受一个Number需要注意的是只有当modelValue为Number时它才会生效。wd-badge modelValue200 max99 wd-button sizesmall评论/wd-button /wd-badge wd-badge modelValue100 max10 wd-button sizesmall回复/wd-button /wd-badge效果是分别显示99与10。「只有 Number 才生效」这一约束直接体现在源码的计算属性content中const content computed(() { const { modelValue, max, isDot } props if (isDot) return let value modelValue if (value max isNumber(value) !Number.isNaN(value) !Number.isNaN(max)) { value max value ? ${max} : value } return value })要点有二截断条件是isNumber(value)严格typeof number判断见 util.ts 第 334~336 行因此modelValue200字符串与max99组合不会触发截断这是文档提醒的类型约束在代码层面的来源isDot为true时content直接返回空串红点模式下不渲染任何文本因此max与is-dot天然互不干扰。对应单测「最大值徽标」wd-badge.test.ts 第 54~66 行验证了modelValue: 100, max: 99时渲染文本为99。展示 0 值show-zero 与 is-dot 的优先级文档「展示 0 值」一节指出可用show-zero控制是否展示0且is-dot属性优先级高于show-zerois-dot为true时将始终显示红点wd-badge modelValue0 max99 show-zero wd-button sizesmall评论/wd-button /wd-badge wd-badge modelValue0 max10 wd-button sizesmall回复/wd-button /wd-badge默认情况下show-zero为falsemodelValue0的徽标完全不显示加上show-zero后显示0。该行为由模板中v-ifshouldShowBadge绑定的计算属性控制// 是否展示徽标数字 const shouldShowBadge computed(() !props.hidden (content.value || (content.value 0 props.showZero) || props.isDot))拆解该布尔表达式可见展示徽标需同时满足hidden为falsehidden优先级最高为true时一切隐藏以下三者之一成立content为真值非零、非空文本、content恰好等于0且showZero开启、或isDot为true。单测中「值为 0 且 showZero 为 false 时隐藏徽标」「值为 0 且 showZero 为 true 时显示徽标且文本为0」wd-badge.test.ts 第 161~188 行逐条验证了这两分支。仓库演示页 badge/Index.vue 的「显示 0 值」区块还额外给出了第三个组合:modelValue0 is-dot即 0 值场景下直接用红点替代数字与文档描述的「is-dot优先级高于show-zero」相互印证。自定义内容显示数字以外的文本文档「自定义内容」一节说明将modelValue定义为String类型时可以显示任意文本wd-badge modelValuenew wd-button sizesmall评论/wd-button /wd-badge wd-badge modelValuehot wd-button sizesmall回复/wd-button /wd-badge由于content计算属性对非数字值不做任何转换isNumber判断失败后直接return valuenew、hot等文本会被原样渲染在徽标胶囊内。此时徽标退化为一个「状态标签」而非计数常用于「NEW」「HOT」「VIP」等运营场景。徽标本身为white-space: nowrap且高度固定默认 16px文本过长时宽度会自适应撑开建议控制文本长度以保持视觉协调。点状标注 is-dot不显示数字的红点文档「点状标注」一节以红点的形式标注需要关注的内容。除了数字外设置is-dot属性它接受一个Boolean。wd-badge is-dot数据查询/wd-badge wd-badge is-dot wd-button classshare-button /wd-button /wd-badge点状模式不依赖modelValue只要is-dot为真shouldShowBadge即为真0 值、空值均可显示同时content计算属性强制返回空串因此红点内不出现任何文字。样式层面is-dot类命中 index.scss 中的when(dot)规则将徽标从「胶囊」变为「圆点」width/height取$-badge-dot-size默认 6px、padding: 0、border-radius: 50%背景色仍跟随bg-color或type。位置微调 top / right 与隐藏 hidden这两个参数未单独成章但出现在文档的 Attributes 表中且在源码中有明确实现。top/right为正时分别向下 / 向左偏移对应像素由contentStyle计算属性写入内联样式const contentStyle computed(() { const style: CSSProperties {} if (isDef(props.bgColor)) { style.backgroundColor props.bgColor } if (isDef(props.top)) { style.top addUnit(props.top) } if (isDef(props.right)) { style.right addUnit(props.right) } return objToStyle(style) })这里top/right使用公共numericProp[Number, String]定义并经由 util.ts 中的addUnit处理第 24~26 行非数值字符串原样透传数值则自动补px。因此:top4与right4px效果一致传rpx等自定义单位字符串也可以。单测「自定义顶部位置」「自定义右侧位置」wd-badge.test.ts 第 115~145 行分别断言了 style 中出现top: 10px、right: 20px。由于默认锚点位于容器右上角外侧translateY(-50%) translateX(50%)top/right常用于把角标拉回元素内部对齐特定图标。hidden布尔值为true时shouldShowBadge恒为false徽标整体不渲染但插槽内容按钮等不受影响。适合根据业务条件如已读后动态隐藏角标。Attributes 完整参数表汇总文档 Attributes 表并结合 types.ts 中badgeProps的默认值补全如下参数说明类型可选值默认值最低版本v-model显示值string / number---max最大值超过最大值会显示 {max}要求 value 是 Number 类型number---top为正时角标向下偏移对应的像素number---right为正时角标向左偏移对应的像素number---is-dot红色点状标注boolean-false-hidden隐藏 badgeboolean-false-type类型stringprimary / success / warning / danger / info--bg-color背景色string各种颜色的 css 写法--show-zero是否显示 0boolean-false0.1.62补充说明源码中is-dot、hidden声明为Boolean类型且未显式给默认值Vue 中即为falsetype的默认值为undefined即不拼接类型类名回落到默认危险色背景modelValue与top/right在源码中声明为[Number, String]故模板中:modelValue12、:top4等绑定均可使用组件通过...baseProps继承了两个公共参数见 props.ts 第 42~51 行custom-style根节点自定义内联样式与custom-class根节点自定义样式类单测中的「自定义类名」「自定义样式」两个用例对二者均有覆盖。外部样式类与暗色模式适配文档「外部样式类」表类名说明最低版本custom-class根节点样式-从源码看custom-class与custom-style直接绑定在根节点view上:class[wd-badge, customClass] :stylecustomStyle组件同时声明了addGlobalClass: true因此外部类可以命中根节点及其派生样式若需覆盖徽标胶囊本身.wd-badge__content的样式可借助:deep()穿透如文档示例中的排布写法。此外index.scss 开头包含一段.wot-theme-dark作用域的规则将徽标内容边框色切换为暗色背景$-dark-background2。也就是说当应用切换到暗色主题时徽标的白色描边会自动适配深色背景无需额外处理。徽标在设计变量与库内其他组件中的复用设计变量如前所述徽标全部视觉参数都收敛为 variable.scss第 120~131 行中的--wot-badge-*CSS 变量并带有默认回退值。这意味着在不修改组件的前提下仅通过页面级或全局 CSS 变量即可统一调整徽标的高度、字号、圆点大小与边框例如把--wot-badge-height调大以适配更大的图标。库内复用从源码结构看徽标能力还被其他组件直接复用。例如 wd-grid-item/types.ts 导入了BadgeProps/BadgeType提供badge-type、badge-value、badge-max、badge-props等透传参数使宫格图标右上角可以直接显示角标而无需手动嵌套wd-badge。类似的属性设计也出现在 tab / tabbar / sidebar 系列组件中。如果你的页面里需要「带角标的宫格项」优先查看对应组件自身的 badge 参数行为与本文wd-badge一致{max}截断规则相同。总结wd-badge虽然体积小但参数设计覆盖了角标场景的主要诉求计数v-modelmax仅对 Number 生效超出显示{max}0 值策略show-zero控制是否展示 0is-dot可无条件以红点代替外观type五档预设色、bg-color任意 CSS 色值内联样式优先级更高、--wot-badge-*CSS 变量全局主题化暗色模式自动适配边框布局默认锚定右上角top/right精确微调custom-class/custom-style控制根节点开关hidden一键隐藏角标而不影响内容。以上每一项行为都能在 wd-badge.vue 的content/contentStyle/shouldShowBadge三个计算属性中找到对应实现并由 wd-badge.test.ts 的 15 个用例逐一验证实际效果可对照演示页 badge/Index.vue 查阅。赞分享前端UI组件移动开发小程序【免费下载链接】wot-design-uni一个基于Vue3TS开发的uni-app组件库提供70高质量组件支持暗黑模式、国际化和自定义主题。项目地址https://gitcode.com/gh_mirrors/wo/wot-design-uni点击查看免费下载相关推荐Wot Design Uni 组件库中 wd-upload 异步上传功能解析Wot Design Uni 组件库中 wd upload 异步上传功能解析 背景介绍 Wot Design Uni 是一款基于 UniApp 的 UI 组件库前端UI组件移动开发小程序创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考