uni-app介绍文档总结

用户斌馨 發表於 2020-4-13 12:24:00

<h1 id="开发规范">开发规范</h1>
<h2 id="基础组件">基础组件</h2>
<blockquote>
<p>uni-app 为开发者提供了一系列基础组件，类似 HTML 里的基础标签元素。但 uni-app 的组件与 HTML 不同，而是与小程序相同，更适合手机端使用。</p>
</blockquote>
<div style="color: rgba(204, 50, 153, 1)">虽然不推荐使用 HTML 标签，但实际上如果开发者写了 div 等标签，在编译到非 H5 平台时也会被编译器转换为 view 标签，类似的还有 span 转 text、a 转 navigator 等，包括 css 里的元素选择器也会转。但为了管理方便、策略统一，新写代码时仍然建议使用 view 等组件。</div>

<p><code>Tips</code></p>
<ul>
<li>所有组件与属性名都是小写，单词之间以连字符<code>-</code>连接。</li>
<li>根节点为 <code><template> </code>,这个<code><template></code> 下只能且必须有一个根<code><view></code>组件。这是vue单文件组件规范。</li>
<li><strong>平台差异说明</strong>若无特殊说明，则表示所有平台均支持。</li>
</ul>
<h3 id="属性类型">属性类型</h3>
<table>
<thead>
<tr>
<th style="text-align: center">类型</th>
<th style="text-align: left">描述</th>
<th style="text-align: left">注解</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: center">Boolean</td>
<td style="text-align: left">布尔值</td>
<td style="text-align: left">组件写上该属性，不管该属性等于什么，其值都为 <code>true</code>，只有组件上没有写该属性时，属性值才为 <code>false</code>。如果属性值为变量，变量的值会被转换为 <code>Boolean</code> 类型。</td>
</tr>
<tr>
<td style="text-align: center">Number</td>
<td style="text-align: left">数字</td>
<td style="text-align: left">1, 2.5</td>
</tr>
<tr>
<td style="text-align: center">String</td>
<td style="text-align: left">字符串</td>
<td style="text-align: left">"string"</td>
</tr>
<tr>
<td style="text-align: center">Array</td>
<td style="text-align: left">数组</td>
<td style="text-align: left">[ 1, "string" ]</td>
</tr>
<tr>
<td style="text-align: center">Object</td>
<td style="text-align: left">对象</td>
<td style="text-align: left"></td>
</tr>
<tr>
<td style="text-align: center">EventHandler</td>
<td style="text-align: left">事件处理函数名</td>
<td style="text-align: left"><code>handlerName</code> 是 methods 中定义的事件处理函数名</td>
</tr>
<tr>
<td style="text-align: center">Any</td>
<td style="text-align: left">任意属性</td>
<td style="text-align: left"></td>
</tr>
</tbody>
</table>
<h3 id="组件列表">组件列表</h3>
<p>基础组件分为以下八大类：</p>
<p><strong>视图容器（View Container）：</strong></p>
<table>
<thead>
<tr>
<th style="text-align: left">组件名</th>
<th style="text-align: left">说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left">view</td>
<td style="text-align: left">视图容器，类似于HTML中的div</td>
</tr>
<tr>
<td style="text-align: left">scroll-view</td>
<td style="text-align: left">可滚动视图容器</td>
</tr>
<tr>
<td style="text-align: left">swiper</td>
<td style="text-align: left">滑块视图容器</td>
</tr>
</tbody>
</table>
<p><strong>基础内容（Basic Content）：</strong></p>
<table>
<thead>
<tr>
<th style="text-align: left">组件名</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left">icon</td>
<td>图标</td>
</tr>
<tr>
<td style="text-align: left">text</td>
<td>文字</td>
</tr>
<tr>
<td style="text-align: left">rich-text</td>
<td>富文本</td>
</tr>
<tr>
<td style="text-align: left">progress</td>
<td>进度条</td>
</tr>
</tbody>
</table>
<p><strong>表单组件（Form）：</strong></p>
<table>
<thead>
<tr>
<th style="text-align: left">标签名</th>
<th style="text-align: left">说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left">button</td>
<td style="text-align: left">按钮</td>
</tr>
<tr>
<td style="text-align: left">form</td>
<td style="text-align: left">表单</td>
</tr>
<tr>
<td style="text-align: left">input</td>
<td style="text-align: left">输入框</td>
</tr>
<tr>
<td style="text-align: left">checkbox</td>
<td style="text-align: left">多项选择器</td>
</tr>
<tr>
<td style="text-align: left">radio</td>
<td style="text-align: left">单项选择器</td>
</tr>
<tr>
<td style="text-align: left">picker</td>
<td style="text-align: left">弹出式列表选择器</td>
</tr>
<tr>
<td style="text-align: left">picker-view</td>
<td style="text-align: left">窗体内嵌式列表选择器</td>
</tr>
<tr>
<td style="text-align: left">slider</td>
<td style="text-align: left">滑动选择器</td>
</tr>
<tr>
<td style="text-align: left">switch</td>
<td style="text-align: left">开关选择器</td>
</tr>
<tr>
<td style="text-align: left">label</td>
<td style="text-align: left">标签</td>
</tr>
</tbody>
</table>
<p><strong>导航（Navigation）：</strong></p>
<table>
<thead>
<tr>
<th style="text-align: left">组件名</th>
<th style="text-align: left">说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left">navigator</td>
<td style="text-align: left">页面链接。类似于HTML中的a标签</td>
</tr>
</tbody>
</table>
<p><strong>媒体组件（Media）：</strong></p>
<table>
<thead>
<tr>
<th style="text-align: left">组件名</th>
<th style="text-align: left">说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left">audio</td>
<td style="text-align: left">音频</td>
</tr>
<tr>
<td style="text-align: left">camera</td>
<td style="text-align: left">相机</td>
</tr>
<tr>
<td style="text-align: left">image</td>
<td style="text-align: left">图片</td>
</tr>
<tr>
<td style="text-align: left">video</td>
<td style="text-align: left">视频</td>
</tr>
<tr>
<td style="text-align: left">live-player</td>
<td style="text-align: left">直播播放</td>
</tr>
<tr>
<td style="text-align: left">live-pusher</td>
<td style="text-align: left">实时音视频录制，也称直播推流</td>
</tr>
</tbody>
</table>
<p><strong>地图（Map）：</strong></p>
<table>
<thead>
<tr>
<th style="text-align: left">组件名</th>
<th style="text-align: left">说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left">map</td>
<td style="text-align: left">地图</td>
</tr>
</tbody>
</table>
<p><strong>画布（Canvas）：</strong></p>
<table>
<thead>
<tr>
<th style="text-align: left">组件名</th>
<th style="text-align: left">说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left">canvas</td>
<td style="text-align: left">画布</td>
</tr>
</tbody>
</table>
<p><strong>webview（Web-view）：</strong></p>
<table>
<thead>
<tr>
<th style="text-align: left">组件名</th>
<th style="text-align: left">说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left">web-view</td>
<td style="text-align: left">web浏览器组件</td>
</tr>
</tbody>
</table>
<h2 id="目录结构">目录结构</h2>
<p>一个uni-app工程，默认包含如下目录及文件：</p>
<pre><code class="language-js">┌─components          uni-app组件目录
│└─comp-a.vue       可复用的a组件
├─hybrid             存放本地网页的目录，详见
├─platforms          存放各平台专用页面的目录，详见
├─pages             业务页面文件存放的目录
│├─index
││└─index.vue    index页面
│└─list
│ └─list.vue    list页面
├─static             存放应用引用静态资源（如图片、视频等）的目录，注意：静态资源只能存放于此
├─wxcomponents       存放小程序组件的目录，详见
├─main.js             Vue初始化入口文件
├─App.vue             应用配置，用来配置App全局样式以及监听应用生命周期
├─manifest.json       配置应用名称、appid、logo、版本等打包信息，详见
└─pages.json          配置页面路由、导航条、选项卡等页面类信息，详见
</code></pre>
<h2 id="资源路径说明">资源路径说明</h2>
<h3 id="模板内引入静态资源">模板内引入静态资源</h3>
<blockquote>
<p><code>template</code>内引入静态资源，如<code>image</code>、<code>video</code>等标签的<code>src</code>属性时，可以使用相对路径或者绝对路径，形式如下</p>
</blockquote>
<pre><code class="language-html">
<image class="logo" src="/static/logo.png"></image>
<image class="logo" src="@/static/logo.png"></image>

