diff --git a/docs/collocation/manifest.md b/docs/collocation/manifest.md index e2c9ba7ce1576f321195355880b01cd21b1ec67a..8b99aaa09e880dfddbeabce4ac91849752260be8 100644 --- a/docs/collocation/manifest.md +++ b/docs/collocation/manifest.md @@ -1,638 +1,639 @@ -`manifest.json` 文件是应用的配置文件,用于指定应用的名称、图标、权限等。HBuilderX 创建的工程此文件在根目录,CLI 创建的工程此文件在 src 目录。 - -### 配置项列表 - -|属性|类型|默认值|描述|最低版本| -|:-|:-|:-|:-|:-| -|name|String||应用名称|| -|appid|String|新建 uni-app 项目时,DCloud 云端分配。用途[详见](https://ask.dcloud.net.cn/article/35907)|应用标识|| -|description|String||应用描述|| -|locale|String|auto|设置当前默认语言,具体参考 [locale](/api/ui/locale)|| -|versionName|String||版本名称,例如:1.0.0。详见下方Tips说明|| -|versionCode|String||版本号,例如:36|| -|transformPx|Boolean|true|是否转换项目的px,为true时将px转换为rpx,为false时,px为传统的实际像素。为兼容历史项目默认值为 true,但不推荐新项目启用此配置(新建项目模板一般配置为 false)|| -|networkTimeout|Object||网络超时时间,[详见](/collocation/manifest?id=networktimeout)|| -|debug|Boolean|false|是否开启 debug 模式,开启后调试信息以 ``info`` 的形式给出,其信息有页面的注册,页面路由,数据更新,事件触发等|| -|uniStatistics|Object||[是否开启 uni 统计,全局配置](/collocation/manifest?id=uniStatistics)|2.2.3+| -|app-plus|Object||[App 特有配置](/collocation/manifest?id=app-plus)|| -|h5|Object||[H5 特有配置](/collocation/manifest?id=h5)|| -|quickapp|Object||快应用特有配置,即将支持|| -|mp-weixin|Object||[微信小程序特有配置](/collocation/manifest?id=mp-weixin)|| -|mp-alipay|Object||[支付宝小程序特有配置](/collocation/manifest?id=mp-alipay)| -|mp-baidu|Object||[百度小程序特有配置](/collocation/manifest?id=mp-baidu)|| -|mp-toutiao|Object||[字节跳动小程序特有配置](/collocation/manifest?id=mp-toutiao)|1.6.0| -|mp-lark|Object||[飞书小程序特有配置](/collocation/manifest?id=mp-lark)|3.2.12| -|mp-qq|Object||[qq 小程序特有配置](/collocation/manifest?id=mp-qq)|2.1.0| - -**Tips** - -- uni-app 的 `appid` 由 DCloud 云端分配,主要用于 DCloud 相关的云服务,请勿自行修改。[详见](https://ask.dcloud.net.cn/article/35907) -- 注意区分 uni-app 的 `appid` 与微信小程序、iOS 等其它平台分配的 `appid`,以及第三方 SDK 的 `appid`。 -- versionName在云打包App和生成wgt应用资源时会使用。如需升级App版本,先修改此处再云打包。导出wgt资源用于离线打包和热更新时也会以此版本为依据。 -- 在本地打包时和热更新时,App版本和wgt应用资源版本将不再保持一致。此时通过[plus.runtime.version](https://www.html5plus.org/doc/zh_cn/runtime.html#plus.runtime.version)可获取App版本,通过[plus.runtime.getProperty](https://www.html5plus.org/doc/zh_cn/runtime.html#plus.runtime.getProperty)获取wgt资源版本。 - -#### networkTimeout - -各类网络请求的超时时间,单位均为毫秒。 - -|属性|类型|必填|默认值|说明| -|--|--|--|--|--| -|request|Number|否|60000|uni.request 的超时时间,单位毫秒。| -|connectSocket|Number|否|60000|uni.connectSocket 的超时时间,单位毫秒。| -|uploadFile|Number|否|60000|uni.uploadFile 的超时时间,单位毫秒。| -|downloadFile|Number|否|60000|uni.downloadFile 的超时时间,单位毫秒。| - -自`HBuilderX 2.5.10`起,上述默认超时时间由6秒改为60秒,对齐微信小程序平台。 - - -#### uniStatistics -uni 统计配置项 - -|属性|类型|必填|默认值|说明| -|--|--|--|--|--| -|enable|Boolean|是|true|是否开启uni统计| - -### app-plus - -|属性|类型|说明|最低版本| -|:-|:-|:-|:-| -|splashscreen|Object|App 启动界面信息,[详见](/collocation/manifest?id=splashscreen)|| -|screenOrientation|Array|重力感应、横竖屏配置,可取值:"portrait-primary":竖屏正方向;"portrait-secondary":竖屏反方向;"landscape-primary":横屏正方向;"landscape-secondary":横屏反方向。|| -|modules|Object|权限模块,[详见](/collocation/manifest?id=modules)|| -|distribute|Object|App 发布信息,[详见](/collocation/manifest?id=distribute)|| -|nvueCompiler|String|切换 nvue 编译模式,可选值,`weex` :老编译模式,`uni-app`: 新编译模式,默认为 `weex` 。[编译模式区别详情](http://ask.dcloud.net.cn/article/36074)|2.0.3+| -|nvueStyleCompiler|String|切换 nvue 样式编译模式,可选值,`weex` :老编译模式,`uni-app`: 新编译模式,默认为 `weex` 。[编译模式区别详情](https://ask.dcloud.net.cn/article/38751)|3.1.1+| -|renderer|String|可不加载基于 webview 的运行框架,减少包体积、提升启动速度。可选值 `native`| App-nvue 2.2.0+| -|nvueLaunchMode|String|Nvue 首页启动模式,可选值:normal、fast 默认 normal(HBuilderX 2.4.4-2.4.9 固定为 fast) [详见](https://ask.dcloud.net.cn/article/36749)|2.5.0+| -|nvue|Object|nvue 页面布局初始配置,[详见](/collocation/manifest?id=nvue)|2.0.3+| -|optimization|Object|分包配置,可以减轻启动时加载的js数量,提升启动速度|2.7.12+| -|uniStatistics|Object|[App 是否开启 uni 统计,配置方法同全局配置](/collocation/manifest?id=uniStatistics)|2.2.3+| -|webView|Object|当系统webview低于指定版本时,会弹出提示。或者下载x5内核后继续启动,仅Android支持,[详情](/collocation/manifest?id=appwebview)|3.5.0+| - - -PS:上表只列出了核心部分,App平台的配置其实非常多,完整内容请参考 [完整的 manifest.json](/collocation/manifest-app?id=full-manifest)。 - -**Tips** - -- manifest.json 文件的配置,推荐在 HBuilderX 提供的可视化操作界面完成。 -- 部分配置在打包时的操作界面补全,例如:证书等信息。 -- Native.js 权限部分会根据配置的模块权限,在打包后自动填充。 -- 部分 modules 是默认的,不需要进行配置。 -- 微信小程序的 `appid` 等信息,需要配置在 `mp-weixin` 节点下。不要配置在 `app-plus`下。`sdkConfigs` 下出现的 `weixin` 节点,配置的是 App 的第三方 SDK 信息。 - - -#### App Splashscreen@splashscreen - -splash(启动封面)是App必然存在的、不可取消的。 -|属性|类型|默认值|描述|最低版本| -|:-|:-|:-|:-|:-| -|alwaysShowBeforeRender|Boolean|true|是否等待首页渲染完毕后再关闭启动界面|1.6.0| -|autoclose|Boolean|true|是否自动关闭启动界面,仅当alwaysShowBeforeRender设置为false时生效,如果需要[手动关闭](https://www.html5plus.org/doc/zh_cn/navigator.html#plus.navigator.closeSplashscreen)启动界面,需将 alwaysShowBeforeRender 及 autoclose 均设置为 false。|| -|waiting|Boolean|true|是否在程序启动界面显示等待圈或雪花|| - -alwaysShowBeforeRender和autoclose属性组合设置,可配置以下三种关闭启动界面(splash)策略,[详见](tutorial/app-splashscreen) - -**注意** -- 如果不配置自己的splash图,App端会默认把App的icon放到splash中 -- splash只能是标准png,不要用jpg改名为png。也不支持gif等动画 -- 相关改动,云打包生效,真机运行不生效。本地打包需自行在原生工程中配置 -- App启动图中iOS的MAX等大屏设备的splash图若不配,会导致iOS认为此App没有为MAX优化,App将无法全屏,四周会有黑边 -- Android的splash支持.9.png,[详见](tutorial/app-splashscreen?id=9png) - - -#### App Modules@modules -模块选择是为了控制App的包体积,不需要的模块可以在打包时剔除。 - -|名称|描述| -|:-|:-| -|Bluetooth|BLE蓝牙| -|Contacts|系统通讯录| -|Fingerprint|指纹识别| -|iBeacon|iBeacon| -|LivePusher|直播推流| -|Maps|地图| -|Messaging|短彩邮件消息| -|OAuth|登录授权| -|Payment|支付| -|Push|消息推送| -|Share|社交分享| -|Speech|语音识别| -|SQLite|SQLite数据库| -|Statistic|统计| -|VideoPlayer|视频播放| - -**注意** -- 仅App云打包生效。本地打包需自行在原生工程中配置。 - -#### App Distribute@distribute - -|属性|类型|描述| -|:-|:-|:-| -|android|Object|Android 应用配置,详见: [Android配置明细](/collocation/manifest-app?id=android)| -|ios|Object|iOS 应用配置,详见: [iOS配置明细](/collocation/manifest-app?id=ios)| -|sdkConfigs|Object|SDK配置,仅打包生效 [详见](/collocation/manifest?id=sdkConfigs)| -|orientation|Array|同 screenOrientation 配置,仅打包生效,已废弃,推荐使用 screenOrientation| - -#### App SdkConfigs@sdkConfigs - -三方原生SDK配置。三方SDK的使用需要向这些SDK提供商申请,并配置参数到此处。可在HBuilderX可视化界面(App SDK配置)输入配置,此配置仅**云打包后生效**,本地打包需自行在原生工程中配置。 - -|属性|类型|描述| -|:-|:-|:-| -|oauth|Object|授权登录,配置后可调用 [uni.login](/api/plugins/login?id=login) 进行登录操作,目前支持的授权登录平台有:[QQ](http://open.qq.com/)、[微信](https://open.weixin.qq.com/)、[新浪微博](http://open.weibo.com/)。| -|share|Object|分享,配置后可调用 [uni.share](/api/plugins/share?id=share) 进行分享,目前支持QQ、微信、新浪微博等分享, 具体配置 [详见](/api/plugins/share?id=app-端各平台分享配置说明)。| -|push|Object|push配置,使用方式 [详见](/unipush),目前支持:[uniPush](http://ask.dcloud.net.cn/article/35716)、[个推](http://www.igetui.com/),注意App仅支持一种 push 方式,配置多个 push 无效,建议使用 uniPush,支持多厂商推送。| -|payment|Object|三方支付配置,配置后可调用 [uni.payment](/api/plugins/payment?id=payment) 进行支付,目前支持微信支付、支付宝支付、苹果内购, 具体配置 [详见](/api/plugins/payment?id=uni-app-app-平台支付流程)。| -|statics|Object|统计配置,目前仅支付友盟统计,[详见](/tutorial/app-statistic),在uni-app中只用 [plus.statistic](http://www.html5plus.org/doc/zh_cn/statistic.html) 进行调用。| -|speech|Object|语音识别配置,支持讯飞语音、百度语音,[详见](/tutorial/app-speech),在uni-app中只用 [plus.speech](http://www.html5plus.org/doc/zh_cn/speech.html) 进行调用。| -|maps|Object|原生地图配置,目前仅支持 [高德地图](http://lbs.amap.com/),申请方式可参考:[地图插件配置](/tutorial/app-maps)。| - -#### optimization@app-vue-optimization - -可以减轻启动时加载的js数量,提升启动速度。 - -从uni-app 2.7.12+ 开始,App-vue平台也兼容了小程序的分包配置,但默认并不开启。 - -在manifest配置以下节点,可以在App端启动分包。 - -|属性|类型|说明| -|:-|:-|:-| -|subPackages|Boolean|是否开启分包优化| - -``` -"app-plus": { - "optimization": { - "subPackages": true - }, - "runmode" : "liberate" // 开启分包优化后,必须配置资源释放模式 -} -``` - -在manifest中启动分包后,需要在pages.json中配置具体的分包规则,与小程序的配置相同,详见:[https://uniapp.dcloud.io/collocation/pages?id=subpackages](https://uniapp.dcloud.io/collocation/pages?id=subpackages) - -也就是一旦在pages.json里配置分包,小程序一定生效,而app是否生效,取决于manifest里是否开启。 - -注意: -* App开启分包后,每个分包单独编译成一个js文件(都包含在app内,不会联网下载),当App首页是vue时,可减小启动加载文件大小,提升启动速度。 -* 首页是nvue时,分包不会提升启动速度,nvue本身启动速度就快于vue,也快于开启分包后的首页为vue的应用。如果追求极致启动速度,还是应该使用nvue做首页并在manifest开启fast模式。 -* App页面较少时,分包对启动速度的优化不明显。 - - -#### nvue@nvue -`nvue` 页面布局初始设置 - -|属性|类型|描述| -|:-|:-|:-| -|flex-direction|String| flex 成员项的排列方向,支持项,row:从左到右; row-reverse:从右到左;column:从上到下;column-reverse:与 column 相反,默认值 column。| - - -#### webview@appwebview - -> uni-app 3.5.0+ - -当App代码使用了低版本webview不支持的语法时(比如使用了vue3),可以在manifest配置本属性,来指定最低运行的webview版本。 - -当系统webview版本不符合需求时,uni-app引擎会自动弹框。同时开发者可以指定使用 x5引擎webview 来替代系统webview,以保障浏览器兼容性。详见[x5文档](/tutorial/app-android-x5.html) - -当你的应用强依赖x5时,比如需要vue页面的字体和tabbar等原生界面保持一致时,也可以在manifest配置本属性。 - -|属性|类型|说明| -|:-|:-|:-| -|minUserAgentVersion|String|最小webview版本,例如:95.0.4638.75。(当低于最小版本要求时,显示 `WebView版本过低` 弹框,点击确定退出应用。)| -|x5|Object|此属性需要在manifest模块配置中勾选 Android X5 Webview 模块,详细参见下面的说明| - -x5 属性说明 - -|属性|类型|默认值|说明| -|:-|:-|:-|:-| -|timeOut|Number|3000|超时时间| -|showTipsWithoutWifi|Boolean|false|是否在非WiFi网络环境时,显示用户确认下载x5内核的弹窗。(如果为true时,在非WiFi网络下载x5模块,会显示用户确认弹框,内容为 `当前处于非WiFi网络,是否允许下载x5模块?` ,false时不显示弹框 。)| -|allowDownloadWithoutWiFi|Boolean|false|是否允许用户在非WiFi网络时进行x5内核的下载。(如果为true,就不会显示用户确认的弹窗。false时,如果showTipsWithoutWifi为true,就会显示用户确认弹框;showTipsWithoutWifi为false时,不下载x5模块。)| - - -webview示例 - -```json -{ - "app-plus" : { - "webView": { - "minUserAgentVersion": "95.0.4638.75", - "x5": { - "timeOut": 3000, - "showTipsWithoutWifi": true, - "allowDownloadWithoutWiFi": false - } - } - } -} -``` - - -### h5 -|属性|类型|说明| -|:-|:-|:-| -|title|String|页面标题,默认使用 manifest.json 的 name| -|template|String|index.html模板路径,相对于应用根目录,可定制生成的 html 代码。参考:[自定义模板](/collocation/manifest?id=h5-template)| -|router|Object|参考:[router](/collocation/manifest?id=h5-router)| -|async|Object|参考:[async](/collocation/manifest?id=h5-async)| -|devServer|Object|开发环境 server 配置,参考:[devServer](/collocation/manifest?id=devserver)| -|publicPath|String|引用资源的地址前缀,仅发布时生效。参考:[publicPath](/collocation/manifest?id=publicPath)| -|sdkConfigs|String|SDK配置,例如地图... 参考:[sdkConfigs](/collocation/manifest?id=h5sdkconfig)| -|optimization|Object|打包优化配置(HBuilderX 2.1.5 以上支持),参考[optimization](/collocation/manifest?id=optimization)| -|uniStatistics|Object|[H5 是否开启 uni 统计,配置方法同全局配置](/collocation/manifest?id=uniStatistics)|| - -#### 自定义模板@h5-template -需要使用自定义模板的场景,通常有以下几种情况: - -- 调整页面 head 中的 meta 配置 -- 补充 SEO 相关的一些配置(仅首页) -- 加入百度统计等三方js - -使用自定义模板时,1. 工程根目录下新建一个html文件;2. 复制下面的基本模板内容,到这个html文件,在此基础上修改meta和引入js;3. 在 `manifest.json->h5->template` 节点中关联这个html文件的路径。 -```html - - -
- - -