404
Not Found
一套代码编到7个平台，难以置信吗？眼见为实，扫描7个二维码，亲自体验最全面的跨平台效果！
+ 注：Appstore、百度、头条平台不能提交简单demo，故补充了一些其他功能。 +
一套代码，可发布到IOS、Android、小程序、H5等多个平台。
在跨端的同时，通过条件编译+平台特有API调用，可以优雅的为某平台写个性化代码，调用专有能力而不影响其他平台。
支持原生代码混写和原生sdk集成。
体验更好的Hybrid框架，加载新页面速度更快。
App端支持weex原生渲染，可支撑更流畅的用户体验。
小程序端的性能优于市场其他框架。评测
丰富的插件市场，各种轮子拿来即用。
支持NPM、支持小程序组件和SDK、兼容mpvue组件和项目、兼容weex组件。
微信生态的各种sdk可直接用于跨平台App。
基于通用的前端技术栈，采用vue语法+微信小程序api，无额外学习成本。
不止开发成本，招聘、管理、测试各方面成本都大幅下降。
HBuilderX是高效开发神器，熟练掌握后研发效率至少翻倍（即便只开发一个平台）。
`储存。 + +| 类型 | 节点 | +| --- | --- | +| 行内元素 | ` ` | +| 块级元素 | ` ` | + +#### 支持的内连样式 + +内联样式仅能设置在行内元素或块级元素上，不能同时设置。例如 font-size` 归类为行内元素属性，在 p 标签上设置是无效的。 + +| 类型 | 样式 | +| --- | --- | +| 块级样式 | `text-align` `direction` `margin` `margin-top` `margin-left` `margin-right` `margin-bottom` +`padding` `padding-top` `padding-left` `padding-right` `padding-bottom` `line-height` `text-indent` | +| 行内样式 | `font` `font-size` `font-style` `font-variant` `font-weight` `font-family` +`letter-spacing` `text-decoration` `color` `background-color` | + +**注意事项** + +1. 插入的 html 中事件绑定会被移除 +2. formats 中的 color 属性会统一以 hex 格式返回 +3. 粘贴时仅纯文本内容会被拷贝进编辑器 +4. 插入 html 到编辑器内时，编辑器会删除一些不必要的标签，以保证内容的统一。例如`xxx`会改写为`xxx` +5. 编辑器聚焦时页面会被上推，系统行为以保证编辑区可见 + +**示例代码** + +```html + + + + 撤销 + + + + + + +``` \ No newline at end of file diff --git a/docs/component/form.md b/docs/component/form.md new file mode 100644 index 0000000000000000000000000000000000000000..1f4efb882e6a0a485c4a9e3b2dbcc4930f3b64ee --- /dev/null +++ b/docs/component/form.md @@ -0,0 +1,100 @@ +#### form +表单，将组件内的用户输入的```` ```` ```` ```` ```` ```` 提交。 + +当点击 ```` 表单中 formType 为 submit 的 ```` 组件时，会将表单组件中的 value 值进行提交，需要在表单组件中加上 name 来作为 key。 + +**属性说明** + +|属性名|类型|说明|平台差异说明| +|:-|:-|:-|:-| +|report-submit|Boolean|是否返回 formId 用于发送[模板消息](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/template-message.html)|微信小程序、支付宝小程序| +|@submit|EventHandle|携带 form 中的数据触发 submit 事件，event.detail = {value : {'name': 'value'} , formId: ''}，report-submit 为 true 时才会返回 formId|| +|@reset|EventHandle|表单重置时会触发 reset 事件| | + +**示例** + +```html + + + + + + switch + + + + + + radio + + + 选项一 + + + 选项二 + + + + + checkbox + + + 选项一 + + + 选项二 + + + + + slider + + + + input + + + + Submit + Reset + + + + + +``` + +```javascript +export default { + data() { + return { + pickerHidden: true, + chosen: '' + } + }, + methods: { + pickerConfirm: function(e) { + this.pickerHidden = true + this.chosen = e.target.value + }, + pickerCancel: function(e) { + this.pickerHidden = true + }, + pickerShow: function(e) { + this.pickerHidden = false + }, + formSubmit: function(e) { + console.log('form发生了submit事件，携带数据为：' + JSON.stringify(e.detail.value)) + }, + formReset: function(e) { + console.log('清空数据') + this.chosen = '' + } + } +} +``` + + + +**tips** +- [插件市场](http://ext.dcloud.net.cn/search?q=%E8%A1%A8%E5%8D%95%E6%A0%A1%E9%AA%8C)有表单校验插件 \ No newline at end of file diff --git a/docs/component/icon.md b/docs/component/icon.md new file mode 100644 index 0000000000000000000000000000000000000000..2da6b56fa6ae7812dabf8bfb0f18b714c25b596a --- /dev/null +++ b/docs/component/icon.md @@ -0,0 +1,65 @@ +#### icon + +图标。 + +**平台差异说明** + +|5+App|H5|微信小程序|支付宝小程序|百度小程序| +|:-:|:-:|:-:|:-:|:-:| +|√|x|√|√|√| + +* 由于 icon 组件各端表现存在差异，可以通过使用 [字体图标](/frame?id=字体图标) 的方式来弥补各端差异。 + +**属性说明** + +|属性名|类型|默认值|说明| +|---|---|---|---| +|type|String||icon的类型| +|size|Number|23|icon的大小，单位px| +|color|Color||icon的颜色，同css的color| + +各平台 type 有效值说明： + +|平台|type 有效值| +|:-:|:-:| +|5+App|success, success_no_circle, info, warn, waiting, cancel, download, search, clear| +|微信小程序|success, success_no_circle, info, warn, waiting, cancel, download, search, clear| +|支付宝小程序|info, warn, waiting, cancel, download, search, clear, success, success_no_circle,loading| +|百度小程序|success, info, warn, waiting, success_no_circle, clear, search, personal, setting, top, close, cancel, download, checkboxSelected, radioSelected, radioUnselect| + + +**示例** +```html + + + {{value}} + +``` +```javascript +export default { + data() { + return { + iconType: ['success'] + } + }, + onLoad() { + // #ifdef APP-PLUS|| MP-WEIXIN + this.iconType = ['success', 'success_no_circle', 'info', 'warn', 'waiting', 'cancel', 'download', 'search','clear'] + // #endif + // #ifdef MP-ALIPAY + this.iconType = ['info', 'warn', 'waiting', 'cancel', 'download', 'search', 'clear', 'success', 'success_no_circle', 'loading'] + // #endif + // #ifdef MP-BAIDU + this.iconType = ['success', 'info', 'warn', 'waiting', 'success_no_circle', 'clear', 'search', 'personal', 'setting', 'top', 'close', 'cancel', 'download', 'checkboxSelected', 'radioSelected', 'radioUnselect'] + // #endif + } +} + +``` + +**效果展示** + + + + + diff --git a/docs/component/image.md b/docs/component/image.md new file mode 100644 index 0000000000000000000000000000000000000000..0a815aeb09087a4a917b23d5d21aeec5926ef27c --- /dev/null +++ b/docs/component/image.md @@ -0,0 +1,159 @@ +#### image + +图片。 + +|属性名|类型|默认值|说明|平台差异说明| +|:-|:-|:-|:-|:-| +|src|String||图片资源地址|| +|mode|String|'scaleToFill'|图片裁剪、缩放的模式|| +|lazy-load|Boolean|false|图片懒加载。只针对page与scroll-view下的image有效|微信小程序、5+APP、百度小程序、头条小程序| +|@error|HandleEvent||当错误发生时，发布到 AppService 的事件名，事件对象event.detail = {errMsg: 'something wrong'}|| +|@load|HandleEvent||当图片载入完毕时，发布到 AppService 的事件名，事件对象event.detail = {height:'图片高度px', width:'图片宽度px'}| | + +**Tips** + +- `` 组件默认宽度 300px、高度 225px； +- `src` 仅支持相对路径、绝对路径，支持 base64 码； +- 页面结构复杂，css样式太多的情况，使用 image 可能导致样式生效较慢，出现 “闪一下” 的情况，此时设置 `image{will-change: transform}` ,可优化此问题。 +- 自定义组件里面使用 ``时，若 `src` 使用相对路径可能出现路径查找失败的情况，故建议使用绝对路径。 + +**mode 有效值：** + +mode 有 13 种模式，其中 4 种是缩放模式，9 种是裁剪模式。 + +|模式|值|说明| +|:-|:-|:-| +|缩放|scaleToFill|不保持纵横比缩放图片，使图片的宽高完全拉伸至填满 image 元素| +|缩放|aspectFit|保持纵横比缩放图片，使图片的长边能完全显示出来。也就是说，可以完整地将图片显示出来。| +|缩放|aspectFill|保持纵横比缩放图片，只保证图片的短边能完全显示出来。也就是说，图片通常只在水平或垂直方向是完整的，另一个方向将会发生截取。| +|缩放|widthFix|宽度不变，高度自动变化，保持原图宽高比不变| +|裁剪|top|不缩放图片，只显示图片的顶部区域| +|裁剪|bottom|不缩放图片，只显示图片的底部区域| +|裁剪|center|不缩放图片，只显示图片的中间区域| +|裁剪|left|不缩放图片，只显示图片的左边区域| +|裁剪|right|不缩放图片，只显示图片的右边区域| +|裁剪|top left|不缩放图片，只显示图片的左上边区域| +|裁剪|top right|不缩放图片，只显示图片的右上边区域| +|裁剪|bottom left|不缩放图片，只显示图片的左下边区域| +|裁剪|bottom right|不缩放图片，只显示图片的右下边区域| + +**示例：** + +```html + + + + + + + + {{item.text}} + + + + +``` +```javascript +export default { + data() { + return { + array: [{ + mode: 'scaleToFill', + text: 'scaleToFill：不保持纵横比缩放图片，使图片完全适应' + }, { + mode: 'aspectFit', + text: 'aspectFit：保持纵横比缩放图片，使图片的长边能完全显示出来' + }, { + mode: 'aspectFill', + text: 'aspectFill：保持纵横比缩放图片，只保证图片的短边能完全显示出来' + }, { + mode: 'top', + text: 'top：不缩放图片，只显示图片的顶部区域' + }, { + mode: 'bottom', + text: 'bottom：不缩放图片，只显示图片的底部区域' + }, { + mode: 'center', + text: 'center：不缩放图片，只显示图片的中间区域' + }, { + mode: 'left', + text: 'left：不缩放图片，只显示图片的左边区域' + }, { + mode: 'right', + text: 'right：不缩放图片，只显示图片的右边边区域' + }, { + mode: 'top left', + text: 'top left：不缩放图片，只显示图片的左上边区域' + }, { + mode: 'top right', + text: 'top right：不缩放图片，只显示图片的右上边区域' + }, { + mode: 'bottom left', + text: 'bottom left：不缩放图片，只显示图片的左下边区域' + }, { + mode: 'bottom right', + text: 'bottom right：不缩放图片，只显示图片的右下边区域' + }], + src: 'https://img-cdn-qiniu.dcloud.net.cn/uniapp/images/shuijiao.jpg' + } + }, + methods: { + imageError: function(e) { + console.error('image发生error事件，携带值为' + e.detail.errMsg) + } + } +} +``` + +原图 + + + +scaleToFill：不保持纵横比缩放图片，使图片完全适应 + + + +aspectFit：保持纵横比缩放图片，使图片的长边能完全显示出来 + + + +aspectFill：保持纵横比缩放图片，只保证图片的短边能完全显示出来 + + + +top：不缩放图片，只显示图片的顶部区域 + + + +bottom：不缩放图片，只显示图片的底部区域 + + + +center：不缩放图片，只显示图片的中间区域 + + + +left：不缩放图片，只显示图片的左边区域 + + + +right：不缩放图片，只显示图片的右边边区域 + + + +top left：不缩放图片，只显示图片的左上边区域 + + + +top right：不缩放图片，只显示图片的右上边区域 + + + +bottom left：不缩放图片，只显示图片的左下边区域 + + + +bottom right：不缩放图片，只显示图片的右下边区域 + + diff --git a/docs/component/input.md b/docs/component/input.md new file mode 100644 index 0000000000000000000000000000000000000000..9ff10bd834c315948ca89083dd932865610b8bfc --- /dev/null +++ b/docs/component/input.md @@ -0,0 +1,237 @@ +#### input + +输入框。 + +**属性说明** + +|属性名|类型|默认值|说明|平台差异说明| +|:-|:-|:-|:-|:-| +|value|String||输入框的初始内容|| +|type|String|text|input 的类型|| +|password|Boolean|false|是否是密码类型|| +|placeholder|String||输入框为空时占位符|| +|placeholder-style|String||指定 placeholder 的样式|| +|placeholder-class|String|"input-placeholder"|指定 placeholder 的样式类|| +|disabled|Boolean|false|是否禁用|| +|maxlength|Number|140|最大输入长度，设置为 -1 的时候不限制最大长度|| +|cursor-spacing|Number|0|指定光标与键盘的距离，单位 px 。取 input 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离|微信小程序、百度小程序| +|focus|Boolean|false|获取焦点。在 H5 平台聚焦后软键盘是否跟随弹出，取决于当前浏览器本身的规范（策略）。|| +|confirm-type|String|done|设置键盘右下角按钮的文字，仅在 type="text" 时生效。|| +|confirm-hold|Boolean|false|点击键盘右下角按钮时是否保持键盘不收起|5+App、微信小程序、支付宝小程序、百度小程序| +|cursor|Number||指定focus时的光标位置|| +|selection-start|Number|-1|光标起始位置，自动聚集时有效，需与selection-end搭配使用|| +|selection-end|Number|-1|光标结束位置，自动聚集时有效，需与selection-start搭配使用|| +|adjust-position|Boolean|true|键盘弹起时，是否自动上推页面|微信小程序、百度小程序| +|@input|EventHandle||当键盘输入时，触发input事件，event.detail = {value}|差异见下方 Tips| +|@focus|EventHandle||输入框聚焦时触发，event.detail = { value, height }，height 为键盘高度|微信小程序（基础库 1.9.90 起）| +|@blur|EventHandle||输入框失去焦点时触发，event.detail = {value: value}|| +|@confirm|EventHandle||点击完成按钮时触发，event.detail = {value: value}| | + +**Tips** + +- `input` 事件处理函数可以直接 return 一个字符串，将替换输入框的内容。仅微信小程序支持。 +- `input` 事件处理函数内实时修改当前值不生效，可以延迟设置，例如：``setTimeout(() => { this.value = 100 }, 0)``。 +- `input` 组件上有默认的 `min-height` 样式，如果 `min-height` 的值大于 `height` 的值那么 `height` 样式无效。 + +**type 有效值** + +|值|说明| +|:-|:-| +|text|文本输入键盘| +|number|数字输入键盘| +|idcard|身份证输入键盘| +|digit|带小数点的数字键盘| + +**注意事项** + +- 小程序平台，`number` 类型只支持输入整型数字。微信开发者工具上体现不出效果，请使用真机预览。 +- 如果需要在小程序平台输入浮点型数字，请使用 `digit` 类型。 +- input组件若不想弹出软键盘，可设置为disable +- App 平台的弹出键盘使用的是系统默认键盘，效果不一定和小程序一致。 +- [uni-app插件市场](https://ext.dcloud.net.cn/)有各种类型的模拟键盘，比如车牌键盘，以及封装好的搜索框ui组件，可去插件市场搜索 [键盘](https://ext.dcloud.net.cn/search?q=%E9%94%AE%E7%9B%98)。 +- [uni-app插件市场](https://ext.dcloud.net.cn/)有输入文字后自动提示候选的组件，可搜索 [autocomplete](https://ext.dcloud.net.cn/search?q=autocomplete) 查看。 + +**confirm-type 有效值** + + +|值|说明|平台差异说明| +|:-|:-|-| +|send|右下角按钮为“发送”|微信、支付宝、百度小程序| +|search|右下角按钮为“搜索”|| +|next|右下角按钮为“下一个”|微信、支付宝、百度小程序| +|go|右下角按钮为“前往”|| +|done|右下角按钮为“完成”|微信、支付宝、百度小程序| + +App平台，在nvue页面，通过weex的api，可以设置键盘右下角按钮为 发送、下一个、前往、完成。[详见](https://weex.apache.org/zh/docs/components/input.html#%E5%B1%9E%E6%80%A7) + +#### App平台iOS端软键盘上方横条去除方案 + +App平台在iOS上，webview中的软键盘弹出时，默认在软键盘上方有一个横条，显示着：上一项、下一项和完成等按钮。如不想显示这个横条，可以配置softinputNavBar: 'none' +- 如需要整个App配置，则在manifest中配置 +```json + "app-plus": { + "softinput": { + "navBar": "none" // 是否显示软键盘上的导航条 + } + } +``` + +- 如需要单个页面配置，则在pages.json中配置 +```json + { + "path": "pages/component/input/input", + "style": { + "app-plus":{ + "softinputNavBar":"none" + } + } + } +``` + +- 如需使用js动态设置softinputNavBar +```javascript +this.$mp.page.$getAppWebview().setStyle({ + softinputNavBar: 'none' +}) +``` + + +#### 关于软键盘弹出的逻辑说明 + +App平台，软键盘弹出有adjustResize|adjustPan 两种模式 +- adjustResize：软键盘弹出时，webview窗体高度挤压。屏幕高度=webview窗体高度+软键盘高度 +- adjustPan：软键盘弹出时，webview窗体高度不变，但窗体上推，以保证输入框不被软键盘盖住 + +除了App平台，其他平台只支持adjustPan模式。App平台两种模式都支持，具体如下： +- Android：默认为adjustResize。配置修改只能在manifest中修改，全局生效。如果改为adjustPan，无法顺利上推窗体，底部的input会被软键盘盖住 +- iOS平台：默认为adjustPan。配置可以在manifest中全局修改，也可以单独页面设置style。没有类似Android的局限。 + +如下为全局或页面的配置方式： +- 在manifest中配置 +```json + "app-plus": { + "softinput": { + "mode": "adjustResize|adjustPan" // 软键盘弹出模式 + } + } +``` + +- 如需要单个页面配置，则在pages.json中配置 +```json + { + "path": "pages/component/input/input", + "style": { + "app-plus":{ + "softinputMode": "adjustResize" //仅iOS支持单个页面配置 + } + } + } +``` + +App端开发聊天类应用时，目前推荐改为adjustResize模式。在hello uni-app的模板-聊天中有详细示例。 + +**注意** +- adjustResize模式在Android App上，弹起键盘和收回键盘时，因为要重设webview高度，可能会临时性出现灰屏或漏出下层页面内容。后续会优化 +- 小程序端在 input 聚焦期间，避免使用 css 动画。 +- H5平台只能在用户交互时修改 focus 生效。 +- 如果遇到 focus 属性设置不生效的问题参考：[组件属性设置不生效解决办法](/use?id=%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98) + + +#### 关于软键盘收起的逻辑说明 +- Android上在软键盘弹出后，点击back或点击非置焦区域可收起软键盘。 +- iOS上如果软键盘上方有带有“完成”的横条，则需要点完成才能收起键盘；如果没有软键盘上方横条，则点击非input/textarea区域即可收起软键盘 + +以上为默认逻辑，uni-app同时提供了隐藏软键盘的api：[uni.hideKeyboard()](https://uniapp.dcloud.io/api/key?id=hidekeyboard) + +#### App平台原生输入框的说明 +在app平台，有titleNView配置的[searchinput](/collocation/pages?id=app-titlenview)原生输入框和plus.nativeObj.view的drawinput。这两种方式的输入框都是原生的，不是webview里的。 +- 原生输入框在iOS上不会有软键盘上方的横条 +- 原生输入框一样受配置的`adjustPan|adjustResize`模式影响 + +**input示例** + +```html + + + + + 可自动聚焦的input + + + + 键盘右下角按钮显示为搜索 + + + + 控制最大输入长度的input + + + + 实时获取输入值：{{inputValue}} + + + + 控制输入的input + + + + + 控制键盘的input + + + + + 数字输入的input + + + + 密码输入的input + + + + 带小数点的input + + + + 身份证输入的input + + + + 控制占位符颜色的input + + + + + +``` + +```javascript +export default { + data() { + return { + title: 'input', + focus: false, + inputValue: '', + changeValue: '' + } + }, + methods: { + onKeyInput: function(event) { + this.inputValue = event.target.value + }, + replaceInput: function(event) { + var value = event.target.value; + if (value === '11') { + this.changeValue = '2'; + } + }, + hideKeyboard: function(event) { + if (event.target.value === '123') { + uni.hideKeyboard(); + } + } + } +} +``` + + diff --git a/docs/component/label.md b/docs/component/label.md new file mode 100644 index 0000000000000000000000000000000000000000..b6fa70ff5435b3cbdd5f52997d63d718bd93eb59 --- /dev/null +++ b/docs/component/label.md @@ -0,0 +1,125 @@ +#### label + +用来改进表单组件的可用性，使用for属性找到对应的id，或者将控件放在该标签下，当点击时，就会触发对应的控件。 + +for优先级高于内部控件，内部有多个控件的时候默认触发第一个控件。 + +目前可以绑定的控件有：````, ````, ````, ````。 + +**属性说明** + +|属性名|类型|说明| +|:-|:-|:-| +|for|String|绑定控件的 id| + +**示例** + +```html + + + + + 表单组件在label内 + + + + + + {{item.value}} + + + + + + label用for标识表单组件 + + + + + + + + {{item.value}} + + + + + + + + label内有多个时选中第一个 + + + + 选项一 + + + 选项二 + + 点击该label下的文字默认选中第一个checkbox + + + + + + + +``` + +```javascript +export default { + data() { + return { + checkboxItems: [{ + name: 'USA', + value: '美国' + }, + { + name: 'CHN', + value: '中国', + checked: 'true' + } + ], + radioItems: [{ + name: 'USA', + value: '美国' + }, + { + name: 'CHN', + value: '中国', + checked: 'true' + } + ], + hidden: false + } + }, + methods: { + checkboxChange: function(e) { + console.log(e) + var checked = e.target.value + var changed = {} + for (var i = 0; i < this.checkboxItems.length; i++) { + if (checked.indexOf(this.checkboxItems[i].name) !== -1) { + changed['checkboxItems[' + i + '].checked'] = true + } else { + changed['checkboxItems[' + i + '].checked'] = false + } + } + }, + radioChange: function(e) { + var checked = e.target.value + var changed = {} + for (var i = 0; i < this.radioItems.length; i++) { + if (checked.indexOf(this.radioItems[i].name) !== -1) { + changed['radioItems[' + i + '].checked'] = true + } else { + changed['radioItems[' + i + '].checked'] = false + } + } + } + } +} +``` + + + \ No newline at end of file diff --git a/docs/component/live-player.md b/docs/component/live-player.md new file mode 100644 index 0000000000000000000000000000000000000000..1595d99cd653778ddc999f350b532964d0341a83 --- /dev/null +++ b/docs/component/live-player.md @@ -0,0 +1,109 @@ +#### live-player + +实时音视频播放，也称直播拉流。 + +使用live-player 组件需注意：如果发布到小程序，需要先通过各家小程序的审核。指定类目的小程序才能使用（[微信小程序类目](https://developers.weixin.qq.com/miniprogram/dev/component/live-player.html)、[百度小程序类目](https://smartprogram.baidu.com/docs/develop/component/media/#live-player/)），审核通过后在各家小程序管理后台自助开通该组件权限。 + +**平台差异说明** + +|5+App|H5|微信小程序|支付宝小程序|百度小程序|头条小程序| +|:-:|:-:|:-:|:-:|:-:|:-:| +|x|x|√|x|√|x| + +- 5+App的实时音视频播放，不是使用 live-player，而是直接使用 video 组件。 +- H5 下可用 video 播放符合 HTML5 规范的流媒体，rtmp 等非 HTML5 标准的流媒体格式，仅在部分支持 flash 的国内手机浏览器上可播放。在 pc 浏览器上，需要安装 flash 插件才能播放 rtmp 等格式。 + + +**属性说明** + +|属性名|类型|默认值|说明|平台差异说明| +|:-:|:-:|:-:|:-:|:-:| +|id|String||live-player 属性的唯一标志符|| +|src|String||音视频地址。百度小程序支持 m3u8 格式；微信小程序支持 flv, rtmp 格式|| +|mode|String|live|live（直播），RTC（实时通话，该模式时延更低）|微信小程序| +|autoplay|Boolean|false|自动播放|| +|muted|Boolean|false|是否静音|| +|orientation|String|vertical|画面方向，可选值有 vertical，horizontal|| +|object-fit|String|contain|填充模式，可选值:contain、fillCrop|| +|background-mute|Boolean|false|进入后台时是否静音|| +|min-cache|Number|1|最小缓冲区，单位s|| +|max-cache|Number|3|最大缓冲区，单位s|| +|@statechange|EventHandle||播放状态变化事件，detail = {code}|| +|@netstatus|EventHandle||网络状态通知，detail = {info}|| +|@fullscreenchange|EventHandle||全屏变化事件，detail = {direction, fullScreen}。| | + +**Tips** + +* 百度小程序 iOS 端不支持设置 orientation 属性； +* 微信小程序已废弃 background-mute 属性，默认为进入后台静音； +* live-player 默认宽度 300px、高度 225px； +* live-player 是原生组件，层级高于前端组件，请勿在 scroll-view、swiper、picker-view、movable-view 中使用 +* 小程序下覆盖live-player需要使用cover-view。[详见](/component/native-component) +* live-player 组件相关 JS API：[createLivePlayerContext](/api/media/live-player-context) + + +**状态码** + +|代码|说明| +|---|---| +|2001|已经连接服务器| +|2002|已经连接服务器,开始拉流| +|2003|网络接收到首个视频数据包(IDR)| +|2004|视频播放开始| +|2005|视频播放进度| +|2006|视频播放结束| +|2007|视频播放Loading| +|2008|解码器启动| +|2009|视频分辨率改变| +|-2301|网络断连，且经多次重连抢救无效，更多重试请自行重启播放| +|-2302|获取加速拉流地址失败| +|2101|当前视频帧解码失败| +|2102|当前音频帧解码失败| +|2103|网络断连, 已启动自动重连| +|2104|网络来包不稳：可能是下行带宽不足，或由于主播端出流不均匀| +|2105|当前视频播放出现卡顿| +|2106|硬解启动失败，采用软解| +|2107|当前视频帧不连续，可能丢帧| +|2108|当前流硬解第一个I帧失败，SDK自动切软解| +|3001|RTMP -DNS解析失败| +|3002|RTMP服务器连接失败| +|3003|RTMP服务器握手失败| +|3005|RTMP 读/写失败| + +**网络状态数据** + +|键名|说明| +|---|---| +|videoBitrate|当前视频编/码器输出的比特率，单位 kbps| +|audioBitrate|当前音频编/码器输出的比特率，单位 kbps| +|videoFPS|当前视频帧率| +|videoGOP|当前视频 GOP,也就是每两个关键帧(I帧)间隔时长，单位 s| +|netSpeed|当前的发送/接收速度| +|netJitter|网络抖动情况，抖动越大，网络越不稳定| +|videoWidth|视频画面的宽度| +|videoHeight|视频画面的高度| + +**示例** + +```html + +``` + +```javascript +export default { + methods:{ + statechange(e){ + console.log('live-player code:', e.detail.code) + }, + error(e){ + console.error('live-player error:', e.detail.errMsg) + } + } +} +``` \ No newline at end of file diff --git a/docs/component/live-pusher.md b/docs/component/live-pusher.md new file mode 100644 index 0000000000000000000000000000000000000000..1335e32c80c2f86fec231fa96b81482c2f000f57 --- /dev/null +++ b/docs/component/live-pusher.md @@ -0,0 +1,13 @@ +#### live-pusher + +实时音视频录制，也称直播推流。 + +各平台开发方式暂未统一，使用时需注意用[条件编译](https://uniapp.dcloud.io/platform)调用不同平台的代码。 + +- 微信小程序：[规范文档](https://developers.weixin.qq.com/miniprogram/dev/component/live-pusher.html) +- App平台：[业务指南](https://ask.dcloud.net.cn/article/13416)、[规范文档](http://www.html5plus.org/doc/zh_cn/video.html#plus.video.LivePusher) + +**注意** + +* live-pusher 是原生组件，层级高于前端组件，请勿在 scroll-view、swiper、picker-view、movable-view 中使用 +* 解决 live-pusher 层级过高无法覆盖，[参考](/component/native-component) \ No newline at end of file diff --git a/docs/component/map.md b/docs/component/map.md new file mode 100644 index 0000000000000000000000000000000000000000..d33ec6fa7fb5824c37f42dac83d31d16f317c004 --- /dev/null +++ b/docs/component/map.md @@ -0,0 +1,194 @@ +#### map + +地图。 + +**平台差异说明** + +|5+App|H5|微信小程序|支付宝小程序|百度小程序|头条小程序| +|:-:|:-:|:-:|:-:|:-:|:-:| +|√|√|√|√|√|x| + +**属性说明** + +|属性名|类型|默认值|说明|平台差异说明| +|:-|:-|:-|:-|:-| +|longitude|Number||中心经度|| +|latitude|Number||中心纬度|| +|scale|Number|16|缩放级别，取值范围为5-18|| +|markers|Array||标记点|| +|polyline|Array||路线|| +|circles|Array||圆|| +|controls|Array||控件|| +|include-points|Array||缩放视野以包含所有给定的坐标点|微信小程序、H5、百度小程序、支付宝小程序| +|show-location|Boolean||显示带有方向的当前定位点|微信小程序、H5、百度小程序、支付宝小程序| +|@markertap|EventHandle||点击标记点时触发|| +|@callouttap|EventHandle||点击标记点对应的气泡时触发|| +|@controltap|EventHandle||点击控件时触发|| +|@regionchange|EventHandle||视野发生变化时触发|微信小程序、H5、百度小程序、支付宝小程序| +|@tap|EventHandle||点击地图时触发|| +|@updated|EventHandle||在地图渲染更新完成时触发|微信小程序、H5、百度小程序| + +**注意** + +- `` 组件的宽/高推荐写直接量，比如：750rpx，不要设置百分比值。 +- `uni-app` 只支持 `gcj02` 坐标 + +**markers** + +标记点用于在地图上显示标记的位置 + +|属性|说明|类型|必填|备注|平台差异说明| +|:-|:-|:-|:-|:-|:-| +|id|标记点id|Number|是|marker点击事件回调会返回此id。建议为每个marker设置上Number类型id，保证更新marker时有更好的性能。|| +|latitude|纬度|Number|是|浮点数，范围 -90 ~ 90|| +|longitude|经度|Number|是|浮点数，范围 -180 ~ 180|| +|title|标注点名|String|否||微信小程序、H5、支付宝小程序、百度小程序| +|iconPath|显示的图标|String|是|项目目录下的图片路径，支持相对路径写法，以'/'开头则表示相对小程序根目录；也支持临时路径|| +|rotate|旋转角度|Number|否|顺时针旋转的角度，范围 0 ~ 360，默认为 0|微信小程序、支付宝小程序、百度小程序| +|alpha|标注的透明度|Number|否|默认1，无透明，范围 0 ~ 1|微信小程序、支付宝小程序、百度小程序| +|width|标注图标宽度|Number|否|默认为图片实际宽度|微信小程序、H5、支付宝小程序、百度小程序| +|height|标注图标高度|Number|否|默认为图片实际高度|微信小程序、H5、支付宝小程序、百度小程序| +|callout|自定义标记点上方的气泡窗口|Object|否|支持的属性见下表，可识别换行符。|| +|label|为标记点旁边增加标签|Object|否|支持的属性见下表，可识别换行符。|微信小程序、H5、5+APP、百度小程序| +|anchor|经纬度在标注图标的锚点，默认底边中点|Object|否|{x, y}，x表示横向(0-1)，y表示竖向(0-1)。{x: .5, y: 1} 表示底边中点|微信小程序、H5、百度小程序| + +**marker 上的气泡 callout** + +|属性|说明|类型|平台差异说明| +|:-|:-|:-|:-| +|content|文本|String|| +|color|文本颜色|String|微信小程序、H5、百度小程序| +|fontSize|文字大小|Number|微信小程序、H5、百度小程序| +|borderRadius|callout边框圆角|Number|微信小程序、H5、百度小程序| +|bgColor|背景色|String|微信小程序、H5、百度小程序| +|padding|文本边缘留白|Number|微信小程序、H5、百度小程序| +|display|'BYCLICK':点击显示; 'ALWAYS':常显|String|微信小程序、H5、百度小程序| +|textAlign|文本对齐方式。有效值: left, right, center|String|微信小程序、百度小程序| + +**marker 上的气泡 label** + +|属性|说明|类型|平台差异说明| +|:-|:-|:-|:-| +|content|文本|String|| +|color|文本颜色|String|微信小程序、H5、百度小程序| +|fontSize|文字大小|Number|微信小程序、H5、百度小程序| +|x|label的坐标，原点是 marker 对应的经纬度|Number|微信小程序、H5、百度小程序| +|y|label的坐标，原点是 marker 对应的经纬度|Number|微信小程序、H5、百度小程序| +|borderWidth|边框宽度|Number|微信小程序、百度小程序| +|borderColor|边框颜色|String|微信小程序、百度小程序| +|borderRadius|边框圆角|Number|微信小程序、百度小程序| +|bgColor|背景色|String|微信小程序、百度小程序| +|padding|文本边缘留白|Number|微信小程序、百度小程序| +|textAlign|文本对齐方式。有效值: left, right, center|String|微信小程序、百度小程序| + +**polyline** + +指定一系列坐标点，从数组第一项连线至最后一项 + +|属性|说明|类型|必填|备注|平台差异说明| +|:-|:-|:-|:-|:-|:-| +|points|经纬度数组|Array|是|[{latitude: 0, longitude: 0}]|| +|color|线的颜色|String|否|8位十六进制表示，后两位表示alpha值，如：#0000AA|| +|width|线的宽度|Number|否||| +|dottedLine|是否虚线|Boolean|否|默认false|微信小程序、H5、百度小程序、支付宝小程序| +|arrowLine|带箭头的线|Boolean|否|默认false，微信小程序开发者工具暂不支持该属性|微信小程序、百度小程序| +|arrowIconPath|更换箭头图标|String|否|在arrowLine为true时生效|微信小程序、百度小程序| +|borderColor|线的边框颜色|String|否||微信小程序、H5、百度小程序| +|borderWidth|线的厚度|Number|否||微信小程序、H5、百度小程序| + +**circles** + +在地图上显示圆 + +|属性|说明|类型|必填|备注| +|:-|:-|:-|:-|:-| +|latitude|纬度|Number|是|浮点数，范围 -90 ~ 90| +|longitude|经度|Number|是|浮点数，范围 -180 ~ 180| +|color|描边的颜色|String|否|8位十六进制表示，后两位表示alpha值，如：#0000AA| +|fillColor|填充颜色|String|否|8位十六进制表示，后两位表示alpha值，如：#0000AA| +|radius|半径|Number|是|| +|strokeWidth|描边的宽度|Number|否| | + +**controls** + +在地图上显示控件，控件不随着地图移动 + +|属性|说明|类型|必填|备注| +|:-|:-|:-|:-|:-| +|id|控件id|Number|否|在控件点击事件回调会返回此id| +|position|控件在地图的位置|Object|是|控件相对地图位置| +|iconPath|显示的图标|String|是|项目目录下的图片路径，支持相对路径写法，以'/'开头则表示相对项目根目录；也支持临时路径| +|clickable|是否可点击|Boolean|否|默认不可点击| + +**position** + +|属性|说明|类型|必填|备注| +|:-|:-|:-|:-|:-| +|left|距离地图的左边界多远|Number|否|默认为0| +|top|距离地图的上边界多远|Number|否|默认为0| +|width|控件宽度|Number|否|默认为图片宽度| +|height|控件高度|Number|否|默认为图片高度| + +地图组件的经纬度必填，如果不填经纬度则默认值是北京的经纬度。 + +**示例** + +```html + + + + + + + + + + +``` + +```javascript +export default { + data() { + return { + title: 'map', + latitude: 39.909, + longitude: 116.39742, + covers: [{ + latitude: 39.909, + longitude: 116.39742, + iconPath: '../../../static/location.png' + }, { + latitude: 39.90, + longitude: 116.39, + iconPath: '../../../static/location.png' + }] + } + }, + methods: { + + } +} +``` + +map 组件相关操作的 JS API：[uni.createMapContext](api/location/map?id=createmapcontext) + +**注意事项** + +- 小程序和 App 中，`` 组件是由引擎创建的原生组件，它的层级是最高的，不能通过 z-index 控制层级。在``上绘制内容，可使用组件自带的marker、controls等属性，也可以使用``组件。App端还可以使用plus.nativeObj.view 或 subNVue 绘制原生内容。[详见](/component/native-component) +- 小程序和 App 中，请勿在 scroll-view、swiper、picker-view、movable-view 中使用 `` 组件。 +- 小程序和 App 中，css 动画对 `` 组件无效。 +- map 组件使用的经纬度是国测局坐标，调用 uni.getLocation 接口需要指定 type 为 gcj02。 +- `` 组件在不同平台的底层引擎是不同的：H5、微信小程序为腾讯地图；App、支付宝小程序为高德地图；百度小程序端为百度地图。App端也可以使用百度地图，在manifest的源码视图中配置，具体[参考](http://ask.dcloud.net.cn/article/29) +- map 组件默认的api是参考微信小程序的，如果觉得不够用，可以用plus.map，可以通过`$getAppMap`获取原生地图对象，[详见](https://uniapp.dcloud.io/api/location/map) +- H5 端获取定位信息，需要部署在 **https** 服务上，本地预览（localhost）仍然可以使用 http 协议。 +- 无 GPS 模块的 PC 设备使用 Chrome 浏览器的时候，位置信息是连接谷歌服务器获取的，国内用户可能获取位置信息失败。 +- App 端使用地图组件需要向高德或百度等三方服务商申请SDK资质，获取AppKey，打包时需要在manifest文件中勾选相应模块，在SDK配置中填写Appkey。在manifest可视化界面有详细申请指南。 + + +##### FAQ + +Q：应用中使用了 `` 组件，打包为原生应用时，提示缺少权限模块怎么办？ +A：原生的地图，依赖第三方的 SDK，因此打包移动应用时，需要勾选相关的权限并填写 key 信息。详见：[http://ask.dcloud.net.cn/article/35090](http://ask.dcloud.net.cn/article/35090) + +Q：国外应用想使用谷歌地图/google地图怎么办？ +A：1. 可以在web-view下调用谷歌的web地图；2. 可以写一个原生插件封装谷歌原生地图，具体参考uni-app插件市场的原生插件开发教程 \ No newline at end of file diff --git a/docs/component/movable-view.md b/docs/component/movable-view.md new file mode 100644 index 0000000000000000000000000000000000000000..28312e4936e99888192e5d5680818cb699cbbbc4 --- /dev/null +++ b/docs/component/movable-view.md @@ -0,0 +1,123 @@ +#### movable-area + +`movable-view` 的可移动区域 + +**平台差异说明** + +|5+App|H5|微信小程序|支付宝小程序|百度小程序|头条小程序| +|:-:|:-:|:-:|:-:|:-:|:-:| +|√|√|√|√|√|x| + +**属性说明** + +|属性名|类型|默认值|说明| +|:-|:-|:-|:-| +|scale-area|Boolean|false|当里面的 movable-view 设置为支持双指缩放时，设置此值可将缩放手势生效区域修改为整个 movable-area| + +**注意：movable-area 必须设置 width 和 height 属性，不设置默认为 10px** + +#### movable-view + +可移动的视图容器，在页面中可以拖拽滑动 + +**平台差异说明** + +|5+App|H5|微信小程序|支付宝小程序|百度小程序|头条小程序| +|:-:|:-:|:-:|:-:|:-:|:-:| +|√|√|√|√|√|x| + +**属性说明** + +|属性名|类型|默认值|说明|平台差异说明| +|:-|:-|:-|:-|:-| +|direction|String|none|movable-view的移动方向，属性值有all、vertical、horizontal、none|| +|inertia|Boolean|false|movable-view是否带有惯性|微信小程序、5+App、H5、百度小程序| +|out-of-bounds|Boolean|false|超过可移动区域后，movable-view是否还可以移动|微信小程序、5+App、H5、百度小程序| +|x|Number / String||定义x轴方向的偏移，如果x的值不在可移动范围内，会自动移动到可移动范围；改变x的值会触发动画|| +|y|Number / String||定义y轴方向的偏移，如果y的值不在可移动范围内，会自动移动到可移动范围；改变y的值会触发动画|| +|damping|Number|20|阻尼系数，用于控制x或y改变时的动画和过界回弹的动画，值越大移动越快|微信小程序、5+App、H5、百度小程序| +|friction|Number|2|摩擦系数，用于控制惯性滑动的动画，值越大摩擦力越大，滑动越快停止；必须大于0，否则会被设置成默认值|微信小程序、5+App、H5、百度小程序| +|disabled|Boolean|false|是否禁用|| +|scale|Boolean|false|是否支持双指缩放，默认缩放手势生效区域是在movable-view内|微信小程序、5+App、H5| +|scale-min|Number|0.5|定义缩放倍数最小值|微信小程序、5+App、H5| +|scale-max|Number|10|定义缩放倍数最大值|微信小程序、5+App、H5| +|scale-value|Number|1|定义缩放倍数，取值范围为 0.5 - 10|微信小程序、5+App、H5| +|animation|Boolean|true|是否使用动画|微信小程序、5+App、H5、百度小程序| +|@change|EventHandle||拖动过程中触发的事件，event.detail = {x: x, y: y, source: source}，其中source表示产生移动的原因，值可为touch（拖动）、touch-out-of-bounds（超出移动范围）、out-of-bounds（超出移动范围后的回弹）、friction（惯性）和空字符串（setData）|| +|@scale|EventHandle||缩放过程中触发的事件，event.detail = {x: x, y: y, scale: scale}，|微信小程序、5+App、H5、百度小程序| + +除了基本事件外，movable-view提供了两个特殊事件 + +|类型|触发条件| +|:-|:-| +|htouchmove|初次手指触摸后移动为横向的移动，如果catch此事件，则意味着touchmove事件也被catch| +|vtouchmove|初次手指触摸后移动为纵向的移动，如果catch此事件，则意味着touchmove事件也被catch| + +> movable-view 必须设置width和height属性，不设置默认为10px +> +> movable-view 默认为绝对定位，top和left属性为0px +> +> 当movable-view小于movable-area时，movable-view的移动范围是在movable-area内；当movable-view大于movable-area时，movable-view的移动范围必须包含movable-area（x轴方向和y轴方向分开考虑） + +**Tips** +- movable-view必须在``组件中，并且必须是直接子节点，否则不能移动。 +- 如果遇到x、y、scale属性设置不生效的问题参考：[组件属性设置不生效解决办法](/use?id=%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98) +- swiper在非H5端，不支持内嵌video、map等原生组件。更新：微信基础库2.4.4起支持了原生组件在 scroll-view、swiper、movable-view 中的使用 + +**示例** +```html + + + + + 示例 1 + \nmovable-view 区域小于 movable-area + + + text + + + 点击这里移动至 (30px, 30px) + + + 示例 2 + \nmovable-view区域大于movable-area + + + text + + + + +``` + +```js +export default { + data() { + return { + x: 0, + y: 0, + old: { + x: 0, + y: 0 + } + } + }, + methods: { + tap: function(e) { + this.x = this.old.x + this.y = this.old.y + this.$nextTick(function() { + this.x = 30 + this.y = 30 + }) + }, + onChange: function(e) { + this.old.x = e.detail.x + this.old.y = e.detail.y + } + } +} +``` + +  \ No newline at end of file diff --git a/docs/component/native-component.md b/docs/component/native-component.md new file mode 100644 index 0000000000000000000000000000000000000000..df841457b375ea234ff414523ab892341d3c4d54 --- /dev/null +++ b/docs/component/native-component.md @@ -0,0 +1,86 @@ +#### 原生组件说明 + +为了提升性能，小程序和App架构下部分ui元素，比如导航栏、tabbar、video、map使用了原生控件。 + +虽然提升了性能，但原生组件带来了其他问题：1) 前端组件无法覆盖原生控件的层级问题、2) 原生组件不能嵌入特殊前端组件(如scroll-view)、3) 原生控件无法灵活自定义。 + +``uni-app`` 中原生组件清单如下： +* [map](/component/map) +* [video](/component/video) +* [camera](/component/camera)（仅微信小程序、百度小程序支持） +* [canvas](/component/canvas)（仅在微信小程序、百度小程序表现为原生组件） +* [input](/component/input)（仅在微信小程序、百度小程序、支付宝小程序、头条小程序中且input置焦时表现为原生组件） +* [textarea](/component/textarea)（仅在微信小程序、百度小程序、头条小程序表现为原生组件） +* [live-player](/component/live-player)（仅微信小程序、百度小程序支持，App端直接使用video组件可同时实现拉流） +* [live-pusher](/component/live-pusher)（仅微信小程序、百度小程序支持，App端直接使用plus.video.LivePusher可实现推流） +* [cover-view](/component/cover-view) +* [cover-image](/component/cover-view?id=cover-image) + +#### 原生组件的使用限制 + +由于原生组件脱离在 WebView 渲染流程外，因此在使用时有以下限制： + +* 原生组件的层级是**最高**的，所以页面中的其他组件无论设置 z-index 为多少，都无法盖在原生组件上。后插入的原生组件可以覆盖之前的原生组件。 +* 原生组件无法在 scroll-view、swiper、picker-view、movable-view 中使用（微信基础库2.4.4起支持了原生组件在 scroll-view、swiper、movable-view 中的使用） +* 部分CSS样式无法应用于原生组件，例如： + * 无法对原生组件设置 CSS 动画； + * 无法定义原生组件为 position: fixed； + * 不能在父级节点使用 overflow: hidden 来裁剪原生组件的显示区域。 +* 在小程序端真机上，原生组件会遮挡 vConsole 弹出的调试面板。 + +#### 其他原生界面元素 +除了原生组件外，uni-app在非H5端还有其他原生界面元素，清单如下： +* 原生导航栏和tabbar（pages.json里配置的） +* web-view组件虽然不是原生的，但这个组件相当于一个原生webview覆盖在页面上，并且小程序上web-view组件是强制全屏的，无法在上面覆盖前端元素 +* 弹出框：picker、showModal、showToast、showLoading、showActionSheet、previewImage、chooseImage、chooseVideo等弹出元素也无法被前端组件覆盖 +* plus下的plus.nativeObj.view、plus.video.LivePusher、plus.nativeUI、plus.webview，层级均高于前端元素 + +#### vue页面层级覆盖解决方案 + +为了解决原生组件层级最高的限制，uni-app提供了 [cover-view](/component/cover-view) 和 [cover-image](/component/cover-view?id=cover-image) 组件，让其覆盖在原生组件上。 + +除了跨端的cover-view，App端还提供了2种方案：plus.nativeObj.view、subNVue。详述如下 + +- [cover-view](https://uniapp.dcloud.io/component/cover-view?id=cover-view) + +cover-view只能覆盖原生组件，不能覆盖其他原生界面元素。比如cover-view可以覆盖video、map，但无法覆盖原生导航栏、tabbar、web-view。 + +微信小程序在基础库 2.4.0 起已支持 video 组件的同层渲染。也就是video在非全屏时，可以被前端元素通过调节zindex来遮挡。但video全屏时，仍需要cover-view覆盖。 + +cover-view在App端相比小程序端还有一些限制，1) 无法嵌套、 2) 无法内部滚动，即cover-view无法内部出现滚动条 + +另外cover-view无论如何都无法解决原生导航栏、tabbar、web-view组件的覆盖，为此App端补充了2个层级覆盖方案plus.nativeObj.view和subNVue + +- [plus.nativeObj.view](https://www.html5plus.org/doc/zh_cn/nativeobj.html#plus.nativeObj.View) + +简称nview，它是一个原生的类画布的控件，其实cover-view也是用plus.nativeObj.view封装的。API文档详见：[https://www.html5plus.org/doc/zh_cn/nativeobj.html#plus.nativeObj.View](https://www.html5plus.org/doc/zh_cn/nativeobj.html#plus.nativeObj.View) + +plus.nativeObj.view的API比较原生，可以画出任何界面，但plus.nativeObj.view有3个问题：1. api很底层，开发比较复杂；2. 不支持动画；3. 不支持内部滚动。 + +- [subNVue](https://ask.dcloud.net.cn/article/35948) + +subNVue是把weex渲染的原生子窗体，覆盖在vue页面上，它解决了plus.nativeObj.view的所有不足，提供了最强大的层级问题解决方案。subNVue的详细介绍见：[https://ask.dcloud.net.cn/article/35948](https://ask.dcloud.net.cn/article/35948) + +subNVue强大，同时也意味着比plus.nativeObj.view多占用一些内存。所以如果你要覆盖的内容很简单，cover-view或plus.nativeObj.view可以简单实现，也没必要用subNVue。 + +另注意App的非自定义组件编译模式不支持subNVue。 + +**关于subNVue和Webview的层级问题** +subNVue的层级高于前端元素，但多个subNVue以及Webview，它们之间的也存在层级关系。 + +默认规则是，先创建的subNVue或webview在底部，后创建的会盖住之前的。 + +当然每个subNVue和webview，都支持Style参数配置，其中有一个zindex属性，可以调节它们的层级。 + + +#### App的nvue页面层级问题 +nvue页面全部都是原生组件，互相之间没有层级问题。 + +但如果在pages.json里注册了原生导航栏和tabbar，nvue里的界面元素默认也无法覆盖这些，也需要plus.nativeObj.view或subNVue。 + +如果仅开发App，不跨端，不愿涉及层级问题，也可以不使用pages.json里的原生导航栏和tabbar，nvue页面不需要这些来强化性能。 + +#### 总结 +所以如果你的层级覆盖问题比较简单，不用嵌套，且有跨端需求，就使用cover-view。 + +如果App端cover-view无法满足需求，且需要覆盖的原生界面比较简单，可以用plus.nativeObj.view。否则，就使用subnvue吧。 \ No newline at end of file diff --git a/docs/component/navigator.md b/docs/component/navigator.md new file mode 100644 index 0000000000000000000000000000000000000000..6bfc4a65e2f3369e7f4e0d01b1b22a558714cfb6 --- /dev/null +++ b/docs/component/navigator.md @@ -0,0 +1,51 @@ +#### navigator + +页面链接。 + +**属性说明** + +|属性名|类型|默认值|说明|平台差异说明| +|:-|:-|:-|:-|:-| +|url|String||应用内的跳转链接，值为相对路径或绝对路径，如："../first/first"，"/pages/first/first"，注意不能加 ``.vue`` 后缀|| +|open-type|String|navigate|跳转方式|| +|delta|Number||当 open-type 为 'navigateBack' 时有效，表示回退的层数|| +|animation-type|String|pop-in/out|当 open-type 为 navigate、navigateBack 时有效，窗口的显示/关闭动画效果，详见：[窗口动画](api/router?id=animation)|5+App| +|animation-duration|Number|300|当 open-type 为 navigate、navigateBack 时有效，窗口显示/关闭动画的持续时间。|5+App| +|hover-class|String|navigator-hover|指定点击时的样式类，当hover-class="none"时，没有点击态效果|| +|hover-stop-propagation|Boolean|false|指定是否阻止本节点的祖先节点出现点击态|微信小程序| +|hover-start-time|Number|50|按住后多久出现点击态，单位毫秒|| +|hover-stay-time|Number|600|手指松开后点击态保留时间，单位毫秒| | + +**open-type 有效值** + +|值|说明|平台差异说明| +|:-|:-|:-| +|navigate|对应 uni.navigateTo 的功能|| +|redirect|对应 uni.redirectTo 的功能|| +|switchTab|对应 uni.switchTab 的功能|| +|reLaunch|对应 uni.reLaunch 的功能|头条小程序不支持| +|navigateBack|对应 uni.navigateBack 的功能| | + +**注：navigator-hover 默认为 {background-color: rgba(0, 0, 0, 0.1); opacity: 0.7;}, ```` 的子节点背景色应为透明色。** + +**示例** + +```html + + + + + + 跳转到新页面 + + + 在当前页打开 + + + + + +``` + +**注意** +- 跳转tabbar页面，必须设置open-type="switchTab" \ No newline at end of file diff --git a/docs/component/open-data.md b/docs/component/open-data.md new file mode 100644 index 0000000000000000000000000000000000000000..d59975f4f149b0c42db57d11590cc130db873e09 --- /dev/null +++ b/docs/component/open-data.md @@ -0,0 +1,42 @@ +#### open-data + +用于展示平台开放的数据。 + +**平台差异说明** + +|5+App|H5|微信小程序|支付宝小程序|百度小程序|头条小程序| +|:-:|:-:|:-:|:-:|:-:|:-:| +|x|x|√|x|√|x| + +**Tips** + +该功能为微信、百度、支付宝、头条等平台提供的开放能力。App端和H5端不涉及此概念。 + +**属性说明** + +|属性名|类型|默认值|说明|平台差异说明| +|:-:|:-:|:-:|:-:|:-:| +|type|String||开放数据类型|| +|open-gid|String||当 type="groupName" 时生效, 群id|微信小程序| +|lang|String|en|当 type="user*" 时生效，以哪种语言展示 userInfo，有效值有：en, zh_CN, zh_TW|微信小程序| + +**type 有效值** + +|值|说明|平台差异说明| +|:-:|:-:|:-:| +|userNickName|用户昵称|| +|userAvatarUrl|用户头像|| +|userGender|用户性别|| +|groupName|拉取群名称|微信小程序| +|userCity|用户所在城市|微信小程序| +|userProvince|用户所在省份|微信小程序| +|userCountry|用户所在国家|微信小程序| +|userLanguage|用户的语言|微信小程序| + +**示例** + +```html + + + +``` diff --git a/docs/component/open.md b/docs/component/open.md new file mode 100644 index 0000000000000000000000000000000000000000..0ec157dbe09c9f3f6912ce50ee7f23690c9e4efc --- /dev/null +++ b/docs/component/open.md @@ -0,0 +1,9 @@ +### ad +Banner 广告。 + +仅微信小程序平台支持，[规范详情](https://developers.weixin.qq.com/miniprogram/dev/component/ad.html) + +### official-account +公众号关注组件。当用户扫小程序码打开小程序时，开发者可在小程序内配置公众号关注组件，方便用户快捷关注公众号，可嵌套在原生组件内。 + +仅微信小程序平台支持，[规范详情](https://developers.weixin.qq.com/miniprogram/dev/component/official-account.html) \ No newline at end of file diff --git a/docs/component/picker-view.md b/docs/component/picker-view.md new file mode 100644 index 0000000000000000000000000000000000000000..a8788328bcb0385b10315daddfe7a6a4ab46b0f9 --- /dev/null +++ b/docs/component/picker-view.md @@ -0,0 +1,91 @@ +#### picker-view + +嵌入页面的滚动选择器 + +**属性说明** + +|属性名|类型|默认值|平台差异说明| +|:-|:-|:-|:-| +|value|Array＜Number＞|数组中的数字依次表示 picker-view 内的 picker-view-column 选择的第几项（下标从 0 开始），数字大于 picker-view-column 可选项长度时，选择最后一项。|| +|indicator-style|String|设置选择器中间选中框的样式|| +|indicator-class|String|设置选择器中间选中框的类名|头条小程序不支持| +|mask-style|String|设置蒙层的样式|| +|mask-class|String|设置蒙层的类名|头条小程序不支持| +|@change|EventHandle|当滚动选择，value 改变时触发 change 事件，event.detail = {value: value}；value为数组，表示 picker-view 内的 picker-view-column 当前选择的是第几项（下标从 0 开始）| | + +**注意：**其中只可放置 `` 组件，其他节点不会显示。 + +#### picker-view-column + +`` 的子组件，仅可放置于 `` 中，其子节点的高度会自动设置成与 picker-view 的选中框的高度一致 + +**示例** + +```html + + + + 日期：{{year}}年{{month}}月{{day}}日 + + + + {{item}}年 + + + {{item}}月 + + + {{item}}日 + + + + +``` + +```javascript +export default { + data: function () { + const date = new Date() + const years = [] + const year = date.getFullYear() + const months = [] + const month = date.getMonth() + 1 + const days = [] + const day = date.getDate() + for (let i = 1990; i <= date.getFullYear(); i++) { + years.push(i) + } + for (let i = 1; i <= 12; i++) { + months.push(i) + } + for (let i = 1; i <= 31; i++) { + days.push(i) + } + return { + title: 'picker-view', + years, + year, + months, + month, + days, + day, + value: [9999, month - 1, day - 1], + visible: true, + indicatorStyle: `height: ${Math.round(uni.getSystemInfoSync().screenWidth/(750/100))}px;` + } + }, + methods: { + bindChange: function (e) { + const val = e.detail.value + this.year = this.years[val[0]] + this.month = this.months[val[1]] + this.day = this.days[val[2]] + } + } +} +``` + + + +**Tips** +微信小程序端，滚动时在iOS自带振动反馈，可在系统设置 -> 声音与触感 -> 系统触感反馈中关闭 \ No newline at end of file diff --git a/docs/component/picker.md b/docs/component/picker.md new file mode 100644 index 0000000000000000000000000000000000000000..63517ef8ffb926de3a83d08c810a80b216422b22 --- /dev/null +++ b/docs/component/picker.md @@ -0,0 +1,229 @@ +#### picker + +从底部弹起的滚动选择器，现支持五种选择器，通过mode来区分，分别是普通选择器，多列选择器，时间选择器，日期选择器，省市区选择器，默认是普通选择器。 + +**普通选择器** + +``mode = selector`` + +**属性说明** + +|属性名|类型|默认值|说明| +|:-|:-|:-|:-| +|range|Array / Array＜Object＞|[]|mode为 selector 或 multiSelector 时，range 有效| +|range-key|String||当 range 是一个 Array＜Object＞ 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容| +|value|Number|0|value 的值表示选择了 range 中的第几个（下标从 0 开始）| +|@change|EventHandle||value 改变时触发 change 事件，event.detail = {value: value}| +|disabled|Boolean|false|是否禁用| +|@cancel|EventHandle||取消选择或点遮罩层收起 picker 时触发| + + +**多列选择器** + +``mode = multiSelector`` + +**平台差异说明** + +|5+App|H5|微信小程序|支付宝小程序|百度小程序|头条小程序| +|:-:|:-:|:-:|:-:|:-:|:-:| +|√|√|√|x|√|√| + + +**属性说明** + +|属性名|类型|默认值|说明| +|:-|:-|:-|:-| +|range|二维 Array / 二维 Array＜Object＞|[]|mode为 selector 或 multiSelector 时，range 有效。二维数组，长度表示多少列，数组的每项表示每列的数据，如[["a","b"], ["c","d"]]| +|range-key|String||当 range 是一个二维 Array＜Object＞ 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容| +|value|Array|[]|value 每一项的值表示选择了 range 对应项中的第几个（下标从 0 开始）| +|@change|EventHandle||value 改变时触发 change 事件，event.detail = {value: value}| +|@columnchange|EventHandle||某一列的值改变时触发 columnchange 事件，event.detail = {column: column, value: value}，column 的值表示改变了第几列（下标从0开始），value 的值表示变更值的下标| +|@cancel|EventHandle||取消选择时触发| +|disabled|Boolean|false|是否禁用| + +**bug & tips** +- 由于 JavaScript 的限制 vue 不能观测如下方式设置 value：``this.value[0] = 0`` （[vue 注意事项](https://cn.vuejs.org/v2/guide/list.html#注意事项)），解决方式参考：[hello-uniapp 示例](https://github.com/dcloudio/hello-uniapp/commit/59264474172a591c865431d02a2a1e3583978827) +- 微信开发工具的pc模拟器有可能出现拖动数据错乱，使用真机正常 + +**时间选择器** + +``mode = time`` + +**平台差异说明** + +|5+App|H5|微信小程序|支付宝小程序|百度小程序|头条小程序| +|:-:|:-:|:-:|:-:|:-:|:-:| +|√|√|√|x|√|√| + +**属性说明** + +|属性名|类型|默认值|说明|平台差异说明| +|:-|:-|:-|:-|:-| +|value|String||表示选中的时间，格式为"hh:mm"|| +|start|String||表示有效时间范围的开始，字符串格式为"hh:mm"|5+App 不支持| +|end|String||表示有效时间范围的结束，字符串格式为"hh:mm"|5+App 不支持| +|@change|EventHandle||value 改变时触发 change 事件，event.detail = {value: value}|| +|@cancel|EventHandle||取消选择时触发|| +|disabled|Boolean|false|是否禁用| | + +**日期选择器** + +``mode = date`` + +**平台差异说明** + +|5+App|H5|微信小程序|支付宝小程序|百度小程序|头条小程序| +|:-:|:-:|:-:|:-:|:-:|:-:| +|√|√|√|x|√|√| + +**属性说明** + +|属性名|类型|默认值|说明|平台差异说明| +|:-|:-|:-|:-|:-| +|value|String|0|表示选中的日期，格式为"YYYY-MM-DD"|| +|start|String||表示有效日期范围的开始，字符串格式为"YYYY-MM-DD"|| +|end|String||表示有效日期范围的结束，字符串格式为"YYYY-MM-DD"|| +|fields|String|day|有效值 year,month,day，表示选择器的粒度|H5、微信小程序、百度小程序、头条小程序| +|@change|EventHandle||value 改变时触发 change 事件，event.detail = {value: value}|| +|@cancel|EventHandle||取消选择时触发|| +|disabled|Boolean|false|是否禁用| | + +**fields 有效值** + +|值|说明| +|:-|:-| +|year|选择器粒度为年| +|month|选择器粒度为月份| +|day|选择器粒度为天| + +**省市区选择器** + +``mode = region`` + +**平台差异说明** + +|5+App|H5|微信小程序|支付宝小程序|百度小程序|头条小程序| +|:-:|:-:|:-:|:-:|:-:|:-:| +|x|x|√|x|√|√| + +- 因省市区选择器包含大量数据，占用体积，且很多城市数据有自维护需求，所以在App和H5平台没有内置。有两种方案解决： + 1. 使用mpvue-picker代替，全端通用，自定义性更强，参考： Hello uni-app的模板-多列选择picker，或[插件市场](https://ext.dcloud.net.cn/plugin?id=115)。手机预览网址：[https://uniapp.dcloud.io/h5/pages/template/mpvue-picker/mpvue-picker](https://uniapp.dcloud.io/h5/pages/template/mpvue-picker/mpvue-picker) + 2. 在H5和App平台使用多列选择器，自行填充城市数据（上述mpvue-picker或hello uni-app自带城市数据city.data.js） + +|属性名|类型|默认值|说明| +|:-|:-|:-|:-| +|value|Array|[]|表示选中的省市区，默认选中每一列的第一个值| +|custom-item|String||可为每一列的顶部添加一个自定义的项| +|@change|EventHandle||value 改变时触发 change 事件，event.detail = {value: value}| +|@cancel|EventHandle||取消选择时触发| +|disabled|Boolean|false|是否禁用| + +**示例** + +```html + + + 地区选择器 + + + + 当前选择 + + + + {{array[index]}} + + + + + + 时间选择器 + + + + 当前选择 + + + + {{time}} + + + + + + 日期选择器 + + + + 当前选择 + + + + {{date}} + + + + + + +``` +```javascript +export default { + data() { + const currentDate = this.getDate({ + format: true + }) + return { + title: 'picker', + array: ['中国', '美国', '巴西', '日本'], + index: 0, + date: currentDate, + time: '12:01' + } + }, + computed: { + startDate() { + return this.getDate('start'); + }, + endDate() { + return this.getDate('end'); + } + }, + methods: { + bindPickerChange: function(e) { + console.log('picker发送选择改变，携带值为', e.target.value) + this.index = e.target.value + }, + bindDateChange: function(e) { + this.date = e.target.value + }, + bindTimeChange: function(e) { + this.time = e.target.value + }, + getDate(type) { + const date = new Date(); + let year = date.getFullYear(); + let month = date.getMonth() + 1; + let day = date.getDate(); + + if (type === 'start') { + year = year - 60; + } else if (type === 'end') { + year = year + 2; + } + month = month > 9 ? month : '0' + month;; + day = day > 9 ? day : '0' + day; + return `${year}-${month}-${day}`; + } + } +} +``` + + + +示例代码说明：以上示例代码从hello uni-app示例中复制，涉及的css样式在hello uni-app的app.vue和uni.css中 + +预览H5效果：使用浏览器的手机模式访问[https://uniapp.dcloud.io/h5/pages/component/picker/picker](https://uniapp.dcloud.io/h5/pages/component/picker/picker) + +**注意** +- 在picker内容还在滚动时或滚动回弹动画还未结束时，点确定关闭弹出的picker，数据无法及时更新。需等待一下，或手动触停滚动再点确定。所有平台均如此 diff --git a/docs/component/progress.md b/docs/component/progress.md new file mode 100644 index 0000000000000000000000000000000000000000..08941b96f5318ace6c299269eb0cce8af965ca75 --- /dev/null +++ b/docs/component/progress.md @@ -0,0 +1,39 @@ +#### progress +进度条。 + +**属性说明** + +|属性名 |类型 |默认值 |说明 |平台差异说明 | +|:- |:- |:- |:- |:- | +|percent |Float |无 |百分比0~100 | | +|show-info |Boolean |false |在进度条右侧显示百分比 | | +|stroke-width |Number |6 |进度条线的宽度，单位px | | +|activeColor |Color |#09BB07 |已选择的进度条的颜色 | | +|backgroundColor|Color |#EBEBEB |未选择的进度条的颜色 | | +|active |Boolean |false |进度条从左往右的动画 | | +|active-mode |String |backwards |backwards: 动画从头播；forwards：动画从上次结束点接着播|微信小程序、5+APP、H5 | +|@activeend |EventHandle| |动画完成事件 |微信小程序 | + +**示例** +```html + + + + + + + + + + + + + + + + + + +``` + + \ No newline at end of file diff --git a/docs/component/radio.md b/docs/component/radio.md new file mode 100644 index 0000000000000000000000000000000000000000..0626c41e89c375ef093374b3c284b29dc265aceb --- /dev/null +++ b/docs/component/radio.md @@ -0,0 +1,105 @@ +#### radio-group + +单项选择器，内部由多个 ```` 组成。 + +**属性说明** + +|属性名|类型|默认值|说明| +|:-|:-|:-|:-| +|@change|EventHandle||```` 中的选中项发生变化时触发 change 事件，event.detail = {value: 选中项radio的value}| + +#### radio + +单选项目。 + +**属性说明** + +|属性名|类型|默认值|说明| +|:-|:-|:-|:-| +|value|String||```` 标识。当该 ```` 选中时，```` 的 change 事件会携带 ```` 的 value| +|checked|Boolean|false|当前是否选中| +|disabled|Boolean|false|是否禁用| +|color|Color||radio的颜色，同css的color| + +**示例** + +```html + + + + 默认样式 + + 选中 + 未选中 + + + 推荐展示样式 + + + + + + + {{item.name}} + + + + + +``` +```javascript +export default { + data() { + return { + items: [{ + value: 'USA', + name: '美国' + }, + { + value: 'CHN', + name: '中国', + checked: 'true' + }, + { + value: 'BRA', + name: '巴西' + }, + { + value: 'JPN', + name: '日本' + }, + { + value: 'ENG', + name: '英国' + }, + { + value: 'FRA', + name: '法国' + }, + ], + current: 0 + } + }, + methods: { + radioChange: function(evt) { + for (let i = 0; i < this.items.length; i++) { + if (this.items[i].value === evt.target.value) { + this.current = i; + break; + } + } + } + } +} +``` + + + +示例代码说明：以上示例代码从hello uni-app示例中复制，涉及的css样式在hello uni-app的app.vue和uni.css中 + +预览H5效果：使用浏览器的手机模式访问[https://uniapp.dcloud.io/h5/pages/component/radio/radio](https://uniapp.dcloud.io/h5/pages/component/radio/radio) + +**注意** +- radio的默认颜色，在不同平台不一样。微信小程序是绿色的，头条小程序为红色，其他平台是蓝色的。更改颜色使用color属性。 +- 如需调节radio大小，可通过css的scale方法调节，如缩小到70%`style="transform:scale(0.7)"` +- radio不是checkbox，点击一个已经选中的radio，不会将其取消选中 \ No newline at end of file diff --git a/docs/component/rich-text.md b/docs/component/rich-text.md new file mode 100644 index 0000000000000000000000000000000000000000..5c6e95409530e36aadd33ca77996ba7dd5232d58 --- /dev/null +++ b/docs/component/rich-text.md @@ -0,0 +1,140 @@ +#### rich-text +富文本。 + +**属性说明** + +|属性名|类型|默认值|说明| +|:-|:-|:-|:-| +|nodes|Array / String|[]|节点列表 / HTML String| + +**注意** + +支付宝小程序 nodes 属性只支持使用 Array 类型。如果需要支持 HTML String，则需要自己将 HTML String转化为 nodes 数组，可使用 [html-parser](https://github.com/dcloudio/hello-uniapp/blob/master/common/html-parser.js) 转换。 + +支持默认事件，包括：click、touchstart、touchmove、touchcancel、touchend、longpress。 + +**nodes 属性推荐使用 Array 类型，由于组件会将 String 类型转换为 Array 类型，因而性能会有所下降。** + +##### nodes + +现支持两种节点，通过 type 来区分，分别是元素节点和文本节点，默认是元素节点，在富文本区域里显示的 HTML 节点。 + +**元素节点：type = node** + +|属性|说明|类型|必填|备注| +|:-|:-|:-|:-|:-| +|name|标签名|String|是|支持部分受信任的 HTML 节点| +|attrs|属性|Object|否|支持部分受信任的属性，遵循 Pascal 命名法| +|children|子节点列表|Array|否|结构和 nodes 一致| + +**文本节点：type = text** + +|属性|说明|类型|必填|备注| +|:-|:-|:-|:-|:-| +|text|文本|String|是|支持 entities| + +##### 受信任的HTML节点及属性 + +全局支持class和style属性，**不支持id属性**。 + +|节点|属性| +|:-|:-| +|a|| +|abbr|| +|b|| +|blockquote|| +|br|| +|code|| +|col|span，width| +|colgroup|span，width| +|dd|| +|del|| +|div|| +|dl|| +|dt|| +|em|| +|fieldset|| +|h1|| +|h2|| +|h3|| +|h4|| +|h5|| +|h6|| +|hr|| +|i|| +|img|alt，src，height，width| +|ins|| +|label|| +|legend|| +|li|| +|ol|start，type| +|p|| +|q|| +|span|| +|strong|| +|sub|| +|sup|| +|table|width| +|tbody|| +|td|colspan，height，rowspan，width| +|tfoot|| +|th|colspan，height，rowspan，width| +|thead|| +|tr|| +|ul| | + +**示例** +```html + + + + + + 数组类型 + \nnodes属性为Array + + + + + + 字符串类型 + \nnodes属性为String + + + + + + + +``` +```javascript +export default { + data() { + return { + nodes: [{ + name: 'div', + attrs: { + class: 'div-class', + style: 'line-height: 60px; color: red; text-align:center;' + }, + children: [{ + type: 'text', + text: 'Hello uni-app!' + }] + }], + strings: '' + } + } +} +``` + + +**Tips** + +- nodes 不推荐使用 String 类型，性能会有所下降。 +- rich-text 组件内屏蔽所有节点的事件。所以如果内容中有链接、图片需要点击，则不能使用rich-text，此时可在[uni-app插件市场](https://ext.dcloud.net.cn/)搜索uparse插件使用。 +- attrs 属性不支持 id ，支持 class 。 +- name 属性大小写不敏感。 +- 如果使用了不受信任的HTML节点，该节点及其所有子节点将会被移除。 +- img 标签仅支持网络图片。 +- 如果在自定义组件中使用 rich-text 组件，那么仅自定义组件的 css 样式对 rich-text 中的 class 生效。 \ No newline at end of file diff --git a/docs/component/scroll-view.md b/docs/component/scroll-view.md new file mode 100644 index 0000000000000000000000000000000000000000..f8cf2095f1526f832c4713d5560ca1c17a581e46 --- /dev/null +++ b/docs/component/scroll-view.md @@ -0,0 +1,105 @@ +#### scroll-view + +可滚动视图区域。 + +**属性说明** + +|属性名 |类型 |默认值 |说明 |平台差异说明 | +|:- |:- |:- |:- |:- | +|scroll-x |Boolean |false |允许横向滚动 | | +|scroll-y |Boolean |false |允许纵向滚动 | | +|upper-threshold |Number |50 |距顶部/左边多远时（单位px），触发 scrolltoupper 事件 | | +|lower-threshold |Number |50 |距底部/右边多远时（单位px），触发 scrolltolower 事件 | | +|scroll-top |Number | |设置竖向滚动条位置 | | +|scroll-left |Number | |设置横向滚动条位置 | | +|scroll-into-view |String | |值应为某子元素id（id不能以数字开头）。设置哪个方向可滚动，则在哪个方向滚动到该元素 | | +|scroll-with-animation |Boolean |false |在设置滚动条位置时使用动画过渡 | | +|enable-back-to-top |Boolean |false |iOS点击顶部状态栏、安卓双击标题栏时，滚动条返回顶部，只支持竖向 |微信小程序 | +|@scrolltoupper |EventHandle| |滚动到顶部/左边，会触发 scrolltoupper 事件 | | +|@scrolltolower |EventHandle| |滚动到底部/右边，会触发 scrolltolower 事件 | | +|@scroll |EventHandle| |滚动时触发，event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY} | | + +使用竖向滚动时，需要给 ```` 一个固定高度，通过 css 设置 height。 + +**示例** +```html + + + + + Vertical Scroll + \n纵向滚动 + + + + A + B + C + + + + 点击这里返回顶部 + + + Horizontal Scroll + \n横向滚动 + + + + A + B + C + + + + + +``` + +```javascript +export default { + data() { + return { + scrollTop: 0, + old: { + scrollTop: 0 + } + } + }, + methods: { + upper: function(e) { + console.log(e) + }, + lower: function(e) { + console.log(e) + }, + scroll: function(e) { + console.log(e) + this.old.scrollTop = e.detail.scrollTop + }, + goTop: function(e) { + this.scrollTop = this.old.scrollTop + this.$nextTick(function() { + this.scrollTop = 0 + }); + uni.showToast({ + icon:"none", + title:"纵向滚动 scrollTop 值已被修改为 0" + }) + } + } +} +``` + + + +**Tips** + +- 5+APP和小程序中，请勿在 scroll-view 中使用 map、video 等原生组件。小程序中 scroll-view 中也不要使用 canvas、textarea 原生组件。更新：微信基础库2.4.4起支持了原生组件在 scroll-view、swiper、movable-view 中的使用 +- scroll-view 不适合放长列表，有性能问题。长列表滚动和下拉刷新，应该使用原生导航栏搭配页面级的滚动和下拉刷新实现。 +- scroll-into-view 的优先级高于 scroll-top。 +- 使用 scroll-view 会和原生下拉刷新造成冲突，所以在使用 scroll-view 的地方不建议使用下拉刷新，也不建议监听 onPullDownRefresh 事件。 +- 若要使用下拉刷新，请使用页面的滚动，而不是 scroll-view 。插件市场有前端模拟的下拉刷新，但性能不佳。 +- 如果遇到scroll-top、scroll-left属性设置不生效的问题参考：[组件属性设置不生效解决办法](/use?id=%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98) +- scroll-view的滚动条设置，可通过css的-webkit-scrollbar自定义，包括隐藏滚动条。（nvue无此css） \ No newline at end of file diff --git a/docs/component/slider.md b/docs/component/slider.md new file mode 100644 index 0000000000000000000000000000000000000000..7897f5b9d4b5dc9dab9433e86cfe537412f2613d --- /dev/null +++ b/docs/component/slider.md @@ -0,0 +1,77 @@ +#### slider + +滑动选择器。 + +**属性说明** + +|属性名|类型|默认值|说明| +|:-|:-|:-|:-| +|min|Number|0|最小值| +|max|Number|100|最大值| +|step|Number|1|步长，取值必须大于 0，并且可被(max - min)整除| +|disabled|Boolean|false|是否禁用| +|value|Number|0|当前取值| +|activeColor|Color|各个平台不同，详见下|滑块左侧已选择部分的线条颜色| +|backgroundColor|Color|#e9e9e9|滑块右侧背景条的颜色| +|block-size|Number|28|滑块的大小，取值范围为 12 - 28 +|block-color|Color|#ffffff|滑块的颜色| +|show-value|Boolean|false|是否显示当前 value| +|@change|EventHandle||完成一次拖动后触发的事件，event.detail = {value: value}| +|@changing|EventHandle||拖动过程中触发的事件，event.detail = {value: value}| + + +**Tips** + +- activeColor默认值在不同平台不一样，微信是绿色(#1aad19)，头条是红色，其他平台是蓝色 +- 如需要区间滑块，即一根横条上使用2个滑块选择一段范围，可见[插件市场](https://ext.dcloud.net.cn/search?q=%E5%8C%BA%E9%97%B4%E6%BB%91%E5%9D%97) + +**示例** + +```html + + + + 设置step + + + + + 显示当前value + + + + + 设置最小/最大值 + + + + + 不同颜色和大小的滑块 + + + + + + +``` + +```javascript +export default { + data() { + return {} + }, + methods: { + sliderChange(e) { + console.log('value 发生变化：' + e.detail.value) + } + } +} + +``` + + + +示例代码说明：以上示例代码从hello uni-app示例中复制，涉及的css样式在hello uni-app的app.vue和uni.css中 + +预览H5效果：使用浏览器的手机模式访问[https://uniapp.dcloud.io/h5/pages/component/slider/slider](https://uniapp.dcloud.io/h5/pages/component/slider/slider) \ No newline at end of file diff --git a/docs/component/swiper.md b/docs/component/swiper.md new file mode 100644 index 0000000000000000000000000000000000000000..a0ef0c33cc0be54344fcfe5ff8fc1e37902ca58d --- /dev/null +++ b/docs/component/swiper.md @@ -0,0 +1,125 @@ +#### swiper + +滑块视图容器。一般用于左右滑动或上下滑动，比如banner轮播图，注意是滑动切换而不是滚动。swiper下的每个swiper-item是一个滑动切换区域，不能停留在2个滑动区域之间。 + +**属性说明** + +|属性名|类型|默认值|说明|平台差异说明| +|:-|:-|:-|:-|:-| +|indicator-dots|Boolean|false|是否显示面板指示点|| +|indicator-color|Color|rgba(0, 0, 0, .3)|指示点颜色|| +|indicator-active-color|Color|#000000|当前选中的指示点颜色|| +|autoplay|Boolean|false|是否自动切换|| +|current|Number|0|当前所在滑块的 index|| +|current-item-id|String||当前所在滑块的 item-id ，不能与 current 被同时指定|微信小程序、5+App、H5、百度小程序、头条小程序| +|interval|Number|5000|自动切换时间间隔|| +|duration|Number|500|滑动动画时长|| +|circular|Boolean|false|是否采用衔接滑动|| +|vertical|Boolean|false|滑动方向是否为纵向|| +|previous-margin|String|0px|前边距，可用于露出前一项的一小部分，接受 px 和 rpx 值|头条小程序不支持| +|next-margin|String|0px|后边距，可用于露出后一项的一小部分，接受 px 和 rpx 值|头条小程序不支持| +|display-multiple-items|Number|1|同时显示的滑块数量|微信小程序、5+App、H5、百度小程序、头条小程序| +|skip-hidden-item-layout|Boolean|false|是否跳过未显示的滑块布局，设为 true 可优化复杂情况下的滑动性能，但会丢失隐藏状态滑块的布局信息|微信小程序、5+App| +|@change|EventHandle||current 改变时会触发 change 事件，event.detail = {current: current, source: source}|| +|@animationfinish|EventHandle||动画结束时会触发 animationfinish 事件，event.detail 同上|头条小程序不支持| + +change 事件返回 detail 中包含一个 source 字段，表示导致变更的原因，可能值如下： + +- autoplay 自动播放导致swiper变化。 +- touch 用户划动引起swiper变化。 +- 其他原因将用空字符串表示。 + +**swiper做左右拖动的长列表问题** +- swiper是单页组件，适合做banner图轮播和简单列表左右滑动。 +- 因为性能问题，用swiper做复杂长列表，需要较高的优化技巧以及接受一些限制。 +- 这是一个范例，[插件市场新闻模板示例](https://ext.dcloud.net.cn/plugin?id=103)，它在App端使用了nvue的原生渲染，实现高性能的左右拖动长列表；并支持可自定义的任何形式的下拉刷新。它在非App端使用的模式是只缓存左右一共3列的数据，dom中的数据过多时，它会自动释放。就是说App上，只要看过这一页，再进去时内容是还在的。而在非App上，只能做到缓存3页数据，其他页即便看过，再进去也会重新加载。并且非App的这种情况下，不再提供下拉刷新。虽然插件市场也有其他前端模拟的下拉刷新，但性能不佳。一般小程序的大厂案例里，提供左右拖长列表的，都是这种做法。 + +**Tips** + +- 使用竖向滚动时，需要给 ```` 一个固定高度，通过 css 设置 height。 +- 注意：其中只可放置 ```` 组件，否则会导致未定义的行为。 +- 如果遇到current、current-item-id属性设置不生效的问题参考：[组件属性设置不生效解决办法](/use?id=%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98) +- banner图的切换效果和指示器的样式，有多种风格可自定义，可在[uni-app插件市场](https://ext.dcloud.net.cn/search?q=%E8%BD%AE%E6%92%AD)搜索 +- swiper在非H5端，不支持内嵌video、map等原生组件。更新：微信基础库2.4.4起支持了原生组件在 scroll-view、swiper、movable-view 中的使用 + +#### swiper-item +仅可放置在 ```` 组件中，宽高自动设置为100%。 + +|属性名|类型|默认值|说明| +|:-|:-|:-|:-|:-| +|item-id|String||该 swiper-item 的标识符| + +**示例** +```html + + + + + + + + A + + + B + + + C + + + + + + + + 指示点 + + + + 自动播放 + + + + + + 幻灯片切换时长(ms) + {{duration}} + + + + 自动播放间隔时长(ms) + {{interval}} + + + + + +``` +```javascript +export default { + data() { + return { + background: ['color1', 'color2', 'color3'], + indicatorDots: true, + autoplay: true, + interval: 2000, + duration: 500 + } + }, + methods: { + changeIndicatorDots(e) { + this.indicatorDots = !this.indicatorDots + }, + changeAutoplay(e) { + this.autoplay = !this.autoplay + }, + intervalChange(e) { + this.interval = e.target.value + }, + durationChange(e) { + this.duration = e.target.value + } + } +} +``` +  \ No newline at end of file diff --git a/docs/component/switch.md b/docs/component/switch.md new file mode 100644 index 0000000000000000000000000000000000000000..4efb451650560aab412faa304a1b0c3745685db1 --- /dev/null +++ b/docs/component/switch.md @@ -0,0 +1,66 @@ +#### switch + +开关选择器。 + +**属性说明** + +|属性名|类型|默认值|说明|平台差异说明| +|:-|:-|:-|:-|:-|:-| +|checked|Boolean|false|是否选中|| +|disabled|Boolean|false|是否禁用|头条小程序不支持| +|type|String|switch|样式，有效值：switch, checkbox|| +|@change|EventHandle||checked 改变时触发 change 事件，event.detail={ value:checked}|| +|color|Color||switch 的颜色，同 css 的 color| | + +**示例** + +```html + + + + 默认样式 + + + + + 推荐展示样式 + + + + 开启中 + + + + 关闭 + + + + + +``` + +```javascript +export default { + data() { + return {} + }, + methods: { + switch1Change: function (e) { + console.log('switch1 发生 change 事件，携带值为', e.target.value) + }, + switch2Change: function (e) { + console.log('switch2 发生 change 事件，携带值为', e.target.value) + } + } +} +``` + + + +示例代码说明：以上示例代码从hello uni-app示例中复制，涉及的css样式在hello uni-app的app.vue和uni.css中 + +预览H5效果：使用浏览器的手机模式访问[https://uniapp.dcloud.io/h5/pages/component/switch/switch](https://uniapp.dcloud.io/h5/pages/component/switch/switch) + +**注意** +- switch的默认颜色，在不同平台不一样。微信小程序是绿色的，头条小程序为红色，其他平台是蓝色的。更改颜色使用color属性。 +- 如需调节switch大小，可通过css的scale方法调节，如缩小到70%`style="transform:scale(0.7)"` diff --git a/docs/component/text.md b/docs/component/text.md new file mode 100644 index 0000000000000000000000000000000000000000..8c47ee51a0a91ea4851eb02fcb0a0e6402f19669 --- /dev/null +++ b/docs/component/text.md @@ -0,0 +1,90 @@ +#### text +文本。 + +**属性说明** + +|属性名 |类型 |默认值 |说明 |平台差异说明 | +|:-|:- |:- |:- |:- |:- | +|selectable |Boolean|false |文本是否可选 | | +|space |String | |显示连续空格 |5+APP、H5、微信小程序 | +|decode |Boolean|false |是否解码 |5+APP、H5、微信小程序 | + +**space 值说明** + +|值|说明| +|:-|:-| +|ensp|中文字符空格一半大小| +|emsp|中文字符空格大小| +|nbsp|根据字体设置的空格大小| + +**Tips** + +- `` 组件内只支持嵌套 ``，不支持其它组件或自定义组件，否则会引发在不同平台的渲染差异。。 +- decode 可以解析的有 ` ` `<` `>` `&` `'` ` ` ` `。 +- 各个操作系统的空格标准并不一致。 +- 除了文本节点以外的其他节点都无法长按选中。 +- 支持 `\n` 方式换行。 +- 如果使用 `` 组件编译时会被转换为 ``。 + +**示例** +```html + + + + + {{text}} + + + add line + remove line + + + + +``` +```javascript +export default { + data() { + return { + texts: [ + 'HBuilder，200万开发者选择的IDE', + 'MUI，轻巧、漂亮的前端开源框架', + 'wap2app，M站快速转换原生体验的App', + '5+Runtime，为HTML5插上原生的翅膀', + 'HBuilderX，轻巧、极速，极客编辑器', + 'uni-app，终极跨平台方案', + 'HBuilder，200万开发者选择的IDE', + 'MUI，轻巧、漂亮的前端开源框架', + 'wap2app，M站快速转换原生体验的App', + '5+Runtime，为HTML5插上原生的翅膀', + 'HBuilderX，轻巧、极速，极客编辑器', + 'uni-app，终极跨平台方案', + '......' + ], + text: '', + canAdd: true, + canRemove: false, + extraLine: [] + } + }, + methods: { + add: function(e) { + this.extraLine.push(this.texts[this.extraLine.length % 12]); + this.text = this.extraLine.join('\n'); + this.canAdd = this.extraLine.length < 12; + this.canRemove = this.extraLine.length > 0; + }, + remove: function(e) { + if (this.extraLine.length > 0) { + this.extraLine.pop(); + this.text = this.extraLine.join('\n'); + this.canAdd = this.extraLine.length < 12; + this.canRemove = this.extraLine.length > 0; + } + } + } +} + +``` + + diff --git a/docs/component/textarea.md b/docs/component/textarea.md new file mode 100644 index 0000000000000000000000000000000000000000..81c3b895d0f273ca47c6cf8bd5a6b4be06e832b7 --- /dev/null +++ b/docs/component/textarea.md @@ -0,0 +1,75 @@ +#### textarea + +多行输入框。 + +**属性说明** + +|属性名|类型|默认值|说明|平台差异说明| +|:-|:-|:-|:-|:-| +|value|String||输入框的内容|| +|placeholder|String||输入框为空时占位符|| +|placeholder-style|String||指定 placeholder 的样式|| +|placeholder-class|String|textarea-placeholder|指定 placeholder 的样式类|头条小程序不支持| +|disabled|Boolean|false|是否禁用|| +|maxlength|Number|140|最大输入长度，设置为 -1 的时候不限制最大长度|| +|focus|Boolean|false|获取焦点|| +|auto-height|Boolean|false|是否自动增高，设置auto-height时，style.height不生效|| +|fixed|Boolean|false|如果 textarea 是在一个 position:fixed 的区域，需要显示指定属性 fixed 为 true|微信小程序、百度小程序、头条小程序| +|cursor-spacing|Number|0|指定光标与键盘的距离，单位 px 。取 textarea 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离|微信小程序、百度小程序、头条小程序| +|cursor|Number||指定focus时的光标位置|微信小程序、5+App、H5、百度小程序、头条小程序| +|show-confirm-bar|Boolean|true|是否显示键盘上方带有”完成“按钮那一栏|微信小程序、百度小程序| +|selection-start|Number|-1|光标起始位置，自动聚集时有效，需与selection-end搭配使用|微信小程序、5+App、H5、百度小程序、头条小程序| +|selection-end|Number|-1|光标结束位置，自动聚集时有效，需与selection-start搭配使用|微信小程序、5+App、H5、百度小程序、头条小程序| +|adjust-position|Boolean|true|键盘弹起时，是否自动上推页面|微信小程序、百度小程序| +|@focus|EventHandle||输入框聚焦时触发，event.detail = { value, height }，height 为键盘高度|微信小程序（基础库 1.9.90 起）| +|@blur|EventHandle||输入框失去焦点时触发，event.detail = {value, cursor}|| +|@linechange|EventHandle||输入框行数变化时调用，event.detail = {height: 0, heightRpx: 0, lineCount: 0}|头条小程序不支持| +|@input|EventHandle||当键盘输入时，触发 input 事件，event.detail = {value, cursor}， @input 处理函数的返回值并不会反映到 textarea 上|| +|@confirm|EventHandle||点击完成时， 触发 confirm 事件，event.detail = {value: value}|微信小程序、百度小程序| + +**示例** + +```html + + + 输入区域高度自适应，不会出现滚动条 + + + + 占位符字体是红色的textarea + + + + + +``` + +```javascript +export default { + data() { + return {} + }, + methods: { + bindTextAreaBlur: function (e) { + console.log(e.detail.value) + } + } +} +``` + + + +**Tips** + +- textarea 的 blur 事件会晚于页面上的 tap 事件，如果需要在 button 的点击事件获取 textarea，可以使用 form 的 @submit。 +- `input` 事件处理函数内实时修改当前值不生效，可以延迟设置，例如：``setTimeout(() => { this.value = 100 }, 0)``。 +- 微信小程序、百度小程序、头条小程序中，textarea是原生组件，层级高于前端组件，请勿在 scroll-view、swiper、picker-view、movable-view 中使用 textarea 组件。覆盖textarea需要使用cover-view。[详见](/component/native-component) +- 小程序端 css 动画对 textarea 组件无效。 +- H5 平台只能在用户交互时修改 focus 生效。 +- 如果遇到 focus 属性设置不生效的问题参考：[组件属性设置不生效解决办法](/use?id=%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98) +- 软键盘的弹起和收齐逻辑，详见[input的文档](/component/input?id=app%E5%B9%B3%E5%8F%B0ios%E7%AB%AF%E8%BD%AF%E9%94%AE%E7%9B%98%E4%B8%8A%E6%96%B9%E6%A8%AA%E6%9D%A1%E5%8E%BB%E9%99%A4%E6%96%B9%E6%A1%88) + +**富文本编辑的解决方案** +在输入框里图文混排内容，在web上该功能依赖document，而小程序和app的正常页面又没有document。 +- 方式一是采用markdown编辑器方案，输入区输入markdown语法，预览区提供预览。插件市场搜[富文本编辑](https://ext.dcloud.net.cn/search?q=%E5%AF%8C%E6%96%87%E6%9C%AC%E7%BC%96%E8%BE%91)，有不少插件。 +- 方式二是在vue页面里内嵌web-view组件，该组件支持完整html语法，此时可使用web中常见的各种富文本编辑器，插件市场也有这类插件。 diff --git a/docs/component/video.md b/docs/component/video.md new file mode 100644 index 0000000000000000000000000000000000000000..b36a269a09fd619deae0b07674cee747282a7650 --- /dev/null +++ b/docs/component/video.md @@ -0,0 +1,146 @@ +#### video +视频。 + +**平台差异说明** + +|5+App|H5|微信小程序|支付宝小程序|百度小程序|头条小程序| +|:-:|:-:|:-:|:-:|:-:|:-:| +|√|√|√|x|√|√| + +**属性说明** + +|属性名|类型|默认值|说明|平台差异说明| +|:-|:-|:-|:-|:-| +|src|String||要播放视频的资源地址|| +|autoplay|Boolean|false|是否自动播放|| +|loop|Boolean|false|是否循环播放|头条小程序不支持| +|muted|Boolean|false|是否静音播放|头条小程序不支持| +|initial-time|Number||指定视频初始播放位置，单位为秒（s）。|头条小程序不支持| +|duration|Number||指定视频时长，单位为秒（s）。|头条小程序不支持| +|controls|Boolean|true|是否显示默认播放控件（播放/暂停按钮、播放进度、时间）|头条小程序不支持| +|danmu-list|Object Array||弹幕列表|头条小程序不支持| +|danmu-btn|Boolean|false|是否显示弹幕按钮，只在初始化时有效，不能动态变更|头条小程序不支持| +|enable-danmu|Boolean|false|是否展示弹幕，只在初始化时有效，不能动态变更|头条小程序不支持| +|page-gesture|Boolean|false|在非全屏模式下，是否开启亮度与音量调节手势|微信小程序、H5| +|direction|Number||设置全屏时视频的方向，不指定则根据宽高比自动判断。有效值为 0（正常竖向）, 90（屏幕逆时针90度）, -90（屏幕顺时针90度）|头条小程序不支持| +|show-progress|Boolean|true|若不设置，宽度大于240时才会显示|头条小程序不支持| +|show-fullscreen-btn|Boolean|true|是否显示全屏按钮|头条小程序不支持| +|show-play-btn|Boolean|true|是否显示视频底部控制栏的播放按钮|头条小程序不支持| +|show-center-play-btn|Boolean|true|是否显示视频中间的播放按钮|头条小程序不支持| +|enable-progress-gesture|Boolean|true|是否开启控制进度的手势|头条小程序不支持| +|objectFit|String|contain|当视频大小与 video 容器大小不一致时，视频的表现形式。contain：包含，fill：填充，cover：覆盖|微信小程序、H5| +|poster|String||视频封面的图片网络资源地址，如果 controls 属性值为 false 则设置 poster 无效|头条小程序不支持| +|@play|EventHandle||当开始/继续播放时触发play事件|头条小程序不支持| +|@pause|EventHandle||当暂停播放时触发 pause 事件|头条小程序不支持| +|@ended|EventHandle||当播放到末尾时触发 ended 事件|头条小程序不支持| +|@timeupdate|EventHandle||播放进度变化时触发，event.detail = {currentTime, duration} 。触发频率 250ms 一次|头条小程序不支持| +|@fullscreenchange|EventHandle||当视频进入和退出全屏时触发，event.detail = {fullScreen, direction}，direction取为 vertical 或 horizontal|头条小程序不支持| +|@waiting|EventHandle||视频出现缓冲时触发|头条小程序不支持| +|@error|EventHandle||视频播放出错时触发|头条小程序不支持| + +`` 默认宽度 300px、高度 225px，可通过 css 设置宽高。 + +**示例** + +```html + + + + + + + + + + + 弹幕内容 + + + + + + + + 发送弹幕 + + + + + +``` + +```javascript +export default { + data() { + return { + src: '', + danmuList: [{ + text: '第 1s 出现的弹幕', + color: '#ff0000', + time: 1 + }, + { + text: '第 3s 出现的弹幕', + color: '#ff00ff', + time: 3 + } + ], + danmuValue: '' + } + }, + onReady: function(res) { + // #ifndef MP-ALIPAY + this.videoContext = uni.createVideoContext('myVideo') + // #endif + }, + methods: { + sendDanmu: function() { + this.videoContext.sendDanmu({ + text: this.danmuValue, + color: this.getRandomColor() + }); + this.danmuValue = ''; + }, + videoErrorCallback: function(e) { + uni.showModal({ + content: e.target.errMsg, + showCancel: false + }) + }, + getRandomColor: function() { + const rgb = [] + for (let i = 0; i < 3; ++i) { + let color = Math.floor(Math.random() * 256).toString(16) + color = color.length == 1 ? '0' + color : color + rgb.push(color) + } + return '#' + rgb.join('') + } + } +} +``` + + + +相关api：[uni.createVideoContext](/api/media/video-context?id=createvideocontext) + +**注意** + +- 视频播放格式说明： + * H5平台：支持支持的视频格式视浏览器而定，一般通用的都支持：mp4、webm 和 ogg。（```` 组件编译到 H5 时会替换为标准 html 的 video 标签）。H5端也可以自行在条件编译里使用video.js等三方库，这些库可以自动判断环境兼容以决定使用标准video或flash来播放。 + * 小程序平台：各小程序平台支持程度不同，详见各家文档：[微信小程序视频组件文档](https://developers.weixin.qq.com/miniprogram/dev/component/video.html)、支付宝不支持video组件、[百度小程序视频组件文档](https://smartprogram.baidu.com/docs/develop/component/media/#video/)、[头条小程序视频组件文档](https://developer.toutiao.com/docs/comp/video.html) + * App平台： 支持本地视频(mp4/flv)、网络视频地址（mp4/flv/m3u8）及流媒体（rtmp/hls/rtsp）。 + +- video全屏后，如何自行绘制界面？ + * 微信基础库 2.4.0 以上可通过cover-view来绘制界面覆盖元素 + * H5端可通过通用h5做法实现 + * app端video正在开发相应方案 + * 其他端无法全屏后自行绘制内容 + +- `` 组件在非H5端是原生组件，层级高于普通前端组件，覆盖其需要使用[cover-view](https://uniapp.dcloud.io/component/cover-view?id=cover-view)组件或plus.nativeObj.view、subNVue。微信基础库 2.4.0 起已支持 video 组件的同层渲染，也就是video在非全屏时，可以被前端元素通过调节zindex来遮挡，但video全屏时，仍需要cover-view覆盖。 +- 除微信基础库 2.4.0 以上，其他情况下非H5的video不能放入scroll-view和swiper。注意参考 [原生组件使用限制](/component/native-component)。 + +- App平台：使用 `` 组件，打包 App 时必须勾选 manifest.json->App 模块权限配置->VideoPlayer 模块。 +- App平台：如果想使用非原生的video，即原来普通的html5自带video，可使用web-view组件load html页面，在其中使用普通h5 video。 +- H5平台： 在部分浏览器中会强制调用原生播放器播放（如：微信内置浏览器、UC浏览器等），在 x5 内核的浏览器中支持配置[同层播放器](https://x5.tencent.com/tbs/guide/video.html)。 \ No newline at end of file diff --git a/docs/component/view.md b/docs/component/view.md new file mode 100644 index 0000000000000000000000000000000000000000..4f39245cff445d7f81db0640d39803d2811b94fd --- /dev/null +++ b/docs/component/view.md @@ -0,0 +1,48 @@ +#### view + +视图容器。 + +**属性说明** + +|属性名|类型|默认值|说明| +|:-|:-|:-|:-| +|hover-class|String|none|指定按下去的样式类。当 hover-class="none" 时，没有点击态效果| +|hover-stop-propagation|Boolean|false|指定是否阻止本节点的祖先节点出现点击态| +|hover-start-time|Number|50|按住后多久出现点击态，单位毫秒| +|hover-stay-time|Number|400|手指松开后点击态保留时间，单位毫秒| + +**示例** + +```html + + + + + flex-direction: row + \n横向布局 + + + A + B + C + + + flex-direction: column + \n纵向布局 + + + A + B + C + + + + +``` + + + +**Tips** + +- 如果需要使用滚动视图，请使用 [scroll-view](/component/scroll-view) +- 如果使用 `` 组件编译时会被转换为 ``。 \ No newline at end of file diff --git a/docs/component/web-view.md b/docs/component/web-view.md new file mode 100644 index 0000000000000000000000000000000000000000..78aab723f8666ad9ee8f523245e3b9615000c1be --- /dev/null +++ b/docs/component/web-view.md @@ -0,0 +1,242 @@ +#### web-view + +`web-view` 是一个 web 浏览器组件，可以用来承载网页的容器，会自动铺满整个页面。 + +> 各小程序平台，web-view 加载的 url 需要在后台配置域名白名单，包括内部再次 iframe 内嵌的其他 url 。 + +**属性说明** + +|属性名|类型|说明|平台差异说明| +|:-|:-|:-|:| +|src|String|webview 指向网页的链接| | +|webview-styles|Object|webview 的样式|5+App| +|@message|EventHandler|网页向应用 `postMessage` 时，会在特定时机（后退、组件销毁、分享）触发并收到消息。|H5 暂不支持| + +**src** + +|来源|5+App|H5|微信小程序|支付宝小程序|百度小程序|头条小程序| +|:-|:-:|:-:|:-:|:-:|:-:|:-:| +|网络|√|√|√|√|√|√| +|本地|√|暂不支持|x|x|x|x| + +**webview-styles** + +|属性|类型|说明| +|:-|:-|:-| +|progress|Object/Boolean|进度条样式。仅加载网络 HTML 时生效，设置为 `false` 时禁用进度条。| + +**progress** + +|属性|类型|默认值|说明| +|:-|:-|:-|:-| +|color|String|#00FF00|进度条颜色| + +```html + + + + + + + + + +``` + +注意： +- 小程序仅支持加载网络网页，不支持本地html +- 小程序端 web-view 组件一定有原生导航栏，下面一定是全屏的 web-view 组件，navigationStyle: custom 对 web-view 组件无效。 +- App 端使用 `自定义组件模式` 时，uni.web-view.js 的最低版为 [uni.webview.1.5.1.js](https://js.cdn.aliyun.dcloud.net.cn/dev/uni-app/uni.webview.1.5.1.js) +- App 平台同时支持网络网页和本地网页，但本地网页及相关资源（js、css等文件）必须放在 `uni-app 项目根目录->hybrid->html` 文件夹下，如下为一个加载本地网页的`uni-app`项目文件目录示例： + + + +┌─components +├─hybrid +│ └─html +│ ├─css +│ │ └─test.css +│ ├─img +│ │ └─icon.png +│ ├─js +│ │ └─test.js +│ └─local.html +├─pages +│ └─index +│ └─index.vue +├─static +├─main.js +├─App.vue +├─manifest.json +└─pages.json + + + +**示例** +```html + + + + + +``` + +`` 加载的网页中支持调用部分 uni 接口： + +|方法名|说明|平台差异说明| +|:-|:-|:-| +|uni.navigateTo|[navigateTo](/api/router?id=navigateto)|| +|uni.redirectTo|[redirectTo](/api/router?id=redirectto)|| +|uni.reLaunch|[reLaunch](/api/router?id=relaunch)|| +|uni.switchTab|[switchTab](/api/router?id=switchtab)|| +|uni.navigateBack|[navigateBack](/api/router?id=navigateback)|| +|uni.postMessage|向应用发送消息|头条小程序不支持| +|uni.getEnv|获取当前环境|头条小程序不支持| + +##### uni.postMessage(OBJECT) +网页向应用发送消息，在 `` 的 `message` 事件回调 `event.detail.data` 中接收消息。 + +**Tips** + +- 传递的消息信息，必须写在 data 对象中。 +- `event.detail.data` 中的数据，以数组的形式接收每次 post 的消息。 + +##### uni.getEnv(CALLBACK) + +**callback 返回的对象** + +|属性|类型|说明| +|:-|:-|:-| +|plus|Boolean|5+App| +|miniprogram|Boolean|微信小程序| +|smartprogram|Boolean|百度小程序| +|miniprogram|Boolean|支付宝小程序| + +**示例** + +在 `` 加载的 HTML 中，添加以下代码： + +```html + + + + + + + + +``` +待触发 `UniAppJSBridgeReady` 事件后，即可调用 uni 的 API。 +```html + +``` + + +##### **App端web-view的扩展** +App端的webview是非常强大的，可以更灵活的控制和拥有更丰富的API。 + +每个vue页面，其实都是一个webview，而vue页面里的web-view组件，其实是webview里的一个子webview。这个子webview被append到父webview上。 + +通过以下方法，可以获得这个web-view组件对应的js对象，然后参考[https://www.html5plus.org/doc/zh_cn/webview.html#plus.webview.WebviewObject](https://www.html5plus.org/doc/zh_cn/webview.html#plus.webview.WebviewObject)，可以进一步重设这个web-view组件的样式，比如调整大小 + +```html + + + + + + +``` + +甚至可以不用`web-view`组件，直接js创建一个子webview来加载html。比如不希望远程网页使用plus的API，不管是因为安全原因还是因为back监听冲突，可以使用如下代码： +```html + + + + + +``` + + +##### `web-view`组件的层级问题解决 +web-view组件在App和小程序中层级较高，如需要在vue页面中写代码为web-view组件覆盖内容，小程序端无解，只能由web-view的组件自己弹出div。App端有如下若干方案： +1. 比较简单的方式是actionsheet等原生弹出菜单 +2. 也可以使用plus.nativeObj.view。这里有一个底部图标菜单的示例，可参考[https://ext.dcloud.net.cn/plugin?id=69](https://ext.dcloud.net.cn/plugin?id=69) +3. 也可以使用HBuilderX1.9.10以后新出的[原生子窗体subNvue](/api/window/subNVues) +4. 也可以在web-view组件内嵌的网页中弹出z-index更高的div。如果是外部网页，可以在vue中获得子webview对象后，通过[evalJS](https://www.html5plus.org/doc/zh_cn/webview.html#plus.webview.WebviewObject.evalJS)为这个子webview注入一段js，操作其弹出div层。 + +**注意事项** +- `` 组件默认铺满全屏并且层级高于前端组件。App端想调节大小或再其上覆盖内容需使用plus规范。 +- `` 组件所在窗口的标题，跟随页面的 `` 值的变化而变化。 +- App端，web-view加载的html页面可以运行plus的api，但注意如果该页面调用了plus.key的API监听了back按键（或使用mui的封装），会造成back监听冲突。需要该html页面移除对back的监听。或按照上面的示例代码禁止网页使用plus对象 +- `uni.webview.js` 最新版地址：[https://js.cdn.aliyun.dcloud.net.cn/dev/uni-app/uni.webview.1.5.1.js](https://js.cdn.aliyun.dcloud.net.cn/dev/uni-app/uni.webview.1.5.1.js) +- 小程序平台，个人类型与海外类型的小程序使用 `web-view` 组件，提交审核时注意微信等平台是否允许使用 +- 小程序平台， `src` 指向的链接需登录小程序管理后台配置域名白名单。`5+App`和`H5` 无此限制。 + +##### FAQ + +Q：web-view 的页面怎么和应用内的页面交互？ +A：调用 uni 相关的 API，就可以实现页面切换及发送消息。参考：[在 web-view 加载的 HTML 中调用 uni 的 API](https://ask.dcloud.net.cn/article/35083) + +Q：web-view 加载的 HTML 中，能够调用 5+ 的能力么？ +A：加载的 HTML 中是有 5+ 环境的，在 plusready 后调用即可。参考：[一个简单实用的 plusready 方法](https://ask.dcloud.net.cn/article/34922) \ No newline at end of file diff --git a/docs/ecosystem.md b/docs/ecosystem.md new file mode 100644 index 0000000000000000000000000000000000000000..5257a0bd9e382a0f10fd3da157fc84f71b5375cb --- /dev/null +++ b/docs/ecosystem.md @@ -0,0 +1,20 @@ + +```uni-app``` 积极拥抱前端社区，创建了开放、兼容的生态系统。 + +- [uni-app插件市场](https://ext.dcloud.net.cn)，支持前端组件、js sdk、页面模板、项目模板、原生插件等多种类型，并为插件作者提供了荣誉+经济回报的双激励模式，打造最强大的开放生态。 + +- 兼容微信小程序 JS SDK，丰富的小程序生态内容可直接引入```uni-app```，并且在App侧通用。以前的跨平台开发框架普遍缺少三方SDK，由于大量SDK厂商均原厂维护小程序SDK，使得```uni-app```成为跨平台开发框架里生态最丰富的平台[参考](httsp://ask.dcloud.net.cn/article/35070) + +- 兼容微信小程序自定义组件，并且App侧通用，[参考](https://uniapp.dcloud.io/frame?id=小程序组件支持) + +- 支持 NPM 包管理系统，[参考](https://uniapp.dcloud.io/frame?id=npm%E6%94%AF%E6%8C%81) + +- 支持 mpvue 项目及组件，全端通用，[参考](https://ask.dcloud.net.cn/article/34945) + +- 支持通用 HTML 和 js 库，虽然小程序不支持通用 HTML 和 DOM，但```uni-app```的web-view组件支持load本地 HTML，可以在需要时引入相关库（注意 HTML 的性能不如 vue 页面）。参考[https://uniapp.dcloud.io/component/web-view](https://uniapp.dcloud.io/component/web-view) + +- App端支持和原生混合编码，支持 [Native.js](https://ask.dcloud.net.cn/docs/#//ask.dcloud.net.cn/article/88) 直接调用原生api、支持 [第三方原生sdk](https://ask.dcloud.net.cn/docs/#//ask.dcloud.net.cn/article/104) + +- App端支持 ```weex``` ，```uni-app``` 内置了 ```weex``` ，并在 ```weex``` 引擎中实现了常用的 uni api 的封装，比如 uni.request 可以在 ```weex``` 引擎中联网。这样的文件后缀名为 nvue。```uni-app```还支持 nvue 和 vue 复用 js 和 css。 + +- App端支持原生插件云打包，[参考](https://ask.dcloud.net.cn/article/35412) diff --git a/docs/extendUI.md b/docs/extendUI.md new file mode 100644 index 0000000000000000000000000000000000000000..0370ed804435606a91e87eded23bed162da0ec11 --- /dev/null +++ b/docs/extendUI.md @@ -0,0 +1,502 @@ +``uni-app`` 扩展了常用的的UI组件，使用方式： + +1. 从 [hello uniapp](https://github.com/dcloudio/hello-uniapp) 的 ``components`` 目录拷贝出以 ``uni`` 开头的相关组件，从 ``common`` 目录拷贝出 ``uni.css``（在 [HBuilderX](http://www.dcloud.io/hbuilderx.html) 中新建 ``hello uniapp`` 示例也可得到相关组件和css）。 +2. 将拷贝出的组件放置于自己工程下的 ``components`` 目录，组件的使用可参考各组件的使用说明。 +3. 项目中如果有多个页面用到扩展组件，可在 ``App.vue`` 里引入 ``uni.css``，若只是很少的页面用到扩展组件，仅需在用到的页面里引入 ``uni.css``，引入外部css可参考 [样式导入](/frame?id=样式导入)。 + + +### Badge 数字角标 + +数字角标一般和其它控件（列表、9宫格等）配合使用，用于进行数量提示，默认为实心灰色背景，组件名：``uni-badge``，代码块： uBadge。 + +**使用方式：** + +在 ``script`` 中引用组件 + +```javascript +import uniBadge from "@/components/uni-badge.vue" +export default { + components: {uniBadge} +} +``` + +在 ``template`` 中使用组件 + +```html +<uni-badge text="1"></uni-badge> +<uni-badge text="2" type="purple" @click="bindClick"></uni-badge> +<uni-badge text="3" type="primary" :inverted="true"></uni-badge> +``` + +**Badge 属性说明：** + +|属性名 |类型 |默认值 |说明 | +|--- |---- |--- |--- | +|text |String | |角标内容 | +|type |String |default|颜色类型，可选值：default（灰色）、primary（蓝色）、success（绿色）、warning(黄色)、danger(红色)、royal(紫色) | +|inverted |Boolean|false |是否无需背景颜色，为 true 时，背景颜色将变为文字的字体颜色| +|@click |EventHandle| |点击 Badge 触发事件 | + +### CountDown 倒计时 + +倒计时组件，组件名：``uni-countdown``，代码块： uCountDown。 + +**使用方式：** + +在 ``script`` 中引用组件 + +```javascript +import uniCountdown from "@/components/uni-countdown.vue" +export default { + components: {uniCountdown} +} +``` + +CountDown 在 ``template`` 中的使用 + +```html +<uni-countdown font-color="#FFFFFF" bgr-color="#000000" timer="2018-12-23 12:00:00"></uni-countdown> +``` + +**CountDown 属性说明：** + +|属性名|类型|默认值 |说明| +|---|----|---|---| +|bgr-color |String|#FFFFFF|背景色| +|border-color|String|#000000|边框颜色| +|font-color |String |#000000|文字颜色| +|splitor-color|String|#000000|割符号颜色| +|timer|String||倒计时时间，格式为：``YY-mm-dd HH:ii:ss``（日期和时间之间以空格隔开），如：``2018-12-23 12:00:00``| + +### Drawer 抽屉 + +抽屉侧滑菜单，组件名：``uni-drawer``，代码块： uDrawer。 + +**使用方式：** + +在 ``script`` 中引用组件 + +```javascript +import uniDrawer from "@/components/uni-drawer.vue" +export default { + components: {uniDrawer} +} +``` + +Drawer 在 ``template`` 中以 **插槽** 形式插入内容 + +```html +<uni-drawer :visible="true"> + <view style="padding:30rpx;"> + <view class="uni-title">抽屉式导航</view> + <view class="uni-list uni-common-mt"> + <view class="uni-list-cell" hover-class="uni-list-cell-hover"> + <view class="uni-list-cell-navigate uni-navigate-right">Item1</view> + </view> + <view class="uni-list-cell uni-list-cell-last" hover-class="uni-list-cell-hover"> + <view class="uni-list-cell-navigate uni-navigate-right">Item2</view> + </view> + </view> + </view> +</uni-drawer> +``` + +**Drawer 属性说明：** + +|属性名 |类型|默认值 |说明| +|---|----|---|---| +|visible |Boolean|false|Drawer的显示状态| +|mask |Boolean |true|是否显示遮罩| +|mode|String|left|Drawe滑出位置，可选值：left（从左侧滑出）， right（从右侧滑出| +|@close|EventHandle||组件关闭时触发事件 | + + +### Icon 图标 + +用于展示 icon，组件名：``uni-icon``，代码块： uIcon。 + +**使用方式：** + +在 ``script`` 中引用组件 + +```javascript +import uniIcon from "@/components/uni-icon.vue" +export default { + components: {uniIcon} +} +``` + +在 ``template`` 中使用组件 + +```html +<uni-icon type="contact" size="30"></uni-icon> +``` + +**Icon 属性说明：** + +|属性名 |类型|默认值 |说明| +|---|----|---|---| +|type |String ||图标图案，参考下表| +|color |String ||图标颜色 | +|size |Number |24|图标大小| +|@click |EventHandle||点击 Icon 触发事件| + +**type 类型** + +<div> + <link rel="stylesheet" type="text/css" href="https://img-cdn-qiniu.dcloud.net.cn/uniapp/doc/icon1.1.css"/> + <ul class="icon-group"> + <li class="icon-item"><span class="uni-icon uni-icon-contact"></span><span>contact</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-person"></span><span>person</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-personadd"></span><span>personadd</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-contact-filled"></span><span>contact-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-person-filled"></span><span>person-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-personadd-filled"></span><span>personadd-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-phone"></span><span>phone</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-email"></span><span>email</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-chatbubble"></span><span>chatbubble</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-chatboxes"></span><span>chatboxes</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-phone-filled"></span><span>phone-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-email-filled"></span><span>email-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-chatbubble-filled"></span><span>chatbubble-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-chatboxes-filled"></span><span>chatboxes-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-weibo"></span><span>weibo</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-weixin"></span><span>weixin</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-pengyouquan"></span><span>pengyouquan</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-chat"></span><span>chat</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-qq"></span><span>qq</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-videocam"></span><span>videocam</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-camera"></span><span>camera</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-mic"></span><span>mic</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-location"></span><span>location</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-mic-filled"></span><span>mic-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-location-filled"></span><span>location-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-micoff"></span><span>micoff</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-image"></span><span>image</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-map"></span><span>map</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-compose"></span><span>compose</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-trash"></span><span>trash</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-upload"></span><span>upload</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-download"></span><span>download</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-close"></span><span>close</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-redo"></span><span>redo</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-undo"></span><span>undo</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-refresh"></span><span>refresh</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-star"></span><span>star</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-plus"></span><span>plus</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-minus"></span><span>minus</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-circle"></span><span>circle</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-clear"></span><span>clear</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-refresh-filled"></span><span>refresh-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-star-filled"></span><span>star-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-plus-filled"></span><span>plus-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-minus-filled"></span><span>minus-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-circle-filled"></span><span>circle-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-checkbox-filled"></span><span>checkbox-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-closeempty"></span><span>closeempty</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-refreshempty"></span><span>refreshempty</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-reload"></span><span>reload</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-starhalf"></span><span>starhalf</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-spinner"></span><span>spinner</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-spinner-cycle"></span><span>spinner-cycle</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-search"></span><span>search</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-plusempty"></span><span>plusempty</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-forward"></span><span>forward</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-back"></span><span>back</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-checkmarkempty"></span><span>checkmarkempty</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-home"></span><span>home</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-navigate"></span><span>navigate</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-gear"></span><span>gear</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-paperplane"></span><span>paperplane</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-info"></span><span>info</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-help"></span><span>help</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-locked"></span><span>locked</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-more"></span><span>more</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-flag"></span><span>flag</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-home-filled"></span><span>home-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-gear-filled"></span><span>gear-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-info-filled"></span><span>info-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-help-filled"></span><span>help-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-more-filled"></span><span>more-filled</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-settings"></span><span>settings</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-list"></span><span>list</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-bars"></span><span>bars</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-loop"></span><span>loop</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-paperclip"></span><span>paperclip</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-eye"></span><span>eye</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-arrowup"></span><span>arrowup</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-arrowdown"></span><span>arrowdown</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-arrowleft"></span><span>arrowleft</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-arrowright"></span><span>arrowright</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-arrowthinup"></span><span>arrowthinup</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-arrowthindown"></span><span>arrowthindown</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-arrowthinleft"></span><span>arrowthinleft</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-arrowthinright"></span><span>arrowthinright</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-pulldown"></span><span>pulldown</span></li> + <li class="icon-item"><span class="uni-icon uni-icon-scan"></span><span>scan</span></li> + </ul> +</div> + + +### LoadMore 加载更多 + +用于列表中，做滚动加载使用，展示 loading 的各种状态，组件名：``uni-load-more``，代码块： uLoadMore。 + +**使用方式：** + +在 ``script`` 中引用组件 + +```javascript +import uniLoadMore from "@/components/uni-load-more.vue" +export default { + components: {uniLoadMore} +} +``` + +在 ``template`` 中使用组件 + +```html +<uni-load-more :loadingType="1"></uni-load-more> +``` + +**LoadMore 属性说明：** + +|属性名 |类型|默认值 |说明| +|---|----|---|---| +|loadingType |Number |0|loading 的状态，可选值：0（loading前），1（loading中），2（没有更多了）| +|showImage |Boolean |true|是否显示 loading 图| +|color |String |#777777|图标和文字颜色 | +|contentText |Object |```{contentdown: "上拉显示更多",contentrefresh: "正在加载...",contentnomore: "没有更多数据了"}```|各状态文字说明| + + +### NavBar 导航栏 + +导航栏组件，主要用于头部导航，组件名：``uni-nav-bar``，代码块： uNavBar。 + +**使用方式：** + +在 ``script`` 中引用组件 + +```javascript +import uniNavBar from "@/components/uni-nav-bar.vue" +export default { + components: {uniNavBar} +} +``` + +在 ``template`` 中使用组件 + +```html +<uni-nav-bar left-icon="back" left-text="返回" right-text="菜单" title="导航栏组件"></uni-nav-bar> +``` + +**NavBar 属性说明：** + +|属性名 |类型|默认值 |说明| +|---|----|---|---| +|title |String ||标题文字| +|left-text |String ||右侧按钮文本| +|right-text |String ||右侧按钮文本| +|left-tcon |String ||左侧按钮图标（图标类型参考 [Icon 图标](/uniUI?id=icon-图标) type 属性）| +|right-tcon |String ||右侧按钮图标（图标类型参考 [Icon 图标](/uniUI?id=icon-图标) type 属性）| +|fixed |Boolean |false|是否固定顶部| +|status-bar |Boolean|false（fixed为true时，status-bar默认值为true）|是否包含状态栏，| +|shadow |Boolean|true|导航栏下是否有阴影| +|color |String |#000000|图标和文字颜色 | +|background-color|String|#FFFFFF|导航栏背景颜色 | +|@click-left|EventHandle||左侧按钮点击时触发 | +|@click-right|EventHandle||右侧按钮点击时触发 | + +**NavBar 插槽** + +开发者使用 NavBar 时，支持向 NavBar 里插入不同内容，以达到自定义的目的。 + + +|子元素 slot 的值|说明| +|---|----| +|left |向导航栏左侧插入| +|right |向导航栏右侧插入| +|其他 |向导航栏中间插入| + +```html +<uni-nav-bar> + <view>标题栏</view> + <view slot="left">left</view> + <view slot="right">right</view> +</uni-nav-bar> +``` + +### NumberBox 数字输入框 + +带加减按钮的数字输入框，组件名：``uni-number-box``，代码块： uNumberBox。 + +**使用方式：** + +在 ``script`` 中引用组件 + +```javascript +import uniNumberBox from "@/components/uni-number-box.vue" +export default { + components: {uniNumberBox} +} +``` + +在 ``template`` 中使用组件 + +```html +<uni-number-box></uni-number-box> +<uni-number-box :min="0" :max="9"></uni-number-box> +<uni-number-box @change="bindChange"></uni-number-box> +``` + +**NumberBox 属性说明：** + +|属性名 |类型 |默认值 |说明 | +|--- |---- |--- |--- | +|value |Number |0|输入框当前值 | +|min |Number |-|最小值 | +|max |Number |-|最大值| +|step |Number |1|每次点击改变的间隔大小| +|disabled |Boolean|false |是否为禁用状态| +|@change |EventHandle| |输入框值改变时触发的事件，参数为输入框当前的 value | + + +### Popup 弹出层 + +在页面不同位置显示弹出层，组件名：``uni-popup``，代码块： uPopup。 + +**使用方式：** + +在 ``script`` 中引用组件 + +```javascript +import uniPopup from "@/components/uni-popup.vue" +export default { + components: {uniPopup} +} +``` + +在 ``template`` 中使用组件 + +```html +<uni-popup :show="true" type="middle" msg="popup 文字内容"></uni-popup> +``` + +**Popup 属性说明：** + +|属性名 |类型|默认值 |说明| +|---|----|---|---| +|show |Boolean|false|是否显示弹出层| +|type|String|middle|弹出层内容出现在页面的位置，可选值：top（顶部）， middle（居中）, bottom（底部）| +|msg |String ||弹出层文字内容| +|@hidePopup|EventHandle||点击遮罩时触发事件 | + +**Popup 插槽** + +开发者使用 Popup 时，支持向 Popup 里插入不同内容，以达到自定义的目的。 + +```html +<uni-popup :show="true" type="middle"> + <view>使用插槽</view> +</uni-popup> +``` + +### SegmentedControl 分段器 + +用作不同视图的显示，组件名：``uni-segmented-control``，代码块： uSegmentedControl。 + +**使用方式：** + +在 ``script`` 中引用组件 + +```javascript +import uniSegmentedControl from "@/components/uni-segmented-control.vue" +export default { + components: {uniSegmentedControl}, + data() { + return { + items: ['选项卡1','选项卡2','选项卡3'], + current: 0 + } + }, + methods: { + onClickItem(index) { + if (this.current !== index) { + this.current = index; + } + } + } +} +``` + +SegmentedControl 在 ``template`` 中的使用 + +```html +<template> + <view> + <uni-segmented-control :current="current" :values="items" @clickItem="onClickItem" style-type="button" active-color="#4cd964"></uni-segmented-control> + <view class="content"> + <view v-show="current === 0"> + 选项卡1的内容 + </view> + <view v-show="current === 1"> + 选项卡2的内容 + </view> + <view v-show="current === 2"> + 选项卡3的内容 + </view> + </view> + </view> +</template> +``` + +**SegmentedControl 属性说明：** + +|属性名 |类型|默认值 |说明| +|---|----|---|---| +|current |Number|0|当前选中的tab索引值，从0计数| +|values |Array<String>||选项数组| +|style-type |String |button|分段器样式类型，可选值：button（按钮类型），text（文字类型）| +|active-color|String |#007aff|选中的标签背景色与边框颜色| +|@clickItem|EventHandle||组件触发点击事件时触发，参数为当前选中的tab索引值 current | + + +### Tag 标签 + +用于展示1个或多个文字标签，可点击切换选中、不选中的状态，组件名：``uni-tag``，代码块： uTag。 + +**使用方式：** + +在 ``script`` 中引用组件 + +```javascript +import uniTag from "@/components/uni-tag.vue" +export default { + components: {uniTag} +} +``` + +在 ``template`` 中使用组件 + +```html +<uni-tag text="标签"></uni-tag> +<uni-tag text="标签" type="danger" :circle="true"></uni-tag> +<uni-tag text="标签" @click="bindClick"></uni-tag> +``` + +**Tag 属性说明：** + +|属性名 |类型 |默认值 |说明 | +|--- |---- |--- |--- | +|text |String |- |标签内容 | +|size |String |normal|大小尺寸，可选值：normal、small | +|type |String |default|颜色类型，可选值：default（灰色）、primary（蓝色）、success（绿色）、warning(黄色)、danger(红色)、royal(紫色) | +|disabled |Boolean|false |是否为禁用状态| +|inverted |Boolean|false |是否无需背景颜色（空心标签）| +|circle |Boolean|false |是否为圆角| +|@click |EventHandle| |点击 Tag 触发事件 | + + + + + diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000000000000000000000000000000000000..c74fbd8bcca710bc37e910d6995e886a2a6a4635 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,43 @@ +**uni-app 中可使用的 UI 框架：**[https://ask.dcloud.net.cn/article/35489](https://ask.dcloud.net.cn/article/35489) + +**uni-app 导航栏开发指南：** [https://ask.dcloud.net.cn/article/34921](https://ask.dcloud.net.cn/article/34921) + +**uni-app 实现全局变量：** [https://ask.dcloud.net.cn/article/35021](https://ask.dcloud.net.cn/article/35021) + +**uni-app 引用 npm 第三方库：** [https://ask.dcloud.net.cn/article/19727](https://ask.dcloud.net.cn/article/19727) + +**uni-app 中使用微信小程序第三方 SDK 及资源汇总：**[https://ask.dcloud.net.cn/article/35070](https://ask.dcloud.net.cn/article/35070) + +**原生控件层级过高无法覆盖的解决方案：**[https://uniapp.dcloud.io/component/native-component](https://uniapp.dcloud.io/component/native-component) + +**uni-app 各环节（HBuilderX、cli、自定义基座、本地sdk、云打包引擎）版本兼容性说明：**[https://ask.dcloud.net.cn/article/35845](https://ask.dcloud.net.cn/article/35845) + +**uni-app 中选择和上传非图像、视频文件：**[https://ask.dcloud.net.cn/article/35547](https://ask.dcloud.net.cn/article/35547) + +**国际化/多语言/i18n方案：**[https://ask.dcloud.net.cn/article/35872](https://ask.dcloud.net.cn/article/35872) + +**本地存储详解：**[https://ask.dcloud.net.cn/article/166](https://ask.dcloud.net.cn/article/166) + +## App常见问题 + +**uni-app App整包升级检测：** [https://ask.dcloud.net.cn/article/34972](https://ask.dcloud.net.cn/article/34972) + +**uni-app App资源热更新：** [https://ask.dcloud.net.cn/article/35667](https://ask.dcloud.net.cn/article/35667) + +**App初期启动的引导轮播：**因为是App专用，为了更好的性能，推荐使用nvue制作。也可以参考插件市场已经封装的插件[https://ext.dcloud.net.cn/plugin?id=192](https://ext.dcloud.net.cn/plugin?id=192) + +**App全面屏底部安全区适配：**[https://ask.dcloud.net.cn/article/35564](https://ask.dcloud.net.cn/article/35564) + +**App权限状态判断及引导：**[https://ext.dcloud.net.cn/plugin?id=594](https://ext.dcloud.net.cn/plugin?id=594) + +**uni-app 中使用 5+ 的原生界面控件（包括map、video、livepusher、barcode、nview）：**[https://ask.dcloud.net.cn/article/35036](https://ask.dcloud.net.cn/article/35036) + +**App分享到微信时分享为小程序：**[使用plus.share，设置分享类型为miniProgram](https://www.html5plus.org/doc/zh_cn/share.html#plus.share.WeixinMiniProgramOptions)。注意uni-app不需要plus ready，将plus ready里的代码写到页面的onLoad生命周期即可 + +**App启动微信小程序：**[使用plus.share的launchMiniProgram](https://www.html5plus.org/doc/zh_cn/share.html#plus.share.ShareService.launchMiniProgram)。注意uni-app不需要plus ready，将plus ready里的代码写到页面的onLoad生命周期即可 + +## H5常见问题 + +**uni-app 的 H5 版使用注意事项：**[https://ask.dcloud.net.cn/article/35232](https://ask.dcloud.net.cn/article/35232) + +**开发微信公众号（H5）JSSDK 的使用方式：**[https://ask.dcloud.net.cn/article/35380](https://ask.dcloud.net.cn/article/35380) diff --git a/docs/frame.md b/docs/frame.md new file mode 100644 index 0000000000000000000000000000000000000000..a45cb2cd12afa3486e276f6d0db8f767181b5e3e --- /dev/null +++ b/docs/frame.md @@ -0,0 +1,918 @@ + +```uni-app``` 使用vue的语法+小程序的标签和API。 + +## 开发规范 + +为了实现多端兼容，综合考虑编译速度、运行性能等因素，```uni-app``` 约定了如下开发规范： + +- 页面文件遵循 [Vue 单文件组件 (SFC) 规范](https://vue-loader.vuejs.org/zh/spec.html) +- 组件标签靠近小程序规范，详见[uni-app 组件规范](component/README.md) +- 接口能力（JS API）靠近微信小程序规范，但需将前缀 ```wx``` 替换为 ```uni```，详见[uni-app接口规范](api/README.md) +- 数据绑定及事件处理同 ```Vue.js``` 规范，同时补充了App及页面的生命周期 +- 为兼容多端运行，建议使用flex布局进行开发 + +## 目录结构 + +一个uni-app工程，默认包含如下目录及文件： + +<pre v-pre="" data-lang=""> + <code class="lang-" style="padding:0"> +┌─components uni-app组件目录 +│ └─comp-a.vue 可复用的a组件 +├─hybrid 存放本地网页的目录，<a href="/component/web-view">详见</a> +├─platforms 存放各平台专用页面的目录，<a href="/platform?id=%E6%95%B4%E4%BD%93%E7%9B%AE%E5%BD%95%E6%9D%A1%E4%BB%B6%E7%BC%96%E8%AF%91">详见</a> +├─pages 业务页面文件存放的目录 +│ ├─index +│ │ └─index.vue index页面 +│ └─list +│ └─list.vue list页面 +├─static 存放应用引用静态资源（如图片、视频等）的目录，<b>注意：</b>静态资源只能存放于此 +├─wxcomponents 存放小程序组件的目录，<a href="/frame?id=%E5%B0%8F%E7%A8%8B%E5%BA%8F%E7%BB%84%E4%BB%B6%E6%94%AF%E6%8C%81">详见</a> +├─main.js Vue初始化入口文件 +├─App.vue 应用配置，用来配置App全局样式以及监听 <a href="/frame?id=应用生命周期">应用生命周期</a> +├─manifest.json 配置应用名称、appid、logo、版本等打包信息，<a href="/collocation/manifest">详见</a> +└─pages.json 配置页面路由、导航条、选项卡等页面类信息，<a href="/collocation/pages">详见</a> + </code> +</pre> + +**Tips** + +- `static` 目录下的 `js` 文件不会被编译，如果里面有 `es6` 的代码，不经过转换直接运行，在手机设备上会报错。 +- `css`、`less/scss` 等资源同样不要放在 `static` 目录下，建议这些公用的资源放在 `common` 目录下。 +- HbuilderX 1.9.0+ 支持在根目录创建 `ext.json` `sitemap.json` 文件。 + +|有效目录|说明| +|:-:|:-:| +|app-plus|5+App| +|h5|H5| +|mp-weixin|微信小程序| +|mp-alipay|支付宝小程序| +|mp-baidu|百度小程序| + +## 生命周期 + + +### 应用生命周期 + +``uni-app`` 支持如下应用生命周期函数： + +|函数名|说明| +|:-|:-| +|onLaunch|当``uni-app`` 初始化完成时触发（全局只触发一次）| +|onShow|当 ``uni-app`` 启动，或从后台进入前台显示| +|onHide|当 ``uni-app`` 从前台进入后台| +|onUniNViewMessage|对 ``nvue`` 页面发送的数据进行监听，可参考 [nvue 向 vue 通讯](/use-weex?id=nvue-向-vue-通讯)| + +**注意** + +- 应用生命周期仅可在``App.vue``中监听，在其它页面监听无效。 +- onlaunch里进行页面跳转，如遇白屏报错，请参考[https://ask.dcloud.net.cn/article/35942](https://ask.dcloud.net.cn/article/35942) + +### 页面生命周期 + +``uni-app`` 支持如下页面生命周期函数： + +|函数名|说明|平台差异说明|最低版本| +|:-|:-|:-|:-| +|onLoad|监听页面加载，其参数为上个页面传递的数据，参数类型为Object（用于页面传参），参考[示例](/api/router?id=navigateto)||| +|onShow|监听页面显示。页面每次出现在屏幕上都触发，包括从下级页面点返回露出当前页面||| +|onReady|监听页面初次渲染完成。注意如果渲染速度快，会在页面进入动画完成前触发||| +|onHide|监听页面隐藏||| +|onUnload|监听页面卸载||| +|onResize|监听窗口尺寸变化|5+App、微信小程序|| +|onPullDownRefresh|监听用户下拉动作，一般用于下拉刷新，参考[示例](api/ui/pulldown)||| +|onReachBottom|页面上拉触底事件的处理函数||| +|onTabItemTap|点击 tab 时触发，参数为Object，具体见下方注意事项|微信小程序、百度小程序、H5、5+App（自定义组件模式）|| +|onShareAppMessage|用户点击右上角分享|微信小程序、百度小程序、头条小程序、支付宝小程序|| +|onPageScroll|监听页面滚动，参数为Object||| +|onNavigationBarButtonTap|监听原生标题栏按钮点击事件，参数为Object|5+ App、H5|| +|onBackPress|监听页面返回，返回 event = {from:backbutton、 navigateBack} ，backbutton 表示来源是左上角返回按钮或 android 返回键；navigateBack表示来源是 uni.navigateBack ；详细说明及使用：[onBackPress 详解](http://ask.dcloud.net.cn/article/35120)|5+App、H5|| +|onNavigationBarSearchInputChanged|监听原生标题栏搜索输入框输入内容变化事件|5+App、H5|1.6.0| +|onNavigationBarSearchInputConfirmed|监听原生标题栏搜索输入框搜索事件，用户点击软键盘上的“搜索”按钮时触发。|5+App、H5|1.6.0| +|onNavigationBarSearchInputClicked|监听原生标题栏搜索输入框点击事件|5+App、H5|1.6.0| + +``onPageScroll`` 参数说明： + +|属性|类型|说明| +|---|---|---| +|scrollTop|Number|页面在垂直方向已滚动的距离（单位px）| + +``onTabItemTap`` 参数说明： + +|属性|类型|说明| +|---|---|---| +|index|String|被点击tabItem的序号，从0开始| +|pagePath|String|被点击tabItem的页面路径| +|text|String|被点击tabItem的按钮文字| + +**注意** +- onTabItemTap常用于点击当前tabitem，滚动或刷新当前页面。如果是点击不同的tabitem，一定会触发页面切换。 +- 如果想在App端实现点击某个tabitem不跳转页面，不能使用onTabItemTap，可以使用[plus.nativeObj.view](http://www.html5plus.org/doc/zh_cn/nativeobj.html)放一个区块盖住原先的tabitem，并拦截点击事件。 +- onTabItemTap在App端，从HBuilderX 1.9 的自定义组件编译模式开始支持。 + +``onNavigationBarButtonTap`` 参数说明： + +|属性|类型|说明| +|---|---|---| +|index|Number|原生标题栏按钮数组的下标| + +`onBackPress` 回调参数对象说明： + +|属性|类型|说明| +|---|---|---| +|from|String|触发返回行为的来源：'backbutton'——左上角导航栏按钮及安卓返回键；'navigateBack'——uni.navigateBack() 方法。| +```javascript +export default { + data() { + return {}; + }, + onBackPress(options) { + console.log('from:' + options.from) + } +} +``` + +**注意** + +- nvue 页面支持的生命周期参考：[nvue 生命周期介绍](/use-weex?id=生命周期)。 + +## 路由 + +``uni-app``路由全部交给框架统一管理，开发者需要在[pages.json](/collocation/pages?id=pages)里配置每个路由页面的路径及页面样式，不支持 ``Vue Router``。 + +### 路由跳转 + +``uni-app`` 有两种路由跳转方式：使用[navigator](/component/navigator)组件跳转、调用[API](/api/router)跳转。 + +### 页面栈 + +框架以栈的形式管理当前所有页面， 当发生路由切换的时候，页面栈的表现如下： + +|路由方式 |页面栈表现 |触发时机 | +|--- |--- |--- | +|初始化 |新页面入栈 |uni-app 打开的第一个页面 | +|打开新页面 |新页面入栈 |调用 API [uni.navigateTo](/api/router?id=navigateto) 、使用组件 <a href="/component/navigator?id=navigator"><navigator open-type="navigate"/></a> | +|页面重定向 |当前页面出栈，新页面入栈 |调用 API [uni.redirectTo](/api/router?id=redirectto) 、使用组件 <a href="/component/navigator?id=navigator"><navigator open-type="redirectTo"/></a> | +|页面返回 |页面不断出栈，直到目标返回页 |调用 API [uni.navigateBack](/api/router?id=navigateback) 、使用组件 <a href="/component/navigator?id=navigator"><navigator open-type="navigateBack"/></a> 、用户按左上角返回按钮、安卓用户点击物理back按键 | +|Tab 切换 |页面全部出栈，只留下新的 Tab 页面 |调用 API [uni.switchTab](/api/router?id=switchtab) 、使用组件 <a href="/component/navigator?id=navigator"><navigator open-type="switchTab"/></a> 、用户切换 Tab | +|重加载 |页面全部出栈，只留下新的页面 |调用 API [uni.reLaunch](/api/router?id=relaunch) 、使用组件 <a href="/component/navigator?id=navigator"><navigator open-type="reLaunch"/></a> | + +## 运行环境判断 + +### 开发环境和生产环境 +``uni-app`` 可通过 ``process.env.NODE_ENV`` 判断当前环境是开发环境还是生产环境。一般用于连接测试服务器或生产服务器的动态切换。 +- 在HBuilderX 中，点击“运行”编译出来的代码是开发环境，点击“发行”编译出来的代码是生产环境 +- cli模式下，是通行的编译环境处理方式。 + +```javascript +if(process.env.NODE_ENV === 'development'){ + console.log('开发环境') +}else{ + console.log('生产环境') +} +``` + +**快捷代码块** + +HBuilderX 中敲入代码块 `uEnvDev`、`uEnvProd` 可以快速生成对应 `development`、`production` 的运行环境判定代码。 +```javascript +// uEnvDev +if (process.env.NODE_ENV === 'development') { + // TODO +} +// uEnvProd +if (process.env.NODE_ENV === 'production') { + // TODO +} +``` + +### 判断平台 + +平台判断有2种场景，一种是在编译期判断，一种是在运行期判断。 + +- 编译期判断 +编译期判断，即条件编译，不同平台在编译出包后已经是不同的代码。详见：[条件编译](/platform) + +```javascript +// #ifdef H5 + alert("只有h5平台才有alert方法") +// #endif +``` +如上代码只会编译到H5的发行包里，其他平台的包不会包含如上代码。 + +- 运行期判断 +运行期判断是指代码已经打入包中，仍然需要在运行期判断平台，此时可使用 ``uni.getSystemInfoSync().platform`` 判断客户端环境是 Android、iOS 还是小程序开发工具（在百度小程序开发工具、微信小程序开发工具、支付宝小程序开发工具中使用 ``uni.getSystemInfoSync().platform`` 返回值均为 devtools）。 + +```javascript +switch(uni.getSystemInfoSync().platform){ + case 'android': + console.log('运行Android上') + break; + case 'ios': + console.log('运行iOS上') + break; + default: + console.log('运行在开发者工具上') + break; +} +``` + +如有必要，也可以在条件编译里自己定义一个变量，赋不同值。在后续运行代码中动态判断环境。 + + +## 页面样式与布局 + +### 尺寸单位 + +`uni-app` 支持的通用 css 单位包括 px、rpx + +- px 即屏幕像素 +- rpx 即响应式px，一种根据屏幕宽度自适应的动态单位。以750宽的屏幕为基准，750rpx恰好为屏幕宽度。屏幕变宽，rpx 实际显示效果会等比放大。 + +vue页面支持普通H5单位，但在nvue里不支持： +- rem 默认根字体大小为 屏幕宽度/20（微信小程序、头条小程序、App、H5）<span style="display:none">百度小程序16px、支付宝小程序50px</span> +- vh viewpoint height，视窗高度，1vh等于视窗高度的1% +- vw viewpoint width，视窗宽度，1vw等于视窗宽度的1% + +nvue还不支持百分比单位。 + +App端，在 pages.json 里的 titleNView 或页面里写的 plus api 中涉及的单位，只支持 px。**注意此时不支持 rpx** + +nvue中，uni-app 模式（[nvue 不同编译模式介绍](https://ask.dcloud.net.cn/article/36074)）可以使用 px 、rpx，表现与 vue 中一致。weex 模式目前遵循weex的单位，它的单位比较特殊： + +- px:，以750宽的屏幕为基准动态计算的长度单位，与 vue 页面中的 rpx 理念相同。（一定要注意 weex 模式的 px，和 vue 里的 px 逻辑不一样。） +- wx：与设备屏幕宽度无关的长度单位，与 vue 页面中的 px 理念相同 + + +下面对 `rpx` 详细说明： + +设计师在提供设计图时，一般只提供一个分辨率的图。 + +严格按设计图标注的 px 做开发，在不同宽度的手机上界面很容易变形。 + +而且主要是宽度变形。高度一般因为有滚动条，不容易出问题。由此，引发了较强的动态宽度单位需求。 + +微信小程序设计了 rpx 解决这个问题，`uni-app` 在 App 端、H5 端都支持了 `rpx`。 + +rpx 是相对于基准宽度的单位，可以根据屏幕宽度进行自适应。```uni-app``` 规定屏幕基准宽度 750rpx。 + +开发者可以通过设计稿基准宽度计算页面元素 rpx 值，设计稿 1px 与框架样式 1rpx 转换公式如下： + +```设计稿 1px / 设计稿基准宽度 = 框架样式 1rpx / 750rpx``` + +换言之，页面元素宽度在 `uni-app` 中的宽度计算公式： + +``` 750 * 元素在设计稿中的宽度 / 设计稿基准宽度 ``` + +**举例说明：** + +1. 若设计稿宽度为 750px，元素 A 在设计稿上的宽度为 100px，那么元素 A 在 `uni-app` 里面的宽度应该设为：`750 * 100 / 750`，结果为：100rpx。 +2. 若设计稿宽度为 640px，元素 A 在设计稿上的宽度为 100px，那么元素 A 在 `uni-app` 里面的宽度应该设为：`750 * 100 / 640`，结果为：117rpx。 +2. 若设计稿宽度为 375px，元素 B 在设计稿上的宽度为 200px，那么元素 B 在 `uni-app` 里面的宽度应该设为：` 750 * 200 / 375`，结果为：400rpx。 + +**Tips** + +- 注意 rpx 是和宽度相关的单位，屏幕越宽，该值实际像素越大。如不想根据屏幕宽度缩放，则应该使用 px 单位。 +- 如果开发者在字体或高度中也使用了 rpx ，那么需注意这样的写法意味着随着屏幕变宽，字体会变大、高度会变大。如果你需要固定高度，则应该使用 px 。 +- rpx不支持动态横竖屏切换计算，使用rpx建议锁定屏幕方向 +- 设计师可以用 iPhone6 作为视觉稿的标准。 +- 如果设计稿不是750px，HBuilderX提供了自动换算的工具，详见：[https://ask.dcloud.net.cn/article/35445](https://ask.dcloud.net.cn/article/35445)。 +- App端，在 pages.json 里的 titleNView 或页面里写的 plus api 中涉及的单位，只支持 px，不支持 rpx。 +- 早期 uni-app 提供了 upx ，目前已经推荐统一改为 rpx 了，[详见](http://ask.dcloud.net.cn/article/36130) + +### 样式导入 + +使用```@import```语句可以导入外联样式表，```@import```后跟需要导入的外联样式表的相对路径，用```;```表示语句结束。 + +**示例代码：** + +``` +<style> + @import "../../common/uni.css"; + + .uni-card { + box-shadow: none; + } +</style> +``` + +### 内联样式 + +框架组件上支持使用 style、class 属性来控制组件的样式。 + +- style：静态的样式统一写到 class 中。style 接收动态的样式，在运行时会进行解析，请尽量避免将静态的样式写进 style 中，以免影响渲染速度。 +``` +<view :style="{color:color}" /> +``` +- class：用于指定样式规则，其属性值是样式规则中类选择器名(样式类名)的集合，样式类名不需要带上.，样式类名之间用空格分隔。 +``` +<view class="normal_view" /> +``` + +### 选择器 + +目前支持的选择器有： + +|选择器|样例|样例描述| +|:-|:-|:-| +|.class|.intro|选择所有拥有 class="intro" 的组件| +|#id|#firstname|选择拥有 id="firstname" 的组件| +|element|view|选择所有 view 组件| +|element, element|view, checkbox|选择所有文档的 view 组件和所有的 checkbox 组件| +|::after|view::after|在 view 组件后边插入内容，**仅微信小程序和5+App生效**| +|::before|view::before|在 view 组件前边插入内容，**仅微信小程序和5+App生效**| + +**注意：** +- 在 ```uni-app``` 中不能使用 ```*``` 选择器。 +- ```page``` 相当于 ```body``` 节点，例如： +```css +<!-- 设置页面背景颜色 --> +page { + background-color:#ccc; +} +``` + + +### 全局样式与局部样式 +定义在 App.vue 中的样式为全局样式，作用于每一个页面。在 pages 目录下 的 vue 文件中定义的样式为局部样式，只作用在对应的页面，并会覆盖 App.vue 中相同的选择器。 + +**注意：** App.vue 中通过 ``@import`` 语句可以导入外联样式，一样作用于每一个页面。 + +### CSS变量 + +uni-app 提供内置 CSS 变量 + +|CSS变量|描述|5+App|小程序|H5| +|:-|:-|:-|:-|:-| +|--status-bar-height|系统状态栏高度|[系统状态栏高度](http://www.html5plus.org/doc/zh_cn/navigator.html#plus.navigator.getStatusbarHeight)|25px|0| +|--window-top|内容区域距离顶部的距离|0|0|NavigationBar 的高度| +|--window-bottom|内容区域距离底部的距离|0|0|TabBar 的高度| + + +**注意：** +- ``var(--status-bar-height)`` 此变量在微信小程序环境为固定 ``25px``，在 5+App 里为手机实际状态栏高度。 +- 当设置 ``"navigationStyle":"custom"`` 取消原生导航栏后，由于窗体为沉浸式，占据了状态栏位置。此时可以使用一个高度为 ``var(--status-bar-height)`` 的 view 放在页面顶部，避免页面内容出现在状态栏。 +- 由于在H5端，不存在原生导航栏和tabbar，也是前端div模拟。如果设置了一个固定位置的居底view，在小程序和App端是在tabbar上方，但在H5端会与tabbar重叠。此时可使用`--window-bottom`，不管在哪个端，都是固定在tabbar上方。 +- 目前 nvue 还不支持css变量 + +**代码块** + +快速书写css变量的方法是：在css中敲hei，在候选助手中即可看到3个css变量。（HBuilderX 1.9.6以上支持） + + +示例： + +```html +<template> + <view> + <view class="status_bar"> + <!-- 这里是状态栏 --> + </view> + <view> 状态栏下的文字 </view> + </view> +</template> +<style> + .status_bar { + height: var(--status-bar-height); + width: 100%; + } +</style> +``` + +```html +<template> + <view> + <view class="toTop"> + <!-- 这里可以放一个向上箭头，它距离底部tabbar上浮10px--> + </view> + </view> +</template> +<style> + .toTop { + bottom: calc(var(--window-bottom) + 10px) + } +</style> +``` + +### 固定值 +`uni-app` 中以下组件的高度是固定的，不可修改： + +|组件|描述|5+App|H5| +|:-|:-|:-|:-| +|NavigationBar|导航栏|44px|44px| +|TabBar|底部选项卡|56px|50px| + +### Flex布局 + +为支持跨平台，框架建议使用Flex布局，关于Flex布局可以参考外部文档[A Complete Guide to Flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/)、[阮一峰的flex教程](http://www.ruanyifeng.com/blog/2015/07/flex-grammar.html)等。 + +### 背景图片 + +``uni-app`` 支持使用在 css 里设置背景图片，使用方式与普通 ``web`` 项目相同，需要注意以下几点： + +- 支持 base64 格式图片。 +- 支持网络路径图片。 +- 使用本地路径背景图片需注意： + 1. 图片小于 40kb，``uni-app`` 会自动将其转化为 base64 格式； + 2. 图片大于等于 40kb， 需开发者自己将其转换为base64格式使用，或将其挪到服务器上，从网络地址引用。 + 3. 本地背景图片的引用路径仅支持以 ~@ 开头的绝对路径（不支持相对路径）。 + ```css + .test2 { + background-image: url('~@/static/logo.png'); + } + ``` + +### 字体图标 + +``uni-app`` 支持使用字体图标，使用方式与普通 ``web`` 项目相同，需要注意以下几点： + +- 支持 base64 格式字体图标。 +- 支持网络路径字体图标。 +- 网络路径必须加协议头 ``https``。 +- 从 [http://www.iconfont.cn](http://www.iconfont.cn) 上拷贝的代码，默认是没加协议头的。 +- ``uni-app`` 本地路径图标字体支持情况： + 1. 字体文件小于 40kb，``uni-app`` 会自动将其转化为 base64 格式； + 2. 字体文件大于等于 40kb， 需开发者自己转换，否则使用将不生效； + 3. 字体文件的引用路径仅支持以 ~@ 开头的绝对路径（不支持相对路径）。 + ```css + @font-face { + font-family: test1-icon; + src: url('~@/static/iconfont.ttf'); + } + ``` + + +**示例：** + +```html +<template> + <view> + <view> + <text class="test"></text> + <text class="test"></text> + <text class="test"></text> + </view> + </view> +</template> +<style> + @font-face { + font-family: 'iconfont'; + src: url('https://at.alicdn.com/t/font_865816_17gjspmmrkti.ttf') format('truetype'); + } + .test { + font-family: iconfont; + margin-left: 20rpx; + } +</style> +``` + +## ``<template/>`` 和 ``<block/>`` @template-block + +``uni-app`` 支持在 template 模板中嵌套 ``<template/>`` 和 ``<block/>``，用来进行 [列表渲染](/use?id=列表渲染) 和 [条件渲染](/use?id=条件渲染)。 + + ``<template/>`` 和 ``<block/>`` 并不是一个组件，它们仅仅是一个包装元素，不会在页面中做任何渲染，只接受控制属性。 + +**代码示例** + +```html +<template> + <view> + <template v-if="test"> + <view>test 为 true 时显示</view> + </template> + <template v-else> + <view>test 为 false 时显示</view> + </template> + </view> +</template> +``` + +```html +<template> + <view> + <block v-for="(item,index) in list" :key="index"> + <view>{{item}} - {{index}}</view> + </block> + </view> +</template> +``` + +## ES6 支持 +uni-app 在支持绝大部分 ES6 API 的同时，也支持了 ES7 的 await/async。 + +ES6 API 的支持，详见如下表格部分（`x` 表示不支持，无特殊说明则表示支持。不区分App、小程序、H5）： + +|String|iOS8|iOS9|iOS10|Android| +|:-|:-|:-|:-|:-| +|codePointAt||||| +|normalize|x|x||| +|includes||||| +|startsWith||||| +|endsWith||||| +|repeat||||| +|String.fromCodePoint|||| | + +|Array|iOS8|iOS9|iOS10|Android| +|:-|:-|:-|:-|:-| +|copyWithin||||| +|find||||| +|findIndex||||| +|fill||||| +|entries||||| +|keys||||| +|values|x|||x| +|includes|x|||| +|Array.from||||| +|Array.of|||| | + +|Number|iOS8|iOS9|iOS10|Android| +|:-|:-|:-|:-|:-| +|isFinite||||| +|isNaN||||| +|parseInt||||| +|parseFloat||||| +|isInteger||||| +|EPSILON||||| +|isSafeInteger|||| | + +|Math|iOS8|iOS9|iOS10|Android| +|:-|:-|:-|:-|:-| +|trunc||||| +|sign||||| +|cbrt||||| +|clz32||||| +|imul||||| +|fround||||| +|hypot||||| +|expm1||||| +|log1p||||| +|log10||||| +|log2||||| +|sinh||||| +|cosh||||| +|tanh||||| +|asinh||||| +|acosh||||| +|atanh|||| | + +|Object|iOS8|iOS9|iOS10|Android| +|:-|:-|:-|:-|:-| +|is||||| +|assign||||| +|getOwnPropertyDescriptor||||| +|keys||||| +|getOwnPropertyNames||||| +|getOwnPropertySymbols|||| | + +|Other|iOS8|iOS9|iOS10|Android| +|:-|:-|:-|:-|:-| +|Symbol||||| +|Set||||| +|Map||||| +|Proxy|x|x||x| +|Reflect||||| +|Promise|||| | + +**注意** +- 不管哪个端都是这个数据，即便是Android4.4。因为uni-app编译器把es6语法自动转es5了。低版本Android的兼容性主要是css，太新的css语法在低版本不支持，js语法不受影响。 +- 默认不需要在微信工具里继续开启es6转换。但如果用了微信的wxml自定义组件（wxcomponents目录下），uni-app编译器并不会处理这些文件中的es6代码，需要去微信工具里开启转换。从HBuilderX调起微信工具时，如果发现工程下有wxcomponents目录会自动配置微信工程打开es6转换。 + + +## NPM支持 + +uni-app支持使用**npm**安装第三方包。 + +此文档要求开发者们对**npm**有一定的了解，因此不会再去介绍**npm**的基本功能。如若之前未接触过**npm**，请翻阅[NPM官方文档](https://docs.npmjs.com/getting-started/what-is-npm)进行学习。 + +**初始化npm工程** + +若项目之前未使用npm管理依赖（项目根目录下无package.json文件），先在项目根目录执行命令初始化npm工程： +```shell +npm init -y +``` + +**安装依赖** + +在项目根目录执行命令安装npm包： +```shell +npm install packageName --save +``` + +**使用** + +安装完即可使用npm包，js中引入npm包： +```js +import package from 'packageName' +const package = require('packageName') +``` + +**注意** + +* 为多端兼容考虑，建议优先从 [uni-app插件市场](https://ext.dcloud.net.cn/) 获取插件。直接从 npm 下载库很容易只兼容H5端。 +* 非 H5 端不支持使用含有 dom、window 等操作的 vue 组件和 js 模块，安装的模块及其依赖的模块使用的 API 必须是 uni-app 已有的 [API](./api/README)（兼容小程序 API），比如：支持[高德地图微信小程序 SDK](https://www.npmjs.com/package/amap-wx)。类似[jQuery](https://www.npmjs.com/package/jquery) 等库只能用于H5端。 +* node_modules 目录必须在项目根目录下。 +* 支持安装 mpvue 组件，但npm方式不支持小程序自定义组件（如 wxml格式的vant-weapp），使用小程序自定义组件请参考：[小程序组件支持](./frame?id=%E5%B0%8F%E7%A8%8B%E5%BA%8F%E7%BB%84%E4%BB%B6%E6%94%AF%E6%8C%81)。 +* 关于ui库的获取，详见[多端UI库](https://ask.dcloud.net.cn/article/35489) + +## TypeScript 支持 +在 uni-app 中使用 ts 开发，请参考 [Vue.js TypeScript 支持](https://cn.vuejs.org/v2/guide/typescript.html) 说明。 + +### 注意事项 +在 uni-app 中使用 ts 需要注意以下事项。 +#### 在 vue 文件的 script 节点声明 lang="ts"@vue-ts +声明 `lang="ts"` 后，该 vue 文件 import 进来的所有 vue 组件，均需要使用 ts 编写。 + +**示例代码** + +改造 uni-badge.vue +```javascript +<script lang="ts"> + // 仅展示需要修改的核心代码，完整代码请参考原来的组件。 + import Vue from 'vue'; + export default Vue.extend({ + props: { + type: { + type: String, + default: 'default' + }, + inverted: { + type: Boolean, + default: false + }, + text: { + type: [String, Number], + default: '' + }, + size: { + type: String, + default: 'normal' + } + }, + computed: { + setClass(): string { + const classList: string[] = ['uni-badge-' + this.type, 'uni-badge-size-' + this.size]; + if (this.inverted === true) { + classList.push('uni-badge-inverted') + } + return classList.join(" ") + } + }, + methods: { + onClick() { + this.$emit('click') + } + } + }) +</script> +``` +在 index.vue 中引用 uni-badge 组件 +```javascript +<script lang="ts"> + import Vue from 'vue'; + import uniBadge from '../../components/uni-badge.vue'; + export default Vue.extend({ + data() { + return { + title: 'Hello' + } + }, + components:{ + uniBadge + } + }); +</script> +``` +## 小程序组件支持 + +``uni-app`` 支持在 5+App 和小程序中使用**小程序组件**。 + +**平台差异说明** + +|平台|支持情况|小程序组件存放目录| +|---|---|---| +|H5|不支持|| +|5+App|支持微信小程序组件|wxcomponents| +|微信小程序|支持微信小程序组件|wxcomponents| +|支付宝小程序|支持支付宝小程序组件|mycomponents| +|百度小程序|支持百度小程序组件|swancomponents| +|头条小程序|支持头条小程序组件|ttcomponents| + +此文档要求开发者对各端小程序的**自定义组件**有一定了解，没接触过小程序**自定义组件**的可以参考： + +- [微信小程序自定义组件](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/) +- [百度小程序自定义组件](https://smartprogram.baidu.com/docs/develop/framework/custom-component/) +- [支付宝小程序自定义组件](https://docs.alipay.com/mini/framework/custom-component-overview) +- [头条小程序自定义组件](https://developer.toutiao.com/docs/framework/custom_component_intro.html) + +**目录结构** + +<pre v-pre="" data-lang=""> + <code class="lang-" style="padding:0"> +┌─wxcomponents 微信小程序自定义组件存放目录 +│ └──custom 微信小程序自定义组件 +│ ├─index.js +│ ├─index.wxml +│ ├─index.json +│ └─index.wxss +├─mycomponents 支付宝小程序自定义组件存放目录 +│ └──custom 支付宝小程序自定义组件 +│ ├─index.js +│ ├─index.axml +│ ├─index.json +│ └─index.wxss +├─swancomponents 百度小程序自定义组件存放目录 +│ └──custom 百度小程序自定义组件 +│ ├─index.js +│ ├─index.swan +│ ├─index.json +│ └─index.wxss +├─pages +│ └─index +│ └─index.vue +│ +├─static +├─main.js +├─App.vue +├─manifest.json +└─pages.json + </code> +</pre> + +**使用方式** + +在 ``pages.json`` 对应页面的 style -> usingComponents 引入组件： + +```javascript +{ + "pages": [ + { + "path": "index/index", + "style": { + "usingComponents": { + // #ifdef APP-PLUS || MP-WEIXIN + "custom": "/wxcomponents/custom/index" + // #endif + // #ifdef MP-BAIDU + "custom": "/swancomponents/custom/index" + // #endif + // #ifdef MP-ALIPAY + "custom": "/mycomponents/custom/index" + // #endif + } + } + } + ] +} +``` + +在页面中使用 + +```html +<!-- 页面模板 (index.vue) --> +<view> + <!-- 在页面中对自定义组件进行引用 --> + <custom name="uni-app"></custom> +</view> +``` + +**代码示例** + +下面以微信小程序官方自定义组件示例 [miniprogram-slide-view](https://github.com/wechat-miniprogram/slide-view) 为例演示小程序自定义组件的使用方式。 +其他组件使用示例见GitHub：[wxcomponents-template](https://github.com/dcloudio/uni-app/tree/master/examples/wxcomponents-template)。 +插件市场有一个完整的``vant weapp`` 引用好的示例工程，详见[https://ext.dcloud.net.cn/plugin?id=302](https://ext.dcloud.net.cn/plugin?id=302)。 + +目录结构 +<pre v-pre="" data-lang=""> + <code class="lang-" style="padding:0"> +┌─components +├─wxcomponents +│ └──miniprogram-slide-view +│ ├─index.js +│ ├─index.wxml +│ ├─index.json +│ └─index.wxss +│ +├─pages +│ └─slide-view +│ └─slide-view.vue +│ +├─static +├─main.js +├─App.vue +├─manifest.json +└─pages.json + </code> +</pre> +pages.json +```json +{ + "pages": [ + { + "path": "slide-view/slide-view", + "style": { + "navigationBarTitleText": "slide-view", + "usingComponents": { + "slide-view": "/wxcomponents/miniprogram-slide-view/index" + } + } + } + ] +} +``` +slide-view.vue +```html +<template> + <view class='slide'> + <slide-view width="750" height="110" slide-width="500"> + <view slot="left" class="l"> + <image src="/static/file_transfer.jpg" class="img"></image> + <view class='text'> + <view class='title'>文件传输助手</view> + <view class='time'>7:00 PM</view> + </view> + </view> + <view slot="right" class="r"> + <view class='read'>标为已读</view> + <view class='delete'>删除</view> + </view> + </slide-view> + </view> +</template> +<script> + export default {} +</script> +<style> + .slide { + border-bottom: 1px solid #DEDEDE; + } + .l { + background-color: white; + height: 110rpx; + width: 750rpx; + display: flex; + flex-direction: row; + } + .r { + height: 110rpx; + display: flex; + direction: row; + text-align: center; + vertical-align: middle; + line-height: 110rpx; + } + .read { + background-color: #ccc; + color: #fff; + width: 350rpx; + } + .delete { + background-color: red; + color: #fff; + width: 150rpx; + } + .img { + width: 90rpx; + height: 90rpx; + border-radius: 10rpx; + margin: 10rpx 15rpx; + } + .text { + display: flex; + flex-direction: row; + } + + .title { + margin-top: 15rpx; + font-size: 33rpx; + } + .time { + margin-top: 15rpx; + color: #ccc; + font-size: 25rpx; + margin-left: 330rpx; + } +</style> +``` + +**注意事项** + +* 小程序组件需要放在项目特殊文件夹 ``wxcomponents``（或 mycomponents、swancomponents）。 +* HBuilderX 建立的工程 ``wxcomponents`` 文件夹在 项目根目录下。 +* vue-cli 建立的工程 ``wxcomponents`` 文件夹在 ``src`` 目录下。 +* 注意数据和事件绑定的差异，使用时应按照 vue 的数据和事件绑定方式 + - 属性绑定从 attr="{{ a }}"，改为 :attr="a"；从 title="复选框{{ item }}" 改为 :title="'复选框' + item" + - 事件绑定从 bind:click="toggleActionSheet1" 改为 @click="toggleActionSheet1" + - 阻止事件冒泡 从 catch:tap="xx" 改为 @tap.native.stop="xx" + - wx:if 改为 v-if + - wx:for="{{ list }}" wx:key="{{ index }}" 改为`v-for="(item,index) in list" + - 原事件命名以短横线分隔的需要手动修改小程序组件源码为驼峰命名，比如：*this.$emit('left-click')* 修改为 *this.$emit('leftClick')*（HBuilderX 1.9.0+ 不再需要修改此项） + +详细的小程序转uni-app语法差异可参考文档[https://ask.dcloud.net.cn/article/35786](https://ask.dcloud.net.cn/article/35786)。 + +## 致谢 + +```uni-app```的设计使用了 ```vue + 自定义组件``` 的模式；开发者使用```Vue```语法，了解```uni-app```的组件，就可以开发跨端App；感谢```Vue```团队！ + +为了照顾开发者的已有学习积累，```uni-app```的组件和api设计，基本参考了微信小程序，学过微信小程序开发，了解```vue```，就能直接上手```uni-app```；感谢微信小程序团队！ + +```uni-app``` 在小程序端，曾引用[mpvue](http://mpvue.com/)及[Megalo](https://megalojs.org/)，感谢美团点评技术团队、网易考拉团队的贡献! \ No newline at end of file diff --git a/docs/matter.md b/docs/matter.md new file mode 100644 index 0000000000000000000000000000000000000000..afa227f9a636a6611929f9545cf48757009ff4f0 --- /dev/null +++ b/docs/matter.md @@ -0,0 +1,189 @@ +### H5正常但App异常的可能性 +1. css异常： +- 不支持的选择器 +非H5端不支持*选择器； + +body的元素选择器请改为page，同样，div和ul和li等改为view、span和font改为text、a改为navigator、img改为image... + +- webview浏览器兼容性 + +vue页面在App端是被系统的webview渲染的（不是手机自带浏览器，是rom的webview），在较老的手机上，比如Android4.4、5.0或iOS8，很多css是不支持的，所以不要使用太新的css，会导致界面异常。 + +注意这不意味着不能使用flex，Android4.4也支持flex，只是不要使用太新的css。 + +可以找Android4.4手机或使用pc模拟器实际测试下，大多数国产Android模拟器都是4.4或5.0。 + +小程序不存在此情况。所以如果你的H5和小程序界面正常，而App界面异常，大多是因为css兼容性。解决这类问题，可以在caniuse查询，也可以使用一个较低版本的chrome浏览器在H5端测试。 + +Android4.4对应的webview是chrome37，如找不到老版chrome，也可以下载老版HBuilder（在HBuilderX下载页面底部有“上一代HBuilder下载”），在老HBuilder的右上角边改边看模式里是chrome37内核，可以把uni-app的H5版运行起来，将url粘贴到边改边看的浏览器中，点右键可以审查元素，排查不支持的css。 + +- 原生组件层级问题 +H5没有原生组件概念问题，非H5端有原生组件并引发了原生组件层级高于前端组件的概念，要遮挡video、map等原生组件，请使用cover-view组件。 + +2. 使用了非H5端不支持的API，比如document、xmlhttp、cookie、window、location、navigator、localstorage、websql、indexdb、webgl等对象。如果你的代码没有直接使用这些，那很可能是引入的三方库使用了这些。如果是后者，去[插件市场](https://ext.dcloud.net.cn/)搜索替代方案。要知道非H5端的js是运行在一个独立的js core或v8下，并不是运行在浏览器里。 +3. 使用了非H5端不支持的vue语法，比如v-html指令、受小程序自定义组件限制的写法，[详见](/use) +4. 不要在引用组件的地方在组件属性上直接写 style="xx"，要在组件内部写样式 +5. `url(//alicdn.net)`等路径，改为`url(https://alicdn.net)`，因为在App端//是file协议 +6. 很多人在H5端联网时使用本地测试服务地址(localhost或127.0.0.1)，这样的联网地址手机端必然无法访问，请使用手机可访问的IP进行联网 + +### H5正常但小程序异常的可能性 +1. 同上 +2. 小程序要求连接的网址都要配白名单 + +### 小程序正常但App异常的可能性 +1. vue页面在App端是被系统的webview渲染的（不是手机自带浏览器，是rom的webview），在较老的手机上，比如Android4.4、5.0或iOS8，很多css是不支持的，所以不要使用太新的css，会导致界面异常。注意这不意味着不能使用flex，Android4.4也支持flex，只是不要使用太新的css。可以找Android4.4手机或使用pc模拟器实际测试下，大多数国产Android模拟器都是4.4或5.0。小程序不存在此情况。所以如果你的H5和小程序界面正常，而App界面异常，大多是因为css兼容性。解决这类问题，可以在caniuse查询，也可以使用一个较低版本的chrome浏览器在H5端测试。Android4.4对应的webview是chrome37，如找不到老版chrome，也可以下载老版HBuilder（在HBuilderX下载页面底部有“上一代HBuilder下载”），在老HBuilder的右上角边改边看模式里是chrome37内核，可以把uni-app的H5版运行起来，将url粘贴到边改边看的浏览器中，点右键可以审查元素，排查不支持的css。 + +### 小程序或App正常，但H5异常的可能性 +1. 使用了小程序原生组件，而没有使用vue标准的跨端组件。wxcomponets只有小程序和App才支持。 + +### App正常，小程序、H5异常的可能性 +1. 使用了App端特有的plus、Native.js、subNVue、原生插件等功能 + +### 使用 Vue.js 的注意 + +1. ```uni-app``` 基于```Vue 2.0```实现，开发者需注意Vue 1.0 -> 2.0 的使用差异，详见[从 Vue 1.x 迁移](https://cn.vuejs.org/v2/guide/migration.html) +2. data 属性必须声明为返回一个初始数据对象的函数；否则页面关闭时，数据不会自动销毁，再次打开该页面时，会显示上次数据 + + ```javascript + //正确用法，使用函数返回对象 + data() { + return { + title: 'Hello' + } + } + //错误写法，会导致再次打开页面时，显示上次数据 + data: { + title: 'Hello' + } + ``` +3. 在微信小程序端，```uni-app``` 将数据绑定功能委托给```Vue```，开发者需按```Vue 2.0```的写法实现数据绑定，不支持微信小程序的数据绑定写法，故如下写法不支持： + + ```javascript + <view id="item-{{id}}"></view> + ``` + 需修改为： + ```javascript + <view v-bind:id="'item-' + id "></view> + ``` + +### 区别于传统 web 开发的注意 +你之前可能习惯自由的web开发，但目前各家小程序都有很多限制。 +当然限制是为了在框架层更好的优化用户体验，所以小程序的体验要优于web。 +并且这些限制只是写法的限制，并不影响功能。 +如果你做过微信小程序开发，对这些限制应该已经很了解了。如果没有做过小程序，请仔细阅读本节。 +1. JS注意 + - 非H5端，不能使用浏览器自带对象，比如document、window、localstorage、cookie等，更不能使用jquery等依赖这些浏览器对象的框架。因为各家小程序快应用都不支持这些对象。 + - 没有这些浏览器自带对象并不影响业务开发，uni提供的api足够完成业务。 + - uni的api在编译到web平台运行时，其实也会转为浏览器的js api。 + - uni的api是多端可用的。在条件编译区，每个平台的专有api也可以使用，比如wx.、plus.等api可以分别在微信下和app下使用。 + - 出于降低小程序向uni-app迁移成本的考虑，wx的api在app里也可以直接运行，比如写wx.requst和uni.requst是一样的，但仍然建议仅在微信的条件编译区使用wx的api。 +2. Tag注意 + - uni-app的tag同小程序的tag，和HTML的tag不一样，比如div要改成view，span要改成text、a要改成navigator。 + - 出于降低h5应用向uni-app迁移成本的考虑，写成div、span也可以运行在app和小程序上，因为uni-app编译器会把这些HTML标签编译为小程序标签。但仍然建议养成新习惯。 +3. Css注意 + - 虽然大部分css样式在微信小程序和app中都可以支持，但推荐使用flex布局模型，这种布局更灵活高效且支持更多平台(比如nvue、快应用只支持flex布局) + - 单位方面，uni-app默认为rpx。这是一种可跨端的通用单位 [详见](/frame?id=%E5%B0%BA%E5%AF%B8%E5%8D%95%E4%BD%8D) +4. 工程目录注意 + - 每个要显示的页面，都要放到pages目录下，新建一个页面所在的目录，然后放同名目录的vue文件，比如project/pages/lista/lista.vue，并且在pages.json里配置。这与小程序的策略相同。 + - 自定义组件，放到component目录 + - 静态资源如图片，固定放到static目录下。这是webpack、mpvue的规则 +5. 数据绑定方式的注意 + - ```uni-app``` 基于```Vue 2.0```实现，开发者需注意Vue 1.0 -> 2.0 的使用差异，详见[从 Vue 1.x 迁移](https://cn.vuejs.org/v2/guide/migration.html) + - +6. 每个页面支持使用原生title，首页支持使用原生底部tab，这些是要在pages.json里配置，这些并不是vue页面的一部分。当然vue里的js api也可以动态修改原生title +6. 虽然使用vue，但在app和小程序里，不是spa而是mpa +7. 位置坐标系统一为国测局坐标系gcj02，这种坐标系可以被多端支持。老版5+的百度定位和百度地图使用的是百度私有坐标系bd09ll，这种坐标系需要转换。新版uni-app里的百度地图已经默认改为gcj02。高德地图不受影响，一直是gcj02 + +### H5 开发注意 + +* H5 发布到服务器注意： + 1. 配置发行后的路径（发行在网站根目录可不配置），比如发行网站路径是 www.xxx.com/html5，在 ``manifest.json`` 文件内编辑 h5 节点，router 下增加 base 属性为 html5 +<div> +<img src="https://img-cdn-qiniu.dcloud.net.cn/uploads/article/20181116/6ab94f68e109bb07e4f422c95a2c9015.png" width="500"> +</div> + 2. 点击菜单 发行-> H5 + 3. 在当下项目下的 ``unpackage/dist/build/h5`` 目录找到出的资源，部署服务器（或者使用本地服务器预览） + +* 引用第三方 js 的方式： + 1. 通过 npm 引入（通过条件编译，只有是 h5 平台是才 import 相应的库） + 2. 在 ``manifest.json`` 文件编辑 h5 节点的 template 属性，填写 html 模版路径，在 html 模版里面可以使用 script 的方式引入三方的 js，如下示例是加了百度统计的 html 模板部分代码，模版全部代码可参考：[自定义模板](/collocation/manifest?id=h5-template) +``` +... +<body> + <noscript> + <strong>Please enable JavaScript to continue.</strong> + </noscript> + <div id="app"></div> + <!-- built files will be auto injected --> + <script> + var _hmt = _hmt || []; + (function() { + var hm = document.createElement("script"); + hm.src = "https://hm.baidu.com/hm.js?xxxxxx"; + var s = document.getElementsByTagName("script")[0]; + s.parentNode.insertBefore(hm, s); + })(); + </script> +</body> +... +``` + +* 组件方面：支持 ``mpvue`` 组件、支持普通 ``vue`` 组件、不支持小程序自定义组件、不支持 ``nvue``。 + +* H5 版 ``uni-app`` 全支持 ``vue`` 语法，所以可能造成部分写法在 H5 端生效，在小程序或 App 端不生效。 + +* H5 校验了更严格的 ``vue`` 语法，有些写法不规范会报警，比如： ``data`` 后面写对象会报警，必须写 ``function``；不能修改 ``props`` 的值；组件最外层 ``template`` 节点下不允许包含多个节点等。 + +* 编译为 H5 版后生成的是单页应用（SPA）。 + +* 如果遇到了白屏或网络不给力的提示，一般是跨域问题，网络请求（request、uploadFile、downloadFile等）在浏览器存在跨域限制，需服务端配合才能跨域。解决方案有2种： + 1. 服务器打开跨域限制； + 2. 本地浏览器安装跨域插件，参考：[Chrome 跨域插件免翻墙安装](http://ask.dcloud.net.cn/article/35267) 或 [firefox跨域插件](https://addons.mozilla.org/zh-CN/firefox/addon/access-control-allow-origin/)。 + +* APP 和小程序的导航栏和 ``tabbar`` 均是原生控件，元素区域坐标是不包含原生导航栏和 ``tabbar`` 的；而 H5 里导航栏和 ``tabbar`` 是 div 模拟实现的，所以元素坐标会包含导航栏和tabbar的高度。为了优雅的解决多端高度定位问题，``uni-app`` 新增了2个css变量：``--window-top`` 和 ``--window-bottom``，这代表了页面的内容区域距离顶部和底部的距离。举个实例，如果你想在原生``tabbar`` 上方悬浮一个菜单，之前写 ``bottom:0``。这样的写法编译到 h5 后，这个菜单会和 ``tabbar`` 重叠，位于屏幕底部。而改为使用 ``bottom:var(--window-bottom)``，则不管在 app 下还是在h5下，这个菜单都是悬浮在 ``tabbar`` 上浮的。这就避免了写条件编译代码。当然仍然也可以使用 H5 的条件编译处理界面的不同。 + +* CSS 內使用 ``vh`` 单位的时候注意 ``100vh`` 包含导航栏，使用时需要减去导航栏和 ``tabBar`` 高度，部分浏览器还包含浏览器操作栏高度，使用时请注意。 + +* 正常支持 ``rpx``，``px`` 是真实物理像素。暂不支持通过设 ``manifest.json`` 的 ``"transformPx" : true``，把 px 当动态单位使用。 + +* 使用罗盘、地理位置、加速计等相关接口需要使用 https 协议，本地预览（localhost）可以使用 http 协议。 + +* PC 端 Chrome 浏览器模拟器设备测试的时候，获取位置 API 需要连接谷歌服务器。 + +* 组件内（页面除外）不支持 ``onLoad``、``onShow`` 等页面生命周期。 + +* 为避免和内置组件冲突，自定义组件请加上前缀（但不能是 u 和 uni）。比如可使用的自定义组件名称：``my-view``、``m-input``、``we-icon``，例如不可使用的自定义组件名称：``u-view``、``uni-input``，如果已有项目使用了可能造成冲突的名称，请修改名称，另外微信小程序下自定义组件名称不能以 wx 开头。 + + + +### 微信小程序开发注意 + +* [微信小程序当前bug列表](https://developers.weixin.qq.com/community/develop/issueList?type=%E4%BF%AE%E5%A4%8D%E4%B8%AD&block=bug) +* [微信小程序更新日志](https://developers.weixin.qq.com/miniprogram/dev/framework/release/) + +### 支付宝小程序开发注意 + +* [支付宝小程序更新日志](https://docs.alipay.com/mini/ide/framework-changelog) +* 支付宝小程序开发工具：[https://docs.alipay.com/mini/ide/download](https://docs.alipay.com/mini/ide/download) +* 目前无分包的配置，并且包体积限制在 3M。 +* showLoading 是不透传的，也就是说 loading 显示的时候无法点击页面内容。 +* 文件名或文件夹名中不允许出现 @ 符号。 +* 网络请求返回的数据会严格按照 ``dataType`` 进行处理，如果不符合规范则会抛出错误，而不是按照原格式返回。 +* ``canvas`` 组件的标识是 ``id``，而不是 ``canvas-id``。目前还未进行处理，所以需要主动添加 id 属性。 +* 目前测试的结果，导航栏只有设置背景颜色为 #FFF(FFF) 时才会变成黑色文字。 +* 支付宝小程序的导航栏是支持透明渐变效果的，后面会提供相关的配置。 +* 使用伪元素做边框时，高度值不能用 ``1rpx``，需要直接用 ``1px``。 +* 不支持 ECharts。 +* 支付功能模拟不了，需要真机测试。 + +### 百度小程序开发注意 + +* [百度小程序更新日志](https://smartprogram.baidu.com/docs/develop/swan/swanchangelog/) +* 百度小程序开发工具：[https://smartprogram.baidu.com/docs/introduction/tool/](https://smartprogram.baidu.com/docs/introduction/tool/)。 +* 不支持属性选择器。 +* 不支持 ``scoped``。 +* login / getUserInfo /支付等功能在模拟器（开发工具）上不能模拟。 +* ``map`` 组件在开发工具上预览效果不对，但是手机上是对的。 +* ``getSystemInfo`` 获取到的 ``windowHeight`` 在模拟器中值不正确，真机预览是正确的。 +* ``v-if`` 和 ``v-for`` 不可在同一标签下同时使用。 +* 页面中引入自定义组件时，渲染的结果中外层会有一个 ``template`` 标签，这会导致部分选择器对应的样式匹配不上。 \ No newline at end of file diff --git a/docs/performance.md b/docs/performance.md new file mode 100644 index 0000000000000000000000000000000000000000..1be6a58ad90ee234f43226428e2d214d287248db --- /dev/null +++ b/docs/performance.md @@ -0,0 +1,68 @@ +#### 运行原理 + +``uni-app`` 在 App 端或小程序端运行时，从架构上分为逻辑层和视图层两个部分。逻辑层负责储存数据和执行业务逻辑，视图层负责页面渲染。 + +目前，视图层以 WebView 作为渲染载体进行渲染，以 evaluateJavascript 的方式在视图层和逻辑层进行数据通讯，evaluateJavascript 通讯是异步操作，所以数据到达视图层不是实时的。 + +数据通讯时，框架会将要传递的数据转换为字符串进行传递，然后将字符串接成一份 JS 脚本，再通过执行 JS 脚本的形式传递到逻辑层和视图层，此操作意味着数据的大小会影响性能。 + +#### 优化建议 + +**使用自定义组件模式** + +使用自定义组件模式，在manifest中配置自定义组件模式（HBuilderX1.9起新建项目默认即为自定义组件模式）。 + +在复杂页面中，页面中嵌套大量组件，如果是非自定义组件模式，更新一个组件会导致整个页面数据更新。而自定义组件模式则可以单独更新一个组件的数据。 + +在App端，除了上述好处，自定义组件模式还新增了一个独立的js引擎，加快启动速度、减少js阻塞。 + +之前的非自定义组件模式已经不再推荐，请尽快升级你的应用。 + +**避免使用大图** + +页面中若大量使用大图资源，会造成页面切换的卡顿，导致系统内存升高，甚至白屏崩溃。 + +尤其是不要把多张大图缩小后显示在一个屏幕内，比如上传图片前选了数张几M体积的照片，然后缩小在一个屏幕中展示多张几M的大图，非常容易白屏崩溃。 + +**优化数据更新** + +在 ``uni-app`` 中，定义在 data 里面的数据每次变化时都会通知视图层重新渲染页面。 所以如果不是视图所需要的变量，可以不定义在 data 中，可在外部定义变量或直接挂载在vue实例上，以避免造成资源浪费。 + +**减少一次性渲染的节点数量** + +页面初始化时，逻辑层如果一次性向视图层传递很大的数据，使视图层一次性渲染大量节点，可能造成通讯变慢、页面切换卡顿，所以建议以局部更新页面的方式渲染页面。如：服务端返回100条数据，可进行分批加载，一次加载20条，500ms 后进行下一次加载。 + +**减少节点嵌套层级** + + 深层嵌套的节点在页面初始化构建时往往需要更多的内存占用，并且在遍历节点时也会更慢些，所以建议减少深层的节点嵌套。 + +**避免视图层和逻辑层频繁进行通讯** + +* 减少 scroll-view 组件的 scroll 事件监听，当监听 scroll-view 的滚动事件时，视图层会频繁的向逻辑层发送数据； +* 监听 scroll-view 组件的滚动事件时，不要实时的改变 scroll-top/scroll-left 属性，因为监听滚动时，视图层向逻辑层通讯，改变 scroll-top/scroll-left 时，逻辑层又向视图层通讯，这样就可能造成通讯卡顿。 +* 注意 onPageScroll 的使用，onPageScroll 进行监听时，视图层会频繁的向逻辑层发送数据； + +**优化页面切换动画** + +* 页面初始化时若存在大量图片渲染和大量数据通讯，很有可能造成页面切换卡顿、掉帧。建议延时100ms~300ms渲染图片，分批进行数据通讯，以减少一次性渲染的节点数量。 +* App端动画效果可以设置，popin/popout的双窗体联动挤压动画效果对资源的消耗更大，如果动画期间页面里在执行耗时的js，可能会造成动画掉帧。此时可以使用消耗资源更小的动画效果，比如slide-in-right/slide-out-right。 + +**优化样式渲染速度** + +将样式写在 ``App.vue`` 里，可以加速页面样式渲染速度。``App.vue`` 里面的样式是全局样式，每次新开页面会优先加载 ``App.vue`` 里面的样式，然后加载普通 vue 页面的样式。尤其是背景为深色的页面，如果不能及时设置样式，会造成进入转场动画时闪烁。 + +**使用 nvue 代替 vue** + +在 App 端 ```uni-app``` 的 nvue 页面可是基于 [weex](https://weex.apache.org/) 定制的原生渲染引擎，实现了页面原生渲染能力、提高了页面流畅性。若对页面性能要求较高可以使用此方式开发，详见：[nvue](/use-weex)。 + +**优化App启动速度的注意** + +* 工程代码越多，包括背景图和本地字体文件越大，对App的启动速度有影响，应注意控制体积。<image>组件引用的前景图不影响性能。 +* App端的 splash 关闭有白屏检测机制，如果首页一直白屏或首页本身就是一个空的中转页面，可能会造成 splash 10秒才关闭，可参考此文解决[http://ask.dcloud.net.cn/article/35565](http://ask.dcloud.net.cn/article/35565) +* App端使用自定义组件模式的话，首页为nvue页面可比vue页面大幅提升启动速度，nvue页面一般2、3秒即可完成启动。 + +**优化包体积** + +* uni-app发行到小程序时，自带引擎只有几十K，主要是一个定制过的vue.js核心库。如果使用了es6转es5、css对齐的功能，可能会增大代码体积，目前可以在cli中配置这些编译功能是否开启，后续在HBuilderX中也会提供配置。 +* uni-app的App端，因为自带了一个独立v8引擎和小程序框架，所以比HTML5Plus或mui等普通hybrid的App引擎体积要大。基础引擎约10M+。App还提供了扩展模块，比如地图、蓝牙等，打包时如不需要这些模块，可以裁剪掉，以缩小发行包体积。在 manifest.json-App模块权限 里可以选择。 +* uni-app的H5端，自带了vue.js、小程序ui库（如picker、switch等）、小程序的对齐js api，目前包体积比较大。下版会提供裁剪方案，按需加载组件和API。 \ No newline at end of file diff --git a/docs/platform.md b/docs/platform.md new file mode 100644 index 0000000000000000000000000000000000000000..25eef2e61f0064efa266942eba7a8722d8a37409 --- /dev/null +++ b/docs/platform.md @@ -0,0 +1,159 @@ +## 跨端兼容 + +uni-app 已将常用的组件、JS API 封装到框架中，开发者按照 uni-app 规范开发即可保证多平台兼容，大部分业务均可直接满足。 + +但每个平台有自己的一些特性，因此会存在一些无法跨平台的情况。 + +- 大量写 if else，会造成代码执行性能低下和管理混乱。 +- 编译到不同的工程后二次修改，会让后续升级变的很麻烦。 + +在 C 语言中，通过 #ifdef、#ifndef 的方式，为 windows、mac 等不同 os 编译不同的代码。 +``uni-app`` 参考这个思路，为 ``uni-app`` 提供了条件编译手段，在一个工程里优雅的完成了平台个性化实现。 + +## 条件编译 + +条件编译是用特殊的注释作为标记，在编译时根据这些特殊的注释，将注释里面的代码编译到不同平台。 + +**写法：**以 <span style="color:#859900;"> #ifdef</span> 或 <span style="color:#859900;"> #ifndef</span> 加<b style="color:#268BD2"> %PLATFORM%</b> 开头，以 <span style="color:#859900;">#endif</span> 结尾。 +* <span style="color:#859900;"> #ifdef</span>：if defined 仅在某平台存在 +* <span style="color:#859900;"> #ifndef</span>：if not defined 除了某平台均存在 +* <b style="color:#268BD2"> %PLATFORM%</b>：平台名称 + +<table><thead><tr><th>条件编译写法</th><th>说明</th></tr></thead><tbody><tr><td><div class="code"><span class="token comment"><span style="color:#859900;"> #ifdef</span><b style="color:#268BD2"> APP-PLUS</b></span><br>需条件编译的代码<br><span class="token comment"> <span style="color:#859900;"> #endif</span></span></div></td><td>仅出现在 5+App 平台下的代码</td></tr><tr><td><div class="code"><span class="token comment"> <span style="color:#859900;"> #ifndef</span><b style="color:#268BD2"> H5</b></span><br>需条件编译的代码<br><span class="token comment"> <span style="color:#859900;"> #endif</span></span></div></td><td>除了 H5 平台，其它平台均存在的代码</td></tr><tr><td><div class="code"><span class="token comment"> <span style="color:#859900;"> #ifdef</span><b style="color:#268BD2"> H5</b></span><span style="color:#859900;"> || </span><b style="color:#268BD2">MP-WEIXIN</b><br>需条件编译的代码<br><span class="token comment"> <span style="color:#859900;"> #endif</span></span></div></td><td>仅在 H5 平台或微信小程序平台存在的代码</td></tr></tbody></table> + + +<b style="color:#268BD2"> %PLATFORM%</b> **可取值如下：** + +|值|平台|参考文档| +|:-|:-|:-| +|APP-PLUS|5+App|[HTML5+ 规范](http://www.html5plus.org/doc/)| +|APP-PLUS-NVUE|5+App nvue|[Weex 规范](https://weex.apache.org/cn/guide/)| +|H5|H5|| +|MP-WEIXIN|微信小程序|[微信小程序](https://developers.weixin.qq.com/miniprogram/dev/api/)| +|MP-ALIPAY|支付宝小程序|[支付宝小程序](https://docs.alipay.com/mini/developer/getting-started)| +|MP-BAIDU|百度小程序|[百度小程序](https://smartprogram.baidu.com/docs/develop/tutorial/codedir/)| +|MP-TOUTIAO|头条小程序|[头条小程序](https://developer.toutiao.com/docs/framework/)| +|MP-QQ|QQ小程序| （目前仅cli版支持）| +|MP|微信小程序/支付宝小程序/百度小程序/头条小程序/QQ小程序| | + +**支持的文件** + +* .vue +* .js +* .css +* pages.json +* 各预编译语言文件，如：.scss、.less、.stylus、.ts、.pug + + +**注意：** 条件编译是利用注释实现的，在不同语法里注释写法不一样，js使用 ``// 注释``、css 使用 ``/* 注释 */``、vue/nvue 模板里使用 ``<!-- 注释 -->``； + +### API 的条件编译 + +<pre v-pre="" data-lang="javascript"><code class="lang-javascript code"><span class="token comment">//<span style="color:#859900;"> #ifdef</span><b style="color:#268BD2"> %PLATFORM%</b></span> +平台特有的API实现 +<span class="token comment">//<span style="color:#859900;"> #endif</span></span></code></pre> + + +示例，如下代码仅在 5+App 下出现: + + + +示例，如下代码不会在 H5 平台上出现： + + + +除了支持单个平台的条件编译外，还支持**多平台**同时编译，使用 || 来分隔平台名称。 + +示例，如下代码会在 5+App 和 H5 平台上出现： + + + +### 组件的条件编译 +<pre v-pre="" data-lang="html"><code class="lang-html code"><span class="token comment"><!-- <span style="color:#859900;"> #ifdef</span><b style="color:#268BD2"> %PLATFORM%</b> --></span> +平台特有的组件 +<span class="token comment"><!-- <span style="color:#859900;"> #endif</span> --></span></code></pre> + +示例，如下广告组件仅会在微信小程序中出现： + + + +### 样式的条件编译 +<pre v-pre="" data-lang="css"><code class="lang-css code"><span class="token comment">/* <span style="color:#859900;"> #ifdef</span><b style="color:#268BD2"> %PLATFORM% </b> */</span> +平台特有样式 +<span class="token comment">/* <span style="color:#859900;"> #endif </span> */</span></code></pre> + +**注意：** 样式的条件编译，无论是 css 还是 sass/scss/less/stylus 等预编译语言中，必须使用 `/*注释*/` 的写法。 + +正确写法 + + + +错误写法 + + + +### pages.json 的条件编译 +下面的页面，只有运行至 5+App 时才会编译进去。 + + + +不同平台下的特有功能，以及小程序平台的分包，都可以通过 pages.json 的条件编译来更好地实现。这样，就不会在其它平台产生多余的资源，进而减小包体积。 + +json的条件编译，如不同平台的key名称相同，cli项目下开发者自己安装的校验器会报错，需自行关闭这些校验器对json相同key的校验规则。如果使用HBuilderX的校验器，无需在意此问题，HBuilderX的语法校验器为此优化过。 + +### static 目录的条件编译 + +在不同平台，引用的静态资源可能也存在差异，通过 static 的的条件编译可以解决此问题，static 目录下新建不同平台的专有目录（目录名称同 `%PLATFORM%` 值域,但字母均为小写），专有目录下的静态资源只有在特定平台才会编译进去。 + +如以下目录结构，``a.png`` 只有在微信小程序平台才会编译进去，``b.png`` 在所有平台都会被编译。 + +<pre v-pre="" data-lang=""> + <code class="lang-" style="padding:0"> +┌─static +│ ├─mp-weixin +│ │ └─a.png +│ └─b.png +├─main.js +├─App.vue +├─manifest.json +└─pages.json + </code> +</pre> + +### 整体目录条件编译 + +如果想把各平台的页面文件更彻底的分开，也可以在uni-app项目根目录创建`platforms`目录，然后在下面进一步创建APP-PLUS、MP-WEIXIN等子目录，存放不同平台的文件。 + +### HBuilderX 支持 + +HBuilderX 为 ``uni-app`` 的条件编译提供了丰富的支持: + +**代码块支持** + +在 HBuilderX 中开发 ``uni-app`` 时，通过输入 **ifdef** 可快速生成条件编译的代码片段 + +  + +**语法高亮** + +在 HBuilderX 中对条件编译的代码注释部分提供了语法高亮，可分辨出写法是否正确，使得代码更加清晰（独立js文件需在编辑器右下角切换javascript es6+编辑器，独立css文件暂不支持高亮，但不高亮不影响使用） + + + + +**正确注释和快速选中** + +在 HBuilderX 中，ctrl+alt+/ 即可生成正确注释（js：``// 注释``、css：``/* 注释 */``、vue/nvue模板： ``<!-- 注释 -->``）。 + + + +点击 **ifdef** 或 **endif** 可快速选中条件编译部分；点击左侧的折叠图标，可折叠条件编译部分代码。 + + + + + +### 注意 +* Android 和 iOS 平台不支持通过条件编译来区分，如果需要区分 Android、iOS 平台，请通过调用 uni.getSystemInfo 来获取平台信息。在HBuilderX1.9.10起，支持`ifios`、`ifAndroid`代码块，可方便编写判断。 +* 有些跨端工具可以提供js的条件编译或多态，但这对于实际开发远远不够。uni-app不止是处理js，任何代码都可以多端条件编译，才能真正解决实际项目的跨端问题。另外所谓多态在实际开发中会造成大量冗余代码，很不利于复用和维护。举例，微信小程序主题色是绿色，而百度支付宝小程序是蓝色，你的应用想分平台适配颜色，只有条件编译是代码量最低、最容易维护的。 +* 有些公司的产品运营总是给不同平台提不同需求，但这不是拒绝uni-app的理由。关键在于项目里，复用的代码多还是个性的代码多，正常都是复用的代码多，所以仍然应该多端。而个性的代码放到不同平台的目录下，差异化维护。 \ No newline at end of file diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000000000000000000000000000000000000..c38e8e58f9908e1363a008730bcabb5112204714 --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,245 @@ + +> `uni-app`支持通过 可视化界面、[`vue-cli`命令行](https://uniapp.dcloud.io/quickstart?id=%e9%80%9a%e8%bf%87vue-cli%e5%91%bd%e4%bb%a4%e8%a1%8c) 两种方式快速创建项目。 + + +## 1. 通过 HBuilderX 可视化界面 + +可视化的方式比较简单，HBuilderX内置相关环境，开箱即用，无需配置nodejs。 + +开始之前，开发者需先下载安装如下工具： + +- HBuilderX：[官方IDE下载地址](http://www.dcloud.io/hbuilderx.html) + +HBuilderX是通用的前端开发工具，但为`uni-app`做了特别强化。 + +下载App开发版，可开箱即用；如下载标准版，在运行或发行`uni-app`时，会提示安装`uni-app`插件，插件下载完成后方可使用。 + +如使用`cli`方式创建项目，可直接下载标准版，因为uni-app编译插件被安装到项目下了。 + + +### 创建uni-app + +在点击工具栏里的文件 -> 新建 -> 项目： +<div align=center> + <img src="//img-cdn-qiniu.dcloud.net.cn/uniapp/doc/create1.png"/> +</div> + +选择uni-app，输入工程名，如：hello-uniapp，点击创建，即可成功创建 uni-app。点击模板里的 Hello uni-app 即可体验官方示例。 + +<div align=center> + <img src="//img-cdn-qiniu.dcloud.net.cn/uniapp/doc/create2.png"/> +</div> + +### 运行uni-app +1. 浏览器运行：进入hello-uniapp项目，点击工具栏的运行 -> 运行到浏览器 -> 选择浏览器，即可在浏览器里面体验uni-app 的 H5 版。 + <div align=center> + <img src="//img-cdn-qiniu.dcloud.net.cn/uniapp/doc/run-chrome.png"/> + </div> + +2. 真机运行：连接手机，开启USB调试，进入hello-uniapp项目，点击工具栏的运行 -> 真机运行 -> 选择运行的设备，即可在该设备里面体验uni-app。 + <div align=center> + <img src="//img-cdn-qiniu.dcloud.net.cn/uniapp/doc/run-phone.png"/> + </div> + + 如手机无法识别，请点击菜单运行-运行到手机或模拟器-真机运行常见故障排查指南。 + 注意目前开发App也需要安装微信开发者工具。 + +3. 在微信开发者工具里运行：进入hello-uniapp项目，点击工具栏的运行 -> 运行到小程序模拟器 -> 微信开发者工具，即可在微信开发者工具里面体验uni-app。 + <br/> + <div align=center> + <img src="https://img-cdn-qiniu.dcloud.net.cn/uniapp/doc/uni20190222-1.png"/> + </div> + + **注意：**如果是第一次使用，需要先配置小程序ide的相关路径，才能运行成功。如下图，需在输入框输入微信开发者工具的安装路径。 若HBuilderX不能正常启动微信开发者工具，需要开发者手动启动，然后将uni-app生成小程序工程的路径拷贝到微信开发者工具里面，在HBuilderX里面开发，在微信开发者工具里面就可看到实时的效果。 + + uni-app默认把项目编译到根目录的unpackage目录。 + <br/> + <div align=center> + <img src="//img-cdn-qiniu.dcloud.net.cn/uniapp/doc/weixin-setting.png"/> + </div> + +4. 在支付宝小程序开发者工具里运行：进入hello-uniapp项目，点击工具栏的运行 -> 运行到小程序模拟器 -> 支付宝小程序开发者工具，即可在支付宝小程序开发者工具里面体验uni-app。 + <br/> + <div align=center> + <img src="https://img-cdn-qiniu.dcloud.net.cn/uniapp/doc/uni20190222-3.png"/> + </div> + +5. 在百度开发者工具里运行：进入hello-uniapp项目，点击工具栏的运行 -> 运行到小程序模拟器 -> 百度开发者工具，即可在百度开发者工具里面体验uni-app。 + <br/> + <div align=center> + <img src="https://img-cdn-qiniu.dcloud.net.cn/uniapp/doc/uni20190222-2.png"/> + </div> + +6. 在字节跳动开发者工具里运行：进入hello-uniapp项目，点击工具栏的运行 -> 运行到小程序模拟器 -> 字节跳动开发者工具，即可在字节跳动开发者工具里面体验uni-app。 + <br/> + <div align=center> + <img src="https://img-cdn-qiniu.dcloud.net.cn/uniapp/doc/uni20190222-4.png"/> + </div> + +**Tips** + +* 如果是第一次使用，需要配置开发工具的相关路径。点击工具栏的运行 -> 运行到小程序模拟器 -> 运行设置，配置相应小程序开发者工具的路径。 +* 支付宝/百度/字节跳动小程序工具，不支持直接指定项目启动并运行。因此开发工具启动后，请将 HBuilderX 控制台中提示的项目路径，在相应小程序开发者工具中打开。 +* 如果自动启动小程序开发工具失败，请手动启动小程序开发工具并将 HBuilderX 控制台提示的项目路径，打开项目。 + +运行的快捷键是`Ctrl+r`。 +HBuilderX 还提供了快捷运行菜单，可以按数字快速选择要运行的设备： +<div align=center> + <img src="https://img-cdn-qiniu.dcloud.net.cn/uniapp/doc/uni20190222-5.png"/> +</div> + +如需调试，可参考：[uni-app调试](/snippet?id=使用-chrome-调试) + +### 发布uni-app + +#### 打包为原生App（云端） + +在HBuilderX工具栏，点击发行，选择原生app-云端打包，如下图： + +<div align=center> + <img src="https://img-cdn-qiniu.dcloud.net.cn/uniapp/doc/uni20190222-11.png"/> +</div> +出现如下界面，点击打包即可。 +<div align=center> + <img src="//img-cdn-qiniu.dcloud.net.cn/uniapp/doc/push.png"/> +</div> + +#### 打包为原生App（离线） + +``uni-app`` 支持离线打包，在 HBuilderX 生成离线打包资源，然后参考 [离线打包](http://ask.dcloud.net.cn/docs/#//ask.dcloud.net.cn/article/104)（或参考其他用户写的 [离线打包日记](https://ask.dcloud.net.cn/article/35302)），即可进行离线打包。 + +在HBuilderX工具栏，点击发行，选择本地打包，如下图，点击即可生成离线打包资源。 + +<div align=center> + <img src="https://img-cdn-qiniu.dcloud.net.cn/uniapp/doc/uni20190222-12.png"/> +</div> + +#### 发布为H5 + +1. 在 ``manifest.json`` 的可视化界面，进行如下配置（发行在网站根目录可不配置应用基本路径），此时发行网站路径是 www.xxx.com/h5，如：[https://uniapp.dcloud.io/h5](https://uniapp.dcloud.io/h5)。 +<div align=center> + <img src="https://img-cdn-qiniu.dcloud.net.cn/uniapp/doc/build-h5-1.png" style="max-width:600px;height:auto;"/> +</div> +2. 在HBuilderX工具栏，点击发行，选择网站-H5手机版，如下图，点击即可生成 H5 的相关资源文件，保存于 unpackage 目录。 + +<div align=center> + <img src="https://img-cdn-qiniu.dcloud.net.cn/uniapp/doc/uni20190222-10.png" style="max-width:600px;height:auto;"/> +</div> + +**注意** +- `history` 模式发行需要后台配置支持，详见：[history 模式的后端配置](https://router.vuejs.org/zh/guide/essentials/history-mode.html#%E5%90%8E%E7%AB%AF%E9%85%8D%E7%BD%AE%E4%BE%8B%E5%AD%90) +- 打包部署后，在服务器上开启 gzip 可以进一步压缩文件。具体的配置，可以参考网上的分享：https://juejin.im/post/5af003286fb9a07aac24611b + +#### 发布为小程序 + +**发布为微信小程序：** +1. 申请微信小程序AppID，参考：[微信教程](https://developers.weixin.qq.com/miniprogram/dev/#申请帐号)。 +2. 在HBuilderX中顶部菜单依次点击 "发行" => "小程序-微信"，输入小程序名称和appid点击发行即可在 ``unpackage/dist/build/mp-weixin`` 生成微信小程序项目代码。 +<div align=center> + <img src="https://img-cdn-qiniu.dcloud.net.cn/uniapp/doc/uni20190222-6.png"/> +</div> +3. 在微信开小程序发者工具中，导入生成的微信小程序项目，测试项目代码运行正常后，点击“上传”按钮，之后按照 “提交审核” => “发布” 小程序标准流程，逐步操作即可，详细查看：[微信官方教程](https://developers.weixin.qq.com/miniprogram/dev/quickstart/basic/release.html)。 + +**发布为百度小程序：** +1. 入驻小程序并申请百度小程序AppID，参考：[百度小程序教程](https://smartprogram.baidu.com/docs/introduction/enter_application/)。 +2. 在HBuilderX中顶部菜单依次点击 "发行" => "小程序-百度"，输入小程序名称和appid点击发行即可在 ``/unpackage/dist/build/mp-baidu`` 生成百度小程序项目代码。 +<div align=center> + <img src="https://img-cdn-qiniu.dcloud.net.cn/uniapp/doc/uni20190222-7.png"/> +</div> +3. 在百度小程序开发者工具中，导入生成的百度小程序项目，测试项目代码运行正常后，点击“上传”按钮上传代码，之后在百度小程序的 [管理中心](https://smartprogram.baidu.com/developer/applist.html) 选择创建的应用点击前往发布，选择对应的版本然后提交审核。 + + +**发布为支付宝小程序：** +1. 入驻支付宝小程序，参考：[支付宝小程序教程](https://docs.alipay.com/mini/introduce)。 +2. 在HBuilderX中顶部菜单依次点击 "发行" => "小程序-支付宝"，即可在 ``/unpackage/dist/build/mp-alipay`` 生成支付宝小程序项目代码。 +<div align=center> + <img src="https://img-cdn-qiniu.dcloud.net.cn/uniapp/doc/uni20190222-8.png"/> +</div> +3. 在支付宝小程序开发者工具中，导入生成的支付宝小程序项目，测试项目代码运行正常后，点击“上传”按钮上传代码，在 [支付宝小程序后台](https://open.alipay.com/platform/mini.htm#/app)，选择刚提交的版本点击提交审核，详见：[支付宝小程序文档](https://docs.alipay.com/mini/developer/publish)。 + + +**发布为头条小程序：** +1. 入驻头条小程序，参考：[头条小程序教程](https://developer.toutiao.com/docs/intro/create.html)。 +2. 在HBuilderX中顶部菜单依次点击 "发行" => "小程序-字节跳动"，即可在 ``/unpackage/dist/build/mp-alipay`` 生成头条小程序项目代码。 +<div align=center> + <img src="https://img-cdn-qiniu.dcloud.net.cn/uniapp/doc/uni20190222-8.png"/> +</div> +3. 在字节跳动小程序开发者工具中，导入生成的头条小程序项目，测试项目代码运行正常后，点击“上传”按钮上传代码，在 [头条小程序后台](https://developer.toutiao.com/app/applist)，选择刚提交的版本点击提交审核，详见：[头条小程序文档](https://developer.toutiao.com/docs/intro/create.html#%E6%8F%90%E5%AE%A1%E3%80%81%E5%8F%91%E5%B8%83%E3%80%81%E6%9B%B4%E6%96%B0)。 + +发布的快捷键是`Ctrl+u`。同样可拉下快速发布菜单并按数字键选择。 + +## 2. 通过vue-cli命令行 + +除了可视化界面，也可以使用 `cli` 脚手架，可以通过 `vue-cli` 创建 `uni-app` 项目。 + +**注意：** +- vue-cli 版本必须是3.x +- `cli` 版本更新快于HBuilderX正式版。HBuilderX正式版所包含的uni-app编译器一般是在`cli`版发布一段时间并稳定后才会更新到HBuilderX正式版。`cli`版适合喜欢鼓捣的尝鲜者，其好处是可以及时获取新功能，坏处是稳定性不如HBuilderX正式版，但因为开源，所以也欢迎开发者一起完善。 + +### 环境安装 + +全局安装vue-cli + +``` +npm install -g @vue/cli +``` + +### 创建uni-app + +``` +vue create -p dcloudio/uni-preset-vue my-project +``` +此时，会提示选择项目模板，初次体验建议选择 `hello uni-app` 项目模板，如下所示： + +<div> +<img src="http://img.cdn.aliyun.dcloud.net.cn/guide/uniapp/h5-cli-01.png" width="300"> +</div> + +#### 自定义模板 +选择自定义模板时，需要填写 uni-app 模板地址，这个地址其实就是托管在云端的仓库地址。以 GitHub 为例，地址格式为 `userName/repositoryName`，如 `dcloudio/uni-template-picture` 就是下载图片模板。 + +更多支持的下载方式，请参考这个插件的说明：[download-git-repo](https://github.com/flipxfx/download-git-repo) + +### 运行并发布uni-app + +``` +npm run dev:%PLATFORM% +npm run build:%PLATFORM% +``` + +``%PLATFORM%`` 可取值如下： + +|值|平台| +|---|---| +|h5|H5| +|mp-alipay|支付宝小程序| +|mp-baidu|百度小程序| +|mp-weixin|微信小程序| +|mp-toutiao|头条小程序| +|mp-qq|qq 小程序| + +**其他：** + +* dev 模式编译出的各平台代码存放于根目录下的 ``/dist/dev/``目录，打开各平台开发工具选择对应平台目录即可进行预览（h5 平台不会在此目录，存在于缓存中）； +* build 模式编译出的各平台代码存放于根目录下的 ``/dist/build/`` 目录，发布时选择此目录进行发布； +* dev 和 build 模式的区别： + 1. dev 模式有 SourceMap 可以方便的进行断点调试； + 2. build 模式会将代码进行压缩，体积更小更适合发布为正式版应用； + 3. 进行 [环境判断](/frame?id=运行环境判断) 时，dev 模式 process.env.NODE_ENV 的值为 development，build 模式 process.env.NODE_ENV 的值为 production。 + +### 使用cli创建项目和使用HBuilderX可视化界面创建项目有什么区别 + +#### 编译器的区别 + +* ``cli``创建的项目，编译器安装在项目下。并且不会跟随HBuilderX升级。如需升级编译器，执行``npm update``。 +* HBuilderX可视化界面创建的项目，编译器在HBuilderX的安装目录下的plugin目录，随着HBuilderX的升级会自动升级编译器。 +* 已经使用``cli``创建的项目，如果想继续在HBuilderX里使用，可以把工程拖到HBuilderX中。注意如果是把整个项目拖入HBuilderX，则编译时走的是项目下的编译器。如果是把src目录拖入到HBuilderX中，则走的是HBuilderX安装目录下plugin目录下的编译器。 +* ``cli``可以自定义webpack，有灵活度但增加了出错的概率。如果想安装less、scss、ts等编译器，需自己手动npm安装。在HBuilderX的插件管理界面安装无效，那个只作用于HBuilderX创建的项目。 + +#### 开发工具的区别 +* ``cli``创建的项目，内置了d.ts，同其他常规npm库一样，可在vscode等支持d.ts的开发工具里正常开发并有语法提示。 +* 但其他开发工具比起HBuilderX，开发效率仍有不足。详见：[https://ask.dcloud.net.cn/article/35451](https://ask.dcloud.net.cn/article/35451) +* ``cli``创建的项目，发布App时，仍然需要使用HBuilderX。其他开发工具无法发布App，但可以发布H5、各种小程序。 +* 如果使用``cli``创建项目，那下载HBuilderX时只需下载10M的标准版即可。因为编译器已经安装到项目下了。 +* 对 `cli` 使用有疑问，欢迎扫码加入 uni-app 微信交流群讨论： + <br/><img src="http://img.cdn.aliyun.dcloud.net.cn/guide/uniapp/wx-barcode.png" width="250"/> diff --git a/docs/resource.md b/docs/resource.md new file mode 100644 index 0000000000000000000000000000000000000000..ecaed56254cbb2810bf461cfaf4fa94adb280d06 --- /dev/null +++ b/docs/resource.md @@ -0,0 +1,51 @@ +建议第一步，看完[uni-app官网](https://uniapp.dcloud.io)的首页介绍。 + +建议第二步，通过[快速上手](https://uniapp.dcloud.io/quickstart)，亲身体验下uni-app。 + +建议第三步，看完[《uni-app官方教程》](https://ke.qq.com/course/343370)，出品人：DCloud，课时：共3节。 + +#### 如果你熟悉h5，但不熟悉vue和小程序 +1. 看完这篇[白话uni-app](http://ask.dcloud.net.cn/article/35657) +2. 看这个培训视频，从vue到uni-app全部讲了。[《uni-app 商业级应用实战》](https://ke.qq.com/course/379043?from=800006421)，出品人：腾讯课堂NEXT学院 +3. 如果不愿意付费看视频，可以去vue官网自学。注意vuejs可以在html中使用，而uni-app里没有HTML，直接就是vue文件。另外vue的路由、npm可以不学 +4. 不太需要专门去学习小程序开发，只看uni-app官网即可 + +#### 如果你使用过mpvue +几乎不用学习，看完这篇即可[mpvue转uni-app指南](http://ask.dcloud.net.cn/article/34945) + +#### 三方培训机构视频 +如下是三方专业培训机构的视频教程 +* [《uni-app 商业级应用实战》](https://ke.qq.com/course/379043?from=800006421)，出品人：腾讯课堂NEXT学院。亮点：腾讯课堂官方出品；不懂 vue 的工程师也可快速学习；从入门到实战都包括。 +* [《uni-app 跨平台应用开发教程》](http://www.hcoder.net/course/info_242.html)，出品人：hcoder 刘海君，课时：共25节。亮点：讲师经验丰富，也是graceui框架作者。 +* [《uni-app 实战教程 - “悦读”项目实战》](https://ke.qq.com/course/364262?tuin=4f8da6)，出品人：hcoder 刘海君，点击[领取专享优惠劵](https://ke.qq.com/p/IYf6YNZf?tuin=4f8da6) +* [《uni-app实战仿糗事百科app开发》](https://study.163.com/course/introduction.htm?courseId=1209188809&_trace_c_p_k2_=4b765abfb2f946039c8ea6230737f6af)，出品人：帝莎IT学院。适用人群：具备Html+Css+Javascript基础知识。 +* [《uni-app仿小米商城实战》](https://study.163.com/course/courseMain.htm?courseId=1209401825&share=2&shareId=480000001892585)，出品人：帝莎IT学院。首页使用nvue开发，目前支持app端和小程序端。 +* [《uni-app多端调试环境配置》](https://study.163.com/course/courseMain.htm?courseId=1209401924&share=2&shareId=480000001892585)，出品人：帝莎IT学院。 +<!-- * [《跟枫桥一起开发App》](https://www.lusita.cn)，出品人：唐枫桥，来源：源码商城（注：源码商城App、小程序本身就是基于```uni-app```开发的） --> +<!-- * [《广州番禺职业技术学院 uni-app课程》](http://doc.zengqs.com/1143144)，出品人：曾教授 --> + +如果你是线下培训机构，想开课合作，联系bd@dcloud.io + +#### 网友学习笔记分享 + +* WordPress搭配uni-app开发app和小程序的教程：[https://ask.dcloud.net.cn/article/35704](https://ask.dcloud.net.cn/article/35704) +* uni-app官方教程学习手记：[https://segmentfault.com/a/1190000017020710](https://segmentfault.com/a/1190000017020710) + + +欢迎更多人分享学习经验，可转载到[社区](http://ask.dcloud.net.cn/explore/)，优秀的文章我们会收录在本文中。 + +#### 题外话：关于各端的管理规则需要耐心学习 + +uni-app并不难学，但我们注意到很多新人在适应各个平台的规则限制时很焦躁。 + +uni-app跨了很多端，虽然代码层面可以开发一次，生成多端。但注意每个端，有每个端的管理规则，这与开发无关，但每个开发者仍然要耐心掌握这些规则限制。 + +- 比如H5端的浏览器有跨域限制； +- 比如微信小程序会强制要求https链接，并且所有要联网的服务器域名都要配到微信的白名单中； +- 比如App端，iOS对隐私控制和虚拟支付控制非常严格； +- 比如App端，Android、国产rom各种兼容性差异，尤其是因为谷歌服务被墙，导致的push、定位等开发混乱的坑； +- 如果你的App要使用三方sdk，比如定位、地图、支付、推送...还要遵循他们的规则和限制； + +#### uni-app的底层框架实现原理及优化策略（高级） +通过[评测对比](https://juejin.im/post/5ca1736af265da30ae314248)，我们知道uni-app的性能比其他小程序开发框架好，但底层原理是什么？ +这篇视频就是讲解uni-app框架底层的实现思路和优化策略：[《uni-app框架如何实现高性能》](https://v.qq.com/x/page/r0886mn8v6l.html) \ No newline at end of file diff --git a/docs/select.md b/docs/select.md new file mode 100644 index 0000000000000000000000000000000000000000..f2c1b3710b0465c252431f27bc5e7123c201522c --- /dev/null +++ b/docs/select.md @@ -0,0 +1,220 @@ +#### uni-app选型评估23问 + +如果你关心竞品对比，这里有几份详尽对比： +1. 多端开发框架对比横评，参考：[https://juejin.im/post/5ca1736af265da30ae314248](https://juejin.im/post/5ca1736af265da30ae314248) +2. 只做App，flutter、react native等App跨平台框架对比，参考：[https://ask.dcloud.net.cn/article/36083](https://ask.dcloud.net.cn/article/36083) +3. 只做小程序，原生wxml开发、wepy、mpvue、taro的对比，[https://ask.dcloud.net.cn/article/35867](https://ask.dcloud.net.cn/article/35867) + +**uni-app收费吗？** + +```uni-app``` 是免费产品，DCloud公司不会向开发者收取任何费用，大家可以放心使用。 + +DCloud提供的所有开发工具都是免费的，也不会有什么陷阱。 + +DCloud的盈利点在帮助开发者进行推广和流量变现上，而不在开发工具收费上。 + +**跨端会造成功能受限制吗？** + +```uni-app```在跨平台的过程中，不牺牲平台特色，不限制平台的能力使用。 + +应用开发中，90%的常规开发，比如界面组件、联网等api，```uni-app```封装为可跨多端的API。 + +各个端的特色功能，```uni-app```引入[条件编译](http://uniapp.dcloud.io/platform)。可以优雅的在一个项目里调用不同平台的特色能力。比如push，微信小程序里不支持，但可以在App里使用，还有很多原生sdk，在App时难免涉及，这些都可以正常的在```uni-app```框架下使用。 + +下图是```uni-app```产品功能框架图，```uni-app```在保持uni规范跨平台的前提下，还可实现每个平台特有的平台能力(如微信小程序平台，可继续调用微信卡劵等微信特有业务API)。 + + + +在做小程序时，小程序所有的api都可以使用；而输出到App时，原生渲染引擎、原生sdk集成和混写都支持，使得原生的所有api都可以使用。 + +同时注意，条件编译不同于代码里if逻辑判断。条件编译块里的代码或指定的文件，只有在特定平台才会被编译进去，不会把不能用的其他平台代码混在一个包里。如果大量使用if判断，会增大体积和影响性能，而条件编译则没有这些问题，减少包体积，减少互相的干扰。 + +**uni-app的手机端用户体验如何？** + +使用```uni-app```开发的微信小程序，因为智能的处理的数据的diff，比大多人手写的原生小程序的性能还好。详细数据评测参考：[https://juejin.im/post/5ca1736af265da30ae314248](https://juejin.im/post/5ca1736af265da30ae314248) + +```uni-app```打包成App后的体验和微信小程序一样好，在某些场景下更好；微信小程序的Hybrid应用框架是业内体验上的标杆，实践证明这种体验足以承载一线互联网开发商获得上亿用户。 + +对比普通hybrid方案，```uni-app```加载新页面速度更快。 + +```uni-app```在App端还支持weex原生渲染（nvue），左右拖动长列表等复杂场景依然可实现高流畅性。 + +对比其他跨平台方案： + +- 对于Hybrid方案，```uni-app```比普通基于webview的Hybrid方案体验更好，包括比DCloud之前的mui体验更好。 +- 对比纯原生渲染的方案，体验差不多，但易用性和生态完整度上uni-app明显胜出（uni-app自身功能组件丰富，并且小程序的周边丰富生态都可以用于跨平台开发）。 + +就当前环境看，```uni-app```是功能、生态完整的跨平台方案里体验最好的。 + +当前的手机硬件越来越好，和以往大不相同。就像486微机时代，网页应用很难发展，肯定是原生开发的天下。但随着终端性能的提升，原生开发的必要性越来越小，加上流量获取的便利性，web开发成为主流。 + +手机上也是这个潮流，社会总是向生产效率更高的方向前进。向前看，不固守旧思维，方能赢得未来。 + +**只开发小程序，需要uni-app吗？** + +是的，单独开发小程序，也应该使用uni-app。它比其他小程序框架或原生小程序开发更有优势。原因如下： + +1. `uni-app`使用通用技术vue开发，不用学习微信自定义的语法。 +2. `uni-app`的运行性能更高 +3. HBuilderX作为通用专业IDE，比微信开发者工具好用 +4. 你迟早会有需求发布到支付宝、百度、头条等小程序平台，使用`uni-app`再无后续顾虑 +5. `uni-app`的插件市场里有非常多的ui库、组件、模板，拿来即用，大幅提升开发效率 +6. 统一H5、App，节约成本，提高效率 +7. 微信原生开发，对于npm、各种预编译器、webpack的支持非常不友好，影响工程效率，大公司很少用原生开发。 + +这里有详细的评测，和原生wxml开发、wepy、mpvue、taro的对比，[https://ask.dcloud.net.cn/article/35867](https://ask.dcloud.net.cn/article/35867) + +**只开发App，需要uni-app吗？** + +```uni-app```是更好的跨平台开发框架，开发一次iOS、Android都有了。体验好、开发效率高。 + +<!-- ```uni-app```在App侧可以使用小程序引擎或weex引擎渲染，性能体验高于其他Hybrid框架。 --> + +```uni-app```在App端，基于能力层/渲染层分离的架构设计（见下图），渲染层是webview和weex二选一，能力调用都是共同的plus api，比如蓝牙、扫码等能力；也就是weex被内置到```uni-app```中，并且被强化了。 + + + +过去weex有个很大的问题是api太少，开发时必须iOS、Android原生和前端3拨团队协作开发，实际上react native也如此，因为他们的核心只是高性能渲染器。 + +plus api的结合解决了这个问题，大多数App的开发不再需要原生介入了，从而把跨平台开发省成本这个核心目的落地了。 + +```uni-app```在App侧可以使用丰富的小程序sdk，如网易云信、环信、七牛等众多sdk厂商均原厂维护其小程序sdk版本，而这些sdk均可直接用于uni-app并发布为iOS、Android的App。 + +```uni-app```的插件市场里有非常多的ui库、组件、模板，可以大幅提升开发效率。 + +相比纯原生开发，```uni-app```体验可商用，也不会限制功能调用，但开发效率和开发成本更优于原生开发。 + +如果你已经有了原生App，那么可以局部使用```uni-app```，内嵌SDK，让工程逐步跨平台化。 + +**uni-app是多端写在一个项目统一升级维护，还是每个端不同的项目，只复用部分代码** + +```uni-app```是多端写在一个基础项目下，差异使用条件编译来管理。 + +这有个巨大的好处是一套工程代码，升级时可多端同时更新。 + +如果把不同端的项目分开，那么维护升级时非常麻烦，无法方便同步升级。 + +所以```uni-app```开发微信小程序时，不止编码，包括域名校验等配置均在HBuilderX里完成，不需要在微信开发者工具里二次调整。 + + +**uni-app 学习成本高吗？基于什么技术栈？** + +```uni-app```简单来说是 vue的语法 + 小程序的api。 + +它遵循```Vue.js```语法规范，组件和API遵循```微信小程序命名```，这些都属于通用技术栈，学习它们是前端必备技能，```uni-app```没有太多额外学习成本。 + +有一定 Vue.js 和微信小程序开发经验的开发者可快速上手 ```uni-app``` 。 + +没学过vue的同学，也不用掌握vue的全部，只需了解vue基础语法、虚拟dom、数据绑定、组件、vuex，其他如路由、loader 不用学，cli、node.js、webpack也不需要学。 + +官方有入门培训视频，且还有众多培训渠道加入```uni-app```生态，可参考[培训教程资源汇总](http://uniapp.dcloud.io/resource)。 + +**uni-app 开发体验如何？支持现代前端开发流程吗？** + +```uni-app``` 积极拥抱社区现有的现代开发流程，包括但不限于： + +- 内置了webpack +- NPM 包管理系统，详见[参考](http://uniapp.dcloud.io/frame?id=npm%E6%94%AF%E6%8C%81) +- es6+ 语法（发布时会自动编译为es5），详见[参考](http://uniapp.dcloud.io/frame?id=es6-%E6%94%AF%E6%8C%81) +- 各种预处理器（less、scss、stylus、typescript） +- uni-app的官方ide：HBuilderX，在vue、json、markdown、代码提示、操作效率上，有非常明显的优势，可帮助开发者大幅提高工作效率 +- uni-app同时也提供了cli方式，可使用其他开发工具如vscode开发，当然开发效率不如HBuilderX。对比详见[https://ask.dcloud.net.cn/article/35451](https://ask.dcloud.net.cn/article/35451) + + +**uni-app 生态开放性如何？能否直接利用现有前端社区资源？** + +```uni-app``` 提供了开放性的生态： + +- 丰富的插件市场为开发者提供大量现成的轮子，[https://ext.dcloud.net.cn](https://ext.dcloud.net.cn) +- 兼容微信小程序 JS SDK，丰富的小程序生态内容可直接引入uni-app，并且在App侧通用，[参考](http://ask.dcloud.net.cn/article/35070) +- 兼容微信小程序自定义组件，并且App侧通用，[参考](http://uniapp.dcloud.io/frame?id=小程序组件支持) +- 支持 NPM 包管理系统，[参考](http://uniapp.dcloud.io/frame?id=npm%E6%94%AF%E6%8C%81) +- 支持 mpvue 项目及组件，[参考](http://ask.dcloud.net.cn/article/34945) +- 支持原生插件，见插件市场：[https://ext.dcloud.net.cn](https://ext.dcloud.net.cn) +- 支持App原生工程里嵌入uni-app的sdk。 + +需要注意的是，```uni-app``` 采用```Vue.js```方案，限制了dom操作，因此所有基于dom的前端库都无法直接使用；所幸的是目前基于微信小程序的库已经非常多了，这个生态也很完善，所有微信小程序的库在```uni-app``` 里都能用，不止是在微信里能用，在App下也能用。 + +**uni-app 支持的手机版本最低到多少？** + +Android4.4、iOS8是官方会保障兼容的。 +更低版本其实也能用，但官方发布时不会测试更低版本。 + +另外如果使用flex布局，更低版本是不支持的，只能使用传统css布局。 + +开发时尽量避免使用太新的css，可能在老款手机上产生兼容问题。 + +**我已有小程序项目，如何迁移到uni-app？** + +- 如果是mpvue开发的小程序，那极其简单，[参考](https://ask.dcloud.net.cn/article/34945) +- 如果是非mpvue开发的小程序，改动也不复杂，毕竟组件、api、样式是一样的，[参考](https://ask.dcloud.net.cn/article/35786) + +如果已有5+或mui App、wap2app、原生App，是无法迁移到uni-app的。 + +**uni-app成熟度高吗？** + +```uni-app```是目前最成熟的多端开发框架，已迭代几十个版本，拥有几十个开发者交流群，几十万应用案例。 + +**uni-app的社区活跃吗？** + +加入```uni-app```的群就知道，几十个QQ/微信群每天数万条聊天记录，非常活跃。 + +插件市场内容也非常丰富，常见开发需求都有轮子可用。[https://ext.dcloud.net.cn/](https://ext.dcloud.net.cn/) + +基于```uni-app```的三方培训也很多。腾讯课堂官方都为uni-app制作了课程。 + + +**uni-app 有哪些已上线的成功案例？** + +开发者分享的案例参考[uni-app 应用案例](http://uniapp.dcloud.io/case) + +**DCloud是家什么公司，是否可信赖** + +```DCloud```从2013年开始做HBuilder，目前300万前端开发者在使用```DCloud```的开发工具，HBuilder百度指数与sublime、webstorm等全球知名工具相同。是中国唯一一家成功的开发工具厂商。 + +```DCloud```是明星创业公司，融资已经过了B2轮，且均为知名VC或战略投资人。 + +```DCloud```是HTML5中国产业联盟的发起单位和秘书单位。该联盟隶属于工信部信通院标准所。 + +```DCloud```产品中使用的HTML5Plus规范，为联盟的标准规范而非私有api。 + +开发者使用```DCloud```5+引擎打包的App，这些App已经安装激活在**2亿**台手机设备上，广泛应用于各行各业。 + +```DCloud```的产品技术一直引领业内，2015年就上线业内第一个"小程序"：DCloud流应用。随后DCloud广泛推动业内各大公司上线"小程序"，普及该技术广泛应用。 + +数年来只有其他公司侵权DCloud，这些作恶公司已被法院判决给DCloud赔款道歉，DCloud从未有劣迹，诚信立足于行业。 + +**App打包必须上传DCloud云端吗？代码会泄露吗？** + +代码可以云打包，也可以离线打包。 + +即使使用云打包，DCloud也不会保留开发者的代码，云端打包完成后程序不会持久化存储相关文件，会立即删除。DCloud不愿也不敢沾惹这方面的麻烦。 + +之所以提供云打包，是方便不熟悉原生的前端工程师直接生成App安装包。包括让没有mac电脑的工程师也可以打出iOS的包。 + +**DCloud提供哪些技术支持？碰到框架bug影响业务怎么办？** + +```uni-app``` 是DCloud全力打造的重点产品，不是非专业公司的KPI项目。不会因为某些负责人的流动导致框架烂尾。 +```uni-app``` 的github上的dev分支是日更的，可随时修复bug。并且作为开源产品，开发者也可以修改源码。 +```uni-app``` 的app引擎，支持原生扩展，只要你会原生扩展，就不怕app引擎有限制，大不了自己补一个原生插件进去。 +```uni-app``` 开发小程序，无需依赖微信等平台升级。它们升级后，uni-app是可以直接使用的，不需要等待uni-app升级才能使用微信的新功能。 + +开发者碰到问题，可以通过如下途径进行反馈交流： +- ask社区：[https://ask.dcloud.net.cn/explore/category-12](https://ask.dcloud.net.cn/explore/category-12) +- QQ群：参考官网左侧导航显示的QQ群列表 + +另外，如果您确实需要商业化的保障才安心，也可以申请付费技术支持。[参考](https://ask.dcloud.net.cn/article/13015) + +**大型互联网公司发布的开源框架，是不是更有影响力？** + +大型互联网公司在自用某个项目时，解决了某个问题，把它摘出来开源，这个是众多大公司开源项目的来源和初衷。 + +而之所以把内部自用的框架开源出来，基本是为了在技术圈塑造形象和威望。对团队而言，有助于招聘；对负责人个人而言，有助于晋升和提升名气。 + +这类开源项目被戏称为KPI项目，往往逃不开4个魔咒： +1. 很多项目开源后一旦取得成绩，负责人就升职调岗，或者因为其他原因最初立项负责人离职，于是之前的开源项目就慢慢变凉。 +2. 其设计初衷是为公司内部使用的，不是站在广泛的开发者需求角度设计的，其他开发者使用时会遇到各种问题。 +3. 大型互联网公司的主业都是toC的，而不是to开发者。投很多资源持续维护这些开源项目并不是其公司目标，也不会有回报。 +4. 优秀的程序员和优秀的开发框架设计者是2个层面的问题，不是说某些一线公司的前端技术人员水平不足，而是他们缺少面向开发者设计产品的经验，这种经验需要长期为开发者提供服务的团队才能具备。经验不足者设计的产品不会好用。 + +而```DCloud```这家公司就是为开发者而生的，优秀的人才和资源全部是为开发者服务的，产品立项之初广泛调研不同开发者的需求，产品发布后持续迭代，让开发者们使用的更便利。 diff --git a/docs/snippet.md b/docs/snippet.md new file mode 100644 index 0000000000000000000000000000000000000000..1b792015f2f27b51b4ca9f4b25d7c42105b64b13 --- /dev/null +++ b/docs/snippet.md @@ -0,0 +1,165 @@ + +### 使用代码块直接创建组件模板 + +为提升开发效率，HBuilderX将 ```uni-app``` 常用代码封装成了以 ```u``` 开头的代码块，如在 ```template``` 标签内输入 ```ulist``` 回车，会自动生成如下代码： + +``` +<view class="uni-list"> + <view class="uni-list-cell"> + <view class="uni-list-cell-navigate uni-navigate-right" v-for="(item,index) in list" :key="index"> + {{item.value}} + </view> + </view> +</view> +``` + +代码块分为Tag代码块、JS代码块，如在 ```script``` 标签内输入 ```uShowToast``` 回车，会自动生成如下代码： + +``` +uni.showToast({ + title: '', + mask: false + duration: 1500 +}); +``` + +```uni-app```已支持代码块见下方列表。 + + +#### Tag代码块 + +- uButton +- uCheckbox +- uGrid：宫格，需引用uni ui +- uList：列表，需引用uni ui +- uListMedia +- uRadio +- uSwiper +- ...... + +几乎各种组件不管是内置组件还是uni ui的组件，均已封装为代码块，在HBuilderX的vue代码template区域中敲u，代码助手会提示所有可见列表。也可在HBuilderX菜单工具-代码块设置-vue代码块的左侧列表查阅所有。 + +除组件外，其他常用代码块包括： + +- viewfor：生成一段带有v-for循环结构的视图代码块 +- vbase：生成一段基本的vue代码结构 + +#### JS代码块 + +##### uni api代码块 +- uRequest +- uGetLocation +- uShowToast +- uShowLoading +- uHideLoading +- uShowModal +- uShowActionSheet +- uNavigateTo +- uNavigateBack +- uRedirectTo +- uStartPullDownRefresh +- uStopPullDownRefresh +- uLogin +- uShare +- uPay +- ...... + +几乎各种常用js api，均已封装为代码块，在HBuilderX的js代码中敲u，代码助手会提示所有可见列表。也可在HBuilderX菜单工具-代码块设置-js代码块的左侧列表查阅所有。 + +##### vue js代码块 +- vImport：导入文件 +- ed：export default +- vData：输出 data(){return{}} +- vMethod：输出 methods:{} +- vComponents：输出 components: {} + +##### 其他常用js代码块 +- iff：简单if +- forr：for循环结构体 +- fori：for循环结构体并包含i +- funn：函数 +- funa：匿名函数 +- rt：return true +- clog：输出："console.log()" +- clogvar：增强的日志输出，可同时把变量的名字打印出来 +- varcw：输出："var currentWebview = this.$mp.page.$getAppWebview()" +- ifios：iOS的平台判断 +- ifAndroid：Android的平台判断 + +预置代码块不满足需求的话，可以自定义代码块，教程参考[https://ask.dcloud.net.cn/article/35924](https://ask.dcloud.net.cn/article/35924) + +### 使用 Chrome 调试 H5 + +进入 ``uni-app`` 项目，点击工具栏的运行 -> 运行到浏览器 -> 选择 Chrome，即可将 uni-app运行到 浏览器，可参考 [运行uni-app](/quickstart?id=运行uni-app)，运行到浏览器后，就能和普通 web 项目一样进行预览和调试了。 + +**注意**：Chrome调试只能保证样式一致，部分原生能力是不支持的。 + +点 Chrome 控制台的 Sources 栏，可以给 js 打断点调试。 + +在 Page 下找到 webpack 里的工程目录，可直接找到对应的vue页面进行断点调试；或按 Ctrl+P搜文件名，进入页面调试；也可点击控制台的 log 信息，进入对应的页面进行调试。 + + + + + +### 使用各家小程序开发工具调试 + +``uni-app`` 运行到微信web开发者工具等小程序开发工具里，可在这些工具的控制台查看 ``console`` 信息，网络请求等信息等。 + +页面样式调试和一般的web项目一样，通过调试的箭头选中元素即可查看相应的节点和样式，如下图： + + + +调试 js 时需要切换到 Sources 栏，选中想要调试的那个页面的js，进行调试（如果js代码是压缩过的，点击右下角的{}可格式化代码），如下图： + + + +### 关于 App 的调试 + +自 `HBuilderX 2.0.3+ Alpha` 版本起开始支持 `App` 端的调试 + +#### 打开调试窗口 +在 `HBuilderX` 中，正确运行项目： `运行 --> 运行到手机或模拟器 --> 选择设备`，项目启动后，在下方的控制台选择 `debug` 图标。 + + + +正确打开调试窗口后，显示如下： + + +#### 调试页面 +在调试窗口控制台的 Sources （图中指示1） 栏，可以给 js 打断点调试。 + +在 uniapp:// （图中指示2）下找到需要调试的页面，单击打开 ，在右侧可以看到我们需要调试的内容（图中指示3）。在需要调试的代码行号的位置，点击打上断点（图中指示4）。 + + + +之后，在设备上进行操作，进入断点位置，可以方便我们跟踪调试代码。 + + + +Tip +- 不支持非自定义组件模式 +- `vue` 和 `nvue` 页面都能打断点调试 +- 目前仅支持 `nvue` 页面查看元素，`vue` 页面暂不支持，`Android` 暂不支持查看 `style` + +<!-- uni-app的App端没有webview调试（即webkit remote debug）。 + +- App端提供真机运行的console.log日志输出，运行到真机或模拟器时，会在HBuilderX的控制台输出日志。（如果使用老版的非自定义组件编译模式，无法输出对象，需要把对象转字符串后输出） +- 如果是调App的界面和常规API，推荐编译到H5端，用Chrome调Dom，保存后立即看到结果，调试更方便。并且H5端也支持titleNView的各种复杂设置。 +- 如果是调与手机能力有关的JS API，那么 uni 部分的js api可以使用微信开发者工具调试，因为uni-app 的 App端引擎实际上是一个强化的小程序引擎，所以可以使用微信开发者工具进行debug调试、查看Dom和网络和存储。 +- 如果是调plus专用的API，目前只能在控制台打log +- 如果是调nvue，可以使用weex的调试工具，[详见](https://weex.apache.org/zh/tools/toolkit.html) + +一般推荐的做法是在PC的Chrome下开发测试，基本完成后运行到微信工具测试，最后再上真机运行看兼容性问题。但此时务必注意css兼容性问题，不要使用太新的css，否则在低版本Android上会不兼容。 + +注意：即使不发布微信小程序、只发布App，也需要安装微信开发者工具。 --> + +### 持续集成 + +很多公司的开发人员提交代码后，需要自动打包或持续集成。 + +此时需要在服务器安装uni-app的cli版本来发布小程序和H5版。 + +HBuilderX版与cli版互转指南参考：[https://ask.dcloud.net.cn/article/35750](https://ask.dcloud.net.cn/article/35750) + +如果是发布App，则需要使用[离线打包](https://ask.dcloud.net.cn/docs/#//ask.dcloud.net.cn/article/508)，配置原生环境，来实现持续集成。（目前HBuilderX还不支持命令行生成wgt资源和云打包，欢迎到需求墙投票：[https://dev.dcloud.net.cn/wish/](https://dev.dcloud.net.cn/wish/)） \ No newline at end of file diff --git a/docs/template.md b/docs/template.md new file mode 100644 index 0000000000000000000000000000000000000000..8243847de57bdbcd708466316bd98f156f6cb35f --- /dev/null +++ b/docs/template.md @@ -0,0 +1,61 @@ + +为方便开发者快速开发，DCloud在```Hello uni-app```示例中包含了部分模板演示，这部分模板源码已开源，详见[Github](https://github.com/dcloudio/uni-app/tree/master/examples/hello-uniapp/pages/template)。 + +下文列出已集成的模板示例，欢迎开发者分享更多的模板示例，一起完善```uni-app```生态！ + +**1.折叠面板** + +<img src="//img.cdn.aliyun.dcloud.net.cn/guide/uniapp/template-01.jpg" width="200"/> + +**2.数字角标** + +<img src="//img.cdn.aliyun.dcloud.net.cn/guide/uniapp/template-02.jpg" width="200"/> + +**3.卡片视图** + +<img src="//img.cdn.aliyun.dcloud.net.cn/guide/uniapp/template-03.jpg" width="200"/> + +**4.列表** + +包括右侧带角标、二级折叠列表、三行列表、图文列表 + +<div style="display:flex;justify-content: space-around;"> + <div style="display:flex;align-items: center;flex-direction: column;"> + <img src="//img.cdn.aliyun.dcloud.net.cn/guide/uniapp/template-04.jpg" width="200"/> + </div> + <div style="display:flex;align-items: center;flex-direction: column;"> + <img src="//img.cdn.aliyun.dcloud.net.cn/guide/uniapp/template-05.jpg" width="200"/> + </div> + <div style="display:flex;align-items: center;flex-direction: column;"> + <img src="//img.cdn.aliyun.dcloud.net.cn/guide/uniapp/template-06.jpg" width="200"/> + </div> + <div style="display:flex;align-items: center;flex-direction: column;"> + <img src="//img.cdn.aliyun.dcloud.net.cn/guide/uniapp/template-07.jpg" width="200"/> + </div> +</div> + +**5.九宫格** + +<img src="//img.cdn.aliyun.dcloud.net.cn/guide/uniapp/template-08.jpg" width="200"/> + +**6.选项卡** + +<img src="//img.cdn.aliyun.dcloud.net.cn/guide/uniapp/template-09.jpg" width="200"/> + +**7.数字选择框** + +<img src="//img.cdn.aliyun.dcloud.net.cn/guide/uniapp/template-10.jpg" width="200"/> + +**8.资讯类列表到详情示例** + +包括资讯类列表页及详情页 + +<div style="display:flex;justify-content: space-around;"> + <div style="display:flex;align-items: center;flex-direction: column;"> + <img src="//img.cdn.aliyun.dcloud.net.cn/guide/uniapp/template-11.jpg" width="200"/> + </div> + <div style="display:flex;align-items: center;flex-direction: column;"> + <img src="//img.cdn.aliyun.dcloud.net.cn/guide/uniapp/template-12.jpg" width="200"/> + </div> +</div> + diff --git a/docs/translate.md b/docs/translate.md new file mode 100644 index 0000000000000000000000000000000000000000..71e17da2644f97db74cd980c24b4bd81c6ab08eb --- /dev/null +++ b/docs/translate.md @@ -0,0 +1,9 @@ + +`uni-app`可以多端输出，也欢迎各平台之前的老项目向uni-app转换迁移。 + + +**vue h5项目转换uni-app指南：**[https://ask.dcloud.net.cn/article/36174](https://ask.dcloud.net.cn/article/36174) + +**微信小程序转换uni-app指南及转换器：**[https://ask.dcloud.net.cn/article/35786](https://ask.dcloud.net.cn/article/35786) + +**mpvue 项目（组件）迁移指南、示例及资源汇总：** [https://ask.dcloud.net.cn/article/34945](https://ask.dcloud.net.cn/article/34945) diff --git a/docs/use-html5plus.md b/docs/use-html5plus.md new file mode 100644 index 0000000000000000000000000000000000000000..4c4ce54af0205b9131d10ac9d895d1a25ff9ecc8 --- /dev/null +++ b/docs/use-html5plus.md @@ -0,0 +1,34 @@ +`uni-app` App 端内置 [HTML5+](https://www.html5plus.org/doc/) 引擎，让 js 可以直接调用丰富的原生能力。 + +- 条件编译调用 HTML5+ + +小程序及 H5 等平台是没有 HTML5+ 扩展规范的，因此在 `uni-app` 调用 HTML5+ 的扩展规范时，需要注意使用条件编译。否则运行到h5、小程序等平台会出现 `plus is not defined`错误。 + +```javascript +// #ifdef APP-PLUS +var appid = plus.runtime.appid; +console.log('应用的 appid 为：' + appid); +// #endif +``` + +- `uni-app`不需要 `plus ready` +在html中使用plus的api，需要等待plus ready。 +而`uni-app`不需要等，可以直接使用。而且如果你调用plus ready，反而不会触发。 + + +- `uni-app` 中的事件监听 + +在普通的 H5+ 项目中，需要使用 `document.addEventListener` 监听原生扩展的事件。 + + `uni-app` 中，没有 document。可以使用 `plus.globalEvent.addEventListener` 来实现（注意manifest中需开启新编译器，即自定义组件模式"usingComponents":true）。 + +```javascript +// #ifdef APP-PLUS +// 监听设备网络状态变化事件 +plus.globalEvent.addEventListener('netchange', function(){}); +// #endif +``` + +同理，在 `uni-app` 中使用 Native.js 时，一些 Native.js 中对于原生事件的监听同样需要按照上面的方法去实现。 + +注意：旧编译器（非自定义组件模式）不支持 `plus.globalEvent` 这个对象。 \ No newline at end of file diff --git a/docs/use-weex.md b/docs/use-weex.md new file mode 100644 index 0000000000000000000000000000000000000000..6fb4eb76d692d679e3b3919b3a387eed25238878 --- /dev/null +++ b/docs/use-weex.md @@ -0,0 +1,736 @@ +## 介绍 + +```uni-app``` App端内置 [weex](https://weex.apache.org/) 渲染引擎，提供了原生渲染能力。 + +```uni-app``` 里根据编译配置不同，可以使用 ``weex`` 的组件，也可以使用小程序组件(即uni-app组件)。编写页面时页面后缀名为 ``.nvue``(native vue的缩写) + +``nvue`` 相当于给 weex 补充了大量 uni-app 的组件和api，以及丰富的 Plus API、Native.js、原生插件。 + +以往的 weex ，有个很大的问题是它只是一个高性能的渲染器，没有足够的API能力，使得开发时非常依赖原生工程师协作，开发者本来想节约成本，结果需要前端、iOS、Android 3拨人开发，适得其反。而 nvue 解决了这个大问题，让前端工程师可以直接开发完整 App，并提供原生插件的市场交易和云打包。这些组合方案，开发者切实的提高效率、降低成本。 + +如果你已经是 weex 的开发者，具有 weex 的填坑能力，那么 nvue 是你的更优选择，能切实提升你的开发效率，降低成本。 + +如果你是web前端，不熟悉 weex，那么建议你仍然以使用 vue 为主，在App端某些 vue 表现不佳的场景下使用 nvue 作为强化补充： +- 左右拖动的长列表。在webview里，通过swiper+scroll-view实现左右拖动的长列表，前端模拟下拉刷新，这套方案的性能不好。此时推荐使用nvue，比如新建uni-app项目时的新闻示例模板，就是首页采用了nvue +- 为了解决 vue 页面的原生控件层级问题和原生导航栏的灵活自定义问题，uni-app 还提供了 subnvue 方案，将一个非全屏的 nvue 页面覆盖到 vue 页面上，[详见](https://ask.dcloud.net.cn/article/35948) + + +## 编译模式差异 + +uni-app 深度改进了 weex，提供了2种编译模式，一种是常规的 weex 组件模式，即编写`<div>`。另一种是 uni-app 组件模式，即编写`<view>`。后者更提供了编译为小程序和H5的能力。 + +也可以理解为uni-app做了一个原生渲染的小程序引擎。 + +| |weex编译模式 |uni-app编译模式 | +|-- |-- |-- | +|平台 |仅App |所有端，包含小程序和H5 | +|组件 |weex组件如`div` |uni-app组件如`view` | +|生命周期 |只支持weex生命周期 |支持所有uni-app生命周期 | +|JS API |weex API、uni API、Plus API |weex API、uni API、Plus API | +|单位 |750px是屏幕宽度，wx是固定像素单位 |750rpx是屏幕宽度，px是固定像素单位 | +|全局样式 |手动引入 |app.vue的样式即为全局样式 | +|页面滚动 |必须给页面套<list>或<scroller>组件 |默认支持页面滚动 | + +修改2种编译模式的在 manifest.json 中，`manifest.json` -> `app-plus` -> `nvueCompiler` 切换编译模式。 + +`nvueCompiler` 有两个值： +- weex +- uni-app + +```json +// manifest.json +{ + // ... + /* App平台特有配置 */ + "app-plus": { + "nvueCompiler":"uni-app" //是否启用 uni-app 模式 + } +} + +``` + +* 如果没有在manifest里明确配置，默认是weex模式。这是为了向下兼容。 +* 当前uni-app编译模式组件还不够完整，详细列表见 [https://ask.dcloud.net.cn/article/36074](https://ask.dcloud.net.cn/article/36074)，但已经可满足常用场景。比如左右拖动的长列表场景推荐使用uni-app编译模式的nvue，其他页面仍然可使用 vue 页面。新建uni-app项目选模板`新闻/资讯模板`，这是一个nvue页面可编译到全平台的示例。 + +## 快速上手 + +### 1. 新建 nvue 页面 + +在 ``uni-app`` 项目中，选中文件或文件夹，鼠标右击选择新建 ``nvue`` 文件输入文件名创建。 + +不管是vue页面还是nvue页面，都需要在pages.json中注册。 + +如果一个页面路由下同时有vue页面和nvue页面，那么在App端，会优先使用nvue页面。 + +在非app端，只有uni-app编译模式的nvue才会编译。 + + + +### 2. 开发 nvue 页面 + +``nvue`` 页面结构同 ``vue``, 由 template、style、script 构成。 +* template： 模板写法、数据绑定同 ``vue``。组件支持2种模式，1、 ``weex`` 组件，参考：[weex 内置组件](https://weex.apache.org/zh/docs/components/a.html)；2、``uni-app``组件，参考：[nvue中支持的uni-app组件](https://ask.dcloud.net.cn/article/36074) +* style：由于采用原生渲染，**并非所有浏览器的 css 均支持，布局模型只支持 flex 布局**，虽然不会造成某些界面布局无法实现，但写法要注意。详见：[weex 样式](https://weex.apache.org/cn/wiki/common-styles.html) +* script：写法同 ``vue``，并支持3种API + - weex API ：使用前需先引入对应模块，参考：[weex 内置模块](http://weex-project.io/cn/references/modules/index.html) + - uni API：nvue可以使用部分 uni API，详细支持列表请参照：[nvue 里可使用的 uni-app API](/use-weex?id=nvue-里可使用的-uni-app-api) + - plus API：在自定义组件编译模式下，nvue里可直接使用plus API + + +**weex组件代码示例（uni-app组件代码和普通uni-app的vue源码相同）** + +```html +<template> + <div class="example"> + <div class="item" @click="changeNum"><text class="text">点击文字，改变数字大小: {{num}}</text></div> + <div class="item" @click="showModal('native')"><text class="text">使用 weex 的 API 弹出模态框</text></div> + <div class="item" @click="showModal('uni')"><text class="text">使用 uni-app 的 API 弹出模态框</text></div> + <div class="item" @click="showModal('plus')"><text class="text">使用 plus 的 API 弹出模态框</text></div> + </div> +</template> +<script> + export default { + data() {return {num: 1}}, + created() {console.log('页面created')}, + methods: { + changeNum() { this.num += 1; }, + showModal(type) { + if (type === 'uni') { + uni.showModal({content: '使用 uni-app 的 API 弹出模态框'}); + } + else if (type === 'plus') { + plus.nativeUI.alert('使用 uni-app 的 API 弹出模态框'); + } else { + var modal = weex.requireModule('modal') + modal.alert({message: '使用 weex 的 API 弹出模态框'}); + } + } + } + } +</script> +<style> + .example {flex-direction: column;} + .text {line-height: 80px;font-size: 32px;color: #333;} + .item {height: 80px;width: 690px;margin: 30px;background-color: #f8f8f8;border-width: 1px;border-color: #eee;border-radius: 10px;align-items: center;} +</style> +``` + + +### 3. 调试 nvue 页面 + +HBuilderX内置了更好用的weex/uni-app调试工具，[详见](https://uniapp.dcloud.io/snippet?id=%e5%85%b3%e4%ba%8e-app-%e7%9a%84%e8%b0%83%e8%af%95) + + +## 生命周期 + +``nvue `` 的 uni-app 编译模式的生命周期同普通vue页面。而 weex 编译模式，即普通 weex 生命周期函数如下： + +|Vue 生命周期钩子|说明| +|---|---| +|beforeCreate|在实例初始化之后，数据观测 (data observer) 和 event/watcher 事件配置之前被调用| +|created |在实例创建完成后被立即调用| +|beforeMount|在挂载开始之前被调用| +|mounted |el 被新创建的 vm.$el 替换时调用| +|beforeUpdate|数据更新时调用| +|updated |页面元素更新后调用| +|beforeDestroy|实例销毁之前调用| +|destroyed |实例销毁后调用| +|errorCaptured|当捕获一个来自子孙组件的错误时被调用| + +**注意：** weex 编译模式不支持 onNavigationBarButtonTap 生命周期函数的写法。在 ``nvue`` 中监听原生标题栏按钮点击事件，详见：[uni.onNavigationBarButtonTap](/use-weex?id=onnavigationbarbuttontap)。 + + +## 页面跳转 + +nvue 的页面跳转，与 weex 不同，仍然遵循 uni-app 的路由模型。vue 页面和 nvue 页面之间不管怎么跳转，都遵循这个模型。包括 nvue 页面跳向 nvue 页面。 + +每个页面都需要在 pages.json 中注册，调用 `uni-app` 的 [路由 API](/api/router) 进行跳转。 + +## nvue 和 vue 相互通讯 + +在 uni-app 中，nvue 和 vue 页面可以混搭使用。 + +### nvue 向 vue 通讯 + +**步骤：** + +1. 在 ``nvue`` 使用 ``uni.postMessage(data)`` 发送数据通讯，``data`` 为 ``JSON`` 格式（键值对的值仅支持String）。 +2. 在 ``App.vue`` 里使用 ``onUniNViewMessage`` 进行监听。 + +**代码示例:** + +```html +//test.nvue +<template> + <div @click="test"> + <text>点击页面发送数据</text> + </div> +</template> +<script> + export default { + methods: { + test(e) { + uni.postMessage({test: "数据",value:"数据"}); + } + } + } +</script> +``` +```html +//App.vue +<script> + export default { + onUniNViewMessage:function(e){ + console.log("App.vue收到数据") + console.log(JSON.stringify(e.data)) + }, + onLaunch: function() { + console.log('App Launch'); + } + } +</script> +``` + +### vue 向 nvue 通讯 + +**步骤：** + +1. 在 ``vue`` 里使用 ``plus.webview.postMessageToUniNView(data,nvueId)`` 发送消息，``data`` 为 ``JSON`` 格式（键值对的值仅支持String），``nvueId`` 为 ``nvue`` 所在 webview 的 id，webview的 id 获取方式参考：[$getAppWebview()](/frame?id=getappwebview)。 +2. 在 ``nvue`` 里引用 ``globalEvent`` 模块监听 ``plusMessage`` 事件，如下： + +```javascript +const globalEvent = weex.requireModule('globalEvent'); +globalEvent.addEventListener("plusMessage", e => { + console.log(e.data);//得到数据 +}); +``` + +**代码示例：** + +```html +//index.nvue +<template> + <div @click="test"> + <text>点击页面发送数据{{num}}</text> + </div> +</template> +<script> + const globalEvent = weex.requireModule('globalEvent'); + export default { + data() { + return { + num: "0" + } + }, + created() { + globalEvent.addEventListener("plusMessage", e => { + console.log(e.data); + if (e.data.num) { //存在num时才赋值，在nvue里调用uni的API也会触发plusMessage事件，所以需要判断需要的数据是否存在 + this.num = e.data.num + } + }); + }, + methods: { + test(e) { + uni.navigateTo({ + url: '../test/test' + }) + } + } + } +``` +```html +//test.vue +<template> + <view> + <button type="primary" @click="test">点击改变nvue的数据</button> + </view> +</template> +<script> + export default { + methods: { + test() { + var pages = getCurrentPages(); + var page = pages[pages.length - 2]; + var currentWebview = page.$getAppWebview(); + plus.webview.postMessageToUniNView({ + num: "123" + }, currentWebview.id); + uni.navigateBack() + } + } + } +</script> +``` + +## vue 和 nvue 共享的变量和数据 +除了通信事件，vue 和 nvue 页面之间还可以共享变量和存储。 +但注意nvue不支持vuex，uni-app提供的共享变量和数据的方案如下： + +1. uni.storage +vue和nvue页面可以使用相同的`uni.storage`存储。这个存储是持久化的。 +比如登陆状态可以保存在这里。 + +2. globalData +小程序有globalData机制，这套机制在uni-app里也可以使用，全端通用。 +在`App.vue`文件里定义globalData，如下： +```html +<script> + export default { + globalData: { + text: 'text' + }, + onLaunch: function() { + console.log('App Launch') + }, + onShow: function() { + console.log('App Show') + }, + onHide: function() { + console.log('App Hide') + } + } +</script> +``` + +js中操作globalData的方式如下： +`getApp().globalData.text = 'test'` + +如果需要把globalData的数据绑定到页面上，可在页面的onShow声明周期里进行变量重赋值。HBuilderX 2.0.3起，nvue页面在`uni-app`编译模式下，也支持onShow。 + +weex编译模式不支持onShow，但熟悉5+的话，可利用监听webview的addEventListener show事件实现onShow效果。 + + +## weex 编译模式中使用 weex 第三方库 + +``nvue`` 的 weex 编译模式中，可以使用weex的第三方库，这里以 [Weex Ui](https://alibaba.github.io/weex-ui/) 为例，介绍如何使用。 + +1.初始化工程 + +``` +npm init -y +``` +2.安装依赖 (暂时只支持名称里包含weex的库) +``` +npm i weex-ui -S +``` +3.在nvue里面使用 +```html +<template> + <div> + <wxc-cell label="标题" title="Weex Ui" :has-arrow="true" @wxcCellClicked="wxcCellClicked" :has-margin="true"></wxc-cell> + </div> +</template> +<script> + import { WxcCell } from 'weex-ui'; + export default { + components: { WxcCell }, + methods: { + wxcCellClicked (e) { + console.log(e) + } + } + }; +</script> +``` + +Tis: +* 插件市场有一个集成好 weex ui 的示例，可以直接查看[https://ext.dcloud.net.cn/plugin?id=442](https://ext.dcloud.net.cn/plugin?id=442) + +## nvue 里使用 BindingX + +``uni-app`` 内置了 [BindingX](https://alibaba.github.io/bindingx/)，可在 ``nvue`` 中使用 BindingX 完成复杂的动画效果。 + +* 使用方式可参考 [BindingX 快速开始](https://alibaba.github.io/bindingx/guide/cn_guide_start)，demo示例可参考 [BindingX 示例](https://alibaba.github.io/bindingx/demos) 里 ``vue`` 的相关示例，将实验田里的 ``vue`` 代码拷贝到 ``nvue`` 文件里即可。 +* 若引入 weex-bindingx 时发现不生效，检查项目路径，路径不能含有中文。 + +**代码示例** + +```html +<template> + <div class="container"> + <div ref="b1" class="btn" style="background-color:#6A1B9A" @click="clickBtn"> + <text class="text">A</text> + </div> + <div ref="b2" class="btn" style="background-color:#0277BD" @click="clickBtn"> + <text class="text">B</text> + </div> + <div ref="b3" class="btn" style="background-color:#FF9800" @click="clickBtn"> + <text class="text">C</text> + </div> + <div ref="main_btn" class="btn" @click="clickBtn"> + <image class="image" ref="main_image" src="https://gw.alicdn.com/tfs/TB1PZ25antYBeNjy1XdXXXXyVXa-128-128.png" /> + </div> + </div> +</template> +<script> + import Binding from 'weex-bindingx'; + module.exports = { + data: { + isExpanded: false + }, + methods: { + getEl: function(el) { + if (typeof el === 'string' || typeof el === 'number') return el; + if (WXEnvironment) { + return el.ref; + } else { + return el instanceof HTMLElement ? el : el.$el; + } + }, + collapse: function() { + let main_btn = this.getEl(this.$refs.main_btn); + let main_image = this.getEl(this.$refs.main_image); + let b1 = this.getEl(this.$refs.b1); + let b2 = this.getEl(this.$refs.b2); + let b3 = this.getEl(this.$refs.b3); + Binding.bind({ + eventType: 'timing', + exitExpression: { + origin: 't>800' + }, + props: [{ + element: main_image, + property: 'transform.rotateZ', + expression: { + origin: 'easeOutQuint(t,45,0-45,800)' + } + },{ + element: main_btn, + property: 'background-color', + expression: { + origin: "evaluateColor('#607D8B','#ff0000',min(t,800)/800)" + } + }] + }); + Binding.bind({ + eventType: 'timing', + exitExpression: { + origin: 't>800' + }, + props: [{ + element: b1, + property: 'transform.translateY', + expression: { + origin: "easeOutQuint(t,-150,150,800)" + } + },{ + element: b2, + property: 'transform.translateY', + expression: { + origin: "t<=100?0:easeOutQuint(t-100,-300,300,700)" + } + },{ + element: b3, + property: 'transform.translateY', + expression: { + origin: "t<=200?0:easeOutQuint(t-200,-450,450,600)" + } + }] + }) + }, + expand: function() { + let main_btn = this.getEl(this.$refs.main_btn); + let main_image = this.getEl(this.$refs.main_image); + let b1 = this.getEl(this.$refs.b1); + let b2 = this.getEl(this.$refs.b2); + let b3 = this.getEl(this.$refs.b3); + Binding.bind({ + eventType: 'timing', + exitExpression: { + origin: 't>100' + }, + props: [{ + element: main_image, + property: 'transform.rotateZ', + expression: { + origin: 'linear(t,0,45,100)' + } + },{ + element: main_btn, + property: 'background-color', + expression: { + origin: "evaluateColor('#ff0000','#607D8B',min(t,100)/100)" + } + }] + }); + Binding.bind({ + eventType: 'timing', + exitExpression: { + origin: 't>800' + }, + props: [{ + element: b1, + property: 'transform.translateY', + expression: { + origin: "easeOutBounce(t,0,0-150,800)" + } + }, { + element: b2, + property: 'transform.translateY', + expression: { + origin: "t<=100?0:easeOutBounce(t-100,0,0-300,700)" + } + }, { + element: b3, + property: 'transform.translateY', + expression: { + origin: "t<=200?0:easeOutBounce(t-200,0,0-450,600)" + } + }] + }) + }, + clickBtn: function(e) { + if (this.isExpanded) { + this.collapse(); + } else { + this.expand(); + } + this.isExpanded = !this.isExpanded; + } + } + } +</script> +<style> + .container {flex: 1;} + .image {width: 60px;height: 60px;} + .text {color: #ffffff;font-size: 30px;} + .btn {width: 100px;height: 100px;background-color: #ff0000;align-items: center;justify-content: center;position: absolute;border-radius: 50px;bottom: 25px;right: 25px;} +</style> +``` + +## nvue 里使用 HTML5Plus API + +- 自定义组件编译模式，HBuilderX 1.9.8起，nvue页面可直接使用plus的API，并且同样不需要等待plus ready。 +- 非自定义组件编译模式，nvue无法直接调用 HTML5Plus 相关的 API，可以通过与vue通讯的方式，在 vue 页面调用 HTML5Plus 的API，传值给nvue页面，以达到类似的结果。 + +以下为非自定义组件模式下，通过页面通讯在nvue页面获得设备uuid的示例（推荐老项目尽快升级为自定义组件，享受更高的性能和功能）： + +nvue 页面 +```html +<template> + <div @click="test"> + <text>点击页面得到设备的uuid为：{{uuid}}</text> + </div> +</template> +<script> + const globalEvent = weex.requireModule('globalEvent'); + export default { + data() { + return { + uuid: null + } + }, + created() { + globalEvent.addEventListener("plusMessage", e => { + console.log(e.data); + if (e.data.detail) { + this.uuid = e.data.detail + } + }); + }, + methods: { + test(e) { + uni.postMessage({module:"device",api:"uuid"}); + } + } + } +</script> +``` +App.vue +```html +<script> + export default { + onUniNViewMessage: function(e) { + console.log("App.vue收到数据:" + JSON.stringify(e.data)); + console.log("uuid:" + plus[e.data.module][e.data.api]) + var pages = getCurrentPages(); + var page = pages[pages.length - 1]; + var currentWebview = page.$getAppWebview(); + plus.webview.postMessageToUniNView({ + detail: plus[e.data.module][e.data.api] + }, currentWebview.id); + } + } +</script> +``` + +## nvue 里可使用的 uni-app API +`nvue` 支持大部分 uni-app API ，下面只列举目前还不支持的 API 。 + +**地图** + +|API|说明| +|:-|:-| +|uni.createMapContext()|创建并返回 map 上下文| + +**视频** + +|API|说明| +|:-|:-| +|uni.createVideoContext()|创建并返回 video 上下文| + +**直播推流** + +|API|说明| +|:-|:-| +|uni.createLivePusherContext()|创建并返回 livePusher 上下文| + +**动画** + +|API|说明| +|:-|:-| +|uni.createAnimation()|创建一个动画实例| + +**滚动** + +|API|说明| +|:-|:-| +|uni.pageScrollTo()|将页面滚动到目标位置| + +**绘画** + +|API|说明| +|:-|:-| +|uni.createCanvasContext()|创建 canvas 绘图上下文| +|uni.canvasToTempFilePath()|把当前画布指定区域的内容导出生成指定大小的图片，并返回文件路径| +|uni.canvasGetImageData()|返回一个数组，用来描述 canvas 区域隐含的像素数据| +|uni.canvasPutImageData()|将像素数据绘制到画布的方法| + +**下拉刷新** + +|API|说明| +|:-|:-| +|uni.onPullDownRefresh()|监听该页面用户下拉刷新事件| +|uni.startPullDownRefresh()|开始下拉刷新| +|uni.stopPullDownRefresh()|停止当前页面下拉刷新| + +**节点信息** + +|API|说明| +|:-|:-| +|uni.createSelectorQuery()|返回一个 SelectorQuery 对象实例| + +**节点布局交互** + +|API|说明| +|:-|:-| +|uni.createIntersectionObserver()|创建并返回一个 IntersectionObserver 对象实例| + + +#### nvue的新增API + +为了解决nvue的weex编译模式不支持uni-app生命周期的问题，`在nvue` 里新增了几个特殊的 API。如果是uni-app编译模式，无需使用这些API： + +##### uni.onNavigationBarButtonTap(CALLBACK)@onNavigationBarButtonTap + +监听原生标题栏按钮点击事件。 + +CALLBACK 参数说明： + +|属性|类型|说明| +|---|---|---| +|index|Number|原生标题栏按钮数组的下标| + +**代码示例** + +```javascript +export default { + created() { + uni.onNavigationBarButtonTap((e) => { + console.log("监听到原生标题栏按钮点击事件"); + console.log(e); + }) + } +} +``` + + +##### uni.onNavigationBarSearchInputChanged(CALLBACK) + +监听原生标题栏搜索输入框输入内容变化事件。 + +CALLBACK 参数说明： + +|属性|类型|说明| +|---|---|---| +|text|String|搜索输入框输入内容| + +**代码示例** + +```javascript +export default { + created() { + uni.onNavigationBarSearchInputChanged((e) => { + console.log("输入内容："+ e.text); + }) + } +} +``` + +##### uni.onNavigationBarSearchInputConfirmed() + +监听原生标题栏搜索输入框搜索事件，用户点击软键盘上的“搜索”按钮时触发。 + + +**代码示例** + +```javascript +export default { + created() { + uni.onNavigationBarSearchInputConfirmed(() => { + console.log("用户点击软键盘搜索"); + }) + } +} +``` + +##### uni.onNavigationBarSearchInputClicked() + +监听原生标题栏搜索输入框点击事件。 + + +**代码示例** + +```javascript +export default { + created() { + uni.onNavigationBarSearchInputClicked(() => { + console.log("点击输入框"); + }) + } +} +``` + + +## nvue开发与vue开发的常见区别 +基于原生引擎的渲染，虽然还是前端技术栈，但和web开发肯定是有区别的。 + +比如没有dom、window等对象，比如只支持flex布局，好在`uni-app`一直以来也是推动开发者不使用dom，默认使用flex布局。所以适应起来要好一些。 + +但仍然还有一些区别需要注意： + +- nvue 页面只能使用 flex 布局，不支持其他布局方式。需要注意的是 weex 的 flex 默认为竖向排列，即 ``flex-direction: column``，这与 html 的 flex 默认为横向排列不同。在 nvue 编译为 uni-app模式时，纠正了这个问题，flex 方向默认改为横向排列。 +- weex 下，页面内容高过屏幕高度并不会自动滚动，它没有页面滚动的概念，只有区域滚动，要滚得内容需要套在<scroller>组件下。在 nvue 编译为 uni-app模式时，纠正了这个问题，页面内容过高会自动滚动。 +- weex 下，px是与屏幕宽度相关的动态单位，750px代表成屏幕宽度100%，它的静态单位是wx。在 nvue 编译为 uni-app模式时，纠正了这个问题，rpx是与屏幕宽度相关的动态单位，px是静态单位。 +- 页面开发前，首先想清楚这个页面的纵向内容有什么，哪些是要滚动的，然后每个纵向内容的横轴排布有什么，按 flex 布局设计好界面。 +- 文字内容，必须、只能在<text>组件下。不能在<div>的text里写文字。 +- 支持的css有限，不过并不影响布局出你需要的界面，flex还是非常强大的。[详见](https://weex.apache.org/zh/docs/styles/common-styles.html#%E7%9B%92%E6%A8%A1%E5%9E%8B) +- class 进行绑定时只支持数组语法。 + +## 单位说明 +- weex的css单位支持如下： + * px：以750宽的屏幕为基准动态计算的长度单位，与vue页面中的rpx理念相同。（一定要注意nvue里的px，和vue里的px逻辑不一样） + * wx：与设备屏幕宽度无关的长度单位，与vue页面中的px理念相同 +- uni-app编译模式下单位和普通vue相同，rpx是以750宽屏幕为基准的动态单位。px则是固定像素单位。[详见](/frame?id=尺寸单位) + +## 注意事项 +- 现阶段 nvue 的定位是 vue 的补充。在 App 平台实现一些 vue 上无法实现或性能有问题的场景。 +- nvue 的各组件在安卓端默认是透明的，如果不设置background-color，可能会导致出现重影的问题。 +- 在 App.vue 中定义的全局js变量不会在 nvue 页面生效。globalData是生效的。 +- nvue 不支持 vue 里的 vuex +- nvue 切换横竖屏时可能导致样式出现问题，建议有 nvue 的页面锁定手机方向。 +- 不能在 style 中引入字体文件，nvue 中字体图标的使用参考：[weex 加载自定义字体](https://weex.apache.org/zh/docs/modules/dom.html#addrule)。 +- 目前不支持在 nvue 页面使用 typescript/ts。 +- HBuilderX 1.9.8以前，nvue 不支持运行在Android三方模拟器上。HBuilderX 2.1以前，nvue不支持less等css预编译器。 +- nvue 页面 ``titleNview`` 设为 ``false``时，想要模拟状态栏，可以参考：[https://ask.dcloud.net.cn/article/35111](https://ask.dcloud.net.cn/article/35111)。 \ No newline at end of file diff --git a/docs/use.md b/docs/use.md new file mode 100644 index 0000000000000000000000000000000000000000..49e6bcebb5b723796973aaad8495ef438e7b6568 --- /dev/null +++ b/docs/use.md @@ -0,0 +1,587 @@ + +``uni-app`` 在发布到H5时支持所有vue的语法；发布到App和小程序时，由于平台限制，无法实现全部vue语法，但``uni-app``仍是是对vue语法支持度最高的跨端框架。本文将详细讲解差异。 + +相比Web平台， ``Vue.js`` 在 ``uni-app`` 中使用差异主要集中在两个方面： +- 新增：uni-app除了支持Vue实例的生命周期，还支持应用启动、页面显示等生命周期 +- 受限：相比web平台，在小程序和App端部分功能受限，具体见下。 + +## 生命周期 + +``uni-app`` 完整支持 ``Vue`` 实例的生命周期，同时还新增 [应用生命周期](/frame?id=应用生命周期) 及 [页面生命周期](/frame?id=页面生命周期)。 + +详见Vue官方文档：[生命周期钩子](https://cn.vuejs.org/v2/api/#%E9%80%89%E9%A1%B9-%E7%94%9F%E5%91%BD%E5%91%A8%E6%9C%9F%E9%92%A9%E5%AD%90)。 + +**注意** + +* 不要在选项属性或回调上使用箭头函数，比如 ``created: () => console.log(this.a)`` 或 ``vm.$watch('a', newValue => this.myMethod())``。因为箭头函数是和父级上下文绑定在一起的，``this`` 不会是如你做预期的 ``Vue`` 实例，且 ``this.a`` 或 ``this.myMethod`` 也会是未定义的。 +* 建议使用 `uni-app` 的 `onReady`代替 `vue` 的 `mounted`。 +* 建议使用 `uni-app` 的 `onLoad` 代替 `vue` 的 `created`。 + + +## 模板语法 + +``uni-app`` 完整支持 ``Vue`` 模板语法。 + +详见Vue官方文档：[模板语法](https://cn.vuejs.org/v2/guide/syntax.html)。 + +**注意** +如果使用**老版**的非自定义组件模式，即manifest中`"usingComponents":false`，部分模版语法不支持，但此模式已不再推荐使用，[详见](https://ask.dcloud.net.cn/article/35699)。 + +**老版**非自定义组件模式不支持情况（**新版自定义组件模式已不存在此情况**）： +- 不支持部分复杂的 JavaScript 渲染表达式 +- 不支持过滤器 + +## data 属性 + +``data`` 必须声明为返回一个初始数据对象的函数；否则页面关闭时，数据不会自动销毁，再次打开该页面时，会显示上次数据。 + +```javascript +//正确用法，使用函数返回对象 +data() { + return { + title: 'Hello' + } +} + +//错误写法，会导致再次打开页面时，显示上次数据 +data: { + title: 'Hello' +} +``` + +## 全局变量 + +实现全局变量的方式需要遵循 Vue 单文件模式的开发规范。详细参考：[uni-app全局变量的几种实现方式](https://ask.dcloud.net.cn/article/35021) + +## Class 与 Style 绑定 + +为节约性能，我们将 ``Class`` 与 ``Style`` 的表达式通过 ``compiler`` 硬编码到 ``uni-app`` 中，支持语法和转换效果如下： + +class 支持的语法: + +```html +<view :class="{ active: isActive }">111</view> +<view class="static" v-bind:class="{ active: isActive, 'text-danger': hasError }">222</view> +<view class="static" :class="[activeClass, errorClass]">333</view> +<view class="static" v-bind:class="[isActive ? activeClass : '', errorClass]">444</view> +<view class="static" v-bind:class="[{ active: isActive }, errorClass]">555</view> +``` + +style 支持的语法: + +```html +<view v-bind:style="{ color: activeColor, fontSize: fontSize + 'px' }">666</view> +<view v-bind:style="[{ color: activeColor, fontSize: fontSize + 'px' }]">777</view> +``` + +非H5端不支持 [Vue官方文档：Class 与 Style 绑定](https://cn.vuejs.org/v2/guide/class-and-style.html) 中的 ``classObject`` 和 ``styleObject`` 语法。 + +不支持示例： + +```html +<template> + <view :class="[activeClass]" :style="[baseStyles,overridingStyles]"></view> +</template> + +<script> + export default { + data() { + return { + activeClass: { + 'active': true, + 'text-danger': false + }, + baseStyles: { + color: 'green', + fontSize: '30px' + }, + overridingStyles: { + 'font-weight': 'bold' + } + } + } + } +</script> +``` + +**注意：以``:style=""``这样的方式设置px像素值，其值为实际像素，不会被编译器转换。** + +此外还可以用 ``computed`` 方法生成 ``class`` 或者 ``style`` 字符串，插入到页面中，举例说明： + +```html +<template> + <!-- 支持 --> + <view class="container" :class="computedClassStr"></view> + <view class="container" :class="{active: isActive}"></view> + + <!-- 不支持 --> + <view class="container" :class="computedClassObject"></view> +</template> +<script> + export default { + data () { + return { + isActive: true + } + }, + computed: { + computedClassStr () { + return this.isActive ? 'active' : '' + }, + computedClassObject () { + return { active: this.isActive } + } + } + } +</script> +``` + +**用在组件上** + +非H5端暂不支持在自定义组件上使用 ``Class`` 与 ``Style`` 绑定 + +## 计算属性 + +完整支持 [Vue官方文档：计算属性](https://cn.vuejs.org/v2/guide/computed.html)。 + +## 条件渲染 + +完整支持 [Vue官方文档：条件渲染](https://cn.vuejs.org/v2/guide/conditional.html) + +## 列表渲染 + +完整vue列表渲染 [Vue官方文档：列表渲染](https://cn.vuejs.org/v2/guide/list.html) + +### key + +如果列表中项目的位置会动态改变或者有新的项目添加到列表中，并且希望列表中的项目保持自己的特征和状态（如 ``<input>`` 中的输入内容，``<switch>`` 的选中状态），需要使用 ``:key`` 来指定列表中项目的唯一的标识符。 + +``:key`` 的值以两种形式提供 + +- 使用 ``v-for`` 循环 ``array`` 中 ``item`` 的某个 ``property``，该 ``property`` 的值需要是列表中唯一的字符串或数字，且不能动态改变。 +- 使用 ``v-for`` 循环中 ``item`` 本身，这时需要 ``item`` 本身是一个唯一的字符串或者数字 + +当数据改变触发渲染层重新渲染的时候，会校正带有 ``key`` 的组件，框架会确保他们被重新排序，而不是重新创建，以确保使组件保持自身的状态，并且提高列表渲染时的效率。 + +**如不提供 ``:key``，会报一个 ``warning``， 如果明确知道该列表是静态，或者不必关注其顺序，可以选择忽略。** + +**示例：** + +```html +<template> + <view> + <!-- array 中 item 的某个 property --> + <view v-for="(item,index) in objectArray" :key="item.id"> + {{index +':'+ item.name}} + </view> + <!-- item 本身是一个唯一的字符串或者数字时，可以使用 item 本身 --> + <view v-for="(item,index) in stringArray" :key="item"> + {{index +':'+ item}} + </view> + </view> +</template> +<script> +export default { + data () { + return { + objectArray:[{ + id:0, + name:'li ming' + },{ + id:1, + name:'wang peng' + }], + stringArray:['a','b','c'] + } + } +} + +</script> +``` + +### 注意事项 +* 在H5平台 使用 v-for 循环整数时和其他平台存在差异，如 `v-for="(item, index) in 10"` 中，在H5平台 item 从 1 开始，其他平台 item 从 0 开始，可使用第二个参数 index 来保持一致。 +* 在非H5平台 循环对象时不支持第三个参数，如 `v-for="(value, name, index) in object"` 中，index 参数是不支持的。 + +## 事件处理器 + +几乎全支持 [Vue官方文档：事件处理器](https://cn.vuejs.org/v2/guide/events.html) + +```javascript +// 事件映射表，左侧为 WEB 事件，右侧为 ``uni-app`` 对应事件 +{ + click: 'tap', + touchstart: 'touchstart', + touchmove: 'touchmove', + touchcancel: 'touchcancel', + touchend: 'touchend', + tap: 'tap', + longtap: 'longtap', + input: 'input', + change: 'change', + submit: 'submit', + blur: 'blur', + focus: 'focus', + reset: 'reset', + confirm: 'confirm', + columnchange: 'columnchange', + linechange: 'linechange', + error: 'error', + scrolltoupper: 'scrolltoupper', + scrolltolower: 'scrolltolower', + scroll: 'scroll' +} +``` + +**注意：** + +<!-- * 事件映射表中没有的原生事件也可以使用，例如``map``组件的``regionchange`` 事件直接在组件上写成 ``@regionchange``,同时这个事件也非常特殊，它的 ``event`` ``type`` 有 ``begin`` 和 ``end`` 两个，导致我们无法在``handleProxy`` 中区分到底是什么事件，所以你在监听此类事件的时候同时监听事件名和事件类型既 +``<map @regionchange="functionName" @end="functionName" @begin="functionName"><map>``。 --> +* 为兼容各端，事件需使用 ``v-on`` 或 ``@`` 的方式绑定，请勿使用小程序端的``bind`` 和 ``catch`` 进行事件绑定。 +* 事件修饰符 + * ``.stop``：各平台均支持， 使用时会阻止事件冒泡，在非 H5 端同时也会阻止事件的默认行为 + * ``.prevent`` 仅在 H5 平台支持 + * ``.self``：仅在 H5 平台支持 + * ``.once``：仅在 H5 平台支持 + * ``.capture``：仅在 H5 平台支持 + * ``.passive``：仅在 H5 平台支持 +* 若需要禁止蒙版下的页面滚动，可使用 ``@touchmove.stop.prevent="moveHandle"``，moveHandle 可以用来处理 touchmove 的事件，也可以是一个空函数。 + ```html + <view class="mask" @touchmove.stop.prevent="moveHandle"></view> + ``` +* 按键修饰符：``uni-app``运行在手机端，没有键盘事件，所以不支持按键修饰符。 + + +## 表单控件绑定 + +支持 [Vue官方文档：表单控件绑定](https://cn.vuejs.org/v2/guide/forms.html)。 + +建议开发过程中直接使用 [uni-app：表单组件](component/button)。用法示例： + +H5 的select 标签用 picker 组件进行代替 + +```html +<template> + <view> + <picker @change="bindPickerChange" :value="index" :range="array"> + <view class="picker"> + 当前选择：{{array[index]}} + </view> + </picker> + </view> +</template> + +<script> +export default { + data () { + return { + index: 0, + array: ['A', 'B', 'C'] + } + }, + methods: { + bindPickerChange (e) { + console.log(e) + } + } +} + +</script> +``` + +表单元素 radio 用 radio-group 组件进行代替 + +```html +<template> + <view> + <radio-group class="radio-group" @change="radioChange"> + <label class="radio" v-for="(item, index) in items" :key="item.name"> + <radio :value="item.name" :checked="item.checked"/> {{item.value}} + </label> + </radio-group> + </view> +</template> + +<script> +export default { + data () { + return { + items: [ + {name: 'USA', value: '美国'}, + {name: 'CHN', value: '中国', checked: 'true'}, + {name: 'BRA', value: '巴西'}, + {name: 'JPN', value: '日本'}, + {name: 'ENG', value: '英国'}, + {name: 'TUR', value: '法国'} + ] + } + }, + methods: { + radioChange (e) { + console.log('radio发生change事件，携带value值为：', e.target.value) + } + } +} + +</script> + +``` + +## v-html指令 + +由于非H5端，不支持dom和普通html元素，所以自然非H5端也不支持v-html。 + +跨端的富文本处理方案详见：[https://ask.dcloud.net.cn/article/35772](https://ask.dcloud.net.cn/article/35772) + +## 组件 + +### Vue 组件 + +组件是 ``vue`` 技术中非常重要的部分，组件使得与ui相关的轮子可以方便的制造和共享，进而使得vue使用者的开发效率大幅提升。 + +uni-app搭建了组件的插件市场，可大幅提升开发者的效率。[https://ext.dcloud.net.cn/](https://ext.dcloud.net.cn/) + +在项目的/component目录下存放组件，在要显示组件的页面中则分为3步：导入、注册和使用。 + +可以这个[评分组件](https://ext.dcloud.net.cn/plugin?id=33)的使用为例，了解vue组件的使用方式。 + +```html +<template> + <view> + <uni-rate value="2"></uni-rate> <!-- 第三步，使用组件。并传值点亮2颗星 --> + </view> +</template> +<script> +import uniRate from "@/components/uni-rate/uni-rate.vue" //第一步，导入组件 +export default { + components: { + uniRate //第二步，注册组件 + } +} +</script> +``` + +**uni-app只支持vue单文件组件（.vue 组件）**。其他的诸如：动态组件，自定义 ``render``，和``<script type="text/x-template">`` 字符串模版等，在非H5端不支持。 + +详细的非H5端不支持列表： + +* ``Slot``（``scoped`` 暂时还没做支持） +* 动态组件 +* 异步组件 +* ``inline-template`` +* ``X-Templates`` +* ``keep-alive`` +* ``transition`` （可使用 [animation](/api/ui/animation) 或 CSS 动画替代） +* [老的非自定义组件编译模式](https://ask.dcloud.net.cn/article/35843)不支持在组件引用时，在组件上定义 ``click`` 等原生事件、``v-show``（可用 ``v-if`` 代替）和 ``class`` ``style`` 等样式属性(例：``<card class="class-name"> </card>`` 样式是不会生效的)。建议更新为自定义组件模式 +* [老的非自定义组件编译模式](https://ask.dcloud.net.cn/article/35843)组件里使用 ``slot`` 嵌套的其他组件时不支持 ``v-for``。建议更新为自定义组件模式 + +[Vue官方文档参考：组件](https://cn.vuejs.org/v2/guide/components.html) 。 + +### uni-app内置基础组件 + +``uni-app`` 内置了小程序的所有[组件](component/)，比如： ``picker``,``map`` 等，需要注意的是原生组件上的事件绑定，需要以 ``vue`` 的事件绑定语法来绑定，如 ``bindchange="eventName"`` 事件，需要写成 ``@change="eventName"`` + +**示例** + +```html +<picker mode="date" :value="date" start="2015-09-01" end="2017-09-01" @change="bindDateChange"> + <view class="picker"> + 当前选择: {{date}} + </view> +</picker> +``` + +### 全局组件 + +```uni-app``` 支持配置全局组件，需在 ``main.js`` 里进行全局注册，注册后就可在所有页面里使用该组件。 + +**注意**：``Vue.component`` 的第一个参数必须是静态的字符串。 + +**示例** + +main.js 里进行全局导入和注册 +```javascript +import Vue from 'vue' +import pageHead from './components/page-head.vue' +Vue.component('page-head',pageHead) +``` +index.vue 里可直接使用组件 +```html +<template> + <view> + <page-head></page-head> + </view> +</template> +``` + +### 命名限制 +在 `uni-app` 中以下这些作为保留关键字，不可作为组件名。 + +- `a` +- `canvas` +- `cell` +- `content` +- `countdown` +- `datepicker` +- `div` +- `element` +- `embed` +- `header` +- `image` +- `img` +- `indicator` +- `input` +- `link` +- `list` +- `loading-indicator` +- `loading` +- `marquee` +- `meta` +- `refresh` +- `richtext` +- `script` +- `scrollable` +- `scroller` +- `select` +- `slider-neighbor` +- `slider` +- `slot` +- `span` +- `spinner` +- `style` +- `svg` +- `switch` +- `tabbar` +- `tabheader` +- `template` +- `text` +- `textarea` +- `timepicker` +- `trisition-group` +- `trisition` +- `video` +- `view` +- `web` + +**Tips** + +- 除以上列表中的名称外，标准的 HTML 及 SVG 标签名也不能作为组件名。 + + +## 常见问题 + +**1. 如何获取上个页面传递的数据** + +在 ``onLoad`` 里得到，``onLoad`` 的参数是其他页面打开当前页面所传递的数据。 + +**2. 如何设置全局的数据和全局的方法** + +``uni-app`` 内置了 [vuex](https://vuex.vuejs.org/zh/guide/) ，在app里的使用，可参考``hello-uniapp`` ``store/index.js``。 + +```javascript +//store.js +import Vue from 'vue' +import Vuex from 'vuex' +Vue.use(Vuex) +const store = new Vuex.Store({ + state: {...}, + mutations: {...}, + actions: {...} +}) + +export default store + +//main.js +... +import store from './store' +Vue.prototype.$store = store +const app = new Vue({ + store,... +}) +... + +//test.vue 使用时： +import {mapState,mapMutations} from 'vuex' +``` + +**3. 如何捕获 app 的 onError** + +由于 ``onError`` 并不是完整意义的生命周期，所以只提供一个捕获错误的方法，在 ``app`` 的根组件上添加名为 ``onError`` 的回调函数即可。如下： + +```javascript +export default { + // 只有 app 才会有 onLaunch 的生命周期 + onLaunch () { + // ... + }, + + // 捕获 app error + onError (err) { + console.log(err) + } +} +``` + +**4. 组件属性设置不生效解决办法** + +当重复设置某些属性为相同的值时，不会同步到view层。 +例如：每次将scroll-view组件的scroll-top属性值设置为0，只有第一次能顺利返回顶部。 +这和props的单向数据流特性有关，组件内部scroll-top的实际值改动后，其绑定的属性并不会一同变化。 + +解决办法有两种（以scroll-view组件为例）： + +* 监听scroll事件，记录组件内部变化的值，在设置新值之前先设置为记录的当前值 + +```html +<scroll-view :scroll-top="scrollTop" scroll-y="true" @scroll="scroll"> +``` + +```js +export default { + data() { + return { + scrollTop: 0, + old: { + scrollTop: 0 + } + } + }, + methods: { + scroll: function(e) { + this.old.scrollTop = e.detail.scrollTop + }, + goTop: function(e) { + this.scrollTop = this.old.scrollTop + this.$nextTick(function() { + this.scrollTop = 0 + }); + } + } +} +``` + +* 监听scroll事件，获取组件内部变化的值，实时更新其绑定值 + +```html +<scroll-view :scroll-top="scrollTop" scroll-y="true" @scroll="scroll"> +``` + +```js +export default { + data() { + return { + scrollTop: 0, + } + }, + methods: { + scroll: function(e) { + this.scrollTop = e.detail.scrollTop + }, + goTop: function(e) { + this.scrollTop = 0 + } + } +} +``` + +第二种解决方式在某些组件可能造成抖动，推荐第一种解决方式。 \ No newline at end of file diff --git a/package.json b/package.json index d5bfab4cd0f42e0085d7abb29d5e5dfebec69e2a..b6cc6dab904844a8d082257f9acdb9f047ea176b 100644 --- a/package.json +++ b/package.json @@ -53,7 +53,7 @@ "vue-router": "^3.0.1", "vue-template-compiler": "^2.6.8", "webpack": "^4.18.0", - "webpack-bundle-analyzer": "^3.0.3", + "webpack-bundle-analyzer": "^3.3.2", "webpack-virtual-modules": "^0.1.10" }, "eslintConfig": { diff --git a/yarn.lock b/yarn.lock index 9542284650396a44df645f7341a530bd9ee9215b..1199a7d87aeab6ee35d201ff58443ce9ea0e0302 100644 --- a/yarn.lock +++ b/yarn.lock @@ -4582,8 +4582,8 @@ js-tokens@^3.0.2: resolved "https://registry.yarnpkg.com/js-tokens/-/js-tokens-3.0.2.tgz#9866df395102130e38f7f996bceb65443209c25b" js-yaml@^3.12.0, js-yaml@^3.9.0, js-yaml@^3.9.1: - version "3.12.2" - resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-3.12.2.tgz#ef1d067c5a9d9cb65bd72f285b5d8105c77f14fc" + version "3.13.1" + resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-3.13.1.tgz#aff151b30bfdfa8e49e05da22e7415e9dfa37847" dependencies: argparse "^1.0.7" esprima "^4.0.0" @@ -4824,8 +4824,8 @@ locate-path@^3.0.0: path-exists "^3.0.0" lodash.defaultsdeep@^4.6.0: - version "4.6.0" - resolved "https://registry.yarnpkg.com/lodash.defaultsdeep/-/lodash.defaultsdeep-4.6.0.tgz#bec1024f85b1bd96cbea405b23c14ad6443a6f81" + version "4.6.1" + resolved "https://registry.yarnpkg.com/lodash.defaultsdeep/-/lodash.defaultsdeep-4.6.1.tgz#512e9bd721d272d94e3d3a63653fa17516741ca6" lodash.get@^4.4.2: version "4.4.2" @@ -4856,8 +4856,8 @@ lodash.uniq@^4.5.0: resolved "https://registry.yarnpkg.com/lodash.uniq/-/lodash.uniq-4.5.0.tgz#d0225373aeb652adc1bc82e4945339a842754773" lodash@^4.17.10, lodash@^4.17.11, lodash@^4.17.3, lodash@^4.17.4, lodash@^4.17.5, lodash@^4.3.0: - version "4.17.11" - resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.11.tgz#b39ea6229ef607ecd89e2c8df12536891cac9b8d" + version "4.17.15" + resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.15.tgz#b447f6670a0455bbfeedd11392eff330ea097548" log-ok@^0.1.1: version "0.1.1" @@ -7707,9 +7707,9 @@ webidl-conversions@^4.0.2: version "4.0.2" resolved "https://registry.yarnpkg.com/webidl-conversions/-/webidl-conversions-4.0.2.tgz#a855980b1f0b6b359ba1d5d9fb39ae941faa63ad" -webpack-bundle-analyzer@^3.0.3, webpack-bundle-analyzer@^3.0.4: - version "3.1.0" - resolved "https://registry.yarnpkg.com/webpack-bundle-analyzer/-/webpack-bundle-analyzer-3.1.0.tgz#2f19cbb87bb6d4f3cb4e59cb67c837bd9436e89d" +webpack-bundle-analyzer@^3.0.4, webpack-bundle-analyzer@^3.3.2: + version "3.3.2" + resolved "https://registry.yarnpkg.com/webpack-bundle-analyzer/-/webpack-bundle-analyzer-3.3.2.tgz#3da733a900f515914e729fcebcd4c40dde71fc6f" dependencies: acorn "^6.0.7" acorn-walk "^6.1.1"
xxx
+ +┌─components +├─hybrid +│ └─html +│ ├─css +│ │ └─test.css +│ ├─img +│ │ └─icon.png +│ ├─js +│ │ └─test.js +│ └─local.html +├─pages +│ └─index +│ └─index.vue +├─static +├─main.js +├─App.vue +├─manifest.json +└─pages.json + +
+┌─components +├─hybrid +│ └─html +│ ├─css +│ │ └─test.css +│ ├─img +│ │ └─icon.png +│ ├─js +│ │ └─test.js +│ └─local.html +├─pages +│ └─index +│ └─index.vue +├─static +├─main.js +├─App.vue +├─manifest.json +└─pages.json +
+ 微信小程序版
+
+
+ 
+ 支付宝小程序版
+
+
+ 
+ 百度小程序版
+
+
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
赞助我们
+ 
+ 
+ 
+ 
+ 
+