提交 f89879a4 编写于 作者: D DCloud_LXH

chore: 改善部分 component 组件文档

上级 4aed0376
......@@ -6,10 +6,10 @@
* [scroll-view](component/scroll-view.md)
* [swiper](component/swiper.md)
* [match-media](component/match-media.md)
* [movable-area](component/movable-view.md?id=movable-area)
* [movable-view](component/movable-view.md?id=movable-view)
* [cover-view](/component/cover-view?id=cover-view)
* [cover-image](/component/cover-view?id=cover-image)
* [movable-area](component/movable-area.md)
* [movable-view](component/movable-view.md)
* [cover-view](/component/cover-view.md)
* [cover-image](/component/cover-image.md)
* [基础内容](component/icon.md)
* [icon](component/icon.md)
* [text](component/text.md)
......
### cover-image
覆盖在原生组件上的图片视图。可覆盖的原生组件同`cover-view`,支持嵌套在`cover-view`里。
**平台差异说明**
|App|H5|微信小程序|支付宝小程序|百度小程序|字节跳动小程序、飞书小程序|QQ小程序|快应用|360小程序|快手小程序|京东小程序|
|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
|√|√|√|√|√|x|√|√|x|√|√|
**属性说明**
|属性名|类型|默认值|说明|平台差异说明|
|:-|:-|:-|:-|:-|
|src|String||图标路径。支持本地路径、网络路径。不支持 base64 格式。||
|@load|eventhandle||图片加载成功时触发|微信小程序 2.1.0、京东小程序|
|@error|eventhandle||图片加载失败时触发|微信小程序 2.1.0、京东小程序|
app-vue上可覆盖的原生组件:`<video>``<map>`
支持的事件:`click`
**不支持的 CSS**
- position: fixed
- opacity
- overflow
- padding
- linebreak
- white-space
注意:nvue的cover-view不在上述限制中,它仅支持且全部支持nvue的所有css。
**Tips**
- App端vue页面 `cover-view``cover-image` 中不支持嵌套其它组件,包括再次嵌套`cover-view`,仅可覆盖`video``map`。App端nvue页面自2.1.5起没有这些限制。
- App端 `cover-image` 使用本地图像的话,打包前需要设置资源为释放模式,在manifest文件内app-plus新增runmode节点,设置值为liberate。
- App端还可以使用plus.nativeObj.view绘制原生内容,参考:[uni-app中使用5+界面控件](https://ask.dcloud.net.cn/article/35036)[plus.nativeObj.view规范](https://www.html5plus.org/doc/zh_cn/nativeobj.html#plus.nativeObj.View)
- App端还提供了更灵活和强大的`subNvue`,参考[原生子窗体subNvue](/api/window/subNVues)
- 在 video 组件中使用时,若想在全屏模式下使用`cover-view`,只有在微信小程序、App端的nvue页面可实现。
- 在App端,如果重度使用video和map,推荐使用nvue页面。
- 百度小程序iOS端暂不支持一个页面有多个video时嵌套cover-view。
- 支付宝小程序中 `cover-view` 不支持嵌套。
**微信小程序的cover-view使用注意:**
- cover-view和cover-image的aria-role仅可设置为button,读屏模式下才可以点击,并朗读出“按钮”;为空时可以聚焦,但不可点击
- 基础库 2.2.4 起支持 touch 相关事件,也可使用 hover-class 设置点击态
- 基础库 2.1.0 起支持设置 scale rotate 的 css 样式,包括 transition 动画
- 基础库 1.9.90 起 cover-view 支持 overflow: scroll,但不支持动态更新 overflow
- 基础库 1.9.90 起最外层 cover-view 支持 position: fixed
- 基础库 1.9.0 起支持插在 view 等标签下。在此之前只可嵌套在原生组件map、video、canvas、camera内,避免嵌套在其他组件内。
- 基础库 1.6.0 起支持css transition动画,transition-property只支持transform (translateX, translateY)与opacity。
- 基础库 1.6.0 起支持css opacity。
- 事件模型遵循冒泡模型,但不会冒泡到原生组件。
- 文本建议都套上cover-view标签,避免排版错误。
- 只支持基本的定位、布局、文本样式。不支持设置单边的border、background-image、shadow、overflow: visible等。
- 建议子节点不要溢出父节点
- 支持使用 z-index 控制层级
- 默认设置的样式有:white-space: nowrap; line-height: 1.2; display: block;
- 自定义组件嵌套 cover-view 时,自定义组件的 slot 及其父节点暂不支持通过 wx:if 控制显隐,否则会导致 cover-view 不显示
**示例** [查看演示](https://hellouniapp.dcloud.net.cn/pages/component/cover-view/cover-view)
以下示例代码,来自于[hello uni-app项目](https://github.com/dcloudio/hello-uniapp),推荐使用HBuilderX,新建uni-app项目,选择hello uni-app模板,可直接体验完整示例。
```html
<!-- 本示例未包含完整css,获取外链css请参考上文,在hello uni-app项目中查看 -->
<template>
<view class="page">
<video class="video" id="demoVideo" :controls="false" :enable-progress-gesture="false" :show-center-play-btn="true" src="https://img.cdn.aliyun.dcloud.net.cn/guide/uniapp/%E7%AC%AC1%E8%AE%B2%EF%BC%88uni-app%E4%BA%A7%E5%93%81%E4%BB%8B%E7%BB%8D%EF%BC%89-%20DCloud%E5%AE%98%E6%96%B9%E8%A7%86%E9%A2%91%E6%95%99%E7%A8%8B@20181126-lite.m4v">
<cover-view class="controls-title">简单的自定义 controls</cover-view>
<cover-image class="controls-play img" @click="play" src="/static/play.png"></cover-image>
<cover-image class="controls-pause img" @click="pause" src="/static/pause.png"></cover-image>
</video>
</view>
</template>
<script>
export default {
data() {
return {}
},
mounted() {
this.videoCtx = uni.createVideoContext('demoVideo')
},
methods: {
play(event) {
this.videoCtx.play();
uni.showToast({
title: '开始播放',
icon: 'none'
});
},
pause(event) {
this.videoCtx.pause();
uni.showToast({
title: '暂停播放',
icon: 'none'
});
}
}
}
</script>
<style>
.page {
display: flex;
justify-content: center;
}
.video {
position: relative;
}
cover-view,
cover-image {
display: inline-block;
}
.img {
position: absolute;
width: 100rpx;
height: 100rpx;
top: 50%;
margin-top: -50rpx;
}
.controls-play {
left: 50rpx;
}
.controls-pause {
right: 50rpx;
}
.controls-title {
width: 100%;
text-align: center;
color: #FFFFFF;
}
</style>
```
#### cover-view
### cover-view
覆盖在原生组件上的文本视图。
app-vue和小程序框架,渲染引擎是webview的。但为了优化体验,部分组件如map、video、textarea、canvas通过原生控件实现,原生组件层级高于前端组件(类似flash层级高于div)。为了能正常覆盖原生组件,设计了cover-view。
......@@ -21,144 +21,3 @@ app-vue和小程序框架,渲染引擎是webview的。但为了优化体验,
|属性名|类型|默认值|说明|平台差异说明|
|:-|:-|:-|:-|:-|
|scroll-top|number/string||设置顶部滚动偏移量,仅在设置了 overflow-y: scroll 成为滚动元素后生效|微信小程序2.1.0、京东小程序|
#### cover-image
覆盖在原生组件上的图片视图。可覆盖的原生组件同`cover-view`,支持嵌套在`cover-view`里。
**平台差异说明**
|App|H5|微信小程序|支付宝小程序|百度小程序|字节跳动小程序、飞书小程序|QQ小程序|快应用|360小程序|快手小程序|京东小程序|
|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
|√|√|√|√|√|x|√|√|x|√|√|
**属性说明**
|属性名|类型|默认值|说明|平台差异说明|
|:-|:-|:-|:-|:-|
|src|String||图标路径。支持本地路径、网络路径。不支持 base64 格式。||
|@load|eventhandle||图片加载成功时触发|微信小程序 2.1.0、京东小程序|
|@error|eventhandle||图片加载失败时触发|微信小程序 2.1.0、京东小程序|
app-vue上可覆盖的原生组件:`<video>``<map>`
支持的事件:`click`
**不支持的 CSS**
- position: fixed
- opacity
- overflow
- padding
- linebreak
- white-space
注意:nvue的cover-view不在上述限制中,它仅支持且全部支持nvue的所有css。
**Tips**
- App端vue页面 `cover-view``cover-image` 中不支持嵌套其它组件,包括再次嵌套`cover-view`,仅可覆盖`video``map`。App端nvue页面自2.1.5起没有这些限制。
- App端 `cover-image` 使用本地图像的话,打包前需要设置资源为释放模式,在manifest文件内app-plus新增runmode节点,设置值为liberate。
- App端还可以使用plus.nativeObj.view绘制原生内容,参考:[uni-app中使用5+界面控件](https://ask.dcloud.net.cn/article/35036)[plus.nativeObj.view规范](https://www.html5plus.org/doc/zh_cn/nativeobj.html#plus.nativeObj.View)
- App端还提供了更灵活和强大的`subNvue`,参考[原生子窗体subNvue](/api/window/subNVues)
- 在 video 组件中使用时,若想在全屏模式下使用`cover-view`,只有在微信小程序、App端的nvue页面可实现。
- 在App端,如果重度使用video和map,推荐使用nvue页面。
- 百度小程序iOS端暂不支持一个页面有多个video时嵌套cover-view。
- 支付宝小程序中 `cover-view` 不支持嵌套。
**微信小程序的cover-view使用注意:**
- cover-view和cover-image的aria-role仅可设置为button,读屏模式下才可以点击,并朗读出“按钮”;为空时可以聚焦,但不可点击
- 基础库 2.2.4 起支持 touch 相关事件,也可使用 hover-class 设置点击态
- 基础库 2.1.0 起支持设置 scale rotate 的 css 样式,包括 transition 动画
- 基础库 1.9.90 起 cover-view 支持 overflow: scroll,但不支持动态更新 overflow
- 基础库 1.9.90 起最外层 cover-view 支持 position: fixed
- 基础库 1.9.0 起支持插在 view 等标签下。在此之前只可嵌套在原生组件map、video、canvas、camera内,避免嵌套在其他组件内。
- 基础库 1.6.0 起支持css transition动画,transition-property只支持transform (translateX, translateY)与opacity。
- 基础库 1.6.0 起支持css opacity。
- 事件模型遵循冒泡模型,但不会冒泡到原生组件。
- 文本建议都套上cover-view标签,避免排版错误。
- 只支持基本的定位、布局、文本样式。不支持设置单边的border、background-image、shadow、overflow: visible等。
- 建议子节点不要溢出父节点
- 支持使用 z-index 控制层级
- 默认设置的样式有:white-space: nowrap; line-height: 1.2; display: block;
- 自定义组件嵌套 cover-view 时,自定义组件的 slot 及其父节点暂不支持通过 wx:if 控制显隐,否则会导致 cover-view 不显示
**示例** [查看演示](https://hellouniapp.dcloud.net.cn/pages/component/cover-view/cover-view)
以下示例代码,来自于[hello uni-app项目](https://github.com/dcloudio/hello-uniapp),推荐使用HBuilderX,新建uni-app项目,选择hello uni-app模板,可直接体验完整示例。
```html
<!-- 本示例未包含完整css,获取外链css请参考上文,在hello uni-app项目中查看 -->
<template>
<view class="page">
<video class="video" id="demoVideo" :controls="false" :enable-progress-gesture="false" :show-center-play-btn="true" src="https://img.cdn.aliyun.dcloud.net.cn/guide/uniapp/%E7%AC%AC1%E8%AE%B2%EF%BC%88uni-app%E4%BA%A7%E5%93%81%E4%BB%8B%E7%BB%8D%EF%BC%89-%20DCloud%E5%AE%98%E6%96%B9%E8%A7%86%E9%A2%91%E6%95%99%E7%A8%8B@20181126-lite.m4v">
<cover-view class="controls-title">简单的自定义 controls</cover-view>
<cover-image class="controls-play img" @click="play" src="/static/play.png"></cover-image>
<cover-image class="controls-pause img" @click="pause" src="/static/pause.png"></cover-image>
</video>
</view>
</template>
<script>
export default {
data() {
return {}
},
mounted() {
this.videoCtx = uni.createVideoContext('demoVideo')
},
methods: {
play(event) {
this.videoCtx.play();
uni.showToast({
title: '开始播放',
icon: 'none'
});
},
pause(event) {
this.videoCtx.pause();
uni.showToast({
title: '暂停播放',
icon: 'none'
});
}
}
}
</script>
<style>
.page {
display: flex;
justify-content: center;
}
.video {
position: relative;
}
cover-view,
cover-image {
display: inline-block;
}
.img {
position: absolute;
width: 100rpx;
height: 100rpx;
top: 50%;
margin-top: -50rpx;
}
.controls-play {
left: 50rpx;
}
.controls-pause {
right: 50rpx;
}
.controls-title {
width: 100%;
text-align: center;
color: #FFFFFF;
}
</style>
```
#### match-media
### match-media
media query 匹配检测节点。
......
### movable-area
可拖动区域
由于app和小程序的架构是逻辑层与视图层分离,使用js监听拖动时会引发逻辑层和视图层的频繁通讯,影响性能。为了方便高性能的实现拖动,平台特封装了`movable-area`组件。
`movable-area`指代可拖动的范围,在其中内嵌`movable-view`组件用于指示可拖动的区域。
即手指/鼠标按住`movable-view`拖动或双指缩放,但拖不出`movable-area`规定的范围。
当然也可以不拖动,而使用代码来触发`movable-view``movable-area`里的移动缩放。
`movable-view`的规范另见[movable-view](/component/movable-view.html)
**平台差异说明**
|App|H5|微信小程序|支付宝小程序|百度小程序|字节跳动小程序、飞书小程序|QQ小程序|快应用|360小程序|快手小程序|京东小程序|
|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
|√|√|√|√|√|x|√|√|√|√|√|
**属性说明**
|属性名|类型|默认值|说明|
|:-|:-|:-|:-|
|scale-area|Boolean|false|当里面的 movable-view 设置为支持双指缩放时,设置此值可将缩放手势生效区域修改为整个 movable-area|
**注意:movable-area 必须设置 width 和 height 属性,不设置默认为 10px**
- movable-area app-nvue平台 暂不支持手势缩放,并且和滚动冲突。
\ No newline at end of file
#### movable-area
可拖动区域
由于app和小程序的架构是逻辑层与视图层分离,使用js监听拖动时会引发逻辑层和视图层的频繁通讯,影响性能。为了方便高性能的实现拖动,平台特封装了`movable-area`组件。
`movable-area`指代可拖动的范围,在其中内嵌`movable-view`组件用于指示可拖动的区域。
即手指/鼠标按住`movable-view`拖动或双指缩放,但拖不出`movable-area`规定的范围。
当然也可以不拖动,而使用代码来触发`movable-view``movable-area`里的移动缩放。
`movable-view`的规范另见[下文](#movable-view)
**平台差异说明**
|App|H5|微信小程序|支付宝小程序|百度小程序|字节跳动小程序、飞书小程序|QQ小程序|快应用|360小程序|快手小程序|京东小程序|
|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
|√|√|√|√|√|x|√|√|√|√|√|
**属性说明**
|属性名|类型|默认值|说明|
|:-|:-|:-|:-|
|scale-area|Boolean|false|当里面的 movable-view 设置为支持双指缩放时,设置此值可将缩放手势生效区域修改为整个 movable-area|
**注意:movable-area 必须设置 width 和 height 属性,不设置默认为 10px**
- movable-area app-nvue平台 暂不支持手势缩放,并且和滚动冲突。
#### movable-view
### movable-view
可移动的视图容器,在页面中可以拖拽滑动或双指缩放。
......
#### scroll-view
### scroll-view
可滚动视图区域。用于区域滚动。
......@@ -110,7 +110,7 @@ export default {
}
```
**自定义下拉刷新**
### 自定义下拉刷新
注意自定义下拉刷新的性能不及pages.json中配置的原生下拉刷新。
```html
......
#### swiper
### swiper
滑块视图容器。
......
所有的视图组件,包括view、swiper等,本身不显示任何可视化元素。它们的用途都是为了包裹其他真正显示的组件。
#### view
### view
视图容器。
......
插件支持多语言是基于[uni-app国际化](https://uniapp.dcloud.net.cn/tutorial/i18n.html)[HBuilderX插件国际化](https://hx.dcloud.net.cn/ExtensionTutorial/localized)规范延伸而来的,所以不同类型的插件多语言规范略有不同。
# uni-app及uniCloud分类
## uni-app及uniCloud分类
参考[国际化专题](https://uniapp.dcloud.net.cn/tutorial/i18n.html)相关教程
# HBuilderX分类
## HBuilderX分类
参考[HBuilderX插件国际化](https://hx.dcloud.net.cn/ExtensionTutorial/localized)规范教程,根据插件根目录下package.nls.[语言代码].json进行识别,如插件除默认语言之外支持英语及日语,插件包则需要包含如下文件:
```
插件根目录
......
### 插件市场介绍
## 插件市场介绍
DCloud有活跃的插件市场,[https://ext.dcloud.net.cn/](https://ext.dcloud.net.cn/),并提供了变现、评价等机制。
......
### 持续集成
## 持续集成
很多公司的开发人员提交代码后,需要自动打包或持续集成。
......
# uni-app cli项目@uniapp-cli
## uni-app cli项目@uniapp-cli
> 本文档仅适用于CLI工程。
......@@ -30,7 +30,7 @@ npm install @dcloudio/uni-automator --save-dev
"test:mp-baidu": "cross-env UNI_PLATFORM=mp-baidu jest -i"
```
#### H5平台测试流程
### H5平台测试流程
1. 进入工程目录,安装依赖
```
......@@ -61,7 +61,7 @@ Time: 14.995s, estimated 16s
更多配置参考 [jest.config.js](collocation/auto/quick-start?id=jestconfigjs)
#### App-Android测试流程
### App-Android测试流程
1. 配置全局 `adb` 环境变量
......@@ -81,7 +81,7 @@ npm run test:android
```
#### App-iOS测试流程
### App-iOS测试流程
目前仅支持 iOS 模拟器(需要mac电脑安装xcode)
......@@ -103,7 +103,7 @@ npm run test:ios
#### 微信小程序测试流程
### 微信小程序测试流程
1. 创建cli项目,同H5平台 (必须配置微信小程序 appid, manifest.json -> mp-weixin -> appid)
......@@ -123,7 +123,7 @@ Time: 14.995s, estimated 16s
#### 测试示例
### 测试示例
使用 hello uni-app 工程测试 H5 平台
......@@ -218,7 +218,7 @@ Time: 14.995s, estimated 16s
##### 屏幕截图示例
#### 屏幕截图示例
```
describe('pages/API/set-navigation-bar-title/set-navigation-bar-title.vue', () => {
let page
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册