教程 框架 组件 接口 其他

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(开启自动反色)

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"
      }
    }
  },
  "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

示例:

注意:实际代码中 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"
         }
      }
    }
}

如果以下没有特别备注,则 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 来显示

条匹配 "" 的结果

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