教程 框架 组件 接口 其他

manifest 文件

manifest.json 文件中包含了应用描述、接口声明、页面路由信息

manifest

属性类型默认值必填描述
packageString-应用包名,确认与原生应用的包名不一致,推荐采用 com.company.module 的格式,如:com.example.demo
nameString-应用名称,6 个汉字以内,与应用商店保存的名称一致,用于在桌面图标、弹窗等处显示应用名称
iconString-应用图标,提供 192x192 大小的即可
versionNameString-应用版本名称,如:"1.0"
versionCodeInteger-应用版本号,从1自增,推荐每次重新上传包时versionCode+1
minPlatformVersionInteger-支持的最小平台版本号,兼容性检查,避免上线后在低版本平台运行并导致不兼容;如果不填按照内测版本处理
featuresArray-接口列表,绝大部分接口都需要在这里声明,否则不能调用,详见每个接口的文档说明
configObject-系统配置信息,详见下面说明
routerObject-路由信息,详见下面说明
displayObject-UI 显示相关配置,详见下面说明
subpackages 1040+Array-定义并启用分包加载,详见下面说明
trustedSslDomains 1060+Array-可信的 https 站点列表,如:"www.quickapp.cn"。当 web 组件在访问这些站点出现证书过期或无效时,会提供继续访问的选项,允许用户继续访问。

config

用于定义系统配置和全局数据。

属性类型默认值描述
logLevelStringlog打印日志等级,分为 off,error,warn,info,log,debug
designWidthInteger750页面设计基准宽度,根据实际设备宽度来缩放元素大小
dataObject-全局数据对象,属性名不能以$或_开头,在页面中可通过 this 进行访问;如果全局数据属性与页面的数据属性重名,则页面初始化时,全局数据会覆盖页面中对应的属性值
background 1050+Object-后台运行配置信息,可使用 features 字段申请需要在后台使用的接口(同时仍需在最外层的 features 字段中声明)。可申请的接口为:

system.audio

system.geolocation

system.record

system.request 等。

详细用法参见后台运行 脚本

network 1060+Object-网络超时时间配置选项,详见下面说明

config.network

参数名类型默认值单位必填描述
connectTimeoutNumber30000ms连接超时时间
readTimeoutNumber30000ms读取超时时间
writeTimeoutNumber30000ms写入超时时间

router

用于定义页面的组成和相关配置信息,如果页面没有配置路由信息,则在编译打包时跳过。

属性类型默认值必填描述
entryString-首页名称;使用分包功能时,建议将首页定义在基础包中
pagesObject-页面配置列表,key 值为页面名称(对应页面目录名,例如 Hello 对应'Hello'目录),value 为页面详细配置 page,详见下面说明
errorPage 1060+String-自定义错误页面的 key 值,需要提供一个在 pages 项里已经配置的 key 值

示例代码:

"router": {
  "entry": "Demo",
  "errorPage": "ErrorPage",
  "pages": {
    "Demo": {
      "component": "index"
    },
    "ErrorPage": {
      "component": "index"
     },
  }
}

router.pages

用于定义单个页面路由信息。

属性类型默认值必填描述
componentString-页面对应的组件名,与 ux 文件名保持一致,例如'hello' 对应 'hello.ux'
pathString/<页面名称>页面路径,例如“/user”,不填则默认为/<页面名称>。
path 必须唯一,不能和其他 page 的 path 相同。
下面 page 的 path 因为缺失,会被设置为“/Index”:
"Index": {"component": "index"}
filterObject-声明页面可以处理某种请求
launchMode 1050+Stringstandard声明页面的启动模式,支持"singleTask","standard"两种页面启动模式。
标识为"singleTask"模式时每次打开目标页面都会打开已有的目标页面并回调 onRefresh 生命周期函数,清除该页面上打开的其他页面,没有打开过此页面时会创建新的目标页面实例。
标识为"standard"模式时会每次打开新的目标页面(多次打开目标页面地址时会存在多个相同页面)

router.pages.filter

匹配页面某种请求,如请求 uri 和 filter 中 uri 匹配成功,则在匹配页面打开。

filter 匹配原则是按照 manifest.json 中 router.pages 中页面顺序自上往下逐一匹配,uri 匹配成功即会在该页面中使用,故不建议多页面采用相同 uri 匹配规则,可能会导致页面跳转出错。

filter 的结构如下:

"filter": {
  "<action>": {
    "uri": "<pattern>"
  }
}
属性类型默认值必填描述
actionString-请求的动作,目前仅支持 view 这一种
uriPattern-请求的数据的匹配规则。必须是正则表达式。如https?://.*可以匹配所有 http 和 https 类型的网址

可以处理所有 http 和 https 请求的 filter 定义如下:

"filter": {
  "view": {
    "uri": "https?://.*"
  }
}

router.errorPage 1060+

当页面跳转异常时,快应用默认将会跳转到 sdk 的默认错误页,同时前端 app.ux 也会收到 onPageNotFound 回调

