系人列表組件完全指南：從 API 到源碼級(jí)實(shí)現(xiàn)解析)
Vant 4 ContactList 聯(lián)系人列表組件完全指南從 API 到源碼級(jí)實(shí)現(xiàn)解析【免費(fèi)下載鏈接】vantA lightweight, customizable Vue UI library for mobile web apps.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/va/vantContactList 是 Vant 4 中用于展示聯(lián)系人列表的移動(dòng)端組件它整合了 Radio 單選、Cell 單元格、Tag 標(biāo)簽與固定底部按鈕等元素開箱即用地提供了「選擇聯(lián)系人 新增聯(lián)系人 編輯聯(lián)系人」的完整交互閉環(huán)。本文以 packages/vant/src/contact-list/README.md 為主線結(jié)合組件源碼、樣式文件與單元測(cè)試帶你掌握該組件的全部 Props / Events / 數(shù)據(jù)結(jié)構(gòu)并深入理解其底層實(shí)現(xiàn)原理與主題定制方式。組件定位與適用場(chǎng)景ContactList 的核心用途是展示聯(lián)系人列表并讓用戶從中選擇一個(gè)聯(lián)系人常見于收貨地址選擇、撥號(hào)列表、IM 好友選擇等業(yè)務(wù)頁(yè)面。它不是一個(gè)孤立組件而是對(duì)RadioGroup、Radio、Cell、Tag、Icon、Button等基礎(chǔ)組件的組合封裝見 ContactList.tsx因此其行為也繼承了這些基礎(chǔ)組件的交互特性。安裝與注冊(cè)ContactList 作為 Vant 4 的按需組件通過app.use全局注冊(cè)即可使用import { createApp } from vue; import { ContactList } from vant; const app createApp(); app.use(ContactList);更多注冊(cè)方式如局部注冊(cè)、自動(dòng)按需引入可參考 組件注冊(cè)。從源碼看組件通過withInstall包裝后導(dǎo)出見 packages/vant/src/contact-list/index.ts并同時(shí)聲明了VanContactList全局組件類型因此在script setup或模板中可直接使用van-contact-list而無需額外類型聲明?；A(chǔ)用法將聯(lián)系人數(shù)組傳入list用v-model綁定當(dāng)前選中聯(lián)系人的id再通過add、edit、select三個(gè)事件完成新增、編輯、選擇的業(yè)務(wù)處理van-contact-list v-modelchosenContactId :listlist default-tag-text默認(rèn) addonAdd editonEdit selectonSelect /import { ref } from vue; import { showToast } from vant; export default { setup() { const chosenContactId ref(1); const list ref([ { id: 1, name: 張三, tel: 13000000000, isDefault: true, }, { id: 2, name: 李四, tel: 1310000000, }, ]); const onAdd () showToast(新增); const onEdit (contact) showToast(編輯 contact.id); const onSelect (contact) showToast(選擇 contact.id); return { list, onAdd, onEdit, onSelect, chosenContactId, }; }, };default-tag-text用于給isDefault: true的聯(lián)系人渲染一個(gè)「默認(rèn)」標(biāo)簽當(dāng)業(yè)務(wù)中有明確的默認(rèn)聯(lián)系人時(shí)這一屬性能讓用戶在視覺上一眼識(shí)別。上述用法在官方 Demo 中有完整對(duì)應(yīng)實(shí)現(xiàn)可參考 packages/vant/src/contact-list/demo/index.vue。Props 詳解參數(shù)說明類型默認(rèn)值v-model當(dāng)前選中聯(lián)系人的 idnumber | string-list聯(lián)系人列表ContactListItem[][]add-text新建按鈕文案string新建聯(lián)系人default-tag-text默認(rèn)聯(lián)系人標(biāo)簽文案string-對(duì)照源碼 ContactList.tsxcontactListProps的定義與文檔完全一致export const contactListProps { list: Array as PropTypeContactListItem[], addText: String, modelValue: unknownProp, defaultTagText: String, };這里有兩個(gè)值得注意的源碼級(jí)細(xì)節(jié)modelValue使用unknownProp而非String/Number類型約束這意味著v-model綁定的聯(lián)系人 id 既可以是字符串也可以是數(shù)字甚至其他類型都會(huì)原樣透?jìng)髋c文檔中「number | string」的類型聲明相呼應(yīng)類型上更寬容。add-text的實(shí)際默認(rèn)值來自多語言文案組件內(nèi)部渲染按鈕文本時(shí)使用的是props.addText || t(addContact)見 ContactList.tsx其中t來自createNamespace的國(guó)際化能力。英文語言包中addContact為Add contact中文語言包中為添加聯(lián)系人見 packages/vant/src/locale/lang/en-US.ts 與 packages/vant/src/locale/lang/zh-CN.ts。因此文檔表格中標(biāo)注的新建聯(lián)系人/Add new contact是「未傳入 add-text 時(shí)按當(dāng)前語言包顯示的文案」隨ConfigProvider或setLang切換語言會(huì)自動(dòng)變化這比硬編碼默認(rèn)值更利于國(guó)際化。Events 事件事件名說明回調(diào)參數(shù)add點(diǎn)擊新增按鈕時(shí)觸發(fā)-edit點(diǎn)擊編輯按鈕時(shí)觸發(fā)contact: ContactListItemindex: numberselect切換選中的聯(lián)系人時(shí)觸發(fā)contact: ContactListItemindex: number組件聲明的 emits 為[add, edit, select, update:modelValue]見 ContactList.tsx四個(gè)事件的觸發(fā)時(shí)機(jī)與實(shí)現(xiàn)如下select點(diǎn)擊聯(lián)系人行觸發(fā)點(diǎn)擊任意一行Cell時(shí)組件會(huì)同時(shí)派發(fā)兩個(gè)事件見 ContactList.tsxconst onClick () { emit(update:modelValue, item.id); emit(select, item, index); };即先同步更新v-model的值再拋出select事件回調(diào)參數(shù)為完整的聯(lián)系對(duì)象與下標(biāo)。單元測(cè)試也驗(yàn)證了這一行為觸發(fā).van-radio__icon點(diǎn)擊后select事件被觸發(fā)且參數(shù)為[contactInfo, 0]見 packages/vant/src/contact-list/test/index.spec.ts。edit點(diǎn)擊編輯圖標(biāo)觸發(fā)右側(cè)的編輯圖標(biāo)Icon的edit圖標(biāo)包裹在Cell內(nèi)部為避免點(diǎn)擊編輯圖標(biāo)時(shí)誤觸發(fā)行選中邏輯源碼中調(diào)用了event.stopPropagation()阻斷冒泡見 ContactList.tsxconst renderEditIcon () ( Icon nameedit class{bem(edit)} onClick{(event) { event.stopPropagation(); emit(edit, item, index); }} / );這一實(shí)現(xiàn)細(xì)節(jié)保證了「編輯」與「選擇」兩個(gè)交互互不干擾。測(cè)試中點(diǎn)擊.van-contact-list__edit后edit事件觸發(fā)且參數(shù)同樣為[contactInfo, 0]見 index.spec.ts。add點(diǎn)擊底部按鈕觸發(fā)底部固定按鈕在組件最外層渲染點(diǎn)擊時(shí)直接emit(add)見 ContactList.tsx。測(cè)試中點(diǎn)擊.van-contact-list__add后add事件僅觸發(fā)一次見 index.spec.ts。ContactListItem 數(shù)據(jù)結(jié)構(gòu)鍵名說明類型id每位聯(lián)系人的唯一標(biāo)識(shí)number | stringname聯(lián)系人姓名stringtel聯(lián)系人手機(jī)號(hào)number | stringisDefault是否為默認(rèn)聯(lián)系人boolean | undefined源碼中該類型定義如下見 ContactList.tsxexport type ContactListItem { id?: Numeric; tel: Numeric; name: string; isDefault?: boolean; };與文檔表格稍有出入的是源碼中tel的類型為Numeric即number | string比文檔中標(biāo)注的_string_更寬松同時(shí)id在源碼中是可選的id?。這意味著即使列表項(xiàng)缺少id組件也能正常渲染只是v-model會(huì)接收到undefined。實(shí)際業(yè)務(wù)中建議始終為每個(gè)聯(lián)系人提供唯一的id作為 Radio 單選值與key標(biāo)識(shí)。組件渲染結(jié)構(gòu)源碼級(jí)原理理解組件的 DOM 結(jié)構(gòu)有助于樣式覆蓋與調(diào)試。從 ContactList.tsx 可以清晰看到三層骨架return () ( div class{bem()} RadioGroup modelValue{props.modelValue} class{bem(group)} {props.list props.list.map(renderItem)} /RadioGroup div class{[bem(bottom), van-safe-area-bottom]} Button round block typeprimary ... / /div /div );外層容器類名為van-contact-list通過height: 100%撐滿父容器見 index.less中部RadioGroupmodelValue直接透?jìng)鹘o RadioGroup作為整個(gè)列表的單選狀態(tài)源每個(gè)聯(lián)系人渲染為一個(gè)Cell其左側(cè)插槽是編輯圖標(biāo)、標(biāo)題插槽是「姓名電話」文本與可選 Tag、右側(cè)插槽是RadioiconSize固定為 18見 ContactList.tsx。Cell開啟了isLink與center屬性右側(cè)呈現(xiàn)箭頭與居中對(duì)齊底部固定按鈕區(qū)類名van-contact-list__bottom使用position: fixed固定在視口底部見 index.less并追加了van-safe-area-bottom類以適配 iPhone 底部安全區(qū)按鈕為roundblocktypeprimary的滿寬圓角主色按鈕高度 40px。此外defaultTagText的邏輯也很直觀僅當(dāng)item.isDefault為真且傳入了default-tag-text時(shí)才在標(biāo)題文本后追加一個(gè)typeprimary的圓角 Tag見 ContactList.tsx。類型定義組件從包入口導(dǎo)出了完整的 TypeScript 類型業(yè)務(wù)代碼中可以這樣引用import type { ContactListItem, ContactListProps } from vant;其中ContactListProps由ExtractPropTypestypeof contactListProps推導(dǎo)而來見 ContactList.tsx保證了聲明與實(shí)現(xiàn)永不脫節(jié)。在 packages/vant/src/contact-list/index.ts 中還額外導(dǎo)出了contactListProps與ContactListThemeVars類型供需要二次封裝或自定義主題的高級(jí)用戶使用。主題定制ContactList 提供以下 CSS 變量用于樣式定制可通過 ConfigProvider 組件 在全局或局部注入也可直接覆蓋在根節(jié)點(diǎn)上名稱默認(rèn)值描述--van-contact-list-paddingvar(--van-padding-sm) var(--van-padding-sm) 80px列表內(nèi)邊距底部 80px 為固定按鈕預(yù)留空間--van-contact-list-edit-icon-size16px編輯圖標(biāo)大小--van-contact-list-add-button-z-index999底部新增按鈕的層疊層級(jí)--van-contact-list-radio-colorvar(--van-primary-color)選中態(tài)單選圖標(biāo)的主題色--van-contact-list-item-paddingvar(--van-padding-md)每個(gè)聯(lián)系人的內(nèi)邊距這些變量的默認(rèn)值統(tǒng)一定義在 index.less 的:root, :host中其消費(fèi)位置與用途分別是--van-contact-list-padding→ 外層容器padding--van-contact-list-edit-icon-size→ 編輯圖標(biāo)font-size--van-contact-list-add-button-z-index→ 底部固定按鈕的z-index--van-contact-list-radio-color→ 通過.van-radio__icon--checked .van-icon選擇器覆蓋選中態(tài)圖標(biāo)的背景色與邊框色--van-contact-list-item-padding→ 每個(gè)Cell項(xiàng)的內(nèi)邊距。同時(shí)組件還導(dǎo)出了ContactListThemeVars類型見 packages/vant/src/contact-list/types.ts在使用 ConfigProvider 的theme-vars時(shí)可以獲得完整的類型提示import type { ContactListThemeVars } from vant; const themeVars: ContactListThemeVars { contactListEditIconSize: 20px, contactListRadioColor: #1989fa, contactListItemPadding: 16px, contactListAddButtonZIndex: 1000, };交互細(xì)節(jié)與最佳實(shí)踐結(jié)合源碼與測(cè)試總結(jié)幾條實(shí)戰(zhàn)經(jīng)驗(yàn)編輯與選擇互斥編輯圖標(biāo)通過stopPropagation與選中邏輯隔離因此無需在業(yè)務(wù)側(cè)做額外判斷v-model 同步時(shí)機(jī)select事件拋出時(shí)v-model已同步更新可直接在回調(diào)里讀取最新選中值默認(rèn)聯(lián)系人標(biāo)簽isDefault只是展示標(biāo)記組件本身不改變選中態(tài)如需進(jìn)入頁(yè)面即選中默認(rèn)聯(lián)系人應(yīng)像 Demo 那樣將chosenContactId初始化為默認(rèn)聯(lián)系人的id列表為空時(shí)組件仍會(huì)渲染底部的「新建聯(lián)系人」按鈕這是引導(dǎo)用戶新增的天然入口配合add跳轉(zhuǎn)新增頁(yè)即可形成完整流程滾動(dòng)容器中部RadioGroup區(qū)域設(shè)置了overflow-y: scroll與-webkit-overflow-scrolling: touch見 index.less聯(lián)系人較多時(shí)列表可獨(dú)立滾動(dòng)底部按鈕始終固定在視口底部。小結(jié)ContactList 是一個(gè)「小而完整」的業(yè)務(wù)型組件文檔覆蓋了安裝、基礎(chǔ)用法、全部 Props / Events、數(shù)據(jù)結(jié)構(gòu)、類型導(dǎo)出與主題定制源碼則揭示了它基于 RadioGroup Cell Tag Button 的組合實(shí)現(xiàn)、unknownProp的寬容類型設(shè)計(jì)、國(guó)際化默認(rèn)文案機(jī)制以及編輯/選擇事件隔離等細(xì)節(jié)。掌握這些信息后無論是直接使用、二次封裝還是深度定制主題你都能做到心中有數(shù)。【免費(fèi)下載鏈接】vantA lightweight, customizable Vue UI library for mobile web apps.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/va/vant創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Vant 4 ContactList 聯(lián)系人列表組件完全指南：從 API 到源碼級(jí)實(shí)現(xiàn)解析
Vant 4 ContactList 聯(lián)系人列表組件完全指南從 API 到源碼級(jí)實(shí)現(xiàn)解析【免費(fèi)下載鏈接】vantA lightweight, customizable Vue UI library for mobile web apps.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/va/vantContactList 是 Vant 4 中用于展示聯(lián)系人列表的移動(dòng)端組件它整合了 Radio 單選、Cell 單元格、Tag 標(biāo)簽與固定底部按鈕等元素開箱即用地提供了「選擇聯(lián)系人 新增聯(lián)系人 編輯聯(lián)系人」的完整交互閉環(huán)。本文以 packages/vant/src/contact-list/README.md 為主線結(jié)合組件源碼、樣式文件與單元測(cè)試帶你掌握該組件的全部 Props / Events / 數(shù)據(jù)結(jié)構(gòu)并深入理解其底層實(shí)現(xiàn)原理與主題定制方式。組件定位與適用場(chǎng)景ContactList 的核心用途是展示聯(lián)系人列表并讓用戶從中選擇一個(gè)聯(lián)系人常見于收貨地址選擇、撥號(hào)列表、IM 好友選擇等業(yè)務(wù)頁(yè)面。它不是一個(gè)孤立組件而是對(duì)RadioGroup、Radio、Cell、Tag、Icon、Button等基礎(chǔ)組件的組合封裝見 ContactList.tsx因此其行為也繼承了這些基礎(chǔ)組件的交互特性。安裝與注冊(cè)ContactList 作為 Vant 4 的按需組件通過app.use全局注冊(cè)即可使用import { createApp } from vue; import { ContactList } from vant; const app createApp(); app.use(ContactList);更多注冊(cè)方式如局部注冊(cè)、自動(dòng)按需引入可參考 組件注冊(cè)。從源碼看組件通過withInstall包裝后導(dǎo)出見 packages/vant/src/contact-list/index.ts并同時(shí)聲明了VanContactList全局組件類型因此在script setup或模板中可直接使用van-contact-list而無需額外類型聲明?；A(chǔ)用法將聯(lián)系人數(shù)組傳入list用v-model綁定當(dāng)前選中聯(lián)系人的id再通過add、edit、select三個(gè)事件完成新增、編輯、選擇的業(yè)務(wù)處理van-contact-list v-modelchosenContactId :listlist default-tag-text默認(rèn) addonAdd editonEdit selectonSelect /import { ref } from vue; import { showToast } from vant; export default { setup() { const chosenContactId ref(1); const list ref([ { id: 1, name: 張三, tel: 13000000000, isDefault: true, }, { id: 2, name: 李四, tel: 1310000000, }, ]); const onAdd () showToast(新增); const onEdit (contact) showToast(編輯 contact.id); const onSelect (contact) showToast(選擇 contact.id); return { list, onAdd, onEdit, onSelect, chosenContactId, }; }, };default-tag-text用于給isDefault: true的聯(lián)系人渲染一個(gè)「默認(rèn)」標(biāo)簽當(dāng)業(yè)務(wù)中有明確的默認(rèn)聯(lián)系人時(shí)這一屬性能讓用戶在視覺上一眼識(shí)別。上述用法在官方 Demo 中有完整對(duì)應(yīng)實(shí)現(xiàn)可參考 packages/vant/src/contact-list/demo/index.vue。Props 詳解參數(shù)說明類型默認(rèn)值v-model當(dāng)前選中聯(lián)系人的 idnumber | string-list聯(lián)系人列表ContactListItem[][]add-text新建按鈕文案string新建聯(lián)系人default-tag-text默認(rèn)聯(lián)系人標(biāo)簽文案string-對(duì)照源碼 ContactList.tsxcontactListProps的定義與文檔完全一致export const contactListProps { list: Array as PropTypeContactListItem[], addText: String, modelValue: unknownProp, defaultTagText: String, };這里有兩個(gè)值得注意的源碼級(jí)細(xì)節(jié)modelValue使用unknownProp而非String/Number類型約束這意味著v-model綁定的聯(lián)系人 id 既可以是字符串也可以是數(shù)字甚至其他類型都會(huì)原樣透?jìng)髋c文檔中「number | string」的類型聲明相呼應(yīng)類型上更寬容。add-text的實(shí)際默認(rèn)值來自多語言文案組件內(nèi)部渲染按鈕文本時(shí)使用的是props.addText || t(addContact)見 ContactList.tsx其中t來自createNamespace的國(guó)際化能力。英文語言包中addContact為Add contact中文語言包中為添加聯(lián)系人見 packages/vant/src/locale/lang/en-US.ts 與 packages/vant/src/locale/lang/zh-CN.ts。因此文檔表格中標(biāo)注的新建聯(lián)系人/Add new contact是「未傳入 add-text 時(shí)按當(dāng)前語言包顯示的文案」隨ConfigProvider或setLang切換語言會(huì)自動(dòng)變化這比硬編碼默認(rèn)值更利于國(guó)際化。Events 事件事件名說明回調(diào)參數(shù)add點(diǎn)擊新增按鈕時(shí)觸發(fā)-edit點(diǎn)擊編輯按鈕時(shí)觸發(fā)contact: ContactListItemindex: numberselect切換選中的聯(lián)系人時(shí)觸發(fā)contact: ContactListItemindex: number組件聲明的 emits 為[add, edit, select, update:modelValue]見 ContactList.tsx四個(gè)事件的觸發(fā)時(shí)機(jī)與實(shí)現(xiàn)如下select點(diǎn)擊聯(lián)系人行觸發(fā)點(diǎn)擊任意一行Cell時(shí)組件會(huì)同時(shí)派發(fā)兩個(gè)事件見 ContactList.tsxconst onClick () { emit(update:modelValue, item.id); emit(select, item, index); };即先同步更新v-model的值再拋出select事件回調(diào)參數(shù)為完整的聯(lián)系對(duì)象與下標(biāo)。單元測(cè)試也驗(yàn)證了這一行為觸發(fā).van-radio__icon點(diǎn)擊后select事件被觸發(fā)且參數(shù)為[contactInfo, 0]見 packages/vant/src/contact-list/test/index.spec.ts。edit點(diǎn)擊編輯圖標(biāo)觸發(fā)右側(cè)的編輯圖標(biāo)Icon的edit圖標(biāo)包裹在Cell內(nèi)部為避免點(diǎn)擊編輯圖標(biāo)時(shí)誤觸發(fā)行選中邏輯源碼中調(diào)用了event.stopPropagation()阻斷冒泡見 ContactList.tsxconst renderEditIcon () ( Icon nameedit class{bem(edit)} onClick{(event) { event.stopPropagation(); emit(edit, item, index); }} / );這一實(shí)現(xiàn)細(xì)節(jié)保證了「編輯」與「選擇」兩個(gè)交互互不干擾。測(cè)試中點(diǎn)擊.van-contact-list__edit后edit事件觸發(fā)且參數(shù)同樣為[contactInfo, 0]見 index.spec.ts。add點(diǎn)擊底部按鈕觸發(fā)底部固定按鈕在組件最外層渲染點(diǎn)擊時(shí)直接emit(add)見 ContactList.tsx。測(cè)試中點(diǎn)擊.van-contact-list__add后add事件僅觸發(fā)一次見 index.spec.ts。ContactListItem 數(shù)據(jù)結(jié)構(gòu)鍵名說明類型id每位聯(lián)系人的唯一標(biāo)識(shí)number | stringname聯(lián)系人姓名stringtel聯(lián)系人手機(jī)號(hào)number | stringisDefault是否為默認(rèn)聯(lián)系人boolean | undefined源碼中該類型定義如下見 ContactList.tsxexport type ContactListItem { id?: Numeric; tel: Numeric; name: string; isDefault?: boolean; };與文檔表格稍有出入的是源碼中tel的類型為Numeric即number | string比文檔中標(biāo)注的_string_更寬松同時(shí)id在源碼中是可選的id?。這意味著即使列表項(xiàng)缺少id組件也能正常渲染只是v-model會(huì)接收到undefined。實(shí)際業(yè)務(wù)中建議始終為每個(gè)聯(lián)系人提供唯一的id作為 Radio 單選值與key標(biāo)識(shí)。組件渲染結(jié)構(gòu)源碼級(jí)原理理解組件的 DOM 結(jié)構(gòu)有助于樣式覆蓋與調(diào)試。從 ContactList.tsx 可以清晰看到三層骨架return () ( div class{bem()} RadioGroup modelValue{props.modelValue} class{bem(group)} {props.list props.list.map(renderItem)} /RadioGroup div class{[bem(bottom), van-safe-area-bottom]} Button round block typeprimary ... / /div /div );外層容器類名為van-contact-list通過height: 100%撐滿父容器見 index.less中部RadioGroupmodelValue直接透?jìng)鹘o RadioGroup作為整個(gè)列表的單選狀態(tài)源每個(gè)聯(lián)系人渲染為一個(gè)Cell其左側(cè)插槽是編輯圖標(biāo)、標(biāo)題插槽是「姓名電話」文本與可選 Tag、右側(cè)插槽是RadioiconSize固定為 18見 ContactList.tsx。Cell開啟了isLink與center屬性右側(cè)呈現(xiàn)箭頭與居中對(duì)齊底部固定按鈕區(qū)類名van-contact-list__bottom使用position: fixed固定在視口底部見 index.less并追加了van-safe-area-bottom類以適配 iPhone 底部安全區(qū)按鈕為roundblocktypeprimary的滿寬圓角主色按鈕高度 40px。此外defaultTagText的邏輯也很直觀僅當(dāng)item.isDefault為真且傳入了default-tag-text時(shí)才在標(biāo)題文本后追加一個(gè)typeprimary的圓角 Tag見 ContactList.tsx。類型定義組件從包入口導(dǎo)出了完整的 TypeScript 類型業(yè)務(wù)代碼中可以這樣引用import type { ContactListItem, ContactListProps } from vant;其中ContactListProps由ExtractPropTypestypeof contactListProps推導(dǎo)而來見 ContactList.tsx保證了聲明與實(shí)現(xiàn)永不脫節(jié)。在 packages/vant/src/contact-list/index.ts 中還額外導(dǎo)出了contactListProps與ContactListThemeVars類型供需要二次封裝或自定義主題的高級(jí)用戶使用。主題定制ContactList 提供以下 CSS 變量用于樣式定制可通過 ConfigProvider 組件 在全局或局部注入也可直接覆蓋在根節(jié)點(diǎn)上名稱默認(rèn)值描述--van-contact-list-paddingvar(--van-padding-sm) var(--van-padding-sm) 80px列表內(nèi)邊距底部 80px 為固定按鈕預(yù)留空間--van-contact-list-edit-icon-size16px編輯圖標(biāo)大小--van-contact-list-add-button-z-index999底部新增按鈕的層疊層級(jí)--van-contact-list-radio-colorvar(--van-primary-color)選中態(tài)單選圖標(biāo)的主題色--van-contact-list-item-paddingvar(--van-padding-md)每個(gè)聯(lián)系人的內(nèi)邊距這些變量的默認(rèn)值統(tǒng)一定義在 index.less 的:root, :host中其消費(fèi)位置與用途分別是--van-contact-list-padding→ 外層容器padding--van-contact-list-edit-icon-size→ 編輯圖標(biāo)font-size--van-contact-list-add-button-z-index→ 底部固定按鈕的z-index--van-contact-list-radio-color→ 通過.van-radio__icon--checked .van-icon選擇器覆蓋選中態(tài)圖標(biāo)的背景色與邊框色--van-contact-list-item-padding→ 每個(gè)Cell項(xiàng)的內(nèi)邊距。同時(shí)組件還導(dǎo)出了ContactListThemeVars類型見 packages/vant/src/contact-list/types.ts在使用 ConfigProvider 的theme-vars時(shí)可以獲得完整的類型提示import type { ContactListThemeVars } from vant; const themeVars: ContactListThemeVars { contactListEditIconSize: 20px, contactListRadioColor: #1989fa, contactListItemPadding: 16px, contactListAddButtonZIndex: 1000, };交互細(xì)節(jié)與最佳實(shí)踐結(jié)合源碼與測(cè)試總結(jié)幾條實(shí)戰(zhàn)經(jīng)驗(yàn)編輯與選擇互斥編輯圖標(biāo)通過stopPropagation與選中邏輯隔離因此無需在業(yè)務(wù)側(cè)做額外判斷v-model 同步時(shí)機(jī)select事件拋出時(shí)v-model已同步更新可直接在回調(diào)里讀取最新選中值默認(rèn)聯(lián)系人標(biāo)簽isDefault只是展示標(biāo)記組件本身不改變選中態(tài)如需進(jìn)入頁(yè)面即選中默認(rèn)聯(lián)系人應(yīng)像 Demo 那樣將chosenContactId初始化為默認(rèn)聯(lián)系人的id列表為空時(shí)組件仍會(huì)渲染底部的「新建聯(lián)系人」按鈕這是引導(dǎo)用戶新增的天然入口配合add跳轉(zhuǎn)新增頁(yè)即可形成完整流程滾動(dòng)容器中部RadioGroup區(qū)域設(shè)置了overflow-y: scroll與-webkit-overflow-scrolling: touch見 index.less聯(lián)系人較多時(shí)列表可獨(dú)立滾動(dòng)底部按鈕始終固定在視口底部。小結(jié)ContactList 是一個(gè)「小而完整」的業(yè)務(wù)型組件文檔覆蓋了安裝、基礎(chǔ)用法、全部 Props / Events、數(shù)據(jù)結(jié)構(gòu)、類型導(dǎo)出與主題定制源碼則揭示了它基于 RadioGroup Cell Tag Button 的組合實(shí)現(xiàn)、unknownProp的寬容類型設(shè)計(jì)、國(guó)際化默認(rèn)文案機(jī)制以及編輯/選擇事件隔離等細(xì)節(jié)。掌握這些信息后無論是直接使用、二次封裝還是深度定制主題你都能做到心中有數(shù)。【免費(fèi)下載鏈接】vantA lightweight, customizable Vue UI library for mobile web apps.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/va/vant創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考