https://uniapp.dcloud.net.cn/component/

擴展文檔

• uni-app原生插件開發

組件概述

• 所有uni-app的組件，都有如下屬性
  • | hidden | Boolean | 組件是否隱藏 | 所有組件默認是顯示的 |
  • | data-* | Any | 自定義屬性 | 組件上觸發的事件時，會發送給事件處理函數 |
• 基礎組件列表
  • | scroll-view | 可滾動視圖容器 |
  • | swiper | 滑塊視圖容器，比如用于輪播banner |
  • | match-media | 屏幕動態適配組件，比如窄屏上不顯示某些內容 |
    • 注釋：可以指定一組 media query 媒體查詢規則，滿足查詢條件時，這個組件才會被展示。
  • | movable-area | 可拖動區域 |
    • 注釋：手指/鼠標按住movable-view拖動或雙指縮放，但拖不出movable-area規定的范圍
  • | movable-view | 可移動的視圖容器，在頁面中可以拖拽滑動或雙指縮放。movable-view必須在movable-area組件中 |
  • | cover-view | 可覆蓋在原生組件的上的文本組件 |
  • | cover-image | 可覆蓋在原生組件的上的圖片組件 |
  • | icon | 圖標 |
  • | text | 文字 |
  • | rich-text | 富文本顯示組件 |
  • | progress | 進度條 |
  • | checkbox | 多項選擇器 |
  • | editor | 富文本輸入框 |
  • | form | 表單 |
  • | input | 輸入框 |
  • | label | 標簽 |
  • | picker | 彈出式列表選擇器 |
    • 注釋：從底部彈起的滾動選擇器。支持五種選擇器，通過mode來區分，分別是普通選擇器，多列選擇器，時間選擇器，日期選擇器，省市區選擇器，默認是普通選擇器
  • | picker-view | 窗體內嵌式列表選擇器 |
    • 注釋：當需要對自定義選擇的彈出方式和UI表現時
  • | radio | 單項選擇器 |
  • | slider | 滑動選擇器 |
  • | switch | 開關選擇器 |
  • | textarea | 多行文本輸入框 |
  • | navigator | 頁面鏈接。類似于HTML中的a標簽 |
  • | audio | 音頻 |
  • | camera | 相機 |
    • 注釋：頁面內嵌的區域相機組件。注意這不是點擊后全屏打開的相機
  • | image | 圖片 |
  • | video | 視頻 |
  • | live-player | 直播播放 |
  • | live-pusher | 實時音視頻錄制，也稱直播推流 |
  • | map | 地圖 |
  • | canvas | 畫布 |
  • | web-view | web瀏覽器組件 |
  • | ad | 廣告組件 |
    • 注釋：嵌入到文章列表中的廣告位
  • | ad-draw | 沉浸視頻流廣告組件 |
  • | custom-tab-bar | 底部tabbar自定義組件 |
    • 注釋：h5頁面專用，H5端尤其是PC寬屏，對tabBar的位置和樣式有更靈活的需求。仍然讀取 pages.json 里配置的tabBar信息
  • | navigation-bar | 頁面頂部導航 |
    • 注釋：頁面導航條配置節點，用于指定導航欄的一些屬性。
  • | page-meta | 頁面屬性配置節點 |
    • 注釋：頁面屬性配置節點，用于指定頁面的一些屬性、監聽頁面事件。可部分替代pages.json的功能。
  • | unicloud-db組件 | uniCloud數據庫訪問和操作組件 |
• 五角星點擊評分的組件https://ext.dcloud.net.cn/plugin?id=33
• easycom組件規范
  • 只要組件安裝在項目的components目錄下或uni_modules目錄下
  • 符合components/組件名稱/組件名稱.(vue|uvue)目錄結構
    • 當同時存在vue和uvue時，uni-app 項目優先使用 vue 文件，而uni-app x 項目優先使用 uvue 文件
  • 可以不用引用、注冊，直接在頁面中使用
  • 如果你的組件名稱或路徑不符合easycom的默認規范，可以在pages.json的easycom節點進行個性化設置，自定義匹配組件的策略
• uni_module其實不止服務于組件，它可以服務于組件、js庫、頁面、項目等所有DCloud插件市場所支持的種類。
  • 注釋：組件支持 easycom 組件
  • 注釋：頁面需要合并pages.json
• uniCloud組件
  • 在uni-ui擴展庫里還有uniCloud的文件選擇和上傳組件，參考：uni-file-picker
• uni-app的基礎組件里，有一批原生組件，如video、map
• uni-app的App端支持原生插件，這類插件使用iOS或Android原生語言編寫，封裝成插件，供其他開發者使用js來調用
  • 原生插件分為原生組件component和原生模塊module。
  • 原生組件component只能在App-nvue環境中使用
    • 注釋：這里是指app的原生組件，uni-app基礎組件中的原生組件是兼容多環境的原生組件。