此参数可提供给开发者配置自定义错误页面

参数:自定义错误页面的参数,需要提供一个在 pages 项里已经配置好的 key 值

注意:开发者自定义错误页面的时候,推荐在 script 标签加入以下这段代码。按照这样设置,当用户 deeplink 跳转进快应用报错时,点击返回键,可以跳到当前快应用的首页,继续浏览快应用的页面。

import router from '@system.router'
export default {
  onBackPress() {
    // 由deep-link等方式进来,异常发生时,一进来首页就是Error Page
    // 则此时返回需要手动修改,使其跳转到首页
    if (router.getLength() === 1) {
      router.replace({
        // 返回首页
        path: '/'
      })
      return true
    }
  }
}

display

用于定义与 UI 显示相关的配置。

如果在 display 对象下定义以下属性值,则生效范围为此快应用全部页面;

如果在 display.pages 对象里的页面 key 值下定义以下属性值,则生效范围仅为此页面;并且,此处指定的页面 display 属性值,优先级高于上述的全局范围的属性值

属性类型默认值描述
backgroundColorString#ffffff窗口背景颜色
fullScreenBooleanfalse是否是全屏模式,默认不会同时作用于 titleBar,titleBar 需要继续通过 titleBar 控制
titleBarBooleantrue是否显示 titleBar
titleBarBackgroundColorString#000000标题栏背景色
titleBarTextColorString-标题栏文字颜色
titleBarTextString-标题栏文字(也可通过页面跳转传递参数(titleBarText)设置)
menuBooleanfalse1000~1060 版本用于配置是否显示标题栏右上角菜单按钮,true 显示,false 隐藏。
注意:menu值设为 true 时,方可在 1000~1060 版本点击菜单按钮,或 1070 版本点击menuBar左边菜单按钮时,触发前端的onMenuPress回调(若前端已实现此回调方法)
windowSoftInputMode 1030+adjustPan | adjustResizeadjustPan软键盘弹出时为保证输入框可见,页面的调整方式。  adjustPan:上移页面; adjustResize:压缩页面显示区域,当页面全屏时,此设置不生效
pagesObject-各个页面的显示样式,key 为页面名(与路由中的页面名保持一致),value 为窗口显示样式,页面样式覆盖 default 样式
orientation 1040+Stringportrait页面显示横屏还是竖屏
portrait:竖屏
landscape:横屏
statusBarImmersive 1050+Booleanfalse是否显示沉浸式状态栏,显示沉浸式状态需要隐藏 titleBar
statusBarTextStyle 1050+light | dark | autoauto状态栏文字样式,有亮、暗和自动,当为自动时会根据状态栏背景色调整
statusBarBackgroundColor 1050+String-状态栏背景色,默认值同标题栏背景色
statusBarBackgroundOpacity 1050+float(0-1.0)false状态栏背景色不透明度,默认值同标题栏背景色不透明度
fitCutout 1060+String-是否在异形区域绘制内容。竖屏下只有在 fullScreen 为 true 时才会生效
none:不会在异形区域绘制,异形区域加黑处理
portrait:竖屏下内容会在异形区域绘制
landscape:横屏下内容会在异形区域绘制
portrait|landscape:竖屏和横屏下都会在异形区域绘制
textSizeAdjust 1060+none | autonone系统字体大小变化时,文本类型组件字体大小的调整方式
none:不跟随系统字体大小变化 auto:跟随系统字体大小变化
themeMode 1070+Number-1主题模式配置值,非必填,默认值为 -1(跟随系统主题模式)。现在支持 3 个值: -1(跟随系统主题模式)、 0(固定日间模式)、1(固定夜间模式)
menuBarData 1070+Object-menuBar 显示相关配置,详见下面说明
forceDark 1070+Booleantrue应用级别的夜间模式自动反色开关(仅 Android 10+系统支持),非必填,默认值为 true(开启自动反色)
pageCache 1080+Booleanfalse是否缓存当前页面,开启缓存后可提高重复打开该页面的打开速度,仅支持在 display 对象下的 pages 对象的 key 值下定义此属性
cacheDuration 1080+Number3600000定义页面缓存的失效时间,仅在pageCache值为 true 时生效,单位为毫秒(ms),默认值为一个小时。仅支持在 display 对象下的 pages 对象的 key 值下定义此属性

subpackages 1040+

用于定义分包的相关配置。分包的详细使用方法参见分包加载

属性类型含义描述
nameString分包名称分包的名称,用于区分不同分包。只能是字母数字和下划线,不允许包含其他符号,"base"作为基础包的保留名称(无需为基础包定义分包配置)
resourceString资源目录分包资源根目录,相对于源码目录"src"的相对路径。只能是字母数字以及"_"、"-"、"/"组成,第一个字符不允许为"-"和"/",不允许包含其他符号。编译时会把该目录下的所有资源都打包到这个分包中去

示例代码:

除了以下示例代码,亦可参考官方示例的manifest.json文件入门

