进销存APP-前端
blame | 历史 | 补丁 | 提交 | 提交对比 | 忽略空白
gaoluyang
5 天以前 92230c9a97dc9ce9df3313d11d26999c04bb6b26 
 src/uni_modules/uni-list/readme.md


¶Ô±ÈÐÂÎļþ


@@ -0,0 +1,346 @@


## List åˆ—表


> **组件名：uni-list**


> ä»£ç å—： `uList`、`uListItem`


> å…³è”组件：`uni-list-item`、`uni-badge`、`uni-icons`、`uni-list-chat`、`uni-list-ad`






List åˆ—表组件，包含基本列表样式、可扩展插槽机制、长列表性能优化、多端兼容。




在vue页面里，它默认使用页面级滚动。在app-nvue页面里，它默认使用原生list组件滚动。这样的长列表，在滚动出屏幕外后，系统会回收不可见区域的渲染内存资源，不会造成滚动越长手机越卡的问题。




uni-list组件是父容器，里面的核心是uni-list-item子组件，它代表列表中的一个可重复行，子组件可以无限循环。




uni-list-item有很多风格，uni-list-item组件通过内置的属性，满足一些常用的场景。当内置属性不满足需求时，可以通过扩展插槽来自定义列表内容。




内置属性可以覆盖的场景包括：导航列表、设置列表、小图标列表、通信录列表、聊天记录列表。




涉及很多大图或丰富内容的列表，比如类今日头条的新闻列表、类淘宝的电商列表，需要通过扩展插槽实现。




下文均有样例给出。