• datacom組件是一種數據驅動的、可云端一體的組件
  • 注釋：搭配 uniCloud 的schema2code頁面生成系統，數據庫定義好schema，前端頁面就不用寫了，自動生成
  • 注釋：符合一種數據規范的組件，大家都使用同一種數據規范，在切換組件、配合uniCloud使用、使用schema2code頁面生成系統時都會更為方便

view

• 如果使用nvue，則需注意，包裹文字應該使用<text>組件
• 屬性說明
  • | hover-class | String | none | 指定按下去的樣式類。當 hover-class="none" 時，沒有點擊態效果 |
  • | hover-stop-propagation | Boolean | false | 指定是否阻止本節點的祖先節點出現點擊態，App、H5、支付寶小程序、百度小程序不支持（支付寶小程序、百度小程序文檔中都有此屬性，實測未支持） |
  • | hover-start-time | Number | 50 | 按住后多久出現點擊態，單位毫秒 |
  • | hover-stay-time | Number | 400 | 手指松開后點擊態保留時間，單位毫秒 |
  • 注釋：這些屬性要在華為HarmonyOS Next實現兼容，需要對應使用 HBuilderX 4.23 及以上的編譯器版本。
• App平臺 Vue2 項目在節點非常多時可以嘗試使用 <div> 替換 <view> 以提升渲染性能。

scroll-view

• 在webview渲染的頁面中，區域滾動的性能不及頁面滾動
• 屬性說明
  • | scroll-x | Boolean | false | 允許橫向滾動 |
    • 使用橫向滾動時，需要給<scroll-view>添加white-space: nowrap;樣式
    • 注釋：normal：合并連續的空白符，忽略開頭和結尾的空白符。文本會在一行內顯示，除非溢出容器。
  • | scroll-y | Boolean | false | 允許縱向滾動 |
    • 使用豎向滾動時，需要給 <scroll-view> 一個固定高度，通過 css 設置 height
  • | upper-threshold | Number/String | 50 | 距頂部/左邊多遠時（單位px），觸發 scrolltoupper 事件 |
  • | lower-threshold | Number/String | 50 | 距底部/右邊多遠時（單位px），觸發 scrolltolower 事件 |
  • | scroll-top | Number/String | | 設置豎向滾動條位置 |
    • scroll-into-view 的優先級高于 scroll-top。
  • | scroll-left | Number/String | | 設置橫向滾動條位置 |
  • | scroll-into-view | String | | 值應為某子元素id（id不能以數字開頭）。設置哪個方向可滾動，則在哪個方向滾動到該元素 |
  • | scroll-with-animation | Boolean | false | 在設置滾動條位置時使用動畫過渡 |
  • | enable-back-to-top | Boolean | false | iOS點擊頂部狀態欄、安卓雙擊標題欄時，滾動條返回頂部，只支持豎向 | app-nvue，微信小程序 |
  • | show-scrollbar | Boolean | false | 控制是否出現滾動條 | App-nvue 2.1.5+ |
  • | refresher-enabled | Boolean | false | 開啟自定義下拉刷新 | H5、app-vue 2.5.12+,微信小程序基礎庫2.10.1+ |
  • | refresher-threshold | Number | 45 | 設置自定義下拉刷新閾值 | H5、app-vue 2.5.12+,微信小程序基礎庫2.10.1+ |
  • | refresher-default-style | String | "black" | 設置自定義下拉刷新默認樣式，支持設置 black，white，none，none 表示不使用默認樣式 | H5、app-vue 2.5.12+,微信小程序基礎庫2.10.1+ |
  • | refresher-background | String | "#FFF" | 設置自定義下拉刷新區域背景顏色 | H5、app-vue 2.5.12+,微信小程序基礎庫2.10.1+ |
  • | refresher-triggered | Boolean | false | 設置當前下拉刷新狀態，true 表示下拉刷新已經被觸發，false 表示下拉刷新未被觸發 | H5、app-vue 2.5.12+,微信小程序基礎庫2.10.1+ |
  • | enable-flex | Boolean | false | 啟用 flexbox 布局。開啟后，當前節點聲明了 display: flex 就會成為 flex container，并作用于其孩子節點。 | 微信小程序 2.7.3 |
  • | scroll-anchoring | Boolean | false | 開啟 scroll anchoring 特性，即控制滾動位置不隨內容變化而抖動，僅在 iOS 下生效，安卓下可參考 CSS overflow-anchor 屬性。 | 微信小程序 2.8.2 |
    • 注釋：overflow-anchor CSS 屬性提供一種退出瀏覽器滾動錨定行為的方法，該行為會調整滾動位置以最大程度地減少內容偏移。
  • | @scrolltoupper | EventHandle | | 滾動到頂部/左邊，會觸發 scrolltoupper 事件 |
  • | @scrolltolower | EventHandle | | 滾動到底部/右邊，會觸發 scrolltolower 事件 |
  • | @scroll | EventHandle | | 滾動時觸發，event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY} |
  • | @refresherpulling | EventHandle | | 自定義下拉刷新控件被下拉 | H5、app-vue 2.5.12+,微信小程序基礎庫2.10.1+ |
  • | @refresherrefresh | EventHandle | | 自定義下拉刷新被觸發 | H5、app-vue 2.5.12+,微信小程序基礎庫2.10.1+ |
  • | @refresherrestore | EventHandle | | 自定義下拉刷新被復位 | H5、app-vue 2.5.12+,微信小程序基礎庫2.10.1+ |
  • | @refresherabort | EventHandle | | 自定義下拉刷新被中止 | H5、app-vue 2.5.12+,微信小程序基礎庫2.10.1+ |
