跳至主要內容

manifest 文件

manifest 文件

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

manifest.json 是一个 JSON 文件，且文件内容必须是一个 JSON Object，本文档会介绍 manifest.json 各个字段的功能。

字段说明

根属性

这些字段是 manifest.json 文件根 JSON 对象的属性。

类型签名
interface Manifest {
  package: string,
  name: string,
  icon: string,
  versionName: string,
  versionCode: number,
  config?: Config,
  router: Router,
  display?: Display,
  dial?: Dial,
  widgets?: Widget[]
}

package

package 字段是应用的包名，必填字段。推荐采用 com.company.module 的格式，如：com.example.demo。系统中的应用包名必须唯一。

name

应用的显示名称，必填字段。6 个汉字以内，与应用商店保存的名称一致，用于在桌面图标、弹窗等处显示应用名称。该字段可以用 ${} 表达式来引用国际化字符串，例如：

{
  "name": "${appName}"
}

中 appName 就是一个国际化字符串的键。国际化的应用名可以让设备的应用列表以当前语言显示应用名称，而不是固定的语言。

icon

应用图标的路径，例如 /assets/icon.png。

versionName

应用版本字符串。

versionCode

应用版本代码，是一个整数。建议在每次发布应用时将版本代码加一。

config

描述系统配置信息的可选字段，见 Config 对象。

router

描述应用内页面路由信息的必填字段，详见 Router 对象。

display

应用内的显示效果配置，详见 Display 对象。

dial

如果存在 dial 字段则表示此项目是一个表盘包而不是应用。表盘的专属元数据由 Dial 对象描述。表盘包 icon 不使用字段。

widgets

表示挂件和小组件列表的配置信息，配置字段详见 Widget 对象。

Config 对象

类型签名
interface Config {
  designWidth?: number,
  designImageScale?: number,
  fontFaces?: string,
  assets?: string | string[]
}

designWidth

页面设计的基准宽度（单位是像素），默认值为 750。CSS 中的 px 长度单位会根据实际的设备宽度和 designWidth 的比值来缩放。例如当 designWidth 的值为 466 时，在实际宽度为 410 像素的设备上像素长度会被缩放 410/466410/466 倍。

建议使用当前设计的设备尺寸，而不是默认的 750，以避免在开发中做大量的换算。

designImageScale

图片资源的切图缩放系数，默认值为 1.01.0。为了满足多设备分辨率适配，需要设计师将图片按照设计稿放大后切图来保证打包后的质量。

designImageScale 是项目中资源原图的尺寸和缩放后图片逻辑分辨率的比值。具体来说，资源图片在实际设备上的缩放系数 scale\it{scale} 为：

scale=designImageScaledeviceWidthdesignWidth \it{scale} = \tt{designImageScale}\frac{\tt{deviceWidth}}{\tt{designWidth}}

其中 deviceWidth\tt{deviceWidth} 为设备屏幕的实际宽度。因此，图片的实际显示尺寸 (w′,h′)(w', h') 为：

(w′,h′)=scale⋅(w,h) (w', h') = \it{scale} \cdot (w, h)

其中 (w,h)(w, h) 是资源原图的尺寸。

提示

不要使用小于 11 的 designImageScale 配置，这意味着打包时会对资源图片进行放大，并因此产生明显的模糊和失真。如果你希望应用可以在多种设备中精致地显示图片，应该按照比实际需求更大的尺寸来准备资源图片，并设置正确的 designImageScale 参数。

例如，如果实际设备（假设 designWidth==deviceWidth\tt{designWidth} == \tt{deviceWidth}）上显示的图片尺寸为 96px×96px96\rm px \times 96\rm px，那么可以准备两倍分辨率的 192px×192px192\rm px \times 192\rm px 素材，并将 designImageScale 设置为 22。

fontFaces

指定应用级的字体映射表文件路径，其中定义的字体可在应用中直接使用。此路径可以是相对于 manifest.json 的相对路径，也可以是相对于应用资源包根目录的绝对路径。

参考字体配置。

assets

指定自定义资源的路径 glob 模式（文件通配符）。例如：

{
  "config": {
    "assets": [ "assets/**", "**/data.bin" ]
  }
}

会将项目中 assets 目录下的所有文件和项目中所有的 data.bin 文件进行打包。这些文件只会按照静态资源文件的形式打包（即直接拷贝文件）。

