Vant 4 ContactCard 联系人卡片组件完全指南从引入注册到主题定制【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vantContactCard联系人卡片是 Vant 4 移动端组件库中用于在表单类页面如结算、地址确认、联系人管理以卡片形式展示和编辑联系人信息的轻量组件。本文基于仓库中 ContactCard 官方文档 与其源码实现系统讲解组件的注册引入、添加/编辑/只读三种典型用法、完整 Props 与 Events API、类型定义并结合 ContactCard.tsx 与 index.less 剖析其底层基于 Cell 的渲染机制、可编辑状态控制和主题定制方式帮助你在实际业务中快速落地一个可复用的联系人卡片。组件介绍与适用场景根据官方文档ContactCard 的核心定位是Display contact information in the form of cards以卡片形式展示联系人信息。它是一个轻量展示型组件常用于以下业务场景结算页 / 下单页展示默认收货联系人或紧急联系人联系人管理页作为添加联系人入口联系人详情页以只读形式展示姓名与电话点击后进入编辑流程。从组件实现看ContactCard.tsx 内部直接复用了 Vant 的 Cell 单元格 组件通过v-slots将卡片内容注入 Cell 的 title 区域并分别设置icon、center、border{false}、isLink、titleClass等属性。因此 ContactCard 天然继承了 Cell 的布局能力、点击反馈rolebutton、tabindex与右侧箭头arrow图标渲染逻辑无需重复实现。安装与组件注册ContactCard 随 Vant 主包发布只需安装vant即可使用。官方文档给出的注册方式是全局注册import { createApp } from vue; import { ContactCard } from vant; const app createApp(); app.use(ContactCard);注册后即可在模板中直接使用van-contact-card /。这一能力来自 index.ts 中的withInstall封装实现在 packages/vant/src/utils/with-install.ts它会为组件挂载install方法同时导出命名导出ContactCard与默认导出。此外index.ts 中还通过declare module vue声明了VanContactCard全局组件类型因此在 TS 环境下模板中使用van-contact-card也能获得完整的类型提示。除了全局注册Vant 还支持按需引入等更多注册方式见 组件注册说明可按项目实际需要选择。典型用法文档提供了三个最核心的使用场景以下逐一展开并结合 官方 Demo 说明。添加联系人当页面处于尚无联系人状态时使用typeadd渲染一个添加入口卡片van-contact-card typeadd clickonAdd /import { showToast } from vant; export default { setup() { const onAdd () showToast(add); return { onAdd, }; }, };点击卡片会触发click事件业务侧可在回调中弹出添加联系人表单Demo 中仅以 Toast 占位示意。编辑联系人已有联系人数据时使用typeedit并传入name与tel展示姓名和手机号van-contact-card typeedit :teltel :namename clickonEdit /import { ref } from vue; import { showToast } from vant; export default { setup() { const tel ref(13000000000); const name ref(John Snow); const onEdit () showToast(edit); return { tel, name, onEdit, }; }, };name与tel均使用ref维护响应式数据实际项目中通常来自接口返回或全局状态。不可编辑只读展示当联系人不可修改例如订单快照、历史记录时将editable设为falsevan-contact-card typeedit nameJohn Snow tel13000000000 :editablefalse /此模式下卡片不再呈现可点击视觉右侧箭头消失且点击不会触发click事件。行为差异的源码印证这三种形态的差异在源码中都有明确对应ContactCard.tsx渲染内容typeadd时渲染props.addText未传时回退到国际化文案t(addContact)typeedit时渲染两行内容姓名xxx与电话xxx左侧图标edit类型使用contact图标add类型使用add-square图标可编辑控制onClick中先判断props.editable为true才emit(click, event)同时isLink{props.editable}决定是否显示右侧箭头文案国际化addContact文案在 locale/lang 目录 下随语言包提供如ar-SA.ts中为 إضافة جهة اتصال、bg-BG.ts中为 Добавяне на контакт 等默认英文为 Add contact info中文为添加联系人。单元测试同样印证了上述行为test/index.spec.ts默认情况下trigger(click)后断言click事件被触发一次而当editable为false时再次点击断言emitted(click)为空。API 详解Props以下参数表格完整来自官方文档并补充了源码 ContactCard.tsx 中的实现细节属性说明类型默认值type卡片类型可选值为editadd为默认添加态stringaddname联系人姓名edit类型下展示string-tel联系人手机号edit类型下展示string-add-text添加卡片时的文案提示add类型下展示stringAdd contact infoeditable是否允许编辑联系人控制点击事件与右侧箭头booleantrue源码中对应声明为type使用makeStringPropContactCardType(add)类型收窄为add | editContactCard.tsxname、tel均为String类型addText为String为空时走国际化兜底editable使用truthProp默认值为true。Events事件说明回调参数click点击组件时触发editable为false时不触发event: MouseEvent组件通过emits: [click]声明ContactCard.tsx回调携带原生MouseEvent对象。类型定义组件对外导出以下 TypeScript 类型见 index.tsimport type { ContactCardType, ContactCardProps } from vant;ContactCardTypeadd | edit联合类型ContactCardProps由ExtractPropTypestypeof contactCardProps推导的完整 Props 类型另有ContactCardThemeVars见 types.ts用于主题变量类型约束。主题定制与样式变量ContactCard 提供 4 个 CSS 变量用于样式定制默认值定义在 index.less 的:root, :host中与官方文档表格完全一致名称默认值说明--van-contact-card-paddingvar(--van-padding-md)卡片内边距--van-contact-card-add-icon-size40px添加态图标尺寸--van-contact-card-add-icon-colorvar(--van-primary-color)添加态图标颜色--van-contact-card-title-line-heightvar(--van-line-height-md)标题行高:root { --van-contact-card-padding: 16px; --van-contact-card-add-icon-size: 48px; --van-contact-card-add-icon-color: #ee0a24; --van-contact-card-title-line-height: 24px; }官方推荐通过 ConfigProvider 配置式组件 统一管理这类主题变量。变量在 index.less 中的实际作用包括.van-contact-card的padding由--van-contact-card-padding控制.van-contact-card__title的line-height与左侧margin-left: 5px共同保证两行文本对齐--add修饰类下左侧图标.van-cell__left-icon使用--van-contact-card-add-icon-color与--van-contact-card-add-icon-size组件底部通过::before伪元素绘制了一条由警告色与主题色组成的 45° 斜纹渐变条纹repeating-linear-gradientbackground-size: 80px形成 Vant 联系人卡片标志性的视觉分隔带。小结ContactCard 是 Vant 4 中一个小而精的表单配套组件对外仅暴露 5 个 Props 和 1 个事件却完整覆盖了添加入口、编辑展示、只读快照三种业务形态。其实现巧妙地复用 Cell 组件与多语言文案体系配合editable对点击事件和箭头图标的双重控制以及通过 4 个 CSS 变量即可完成的主题定制使开发者能够以极低的成本将联系人交互无缝接入移动端表单流程。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考