• webview中使用scroll-view的注意
  • 原生組件嵌套問題
    • APP-vue，scroll-view 中避免使用 map、video 等原生組件。
    • 微信基礎庫2.4.4起支持了原生組件在 scroll-view、swiper、movable-view 中的使用。但并非所有小程序都支持，需具體查詢各家小程序webview是否實現了同層渲染。
      • 注釋：在微信小程序中，“原生組件”通常指的是那些由微信團隊直接提供的、基于原生技術實現的UI組件。這些組件相比于普通的H5元素，具有更高的性能和更豐富的功能。原生組件可以直接利用設備的硬件能力，從而提供更好的用戶體驗。
  • 長列表性能問題
    • scroll-view 不適合放長列表，有性能問題。webview渲染時，建議改用webview的頁面滾動；app-nvue需使用list組件；app-uvue需使用list-view組件。
    • 如果您一定要在webview中實現區域長列表，建議使用三方如better-scroll組件，或者插件市場搜索 虛擬列表，這些專業組件實現了dom復用，即便列表很長也不會創建很多dom。
  • 下拉刷新問題
    • webview渲染時，建議使用頁面級的原生下拉刷新，性能更好。如一定要在webview中自定義下拉刷新，建議插件市場搜索虛擬列表，這些專業組件使用wxs、renderjs等技術避免通信阻塞。
  • scroll-view是區域滾動，不會觸發頁面滾動，無法觸發pages.json配置的下拉刷新、頁面觸底onReachBottomDistance、titleNView的transparent透明漸變。但在app-uvue下，scroll-view如果是頁面頂級節點，則等同于頁面滾動。
  • webview渲染時，scroll-view的滾動條設置，可通過css的-webkit-scrollbar自定義，包括隱藏滾動條。
• 在app-uvue中，其實沒有頁面級滾動，scroll-view也不存在原生組件層級、下拉刷新性能問題
  • 但app-uvue里使用長列表，請務必使用list-view組件，這個組件內置了recycle-view機制，不管列表多長，都可以通過回收不顯示的列表來保證高性能
  • 注釋：nvue 組件中的 list 組件

swiper 滑塊視圖容器

• 滑動切換和滾動的區別，滑動切換是一屏一屏的切換
• 屬性說明
  • | indicator-dots | Boolean | false | 是否顯示面板指示點 |
  • | indicator-color | Color | rgba(0, 0, 0, .3) | 指示點顏色 |
  • | indicator-active-color | Color | #000000 | 當前選中的指示點顏色 |
  • | active-class | String | | swiper-item 可見時的 class | 支付寶小程序 |
  • | changing-class | String | | acceleration 設置為 true 時且處于滑動過程中，中間若干屏處于可見時的class | 支付寶小程序 |
  • | autoplay | Boolean | false | 是否自動切換 |
  • | current | Number | 0 | 當前所在滑塊的 index |
  • | current-item-id | String | | 當前所在滑塊的 item-id ，不能與 current 被同時指定 | 支付寶小程序不支持 |
  • | interval | Number | 5000 | 自動切換時間間隔 |
  • | duration | Number | 500 | 滑動動畫時長 | app-nvue不支持 |
  • | circular | Boolean | false | 是否采用銜接滑動，即播放到末尾后重新回到開頭 |
  • | vertical | Boolean | false | 滑動方向是否為縱向 |
  • | previous-margin | String | 0px | 前邊距，可用于露出前一項的一小部分，接受 px 和 rpx 值 | app-nvue、抖音小程序、飛書小程序不支持 |
  • | next-margin | String | 0px | 后邊距，可用于露出后一項的一小部分，接受 px 和 rpx 值 | app-nvue、抖音小程序、飛書小程序不支持 |
  • | acceleration | Boolean | false | 當開啟時，會根據滑動速度，連續滑動多屏 | 支付寶小程序 |
  • | disable-programmatic-animation | Boolean | false | 是否禁用代碼變動觸發 swiper 切換時使用動畫。 | 支付寶小程序 |
  • | display-multiple-items | Number | 1 | 同時顯示的滑塊數量 | app-nvue、支付寶小程序不支持 |