diff --git a/docs/api/location/map.md b/docs/api/location/map.md index a66be62edf868f4dcafa1da490b0df9823f2acf4..caf1f229bfe997c87f33bb7b3d359102606ed36f 100644 --- a/docs/api/location/map.md +++ b/docs/api/location/map.md @@ -186,7 +186,7 @@ mapContext |complete |function | |否 |接口调用结束的回调函数(调用成功、失败都会执行) | -**mapContext (地图服务商差异)** +**mapContext (App平台地图服务商差异)** |属性 |说明 |高德是否支持 |google地图是否支持 | |:---- |:---- |:---- |:---- | @@ -343,7 +343,7 @@ mapContext ``` -## mapSearch 模块(仅app-nvue支持) +## mapSearch 模块(仅app-nvue支持,Goolge地图不支持) #### reverseGeocode(Object,callback);@reverseGeocode > 反向地理编码 diff --git a/docs/api/ui/menuButton.md b/docs/api/ui/menuButton.md index adcc713dc74eba2bb5090665291379f36b17b9b8..c4c0ae1353c57301ee03130d9bb09371e9b56578 100644 --- a/docs/api/ui/menuButton.md +++ b/docs/api/ui/menuButton.md @@ -8,7 +8,7 @@ |App |H5 |微信小程序 |支付宝小程序 |百度小程序 |字节跳动小程序|飞书小程序 |QQ小程序 | |:-: |:-:|:-: |:-: |:-: |:-: |:-: |:-: | -|x |x |√ |x |√ |√ |x|√ | +|x |x |√ |√ |√ |√ |x|√ | **返回值说明** diff --git a/docs/app-maps.md b/docs/app-maps.md new file mode 100644 index 0000000000000000000000000000000000000000..9364a9e3d2e76bdea3a537c2df4d8a6fea4ee53d --- /dev/null +++ b/docs/app-maps.md @@ -0,0 +1,90 @@ +App端地图模块封装了市场上主流的三方地图SDK,提供JS API统一调用Android、iOS原生地图功能。 + +|项目类型|API| +|:-|:-| +|uni-app|[uni.getLocation(OBJECT)](https://uniapp.dcloud.io/api/location/location?id=getlocation)、[uni.chooseLocation(OBJECT)](https://uniapp.dcloud.io/api/location/location?id=chooselocation)、[uni.openLocation(OBJECT)](https://uniapp.dcloud.io/api/location/open-location?id=openlocation)、[uni.createMapContext(mapId,this)](api/location/map?id=createmapcontext)、[map](component/map)组件| +|5+App/Wap2App|[plus.maps.*](https://www.html5plus.org/doc/zh_cn/maps.html) + +使用地图功能需在项目manifest.json的“App模块配置”中勾选“Maps(地图)”,并根据项目实际情况勾选使用的三方地图SDK: +![](https://partner-dcloud-native.oss-cn-hangzhou.aliyuncs.com/images/uniapp/maps/modules.png) + +> 提示:App模块配置需提交云端打包后才能生效,真机运行调试时请使用[自定义基座](http://ask.dcloud.net.cn/article/35115) + +**注意** +- 使用高德地图、百度地图需要商业授权,详情参考 [商业授权相关说明](app-geolocation?id=business) +- uni-app项目中仅nvue页面支持使用原生SDK +- uni-app项目暂时不支持使用百度地图 + + +### 高德地图 + +#### 申请高德地图Key +使用前需到[高德开放平台](https://lbs.amap.com/)创建应用并申请Key +- 登录 [高德开放平台](https://lbs.amap.com/),进入“控制台”,如果没有注册账号请先根据页面提示注册账号 +- 打开 “应用管理” -> “我的应用”页面,点击“创建新应用”,根据页面提示填写内容创建应用 +- 在应用下点击“添加”为应用添加Key,根据需要分别为Android平台、iOS平台申请Key + +#### 配置使用高德地图 +打开项目的manifest.json文件,在“App模块配置”项的“Maps(地图)”下,勾选“高德地图”: +![](https://partner-dcloud-native.oss-cn-hangzhou.aliyuncs.com/images/uniapp/maps/amap.png) + +#### 参数说明 +- appkey_android +高德开放平台申请的Android平台Key +- appkey_ios +高德开放平台申请的iOS平台Key + +**注意** +- HBuilderX标准基座默认使用高德地图SDK,可以直接真机运行测试,此时配置的应用包名、签名信息不生效,正式发布前请提交云端打包或使用[自定义调试基座](https://ask.dcloud.net.cn/article/35115)测试 +- 本地离线打包参考[Android平台高德地图模块配置](https://nativesupport.dcloud.net.cn/AppDocs/usemodule/androidModuleConfig/map?id=%e9%ab%98%e5%be%b7%e5%9c%b0%e5%9b%be)、[iOS平台高德地图模块配置](https://nativesupport.dcloud.net.cn/AppDocs/usemodule/iOSModuleConfig/map?id=%e9%ab%98%e5%be%b7%e5%9c%b0%e5%9b%be) + + +### 百度地图 + +#### 申请百度地图Key +使用前需到[百度开放平台](https://lbsyun.baidu.com/)创建应用并申请Key +- 登录 [百度开放平台](https://lbsyun.baidu.com/),进入“控制台”,如果没有注册账号请先根据页面提示注册账号 +- 打开 “应用管理” -> “我的应用”页面,点击“创建应用”,根据页面提示填写内容创建应用获取Key + +#### 配置使用百度地图 +打开项目的manifest.json文件,在“App模块配置”项的“Maps(地图)”下,勾选“百度地图”: +![](https://partner-dcloud-native.oss-cn-hangzhou.aliyuncs.com/images/uniapp/maps/bmap.png) + +#### 参数说明 +- appkey_android +百度地图开放平台申请的Android平台Key +- appkey_ios +百度地图开放平台申请的iOS平台Key + +**注意** +- HBuilderX标准基座没有包含百度地图,请配置后使用[自定义调试基座](https://ask.dcloud.net.cn/article/35115)测试 +- 本地离线打包参考[Android平台百度地图模块配置](https://nativesupport.dcloud.net.cn/AppDocs/usemodule/androidModuleConfig/map?id=%e7%99%be%e5%ba%a6%e5%9c%b0%e5%9b%be)、[iOS平台百度地图模块配置](https://nativesupport.dcloud.net.cn/AppDocs/usemodule/iOSModuleConfig/map?id=%e7%99%be%e5%ba%a6%e5%9c%b0%e5%9b%be) + + +### Google地图 + +> HBuilderX3.4.0+版本新增支持 + +#### 申请Google地图Key +使用前需到[Google地图开放平台](https://console.cloud.google.com/google/maps-apis)创建应用并申请APIKey +- 登录 [Google地图开放平台](https://console.cloud.google.com/google/maps-apis),如果没有注册账号请先根据页面提示注册账号 +- 根据页面提示新建项目,也可以选择已经存在的项目 +- 打开“凭证”页面,点击 “创建凭证” -> “API密钥”获取APIKey,由于Google地图需要收费,为了保证安全建议配置限制密钥 + + Android平台 + 在“应用限制”下勾选“Android应用”,并添加绑定“软件包名称”、“SHA-1证书指纹”;在“API限制”下建议勾选“不限制密钥” + + iOS平台 + 在“应用限制”下勾选“iOS应用”,并添加绑定“软件包ID”;在“API限制”下建议勾选“不限制密钥” + +#### 配置使用Google地图 +打开项目的manifest.json文件,在“App模块配置”项的“Maps(地图)”下,勾选“Google地图”: +![](https://partner-dcloud-native.oss-cn-hangzhou.aliyuncs.com/images/uniapp/maps/gmap.png) + +#### 参数说明 +- APIKey_android +Google地图开放平台申请的Android平台APIKey +- APIKey_ios +Google地图开放平台申请的iOS平台APIKey + +**注意** +- Google地图在Android、iOS平台SDK不支持POI搜索,无法直接使用[uni.chooseLocation(OBJECT)](https://uniapp.dcloud.io/api/location/location?id=chooselocation),可以申请Web Server APIKey在业务服务器端进行POI搜索,在App端自己实现chooseLocation相关功能 +- HBuilderX标准基座没有包含Google地图,请配置后使用[自定义调试基座](https://ask.dcloud.net.cn/article/35115)测试 diff --git a/docs/collocation/pages.md b/docs/collocation/pages.md index e3c83277b7317e00561fd0d6f899fd15063b17a8..e9a043185ac127ae6dd379c2ba09d434dbd959ee 100644 --- a/docs/collocation/pages.md +++ b/docs/collocation/pages.md @@ -330,7 +330,7 @@ uni-app 2.9+ 新增 leftWindow, topWindow, rightWindow 配置。用于解决宽 |onReachBottomDistance|Number|50|页面上拉触底事件触发时距页面底部距离,单位只支持px,详见[页面生命周期](/tutorial/page.html#lifecycle)|| |backgroundColorTop|HexColor|#ffffff|顶部窗口的背景色(bounce回弹区域)|仅 iOS 平台| |backgroundColorBottom|HexColor|#ffffff|底部窗口的背景色(bounce回弹区域)|仅 iOS 平台| -|disableSwipeBack|Boolean|false|是否禁用滑动返回|仅 iOS 平台(HBuilder X 3.4.0+)| +|disableSwipeBack|Boolean|false|是否禁用滑动返回|App-iOS(3.4.0+)| |titleImage|String||导航栏图片地址(替换当前文字标题),支付宝小程序内必须使用https的图片链接地址|支付宝小程序、H5| |transparentTitle|String|none|导航栏透明设置。支持 always 一直透明 / auto 滑动自适应 / none 不透明|支付宝小程序、H5、APP| |titlePenetrate|String|NO|导航栏点击穿透|支付宝小程序、H5| diff --git a/docs/component/_sidebar.md b/docs/component/_sidebar.md index 1fccb376708b7122339b96fed94984001ff20dbe..da066f76c2bb03e549d075ff6fadccac40c07c55 100644 --- a/docs/component/_sidebar.md +++ b/docs/component/_sidebar.md @@ -113,4 +113,4 @@ * [更多插件市场的组件](https://ext.dcloud.net.cn/?cat1=2) * [ui 设计资源](component/uniui/resource.md) * [datacom 组件规范](component/datacom.md) -* [组件库选型指南](component/component-selection.md) \ No newline at end of file +* [组件库选型指南](component/component-selection.md) diff --git a/docs/component/map.md b/docs/component/map.md index ab290d77c18ca7ec8bc3d125692bb740c988ddf2..7ce609948d6ce5e18a81f818802774ddd87c7ceb 100644 --- a/docs/component/map.md +++ b/docs/component/map.md @@ -238,7 +238,7 @@ export default { ``` -## 地图服务商差异 +## App平台地图服务商差异 ### Map 地图组件 @@ -303,7 +303,9 @@ Q:应用中使用了 `` 组件,打包为App时,提示缺少权限模 A:App端原生地图,依赖第三方的 SDK,因此打包移动应用时,需要在manifest中勾选相关的权限并填写 key 信息。详见:[https://ask.dcloud.net.cn/article/29](https://ask.dcloud.net.cn/article/29) Q:国外应用想使用谷歌地图/google地图怎么办? -A:1. 可以在web-view下调用谷歌的web地图;2. 可以写一个原生插件封装谷歌原生地图,具体参考uni-app插件市场的原生插件开发教程。插件市场已有三方写好的[地图插件](https://ext.dcloud.net.cn/search?q=%E8%B0%B7%E6%AD%8C%E5%9C%B0%E5%9B%BE)。 +A: App 3.3.4+ 已支持 Google 地图, App 3.3.4 以下版本使用下面的方案 + 1. 可以在web-view下调用谷歌的web地图 + 2. 可以写一个原生插件封装谷歌原生地图,具体参考uni-app插件市场的原生插件开发教程。插件市场已有三方写好的[地图插件](https://ext.dcloud.net.cn/search?q=%E8%B0%B7%E6%AD%8C%E5%9C%B0%E5%9B%BE)。 ### 三方定位和地图服务收费说明 diff --git a/docs/tutorial/_sidebar.md b/docs/tutorial/_sidebar.md index 624222235831ff522b47b9888270006067cbbb28..da6189866876db34959f0a6c01cf0dc5a26ffd47 100644 --- a/docs/tutorial/_sidebar.md +++ b/docs/tutorial/_sidebar.md @@ -48,6 +48,7 @@ * [启动界面](/tutorial/app-splashscreen.md) * [功能模块](/tutorial/app-modules.md) * [Geolocation(定位)](/tutorial/app-geolocation.md) + * [Maps(地图)](/tutorial/app-maps.md) * [Payment(支付)](/tutorial/app-payment.md) * [Apple应用内支付](/tutorial/app-payment-aip.md) * [支付宝支付](/tutorial/app-payment-alipay.md) @@ -61,6 +62,7 @@ * [友盟统计](/tutorial/app-statistic-umeng.md) * [Google统计](/tutorial/app-statistic-google.md) * [其它配置](/tutorial/app-ios-dsym.md) + * [iOS应用访问白名单](/tutorial/app-ios-schemewhitelist.md) * [iOS符号表文件](/tutorial/app-ios-dsym.md) * [App 上架注意](/tutorial/store.md) * [国内应用市场上架](/tutorial/android-store.md) diff --git a/docs/uniCloud/cf-functions.md b/docs/uniCloud/cf-functions.md index 554a17abf308d46d6fed7aac5cd11ff4351e93dd..7044086b1158441e0c199c3d9cfeb776982658a2 100644 --- a/docs/uniCloud/cf-functions.md +++ b/docs/uniCloud/cf-functions.md @@ -226,6 +226,15 @@ uniCloud服务器给客户端返回的数据格式是json,但json的格式具 } ``` +HBuilderX内使用代码块`ufr`可以快速输入以下代码: + +```js +return { + errCode: 0, + errMsg: '' +} +``` + - errCode errCode在成功时应返回数字`0`,失败时应返回一个以插件id开头的“字符串”,每个单词以连字符(`-`)分割。做出这样的规定是为了防止不同插件之间出现重复错误码 diff --git a/docs/uniCloud/cloud-obj.md b/docs/uniCloud/cloud-obj.md index 6eb72a7dd30e757ee2d7a173c3f489e89fbc2c8a..1fb73e64114992aeb911815147ca16ce76f17f21 100644 --- a/docs/uniCloud/cloud-obj.md +++ b/docs/uniCloud/cloud-obj.md @@ -2,11 +2,65 @@ > 新增于 HBuilderX 3.4.0 -云对象本质上是对云函数的封装,和传统方式通过callFunction调用云函数相比,云对象写法更简单,调用更清晰。另外云对象默认支持[uniCloud响应体规范](uniCloud/cf-functions.md?id=resformat),对于满足规范的错误响应会在客户端自动抛出错误,开发者可以少写很多繁琐的判断。 +## 背景和优势 -以下面的云函数为例,对比一下云对象和传统云函数 +20年前,restful接口开发开始流行,服务器编写接口,客户端调用接口,传输json。 -**传统callFunction方式代码如下:** +现在,替代restful的新模式来了。 + +云对象,服务器编写API,客户端调用API,不再开发传输json的接口。思路更清晰、代码更精简。 + +比如服务端编写一个云对象todo,该对象有add、get、remove、update等方法。客户端的js则可以直接import这个todo云对象,直接调用add等方法。 + +服务器示例代码如下: + +HBuilderX中在uniCloud/cloudfunctions目录新建云函数,选择类型为云对象,起名为todo。打开云对象入口index.obj.js,添加一个add方法。 + +```js +// 云对象名:todo +module.exports = { + add(title, content) { + title = title.trim() + content = content.trim() + if(!title || !content) { + return { + errCode: 'INVALID_TODO', + errMsg: 'TODO标题或内容不可为空' + } + } + // ...其他逻辑 + return { + errCode: 0, + errMsg: '创建成功' + } + } +} +``` + +然后在客户端的js中,import这个todo对象,调用它的add方法 + +```js +const todo = uniCloud.importObject('todo') //第一步导入云对象 +async function addTodo () { + try { + const res = await todo.add('title demo', 'content demo') //导入云对象后就可以直接调用该对象的方法了,注意使用异步await + uni.showToast({ + title: '创建成功' + }) + } catch (e) { + // 符合uniCloud响应体规范 https://uniapp.dcloud.net.cn/uniCloud/cf-functions?id=resformat,自动抛出此错误 + uni.showModal({ + title: '创建失败', + content: e.errMsg, + showCancel: false + }) + } +} +``` + +可以看到云对象的代码非常清晰,代码行数也只有33行。 + +而同样的逻辑,使用传统的接口方式则需要更多代码,见下: ```js // 传统方式调用云函数-云函数代码 @@ -83,60 +137,26 @@ async function addToDo () { } ``` -**使用云对象的写法如下:** - -```js -// 使用云对象的写法-云对象代码 -// 云对象名:todo -// 云对象入口index.obj.js内容如下 -module.exports = { - add(title, content) { - title = title.trim() - content = content.trim() - if(!title || !content) { - return { - errCode: 'INVALID_TODO', - errMsg: 'TODO标题或内容不可为空' - } - } - // ...其他逻辑 - return { - errCode: 0, - errMsg: '创建成功' - } - } -} +以上传统开发需要68行代码,对比云对象的33行代码,不但工作量大,而且逻辑也不如云对象清晰。 -// 使用云对象的写法-客户端代码 -const todo = uniCloud.importObject('todo') -async function addTodo () { - try { - const res = await todo.add('title demo', 'content demo') - uni.showToast({ - title: '创建成功' - }) - } catch (e) { - // 此形式响应符合uniCloud响应体规范中的错误响应,自动抛出此错误 - // { - // errCode: 'INVALID_TODO', - // errMsg: 'TODO标题或内容不可为空' - // } - uni.showModal({ - title: '创建失败', - content: e.errMsg, - showCancel: false - }) - } -} -``` +_注:以上例子仅用于方便初学者理解。实质上对于简单的数据库操作,使用clientDB在前端直接操作数据库是更简单、代码更少的方案,[另见](/uniCloud/clientdb)_ -可以看到大量的业务无关代码被简化掉,开发效率UP。此外通过`ObjectName.MethodName`的方式调用云函数和云端写法完全一致,心智负担大幅减小。请阅读以下内容深入了解云对象 +总结下云对象带来的好处: +1. 更清晰的逻辑 +2. 更精简的代码 +3. 更少的协作成本(以及矛盾~) +4. 客户端调用时在ide里有完善的代码提示,方法参数均可提示。(传输json可没法在ide里提示) +5. 自动支持[uniCloud响应体规范](uniCloud/cf-functions.md?id=resformat),方便错误拦截和统一处理 ## 快速上手 ### 创建云对象 -和创建云函数一样,在`cloudfunctions`目录右键即可输入云对象名称创建云对象,此处以云对象todo为例,创建的云对象包含一个`index.obj.js`。内容如下 +云对象,其实是对云函数的封装。和创建云函数一样,在`uniCloud/cloudfunctions`目录右键新建云函数,选择云对象类型,输入云对象名称创建云对象,此处以云对象todo为例,创建的云对象包含一个`index.obj.js`。 + +![创建云对象](https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/1c2bff0e-3c93-4417-bc21-90a842c779af.jpg) + +一个空的云对象内容如下 ```js // cloudfunctions/todo/index.obj.js @@ -159,7 +179,7 @@ module.exports = { errMsg: 'TODO标题或内容不可为空' } } - // ...其他逻辑 + // ...其他逻辑,如操作todo数据表添加数据 return { errCode: 0, errMsg: '创建成功' @@ -179,6 +199,12 @@ const todo = uniCloud.importObject('todo') const res = await todo.add('title demo', 'content demo') ``` +通过代码块`cco`可以快捷的输入以下代码: + +```js +const todo = uniCloud.importObject('todo') +``` + ## 云对象的API@api 云对象的方法内可以通过this上的一些接口获取一些信息 @@ -305,9 +331,9 @@ module.exports = { ### 预处理 _before@before -云对象内可以创建一个特殊的方法_after用来在调用方法之前进行一些额外的操作 +云对象内可以创建一个特殊的方法_before,用来在调用常规方法之前进行预处理,一般用于拦截器、身份验证、参数校验等。 -请看以下示例: +以下示例的逻辑是,当客户端调用todo云对象的add方法时,会先执行_before方法中的逻辑,判断为add方法时校验了客户端token,校验失败则直接报错返回客户端,校验通过继续执行add方法。 ```js // todo/index.obj.js @@ -329,7 +355,7 @@ module.exports = { ### 后处理 _after@after -云对象内可以创建一个特殊的方法_after用来处理本次调用方法的返回结果或者抛出的错误 +与预处理`_before`对应的是后处理`_after`。云对象内可以创建一个特殊的方法_after用来再加工处理本次调用方法的返回结果或者抛出的错误 请看以下示例: @@ -462,4 +488,14 @@ const res = await todo.add('title demo', 'content demo') ## 本地运行@run-local -云对象无法直接本地运行,可以通过其他云函数调用本地云对象(在调用云对象的云函数右键本地运行),或者客户端调用本地云对象的方式来实现云对象的本地运行。 \ No newline at end of file +云对象无法直接本地运行,可以通过其他云函数调用本地云对象(在调用云对象的云函数右键本地运行),或者客户端调用本地云对象的方式来实现云对象的本地运行。 + +## 推荐最佳实践 + +uniCloud的服务器和客户端交互,有云函数、云对象、clientDB三种方式。 + +从云对象发布后,不再推荐使用传统云函数了。 + +如果是以数据库操作为主,则推荐使用clientDB,开发效率是最高的。 + +如果服务器端除了操作数据库外,还有复杂的、不宜公开在前端的逻辑,此时推荐使用云对象。 \ No newline at end of file