文件通配符可以和路径相同，但是有以下特殊形式：

  • * 匹配一个路径组件，但不包含路径分隔符（/）。
  • ** 匹配任意数量的路径组建，并可以包含路径分隔符。

例如：

  • test.js 可以匹配项目跟目录下的 test.js 文件。
  • **/*-data.bin 可以匹配任意路径下具有 -data.bin 后缀的文件。
  • */*.bin 匹配项目根中任意一级目录下具有 .bin 后缀的文件。

Router 对象

定义页面的组成和相关配置信息。

类型签名
interface Router {
  entry?: string,
  pages: { [name: string]: PageInfo }
}

entry

应用首页的名称，启动应用后会先跳转到此页面。默认为 "main"。

pages

声明各个页面的信息。 pages 属性的键 name 是页面名称，属性值 PageInfo 对象是页面的详细配置信息。例如：

{
  "router": {
    "entry": "Main",
    "pages": {
      "Main": {
        "path": "/Path/To/Main",
        "component": "index"
      }
    }
  }
}

应用中所有的页面都必须填写到路由表中才可以使用，每个页面也必须具有唯一的名字。

Display 对象

pageAnimation

应用内页面的默认转场动画配置，值是 PageAnimation 对象。

PageInfo 对象

页面配置对象是 router.pages 对象的属性值。页面配置对象的类型是 Object。本节介绍页面配置对象的属性字段定义。

类型签名
interface PageInfo {
  path?: string,
  component?: string,
  pageAnimation?: PageAnimation
}

path

页面目录的路径（存放页面组件的文件夹的路径）。默认和页面名称相同，即 Router 对象的键。

component

页面组件的名称，和 UX 文件名一致并且不需要 .ux 后缀名，例如组件名 "index" 对应 index.ux 文件。

pageAnimation

页面的转场动画配置，值是 PageAnimation 对象。此配置的优先级高于 mainfest.json 中的 display.pageAnimation 配置。

PageAnimation 对象

此对象的属性配置页面转场动画的行为。转场动画只对顶部的页面有效，非顶部的页面是不会播放转场动画的。

类型签名
interface PageAnimation {
  openEnter?: string,
  closeEnter?: string,
  openExit?: string,
  closeExit?: string
}

每个属性都可以取以下值：

  • "none"：无转场动画，这是所有属性的默认值
  • "slide"：页面以滑动动画进行转场，此转场效果在不同的转场配置属性下有所不同，其中：
    • 对于 openEnter 转场，slide 效果是页面从屏幕左边向右开始进入，直到完全覆盖屏幕
    • 对于 closeExit 转场，slide 效果是页面从完全覆盖屏幕的位置开始向右滑动，直到完全离开屏幕
    • 对于 closeEnter 和 openExit 转场，slide 效果是没有动画的

页面和应用的默认转场动画是由设备定义的。如果 manifest.json 中没有指定 pageAnimation 相关的字段，某些设备可能不播放转场动画，而另一些设备则可能使用厂商定制的动画效果。

注意

模拟器总会播放 slide 页面转场动画，而无论它在模拟哪一款设备。如果想确保关闭页面的转场动画，请使用

{
  "pageAnimation": { "openEnter": "none" }
}

这样的写法，而不是 "pageAnimation": {}，后者由于未知原因不生效。

openEnter

这个属性配置打开新页面时，新页面的转场动画。

closeEnter

这个属性配置打开新页面时，底下将被覆盖的旧页面的转场动画。

openExit

这个属性配置关闭页面时，被关闭页面的退出转场动画。

closeExit

这个属性配置关闭页面时，被关闭页面底下将要重新显示页面的转场动画。

Dial 对象

Dial 对象描述表盘相关的配置信息。

类型签名
interface Dial {
  component: string,
  preview: string
}

component

表盘入口组件的路径。可以是包中的绝对路径或相对于 manifest.json 文件的相对路径。

preview

表盘预览图片的路径。可以是包中的绝对路径或相对于 manifest.json 文件的相对路径。

Widget 对象

Widget 对象描述挂件或小组件的配置信息。

类型签名
interface Widget {
  name: string,
  component: string,
  preview: string
}

name

挂件/小部件的名字，同一个应用包内的小部件不能重名。

component

挂件/小部件入口组件的路径。可以是包中的绝对路径或相对于 manifest.json 文件的相对路径。

preview

挂件/小部件预览图片的路径。可以是包中的绝对路径或相对于 manifest.json 文件的相对路径。

Glyphix framework