{
  "package": "com.company.unit",
  "name": "appName",
  "icon": "/Common/icon.png",
  "versionName": "1.0",
  "versionCode": 1,
  "minPlatformVersion": 1000,
  "features": [{ "name": "system.network" }],
  "permissions": [{ "origin": "*" }],
  "config": {
    "logLevel": "off",
    "background": {
      "features": [
        "system.audio",
        "system.record",
        "system.request",
        "system.geolocation"
      ]
    },
    "network": {
      "connectTimeout": 10000,
      "readTimeout": 10000,
      "writeTimeout": 10000
    }
  },
  "router": {
    "entry": "Hello",
    "pages": {
      "Hello": {
        "component": "hello",
        "path": "/",
        "filter": {
          "view": {
            "uri": "https?://.*"
          }
        }
      },
      "PackageA/Page1": {
        "component": "page1"
      },
      "PackageA/Page2": {
        "component": "page2"
      }
    }
  },
  "display": {
    "backgroundColor": "#ffffff",
    "fullScreen": false,
    "titleBar": true,
    "titleBarBackgroundColor": "#000000",
    "titleBarTextColor": "#fffff",
    "statusBarImmersive": false,
    "statusBarTextStyle": "auto",
    "statusBarBackgroundColor": "#000000",
    "themeMode": -1,
    "pages": {
      "Hello": {
        "backgroundColor": "#eeeeee",
        "fullScreen": true,
        "titleBarBackgroundColor": "#0000ff",
        "titleBarText": "Hello",
        "forceDark": false,
        "orientation": "landscape",
        "pageCache": true,
        "cacheDuration": 2400000
      }
    }
  },
  "subpackages": [
    {
      "name": "pkgA",
      "resource": "PackageA"
    }
  ],
  "trustedSslDomains": ["www.quickapp.cn", "m.quickapp.cn"]
}

menuBar

用于定义 menuBar 的相关配置。

属性类型含义描述
menuBarBoolean是否显示配置 menuBar 是否显示,默认是否显示请查看厂商支持表格。当fullScreen属性为 true 或视频全屏状态下,若menuBar不显式设置为 true,则 menuBar 会自动隐藏。
menuBarStyleString样式menuBar 样式,默认黑色图标 icon 样式,dark,可以设置 light 浅色
shareTitleString分享标题menuBar 中分享功能对应 标题,默认当前快应用名称
shareDescriptionString分享描述menuBar 中分享功能对应描述,默认当前快应用描述
shareIconString分享图片menuBar 中分享功能对应图片,默认当前快应用 icon
shareCurrentPageBoolean是否分享当前页面menuBar 中是否分享当前页面,默认 false 分享首页, 设置 true 后可以分享当前页面 1080+
shareParamsString分享当前页面的透传参数menuBar 中分享当前页面的透传参数 1080+
shareUrlString页面配置备用分享链接menuBar 中备用分享链接,不支持跳转快应用设备时, 分享跳转到此链接页面 1080+

示例:

注意:实际代码中 json 文件不能包含注释行,此处注释仅为说明用

{
  "package": "com.company.unit",
  "name": "appName",
  "icon": "/Common/icon.png",
  "versionName": "1.0",
  "versionCode": 1,
  "minPlatformVersion": 1000,
  "display": {
    "menuBarData": {
      // 全局配置
      "menuBar" : true,
      "menuBarStyle":"dark",
      "shareTitle":"分享标题",
      "shareDescription":"分享描述",
      "shareIcon":"分享url"
    },
    "pages": {
      "Hello": {
        // 页面配置,默认使用页面menuBarData配置,页面无配置使用全局menuBarData配置
        "menuBarData": {
          "menuBar" : true,
          "menuBarStyle":"dark",
          "shareTitle":"分享标题",
          "shareDescription":"分享描述",
          "shareIcon":"分享url",
          "shareCurrentPage":true,
          "shareUrl":'https://www.quickapp.cn/',
          "shareParams":"{\"key\":\"1\",\"id\":0}"})`
         }
      }
    }
}

如果以下没有特别备注,则 menuBar 在此厂商手机 1070+的 sdk 上会默认显示。同时,开发者可通过配置menuBarData.menuBar决定是否显示。

厂商支持备注
预览版YES
OPPOYES
小米YES1070 版本默认隐藏,可设置menuBarData.menuBar参数为true 来显示
vivoYES
华为YES1070 版本默认隐藏。仅在项目设置manifest.jsonminPlatformVersion大于等于1070时,快应用会显示 menuBar。
且不可以通过设置menuBarData.menuBarfalse来隐藏 menuBar。
一加YES
中兴YES
努比亚YES
金立YES1070 版本默认隐藏,可设置menuBarData.menuBar参数为true 来显示
联想YES1070 版本默认隐藏,可设置menuBarData.menuBar参数为true 来显示
魅族YES1070 版本默认隐藏,可设置menuBarData.menuBar参数为true 来显示

条匹配 "" 的结果

    没有搜索到与 "" 相关的内容