<image class="logo" src="../../static/logo.png"></image>
</code></pre>
<p><strong>注意</strong></p>
<ul>
<li><code>@</code>开头的绝对路径以及相对路径会经过base64转换规则校验</li>
<li>引入的静态资源在非h5平台，均不转为base64。</li>
<li>H5平台，小于4kb的资源会被转换成base64，其余不转。</li>
<li>自<code>HBuilderX 2.6.6-alpha</code>起<code>template</code>内支持<code>@</code>开头路径引入静态资源，旧版本不支持此方式</li>
<li>App平台自<code>HBuilderX 2.6.9-alpha</code>起<code>template</code>节点中引用静态资源文件时（如：图片），调整查找策略为【基于当前文件的路径搜索】，与其他平台保持一致</li>
<li>支付宝小程序组件内 image 标签不可使用相对路径</li>
</ul>
<h3 id="js文件引入">js文件引入</h3>
<p><code>js</code>文件或<code>script</code>标签内（包括renderjs等）引入<code>js</code>文件时，可以使用相对路径和绝对路径，形式如下</p>
<pre><code class="language-js">// 绝对路径，@指向项目根目录，在cli项目中@指向src目录
import add from '@/common/add.js'
// 相对路径
import add from '../../common/add.js'
</code></pre>
<p><strong>注意</strong></p>
<ul>
<li>js文件不支持使用<code>/</code>开头的方式引入</li>
</ul>
<h3 id="css引入静态资源">css引入静态资源</h3>
<blockquote>
<p><code>css</code>文件或<code>style标签</code>内引入<code>css</code>文件时（scss、less文件同理），只能使用相对路径</p>
</blockquote>
<pre><code class="language-css">/* 绝对路径 */
@import url('/common/uni.css');
@import url('@/common/uni.css');
/* 相对路径 */
@import url('../../common/uni.css');
</code></pre>
<p><strong>注意</strong></p>
<ul>
<li>自<code>HBuilderX 2.6.6-alpha</code>起支持绝对路径引入静态资源，旧版本不支持此方式</li>
</ul>
<blockquote>
<p><code>css</code>文件或<code>style标签</code>内引用的图片路径可以使用相对路径也可以使用绝对路径，需要注意的是，有些小程序端css文件不允许引用本地文件（请看注意事项）。</p>
</blockquote>
<pre><code class="language-css">/* 绝对路径 */
background-image: url(/static/logo.png);
background-image: url(@/static/logo.png);
/* 相对路径 */
background-image: url(../../static/logo.png);
</code></pre>
<p><strong>Tips</strong></p>
<ul>
<li>引入字体图标请参考，字体图标</li>
<li><code>@</code>开头的绝对路径以及相对路径会经过base64转换规则校验</li>
<li>不支持本地图片的平台，小于40kb，一定会转base64。（共四个平台mp-weixin, mp-qq, mp-toutiao, app v2）</li>
<li>h5平台，小于4kb会转base64，超出4kb时不转。</li>
<li>其余平台不会转base64</li>
</ul>
<h2 id="页面样式与布局">页面样式与布局</h2>
<h3 id="尺寸单位">尺寸单位</h3>
<p><strong>Tips</strong></p>
<ul>
<li>注意 rpx 是和宽度相关的单位，屏幕越宽，该值实际像素越大。如不想根据屏幕宽度缩放，则应该使用 px 单位。</li>
<li>如果开发者在字体或高度中也使用了 rpx ，那么需注意这样的写法意味着随着屏幕变宽，字体会变大、高度会变大。如果你需要固定高度，则应该使用 px 。</li>
<li>设计师可以用 iPhone6 作为视觉稿的标准。</li>
<li>如果设计稿不是750px，HBuilderX提供了自动换算的工具，详见：https://ask.dcloud.net.cn/article/35445。</li>
<li>早期 uni-app 提供了 upx ，<em><u>目前已经推荐统一改为 rpx 了</u></em>，详见</li>
</ul>
<h3 id="选择器">选择器</h3>
<ul>
<li>在 <code>uni-app</code> 中不能使用 <code>*</code> 选择器。</li>
<li><code>page</code> 相当于 <code>body</code> 节点，例如：</li>
</ul>
<pre><code class="language-scss">
page {
background-color:#ccc;
}
</code></pre>
<h3 id="css变量">CSS变量</h3>
<p>uni-app 提供内置 CSS 变量</p>
<table>
<thead>
<tr>
<th style="text-align: left">CSS变量</th>
<th style="text-align: left">描述</th>
<th style="text-align: left">App</th>
<th style="text-align: left">小程序</th>
<th style="text-align: left">H5</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left">--status-bar-height</td>
<td style="text-align: left">系统状态栏高度</td>
<td style="text-align: left">系统状态栏高度、nvue注意见下</td>
<td style="text-align: left">25px</td>
<td style="text-align: left">0</td>
</tr>
<tr>
<td style="text-align: left">--window-top</td>
<td style="text-align: left">内容区域距离顶部的距离</td>
<td style="text-align: left">0</td>
<td style="text-align: left">0</td>
<td style="text-align: left">NavigationBar 的高度</td>
</tr>
<tr>
<td style="text-align: left">--window-bottom</td>
<td style="text-align: left">内容区域距离底部的距离</td>
<td style="text-align: left">0</td>
<td style="text-align: left">0</td>
<td style="text-align: left">TabBar 的高度</td>
</tr>
</tbody>
</table>
<pre><code class="language-scss">.status_bar {
height: var(--status-bar-height);
width: 100%;
}
</code></pre>
<p><strong>注意：</strong></p>
<ul>
<li><code>var(--status-bar-height)</code> 此变量在微信小程序环境为固定 <code>25px</code>，在 App 里为手机实际状态栏高度。</li>
<li>当设置 <code>"navigationStyle":"custom"</code> 取消原生导航栏后，由于窗体为沉浸式，占据了状态栏位置。此时可以使用一个高度为 <code>var(--status-bar-height)</code> 的 view 放在页面顶部，避免页面内容出现在状态栏。</li>
<li>由于在H5端，不存在原生导航栏和tabbar，也是前端div模拟。如果设置了一个固定位置的居底view，在小程序和App端是在tabbar上方，但在H5端会与tabbar重叠。此时可使用<code>--window-bottom</code>，不管在哪个端，都是固定在tabbar上方。</li>
<li>目前 nvue 在App端，还不支持 <code>--status-bar-height</code>变量，替代方案是在页面onLoad时通过uni.getSystemInfoSync().statusBarHeight获取状态栏高度，然后通过style绑定方式给占位view设定高度。下方提供了示例代码</li>
</ul>
<h3 id="背景图片">背景图片</h3>
<p><code>uni-app</code> 支持使用在 css 里设置背景图片，使用方式与普通 <code>web</code> 项目大体相同，但需要注意以下几点：</p>
<ul>
<li>
<p>支持 base64 格式图片。</p>
</li>
<li>
<p>支持网络路径图片。</p>
</li>
<li>
<p>小程序不支持在css中使用本地文件，包括本地的背景图和字体文件。需以base64方式方可使用。App端在v3模式以前，也有相同限制。v3编译模式起支持直接使用本地背景图和字体。</p>
</li>
<li>
<p>使用本地路径背景图片需注意：</p>
<ol>
<li>
<p>为方便开发者，在背景图片小于 40kb 时，<code>uni-app</code> 编译到不支持本地背景图的平台时，会自动将其转化为 base64 格式；</p>
</li>
<li>
<p>图片大于等于 40kb，会有性能问题，不建议使用太大的背景图，如开发者必须使用，则需自己将其转换为 base64 格式使用，或将其挪到服务器上，从网络地址引用。</p>
</li>
<li>
<p>本地背景图片的引用路径推荐使用以 ~@ 开头的绝对路径。</p>
<pre><code class="language-css"> .test2 {
background-image: url('~@/static/logo.png');
}
</code></pre>
</li>
</ol>
</li>
</ul>
<p><strong>注意</strong></p>
<ul>
<li><code>微信小程序不支持相对路径（真机不支持，开发工具支持）</code></li>
</ul>
<h3 id="template和block"><code><template/></code>和<code><block/></code></h3>
<p><code>uni-app</code> 支持在 template 模板中嵌套 <code>和</code>，用来进行列表渲染和条件渲染。</p>
<p><code>和</code> 并不是一个组件，它们仅仅是一个包装元素，不会在页面中做任何渲染，只接受控制属性。</p>
<ul>
<li><code><template/></code>官方用于条件判断</li>
<li><code><block/></code>官方用于做循环</li>
</ul>
<h2 id="class-与-style-绑定">Class 与 Style 绑定</h2>
<p>为节约性能，我们将 <code>Class</code> 与 <code>Style</code> 的表达式通过 <code>compiler</code> 硬编码到 <code>uni-app</code> 中，支持语法和转换效果如下：</p>
<p>class 支持的语法:</p>
<pre><code class="language-html"><view :class="{ active: isActive }">111</view>
<view class="static" v-bind:class="{ active: isActive, 'text-danger': hasError }">222</view>
<view class="static" :class="">333</view>
<view class="static" v-bind:class="">444</view>
<view class="static" v-bind:class="[{ active: isActive }, errorClass]">555</view>
</code></pre>
<p>style 支持的语法:</p>
<pre><code class="language-html"><view v-bind:style="{ color: activeColor, fontSize: fontSize + 'px' }">666</view>
<view v-bind:style="[{ color: activeColor, fontSize: fontSize + 'px' }]">777</view>
</code></pre>
<h3 id="全局组件">全局组件</h3>
<p><code>uni-app</code> 支持配置全局组件，需在 <code>main.js</code> 里进行全局注册，注册后就可在所有页面里使用该组件。</p>
<p><strong>注意</strong></p>
<ul>
<li><code>Vue.component</code> 的第一个参数必须是静态的字符串。</li>
<li>nvue页面暂不支持全局组件</li>
</ul>
<p><strong>示例</strong></p>
<p>main.js 里进行全局导入和注册</p>
<pre><code class="language-javascript">import Vue from 'vue'
import pageHead from './components/page-head.vue'
Vue.component('page-head',pageHead)
</code></pre><br><br>
来源：https://www.cnblogs.com/cjh1996/p/12690609.html

頁: [1]

琼殿技术论坛's Archiver

uni-app介绍文档总结