uni-list不包含下拉刷新和上拉翻页。上拉翻页另见组件：[uni-load-more](https://ext.dcloud.net.cn/plugin?id=29)






### å®‰è£…方式




本组件符合[easycom](https://uniapp.dcloud.io/collocation/pages?id=easycom)规范，`HBuilderX 2.5.5`起，只需将本组件导入项目，在页面`template`中即可直接使用，无需在页面中`import`和注册`components`。




如需通过`npm`方式使用`uni-ui`组件，另见文档：[https://ext.dcloud.net.cn/plugin?id=55](https://ext.dcloud.net.cn/plugin?id=55)




> **注意事项**


> ä¸ºäº†é¿å…é”™è¯¯ä½¿ç”¨ï¼Œç»™å¤§å®¶å¸¦æ¥ä¸å¥½çš„开发体验，请在使用组件前仔细阅读下面的注意事项，可以帮你避免一些错误。


> - ç»„件需要依赖 `sass` æ’件 ï¼Œè¯·è‡ªè¡Œæ‰‹åŠ¨å®‰è£…


> - ç»„件内部依赖 `'uni-icons'` ã€`uni-badge` ç»„件


> - `uni-list` å’Œ `uni-list-item` éœ€è¦é…å¥—使用，暂不支持单独使用 `uni-list-item`


> - åªæœ‰å¼€å¯ç‚¹å‡»åé¦ˆåŽï¼Œä¼šæœ‰ç‚¹å‡»é€‰ä¸­æ•ˆæžœ


> - ä½¿ç”¨æ’槽时，可以完全自定义内容


> - note ã€rightText å±žæ€§æš‚时没做限制，不支持文字溢出隐藏，使用时应该控制长度显示或通过默认插槽自行扩展


> - æ”¯ä»˜å®å°ç¨‹åºå¹³å°éœ€è¦åœ¨æ”¯ä»˜å®å°ç¨‹åºå¼€å‘者工具里开启 component2 ç¼–译模式，开启方式： è¯¦æƒ… --> é¡¹ç›®é…ç½® --> å¯ç”¨ component2 ç¼–译


> - å¦‚果需要修改 `switch`、`badge` æ ·å¼ï¼Œè¯·ä½¿ç”¨æ’槽自定义


> - åœ¨ `HBuilderX` ä½Žç‰ˆæœ¬ä¸­ï¼Œå¯èƒ½ä¼šå‡ºçŽ°ç»„件显示 `undefined` çš„问题，请升级最新的 `HBuilderX` æˆ–者 `cli`


> - å¦‚使用过程中有任何问题，或者您对uni-ui有一些好的建议，欢迎加入 uni-ui äº¤æµç¾¤ï¼š871950839


 




### åŸºæœ¬ç”¨æ³• 




- è®¾ç½® `title` å±žæ€§ï¼Œå¯ä»¥æ˜¾ç¤ºåˆ—表标题


- è®¾ç½® `disabled` å±žæ€§ï¼Œå¯ä»¥ç¦ç”¨å½“前项




```html


<uni-list>


   <uni-list-item  title="列表文字" ></uni-list-item>


   <uni-list-item :disabled="true" title="列表禁用状态" ></uni-list-item>


</uni-list>


			 


```




### å¤šè¡Œå†…容显示




- è®¾ç½® `note` å±žæ€§ ï¼Œå¯ä»¥åœ¨ç¬¬äºŒè¡Œæ˜¾ç¤ºæè¿°æ–‡æœ¬ä¿¡æ¯




```html


<uni-list>


   <uni-list-item title="列表文字" note="列表描述信息"></uni-list-item>


   <uni-list-item :disabled="true" title="列表文字" note="列表禁用状态"></uni-list-item>


</uni-list>




```




### å³ä¾§æ˜¾ç¤ºè§’标、switch




- è®¾ç½® `show-badge` å±žæ€§ ï¼Œå¯ä»¥æ˜¾ç¤ºè§’标内容


- è®¾ç½® `show-switch` å±žæ€§ï¼Œå¯ä»¥æ˜¾ç¤º switch å¼€å…³




```html


<uni-list>


   <uni-list-item  title="列表右侧显示角标" :show-badge="true" badge-text="12" ></uni-list-item>


   <uni-list-item title="列表右侧显示 switch"  :show-switch="true"  @switchChange="switchChange" ></uni-list-item>


</uni-list>




```




### å·¦ä¾§æ˜¾ç¤ºç•¥ç¼©å›¾ã€å›¾æ ‡  




- è®¾ç½® `thumb` å±žæ€§ ï¼Œå¯ä»¥åœ¨åˆ—表左侧显示略缩图


- è®¾ç½® `show-extra-icon` å±žæ€§ï¼Œå¹¶æŒ‡å®š `extra-icon` å¯ä»¥åœ¨å·¦ä¾§æ˜¾ç¤ºå›¾æ ‡




```html


 <uni-list>


    <uni-list-item title="列表左侧带略缩图" note="列表描述信息" thumb="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-dc-site/460d46d0-4fcc-11eb-8ff1-d5dcf8779628.png"


     thumb-size="lg" rightText="右侧文字"></uni-list-item>


    <uni-list-item :show-extra-icon="true" :extra-icon="extraIcon1" title="列表左侧带扩展图标" ></uni-list-item>


</uni-list>


```




### å¼€å¯ç‚¹å‡»åé¦ˆå’Œå³ä¾§ç®­å¤´


- è®¾ç½® `clickable` ä¸º `true` ï¼Œåˆ™è¡¨ç¤ºè¿™æ˜¯ä¸€ä¸ªå¯ç‚¹å‡»çš„列表，会默认给一个点击效果，并可以监听 `click` äº‹ä»¶


- è®¾ç½® `link` å±žæ€§ï¼Œä¼šè‡ªåŠ¨å¼€å¯ç‚¹å‡»åé¦ˆï¼Œå¹¶ç»™åˆ—表右侧添加一个箭头


- è®¾ç½® `to` å±žæ€§ï¼Œå¯ä»¥è·³è½¬é¡µé¢ï¼Œ`link` çš„值表示跳转方式，如果不指定，默认为 `navigateTo`




```html




<uni-list>


   <uni-list-item title="开启点击反馈" clickable  @click="onClick" ></uni-list-item>


   <uni-list-item title="默认 navigateTo æ–¹å¼è·³è½¬é¡µé¢" link to="/pages/vue/index/index" @click="onClick($event,1)" ></uni-list-item>


   <uni-list-item title="reLaunch æ–¹å¼è·³è½¬é¡µé¢" link="reLaunch" to="/pages/vue/index/index" @click="onClick($event,1)" ></uni-list-item>


</uni-list>




```






### èŠå¤©åˆ—表示例


- è®¾ç½® `clickable` ä¸º `true` ï¼Œåˆ™è¡¨ç¤ºè¿™æ˜¯ä¸€ä¸ªå¯ç‚¹å‡»çš„列表，会默认给一个点击效果，并可以监听 `click` äº‹ä»¶


- è®¾ç½® `link` å±žæ€§ï¼Œä¼šè‡ªåŠ¨å¼€å¯ç‚¹å‡»åé¦ˆï¼Œ`link` çš„值表示跳转方式，如果不指定，默认为 `navigateTo`


- è®¾ç½® `to` å±žæ€§ï¼Œå¯ä»¥è·³è½¬é¡µé¢


- `time` å±žæ€§ï¼Œé€šå¸¸ä¼šè®¾ç½®æˆæ—¶é—´æ˜¾ç¤ºï¼Œä½†æ˜¯è¿™ä¸ªå±žæ€§ä¸ä»…仅可以设置时间，你可以传入任何文本，注意文本长度可能会影响显示


- `avatar` å’Œ `avatarList` å±žæ€§åŒæ—¶åªä¼šæœ‰ä¸€ä¸ªç”Ÿæ•ˆï¼ŒåŒæ—¶è®¾ç½®çš„话，`avatarList` å±žæ€§çš„长度大于1 ï¼Œ`avatar` å±žæ€§å°†å¤±æ•ˆ


- å¯ä»¥é€šè¿‡é»˜è®¤æ’槽自定义列表右侧内容




```html




<uni-list>


   <uni-list :border="true">


      <!-- æ˜¾ç¤ºåœ†å½¢å¤´åƒ -->


      <uni-list-chat :avatar-circle="true" title="uni-app" avatar="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-dc-site/460d46d0-4fcc-11eb-8ff1-d5dcf8779628.png" note="您收到一条新的消息" time="2020-02-02 20:20" ></uni-list-chat>


      <!-- å³ä¾§å¸¦è§’æ ‡ -->


      <uni-list-chat title="uni-app" avatar="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-dc-site/460d46d0-4fcc-11eb-8ff1-d5dcf8779628.png" note="您收到一条新的消息" time="2020-02-02 20:20" badge-text="12" :badge-style="{backgroundColor:'#FF80AB'}"></uni-list-chat>


      <!-- å¤´åƒæ˜¾ç¤ºåœ†ç‚¹ -->


      <uni-list-chat title="uni-app" avatar="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-dc-site/460d46d0-4fcc-11eb-8ff1-d5dcf8779628.png" note="您收到一条新的消息" time="2020-02-02 20:20" badge-positon="left" badge-text="dot"></uni-list-chat>


      <!-- å¤´åƒæ˜¾ç¤ºè§’æ ‡ -->


      <uni-list-chat title="uni-app" avatar="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-dc-site/460d46d0-4fcc-11eb-8ff1-d5dcf8779628.png" note="您收到一条新的消息" time="2020-02-02 20:20" badge-positon="left" badge-text="99"></uni-list-chat>


      <!-- æ˜¾ç¤ºå¤šå¤´åƒ -->


      <uni-list-chat title="uni-app" :avatar-list="avatarList" note="您收到一条新的消息" time="2020-02-02 20:20" badge-positon="left" badge-text="dot"></uni-list-chat>


      <!-- è‡ªå®šä¹‰å³ä¾§å†…容 -->


      <uni-list-chat title="uni-app" :avatar-list="avatarList" note="您收到一条新的消息" time="2020-02-02 20:20" badge-positon="left" badge-text="dot">


         <view class="chat-custom-right">


            <text class="chat-custom-text">刚刚</text>


            <!-- éœ€è¦ä½¿ç”¨ uni-icons è¯·è‡ªè¡Œå¼•å…¥ -->


            <uni-icons type="star-filled" color="#999" size="18"></uni-icons>


         </view>


      </uni-list-chat>


   </uni-list>


</uni-list>




```




```javascript




export default {


   components: {},


   data() {


      return {


         avatarList: [{


            url: 'https://vkceyugu.cdn.bspapp.com/VKCEYUGU-dc-site/460d46d0-4fcc-11eb-8ff1-d5dcf8779628.png'


         }, {


            url: 'https://vkceyugu.cdn.bspapp.com/VKCEYUGU-dc-site/460d46d0-4fcc-11eb-8ff1-d5dcf8779628.png'


         }, {


            url: 'https://vkceyugu.cdn.bspapp.com/VKCEYUGU-dc-site/460d46d0-4fcc-11eb-8ff1-d5dcf8779628.png'


         }]


      }


   }


}




```






```css




.chat-custom-right {


   flex: 1;


   /* #ifndef APP-NVUE */


   display: flex;


   /* #endif */


   flex-direction: column;


   justify-content: space-between;


   align-items: flex-end;


}




.chat-custom-text {


   font-size: 12px;


   color: #999;


}




```




## API




### List Props




属性名         |类型      |默认值      |   è¯´æ˜Ž																									


:-:            |:-:      |:-:      |   :-:	


border         |Boolean   |true      |   æ˜¯å¦æ˜¾ç¤ºè¾¹æ¡†






### ListItem Props




属性名         |类型      |默认值      |   è¯´æ˜Ž																					


:-:            |:-:      |:-:      |   :-:	


title         |String      |-         |   æ ‡é¢˜


note         |String      |-         |   æè¿°


ellipsis      |Number      |0         |   title æ˜¯å¦æº¢å‡ºéšè—ï¼Œå¯é€‰å€¼ï¼Œ0:默认;  1:显示一行;   2:显示两行;【nvue æš‚不支持】


thumb         |String      |-         |   å·¦ä¾§ç¼©ç•¥å›¾ï¼Œè‹¥thumb有值，则不会显示扩展图标


thumbSize      |String    |medium    |   ç•¥ç¼©å›¾å°ºå¯¸ï¼Œå¯é€‰å€¼ï¼Œlg:大图;  medium:一般;   sm:小图;


showBadge      |Boolean   |false      |   æ˜¯å¦æ˜¾ç¤ºæ•°å­—角标	


badgeText      |String      |-         |   æ•°å­—角标内容


badgeType      |String      |-         |   æ•°å­—角标类型，参考[uni-icons](https://ext.dcloud.net.cn/plugin?id=21)	


badgeStyle  |Object   |-      | æ•°å­—角标样式，使用uni-badge的custom-style参数


rightText      |String      |-         |   å³ä¾§æ–‡å­—内容


disabled      |Boolean   |false      |   æ˜¯å¦ç¦ç”¨	


showArrow       |Boolean   |true      |   æ˜¯å¦æ˜¾ç¤ºç®­å¤´å›¾æ ‡			


link         |String    |navigateTo   |   æ–°é¡µé¢è·³è½¬æ–¹å¼ï¼Œå¯é€‰å€¼è§ä¸‹è¡¨


to            |String      |-         |   æ–°é¡µé¢è·³è½¬åœ°å€ï¼Œå¦‚填写此属性，click ä¼šè¿”回页面是否跳转成功			


clickable      |Boolean   |false      |   æ˜¯å¦å¼€å¯ç‚¹å‡»åé¦ˆ


showSwitch       |Boolean   |false      |   æ˜¯å¦æ˜¾ç¤ºSwitch																			


switchChecked   |Boolean   |false      |   Switch是否被选中																			


showExtraIcon   |Boolean   |false      |   å·¦ä¾§æ˜¯å¦æ˜¾ç¤ºæ‰©å±•å›¾æ ‡																		


extraIcon      |Object      |-         |   æ‰©å±•å›¾æ ‡å‚数，格式为 ``{color: '#4cd964',size: '22',type: 'spinner'}``，参考 [uni-icons](https://ext.dcloud.net.cn/plugin?id=28)	


direction      | String   |row      |   æŽ’版方向，可选值，row:水平排列;  column:垂直排列; 3个插槽是水平排还是垂直排，也受此属性控制






#### Link Options




属性名            |   è¯´æ˜Ž


:-:               |   :-:


navigateTo    |    åŒ uni.navigateTo()


redirectTo    |   åŒ uni.reLaunch()


reLaunch      |   åŒ uni.reLaunch()


switchTab     |   åŒ uni.switchTab()




### ListItem Events




事件称名         |说明                           |返回参数			


:-:            |:-:                           |:-:				


click         |点击 uniListItem è§¦å‘事件，需开启点击反馈   |-					


switchChange   |点击切换 Switch æ—¶è§¦å‘，需显示 switch      |e={value:checked}	








### ListItem Slots




名称       |   è¯´æ˜Ž					


:-:      |   :-:						


header   |   å·¦/上内容插槽，可完全自定义默认显示


body   |   ä¸­é—´å†…容插槽，可完全自定义中间内容				


footer   |   å³/下内容插槽，可完全自定义右侧内容		






> **通过插槽扩展**


> éœ€è¦æ³¨æ„çš„是当使用插槽时，内置样式将会失效，只保留排版样式，此时的样式需要开发者自己实现


> å¦‚æžœ   `uni-list-item` ç»„件内置属性样式无法满足需求，可以使用插槽来自定义uni-list-item里的内容。


> uni-list-item提供了3个可扩展的插槽：`header`、`body`、`footer`


> - å½“ `direction` å±žæ€§ä¸º `row` æ—¶è¡¨ç¤ºæ°´å¹³æŽ’列，此时 `header` è¡¨ç¤ºåˆ—表的左边部分，`body` è¡¨ç¤ºåˆ—表的中间部分，`footer` è¡¨ç¤ºåˆ—表的右边部分


> - å½“ `direction` å±žæ€§ä¸º `column` æ—¶è¡¨ç¤ºåž‚直排列，此时 `header` è¡¨ç¤ºåˆ—表的上边部分，`body` è¡¨ç¤ºåˆ—表的中间部分，`footer` è¡¨ç¤ºåˆ—表的下边部分


> å¼€å‘者可以只用1个插槽，也可以3个一起使用。在插槽中可自主编写view标签，实现自己所需的效果。




	


**示例**




```html


<uni-list>


   <uni-list-item title="自定义右侧插槽" note="列表描述信息" link>


      <template slot="header">


         <image class="slot-image" src="/static/logo.png" mode="widthFix"></image>


      </template>


   </uni-list-item>


   <uni-list-item>


      <!-- è‡ªå®šä¹‰ header -->


      <view slot="header" class="slot-box"><image class="slot-image" src="/static/logo.png" mode="widthFix"></image></view>


      <!-- è‡ªå®šä¹‰ body -->


      <text slot="body" class="slot-box slot-text">自定义插槽</text>


      <!-- è‡ªå®šä¹‰ footer-->


      <template slot="footer">


         <image class="slot-image" src="/static/logo.png" mode="widthFix"></image>


      </template>


   </uni-list-item>


</uni-list>


```












### ListItemChat Props




属性名         |类型      |默认值      |   è¯´æ˜Ž																		


:-:            |:-:      |:-:      |   :-:	


title          |String      |-         |   æ ‡é¢˜


note          |String      |-         |   æè¿°


clickable      |Boolean   |false      |   æ˜¯å¦å¼€å¯ç‚¹å‡»åé¦ˆ


badgeText      |String      |-         |   æ•°å­—角标内容，设置为 `dot` å°†æ˜¾ç¤ºåœ†ç‚¹


badgePositon    |String      |right      |   è§’标位置


link         |String    |navigateTo   |   æ˜¯å¦å±•ç¤ºå³ä¾§ç®­å¤´å¹¶å¼€å¯ç‚¹å‡»åé¦ˆï¼Œå¯é€‰å€¼è§ä¸‹è¡¨


clickable      |Boolean   |false      |   æ˜¯å¦å¼€å¯ç‚¹å‡»åé¦ˆ


to            |String      |-         |   è·³è½¬é¡µé¢åœ°å€ï¼Œå¦‚填写此属性，click ä¼šè¿”回页面是否跳转成功	


time         |String    |-         |   å³ä¾§æ—¶é—´æ˜¾ç¤º


avatarCircle    |Boolean    |false      |   æ˜¯å¦æ˜¾ç¤ºåœ†å½¢å¤´åƒ


avatar         |String    |-         |   å¤´åƒåœ°å€ï¼ŒavatarCircle ä¸å¡«æ—¶ç”Ÿæ•ˆ


avatarList       |Array       |-         |   å¤´åƒç»„，格式为 [{url:''}]




#### Link Options




属性名      |   è¯´æ˜Ž


:-:         |   :-:


navigateTo    |    åŒ uni.navigateTo()


redirectTo    |   åŒ uni.reLaunch()


reLaunch   |   åŒ uni.reLaunch()


switchTab     |   åŒ uni.switchTab()




### ListItemChat Slots




名称       |   è¯´æ˜Ž					


:-      |   :-						


default   |   è‡ªå®šä¹‰åˆ—表右侧内容（包括时间和角标显示）




### ListItemChat Events


事件称名         |   è¯´æ˜Ž                  |   è¿”回参数			


:-:            |   :-:                  |   :-:	


@click         |   ç‚¹å‡» uniListChat è§¦å‘事件   |   {data:{}}   ï¼Œå¦‚有 to å±žæ€§ï¼Œä¼šè¿”回页面跳转信息	














## åŸºäºŽuni-list扩展的页面模板




通过扩展插槽，可实现多种常见样式的列表




**新闻列表类**




1. äº‘端一体混合布局：[https://ext.dcloud.net.cn/plugin?id=2546](https://ext.dcloud.net.cn/plugin?id=2546)


2. äº‘端一体垂直布局，大图模式：[https://ext.dcloud.net.cn/plugin?id=2583](https://ext.dcloud.net.cn/plugin?id=2583)


3. äº‘端一体垂直布局，多行图文混排：[https://ext.dcloud.net.cn/plugin?id=2584](https://ext.dcloud.net.cn/plugin?id=2584)


4. äº‘端一体垂直布局，多图模式：[https://ext.dcloud.net.cn/plugin?id=2585](https://ext.dcloud.net.cn/plugin?id=2585)


5. äº‘端一体水平布局，左图右文：[https://ext.dcloud.net.cn/plugin?id=2586](https://ext.dcloud.net.cn/plugin?id=2586)


6. äº‘端一体水平布局，左文右图：[https://ext.dcloud.net.cn/plugin?id=2587](https://ext.dcloud.net.cn/plugin?id=2587)


7. äº‘端一体垂直布局，无图模式，主标题+副标题：[https://ext.dcloud.net.cn/plugin?id=2588](https://ext.dcloud.net.cn/plugin?id=2588)




**商品列表类**




1. äº‘端一体列表/宫格视图互切：[https://ext.dcloud.net.cn/plugin?id=2651](https://ext.dcloud.net.cn/plugin?id=2651)


2. äº‘端一体列表（宫格模式）：[https://ext.dcloud.net.cn/plugin?id=2671](https://ext.dcloud.net.cn/plugin?id=2671)


3. äº‘端一体列表（列表模式）：[https://ext.dcloud.net.cn/plugin?id=2672](https://ext.dcloud.net.cn/plugin?id=2672)




## ç»„件示例




点击查看：[https://hellouniapp.dcloud.net.cn/pages/extUI/list/list](https://hellouniapp.dcloud.net.cn/pages/extUI/list/list)