long
/
repair-project-240821
1
0
Fork 0
Code Issues 0 Pull Requests 0 Projects 0 Releases 0 Wiki Activity
艺易修小程序24.08.21
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
13 Commits
1 Branch
1.6 MiB
Tree: d90b582e8a
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from 'd90b582e8a'
${ noResults }
repair-project-240821/uni_modules/uni-list/readme.md

345 lines
15 KiB
Raw Normal View History

.
7 months ago
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
 
  1. ## List 列表

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

  3. > 代码块： `uList`、`uListItem`

  4. > 关联组件：`uni-list-item`、`uni-badge`、`uni-icons`、`uni-list-chat`、`uni-list-ad`

  5. 

  6. 

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

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

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

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

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

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

  19. 下文均有样例给出。
  20. 

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

  23. 

  24. ### 安装方式

  25. 

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

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

  30. > **注意事项**

  31. > 为了避免错误使用，给大家带来不好的开发体验，请在使用组件前仔细阅读下面的注意事项，可以帮你避免一些错误。

  32. > - 组件需要依赖 `sass` 插件 ，请自行手动安装

  33. > - 组件内部依赖 `'uni-icons'` 、`uni-badge` 组件

  34. > - `uni-list` 和 `uni-list-item` 需要配套使用，暂不支持单独使用 `uni-list-item`

  35. > - 只有开启点击反馈后，会有点击选中效果

  36. > - 使用插槽时，可以完全自定义内容

  37. > - note 、rightText 属性暂时没做限制，不支持文字溢出隐藏，使用时应该控制长度显示或通过默认插槽自行扩展

  38. > - 支付宝小程序平台需要在支付宝小程序开发者工具里开启 component2 编译模式，开启方式： 详情 --> 项目配置 --> 启用 component2 编译

  39. > - 如果需要修改 `switch`、`badge` 样式，请使用插槽自定义

  40. > - 在 `HBuilderX` 低版本中，可能会出现组件显示 `undefined` 的问题，请升级最新的 `HBuilderX` 或者 `cli`

  41. > - 如使用过程中有任何问题，或者您对uni-ui有一些好的建议，欢迎加入 uni-ui 交流群：871950839

  42.  
  43. 

  44. ### 基本用法 

  45. 

  46. - 设置 `title` 属性，可以显示列表标题
  47. - 设置 `disabled` 属性，可以禁用当前项
  48. 

  49. ```html
  50. <uni-list>
  51. 	<uni-list-item  title="列表文字" ></uni-list-item>
  52. 	<uni-list-item :disabled="true" title="列表禁用状态" ></uni-list-item>
  53. </uni-list>
  54. 			 
  55. ```
  56. 

  57. ### 多行内容显示

  58. 

  59. - 设置 `note` 属性 ，可以在第二行显示描述文本信息
  60. 

  61. ```html
  62. <uni-list>
  63. 	<uni-list-item title="列表文字" note="列表描述信息"></uni-list-item>
  64. 	<uni-list-item :disabled="true" title="列表文字" note="列表禁用状态"></uni-list-item>
  65. </uni-list>
  66. 

  67. ```
  68. 

  69. ### 右侧显示角标、switch

  70. 

  71. - 设置 `show-badge` 属性 ，可以显示角标内容
  72. - 设置 `show-switch` 属性，可以显示 switch 开关
  73. 

  74. ```html
  75. <uni-list>
  76. 	<uni-list-item  title="列表右侧显示角标" :show-badge="true" badge-text="12" ></uni-list-item>
  77. 	<uni-list-item title="列表右侧显示 switch"  :show-switch="true"  @switchChange="switchChange" ></uni-list-item>
  78. </uni-list>
  79. 

  80. ```
  81. 

  82. ### 左侧显示略缩图、图标  

  83. 

  84. - 设置 `thumb` 属性 ，可以在列表左侧显示略缩图
  85. - 设置 `show-extra-icon` 属性，并指定 `extra-icon` 可以在左侧显示图标
  86. 

  87. ```html
  88.  <uni-list>
  89.  	<uni-list-item title="列表左侧带略缩图" note="列表描述信息" thumb="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-dc-site/460d46d0-4fcc-11eb-8ff1-d5dcf8779628.png"
  90.  	 thumb-size="lg" rightText="右侧文字"></uni-list-item>
  91.  	<uni-list-item :show-extra-icon="true" :extra-icon="extraIcon1" title="列表左侧带扩展图标" ></uni-list-item>
  92. </uni-list>
  93. ```
  94. 

  95. ### 开启点击反馈和右侧箭头

  96. - 设置 `clickable` 为 `true` ，则表示这是一个可点击的列表，会默认给一个点击效果，并可以监听 `click` 事件
  97. - 设置 `link` 属性，会自动开启点击反馈，并给列表右侧添加一个箭头
  98. - 设置 `to` 属性，可以跳转页面，`link` 的值表示跳转方式，如果不指定，默认为 `navigateTo`
  99. 

  100. ```html
  101. 

  102. <uni-list>
  103. 	<uni-list-item title="开启点击反馈" clickable  @click="onClick" ></uni-list-item>
  104. 	<uni-list-item title="默认 navigateTo 方式跳转页面" link to="/pages/vue/index/index" @click="onClick($event,1)" ></uni-list-item>
  105. 	<uni-list-item title="reLaunch 方式跳转页面" link="reLaunch" to="/pages/vue/index/index" @click="onClick($event,1)" ></uni-list-item>
  106. </uni-list>
  107. 

  108. ```
  109. 

  110. 

  111. ### 聊天列表示例

  112. - 设置 `clickable` 为 `true` ，则表示这是一个可点击的列表，会默认给一个点击效果，并可以监听 `click` 事件
  113. - 设置 `link` 属性，会自动开启点击反馈，`link` 的值表示跳转方式，如果不指定，默认为 `navigateTo`
  114. - 设置 `to` 属性，可以跳转页面
  115. - `time` 属性，通常会设置成时间显示，但是这个属性不仅仅可以设置时间，你可以传入任何文本，注意文本长度可能会影响显示
  116. - `avatar` 和 `avatarList` 属性同时只会有一个生效，同时设置的话，`avatarList` 属性的长度大于1 ，`avatar` 属性将失效
  117. - 可以通过默认插槽自定义列表右侧内容
  118. 

  119. ```html
  120. 

  121. <uni-list>
  122. 	<uni-list :border="true">
  123. 		<!-- 显示圆形头像 -->
  124. 		<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>
  125. 		<!-- 右侧带角标 -->
  126. 		<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>
  127. 		<!-- 头像显示圆点 -->
  128. 		<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>
  129. 		<!-- 头像显示角标 -->
  130. 		<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>
  131. 		<!-- 显示多头像 -->
  132. 		<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>
  133. 		<!-- 自定义右侧内容 -->
  134. 		<uni-list-chat title="uni-app" :avatar-list="avatarList" note="您收到一条新的消息" time="2020-02-02 20:20" badge-positon="left" badge-text="dot">
  135. 			<view class="chat-custom-right">
  136. 				<text class="chat-custom-text">刚刚</text>
  137. 				<!-- 需要使用 uni-icons 请自行引入 -->
  138. 				<uni-icons type="star-filled" color="#999" size="18"></uni-icons>
  139. 			</view>
  140. 		</uni-list-chat>
  141. 	</uni-list>
  142. </uni-list>
  143. 

  144. ```
  145. 

  146. ```javascript
  147. 

  148. export default {
  149. 	components: {},
  150. 	data() {
  151. 		return {
  152. 			avatarList: [{
  153. 				url: 'https://vkceyugu.cdn.bspapp.com/VKCEYUGU-dc-site/460d46d0-4fcc-11eb-8ff1-d5dcf8779628.png'
  154. 			}, {
  155. 				url: 'https://vkceyugu.cdn.bspapp.com/VKCEYUGU-dc-site/460d46d0-4fcc-11eb-8ff1-d5dcf8779628.png'
  156. 			}, {
  157. 				url: 'https://vkceyugu.cdn.bspapp.com/VKCEYUGU-dc-site/460d46d0-4fcc-11eb-8ff1-d5dcf8779628.png'
  158. 			}]
  159. 		}
  160. 	}
  161. }
  162. 

  163. ```
  164. 

  165. 

  166. ```css
  167. 

  168. .chat-custom-right {
  169. 	flex: 1;
  170. 	/* #ifndef APP-NVUE */
  171. 	display: flex;
  172. 	/* #endif */
  173. 	flex-direction: column;
  174. 	justify-content: space-between;
  175. 	align-items: flex-end;
  176. }
  177. 

  178. .chat-custom-text {
  179. 	font-size: 12px;
  180. 	color: #999;
  181. }
  182. 

  183. ```
  184. 

  185. ## API

  186. 

  187. ### List Props

  188. 

  189. 属性名			|类型		|默认值		|	说明																									
  190. :-:				|:-:		|:-:		|	:-:	
  191. border			|Boolean	|true		|	是否显示边框
  192. 

  193. 

  194. ### ListItem Props

  195. 

  196. 属性名			|类型		|默认值		|	说明																					
  197. :-:				|:-:		|:-:		|	:-:	
  198. title			|String		|-			|	标题
  199. note			|String		|-			|	描述
  200. ellipsis		|Number		|0			|	title 是否溢出隐藏，可选值，0:默认;  1:显示一行;	2:显示两行;【nvue 暂不支持】
  201. thumb			|String		|-			|	左侧缩略图，若thumb有值，则不会显示扩展图标
  202. thumbSize		|String 	|medium 	|	略缩图尺寸，可选值，lg:大图;  medium:一般;	sm:小图;
  203. showBadge		|Boolean	|false		|	是否显示数字角标	
  204. badgeText		|String		|-			|	数字角标内容
  205. badgeType		|String		|-			|	数字角标类型，参考[uni-icons](https://ext.dcloud.net.cn/plugin?id=21)	
  206. badgeStyle  |Object   |-      | 数字角标样式，使用uni-badge的custom-style参数
  207. rightText		|String		|-			|	右侧文字内容
  208. disabled		|Boolean	|false		|	是否禁用	
  209. showArrow 		|Boolean	|true		|	是否显示箭头图标			
  210. link			|String 	|navigateTo	|	新页面跳转方式，可选值见下表
  211. to				|String		|-			|	新页面跳转地址，如填写此属性，click 会返回页面是否跳转成功			
  212. clickable		|Boolean	|false		|	是否开启点击反馈
  213. showSwitch	    |Boolean	|false		|	是否显示Switch																			
  214. switchChecked	|Boolean	|false		|	Switch是否被选中																			
  215. showExtraIcon   |Boolean	|false		|	左侧是否显示扩展图标																		
  216. extraIcon		|Object		|-			|	扩展图标参数，格式为 ``{color: '#4cd964',size: '22',type: 'spinner'}``，参考 [uni-icons](https://ext.dcloud.net.cn/plugin?id=28)	
  217. direction		| String	|row		|	排版方向，可选值，row:水平排列;  column:垂直排列; 3个插槽是水平排还是垂直排，也受此属性控制
  218. 

  219. 

  220. #### Link Options

  221. 

  222. 属性名				|	说明
  223. :-:					|	:-:
  224. navigateTo 	| 	同 uni.navigateTo()
  225. redirectTo 	|	同 uni.reLaunch()
  226. reLaunch		|	同 uni.reLaunch()
  227. switchTab  	|	同 uni.switchTab()
  228. 

  229. ### ListItem Events

  230. 

  231. 事件称名			|说明									|返回参数			
  232. :-:				|:-:									|:-:				
  233. click			|点击 uniListItem 触发事件，需开启点击反馈	|-					
  234. switchChange	|点击切换 Switch 时触发，需显示 switch		|e={value:checked}	
  235. 

  236. 

  237. 

  238. ### ListItem Slots

  239. 

  240. 名称	 	|	说明					
  241. :-:		|	:-:						
  242. header	|	左/上内容插槽，可完全自定义默认显示
  243. body	|	中间内容插槽，可完全自定义中间内容				
  244. footer	|	右/下内容插槽，可完全自定义右侧内容		
  245. 

  246. 

  247. > **通过插槽扩展**

  248. > 需要注意的是当使用插槽时，内置样式将会失效，只保留排版样式，此时的样式需要开发者自己实现

  249. > 如果	`uni-list-item` 组件内置属性样式无法满足需求，可以使用插槽来自定义uni-list-item里的内容。

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

  251. > - 当 `direction` 属性为 `row` 时表示水平排列，此时 `header` 表示列表的左边部分，`body` 表示列表的中间部分，`footer` 表示列表的右边部分

  252. > - 当 `direction` 属性为 `column` 时表示垂直排列，此时 `header` 表示列表的上边部分，`body` 表示列表的中间部分，`footer` 表示列表的下边部分

  253. > 开发者可以只用1个插槽，也可以3个一起使用。在插槽中可自主编写view标签，实现自己所需的效果。

  254. 

  255. 	
  256. **示例**
  257. 

  258. ```html
  259. <uni-list>
  260. 	<uni-list-item title="自定义右侧插槽" note="列表描述信息" link>
  261. 		<template slot="header">
  262. 			<image class="slot-image" src="/static/logo.png" mode="widthFix"></image>
  263. 		</template>
  264. 	</uni-list-item>
  265. 	<uni-list-item>
  266. 		<!-- 自定义 header -->
  267. 		<view slot="header" class="slot-box"><image class="slot-image" src="/static/logo.png" mode="widthFix"></image></view>
  268. 		<!-- 自定义 body -->
  269. 		<text slot="body" class="slot-box slot-text">自定义插槽</text>
  270. 		<!-- 自定义 footer-->
  271. 		<template slot="footer">
  272. 			<image class="slot-image" src="/static/logo.png" mode="widthFix"></image>
  273. 		</template>
  274. 	</uni-list-item>
  275. </uni-list>
  276. ```
  277. 

  278. 

  279. 

  280. 

  281. 

  282. ### ListItemChat Props

  283. 

  284. 属性名			|类型		|默认值		|	说明																		
  285. :-:				|:-:		|:-:		|	:-:	
  286. title 			|String		|-			|	标题
  287. note 			|String		|-			|	描述
  288. clickable		|Boolean	|false		|	是否开启点击反馈
  289. badgeText		|String		|-			|	数字角标内容，设置为 `dot` 将显示圆点
  290. badgePositon 	|String		|right		|	角标位置
  291. link			|String 	|navigateTo	|	是否展示右侧箭头并开启点击反馈，可选值见下表
  292. clickable		|Boolean	|false		|	是否开启点击反馈
  293. to				|String		|-			|	跳转页面地址，如填写此属性，click 会返回页面是否跳转成功	
  294. time			|String 	|-			|	右侧时间显示
  295. avatarCircle 	|Boolean 	|false		|	是否显示圆形头像
  296. avatar			|String 	|-			|	头像地址，avatarCircle 不填时生效
  297. avatarList 		|Array	 	|-			|	头像组，格式为 [{url:''}]
  298. 

  299. #### Link Options

  300. 

  301. 属性名		|	说明
  302. :-:			|	:-:
  303. navigateTo 	| 	同 uni.navigateTo()
  304. redirectTo 	|	同 uni.reLaunch()
  305. reLaunch	|	同 uni.reLaunch()
  306. switchTab  	|	同 uni.switchTab()
  307. 

  308. ### ListItemChat Slots

  309. 

  310. 名称	 	|	说明					
  311. :-		|	:-						
  312. default	|	自定义列表右侧内容（包括时间和角标显示）
  313. 

  314. ### ListItemChat Events

  315. 事件称名			|	说明						|	返回参数			
  316. :-:				|	:-:						|	:-:	
  317. @click			|	点击 uniListChat 触发事件	|	{data:{}}	，如有 to 属性，会返回页面跳转信息	
  318. 

  319. 

  320. 

  321. 

  322. 

  323. 

  324. ## 基于uni-list扩展的页面模板

  325. 

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

  328. **新闻列表类**
  329. 

  330. 1. 云端一体混合布局：[https://ext.dcloud.net.cn/plugin?id=2546](https://ext.dcloud.net.cn/plugin?id=2546)
  331. 2. 云端一体垂直布局，大图模式：[https://ext.dcloud.net.cn/plugin?id=2583](https://ext.dcloud.net.cn/plugin?id=2583)
  332. 3. 云端一体垂直布局，多行图文混排：[https://ext.dcloud.net.cn/plugin?id=2584](https://ext.dcloud.net.cn/plugin?id=2584)
  333. 4. 云端一体垂直布局，多图模式：[https://ext.dcloud.net.cn/plugin?id=2585](https://ext.dcloud.net.cn/plugin?id=2585)
  334. 5. 云端一体水平布局，左图右文：[https://ext.dcloud.net.cn/plugin?id=2586](https://ext.dcloud.net.cn/plugin?id=2586)
  335. 6. 云端一体水平布局，左文右图：[https://ext.dcloud.net.cn/plugin?id=2587](https://ext.dcloud.net.cn/plugin?id=2587)
  336. 7. 云端一体垂直布局，无图模式，主标题+副标题：[https://ext.dcloud.net.cn/plugin?id=2588](https://ext.dcloud.net.cn/plugin?id=2588)
  337. 

  338. **商品列表类**
  339. 

  340. 1. 云端一体列表/宫格视图互切：[https://ext.dcloud.net.cn/plugin?id=2651](https://ext.dcloud.net.cn/plugin?id=2651)
  341. 2. 云端一体列表（宫格模式）：[https://ext.dcloud.net.cn/plugin?id=2671](https://ext.dcloud.net.cn/plugin?id=2671)
  342. 3. 云端一体列表（列表模式）：[https://ext.dcloud.net.cn/plugin?id=2672](https://ext.dcloud.net.cn/plugin?id=2672)
  343. 

  344. ## 组件示例

  345. 

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