框架与配置

框架与配置

框架

项目目录结构:

├── dist                   编译结果目录
├── config                 配置目录
|   ├── dev.js             开发时配置
|   ├── index.js           默认配置
|   └── prod.js            打包时配置
├── src                    源码目录
|   ├── pages              页面文件目录
|   |   ├── index          index 页面目录
|   |   |   ├── index.js   index 页面逻辑
|   |   |   └── index.css  index 页面样式
|   ├── app.css            项目总通用样式
|   └── app.js             项目入口文件
└── package.json

一个普通的入口文件示例如下:

import Taro, { Component } from "@tarojs/taro";
import Index from "./pages/index";

import "./app.scss";

class App extends Component {
  // 项目配置
  config = {
    pages: ["pages/index/index"],
    window: {
      backgroundTextStyle: "light",
      navigationBarBackgroundColor: "#fff",
      navigationBarTitleText: "WeChat",
      navigationBarTextStyle: "black",
    },
  };

  componentWillMount() {}

  componentDidMount() {}

  componentDidShow() {}

  componentDidHide() {}

  render() {
    return <Index />;
  }
}

通常入口文件会包含一个 config 配置项,这个配置是整个应用的全局的配置,配置规范基于微信小程序的全局配置进行制定,所有平台进行统一。入口文件中的全局配置,在编译后将生成全局配置文件 app.json。

配置

配置项列表

Taro 中全局配置所包含的配置项及各端支持程度如下:

属性 类型 必填 描述 微信小程序 百度小程序 字节跳动小程序 支付宝小程序 H5 RN
pages String Array 页面路径列表 ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
window Object 全局的默认窗口表现 具体支持程度见下方 具体支持程度见下方 具体支持程度见下方 具体支持程度见下方 具体支持程度见下方 具体支持程度见下方
tabBar Object 底部 tab 栏的表现 具体支持程度见下方 具体支持程度见下方 具体支持程度见下方 具体支持程度见下方 具体支持程度见下方 具体支持程度见下方
networkTimeout Object 网络超时时间 ✔️
debug Boolean 是否开启 debug 模式,默认关闭 ✔️ ✔️
functionalPages Boolean 是否启用插件功能页,默认关闭 ✔️(基础库 2.1.0 以上)
subPackages Object Array 分包结构配置 ✔️(基础库 1.7.3 以上) ✔️ ✔️ ✔️
workers String Worker 代码放置的目录 ✔️(基础库 1.9.90 以上)
requiredBackgroundModes String Array 需要在后台使用的能力,如音乐播放 ✔️
plugins Object 使用到的插件 ✔️(基础库 1.9.6 以上)
preloadRule Object 分包预下载规则 ✔️(基础库 2.3.0 以上) ✔️
resizable Boolean iPad 小程序是否支持屏幕旋转,默认关闭 ✔️(基础库 2.3.0 以上)
navigateToMiniProgramAppIdList String Array 需要跳转的小程序列表,详见 wx.navigateToMiniProgram ✔️(基础库 2.4.0 以上)
usingComponents Object 全局自定义组件配置 ✔️(开发者工具 1.02.1810190)
permission Object 小程序接口权限相关设置 ✔️ 微信客户端 7.0.0

pages

用于指定小程序由哪些页面组成,每一项都对应一个页面的 路径 + 文件名 信息。文件名不需要写文件后缀,框架会自动去寻找对应位置的文件进行处理。数组的第一项代表小程序的初始页面(首页)。小程序中新增/减少页面,都需要对 pages 数组进行修改。如开发目录为:

├── app.js
├── app.json
├── app.wxss
├── pages
│   │── index
│   │   ├── index.wxml
│   │   ├── index.js
│   │   ├── index.json
│   │   └── index.wxss
│   └── logs
│       ├── logs.wxml
│       └── logs.js
└── utils

则需要在入口文件配置中写

class App extends Component {
  // 项目配置
  config = {
    pages: [
      'pages/index/index',
      'pages/logs/logs'
    ]
  }
  ...
}

window

用于设置小程序的状态栏、导航条、标题、窗口背景色,其配置项如下。

属性 类型 默认值 描述
navigationBarBackgroundColor HexColor(十六进制颜色值) #000000 导航栏背景颜色,如 #000000
navigationBarTextStyle String white 导航栏标题颜色,仅支持 black / white
navigationBarTitleText String 导航栏标题文字内容
navigationStyle String default 导航栏样式,仅支持以下值:default 默认样式;custom 自定义导航栏,只保留右上角胶囊按钮
backgroundColor String 窗口的背景色
backgroundTextStyle String dark 下拉 loading 的样式,仅支持 dark / light
backgroundColorTop String #ffffff 顶部窗口的背景色,仅 iOS 支持
backgroundColorBottom String #ffffff 底部窗口的背景色,仅 iOS 支持
enablePullDownRefresh boolean false 是否开启当前页面的下拉刷新。
onReachBottomDistance Number 50 页面上拉触底事件触发时距页面底部距离,单位为 px
pageOrientation String portrait 屏幕旋转设置,支持 auto / portrait / landscape 详见 响应显示区域变化

各端支持程度如下:

属性 微信小程序 百度小程序 字节跳动小程序 支付宝小程序 H5 RN
navigationBarBackgroundColor ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
navigationBarTextStyle ✔️ ✔️ ✔️ ✔️ ✔️
navigationBarTitleText ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
navigationStyle ✔️(微信客户端 6.6.0) ✔️(百度 App 版本 11.1.0) ✔️
backgroundColor ✔️ ✔️ ✔️ ✔️
backgroundTextStyle ✔️ ✔️ ✔️
backgroundColorTop ✔️(微信客户端 6.5.16) ✔️
backgroundColorBottom ✔️(微信客户端 6.5.16) ✔️
enablePullDownRefresh ✔️ ✔️ ✔️ ✔️
onReachBottomDistance ✔️ ✔️ ✔️
pageOrientation ✔️2.4.0 (auto) / 2.5.0 (landscape)

配置示例如下:

class App extends Component {
  // 项目配置
  config = {
    pages: [
      'pages/index/index',
      'pages/logs/logs'
    ],
    window: {
      navigationBarBackgroundColor: '#ffffff',
      navigationBarTextStyle: 'black',
      navigationBarTitleText: '微信接口功能演示',
      backgroundColor: '#eeeeee',
      backgroundTextStyle: 'light'
    }
  }
  ...
}

tabBar

如果小程序是一个多 tab 应用(客户端窗口的底部或顶部有 tab 栏可以切换页面),可以通过 tabBar 配置项指定 tab 栏的表现,以及 tab 切换时显示的对应页面。

其配置项如下

属性 类型 必填 默认值 描述
color HexColor(十六进制颜色值) tab 上的文字默认颜色,仅支持十六进制颜色
selectedColor HexColor(十六进制颜色值) tab 上的文字选中时的颜色,仅支持十六进制颜色
backgroundColor HexColor(十六进制颜色值) tab 的背景色,仅支持十六进制颜色
borderStyle String black tabbar 上边框的颜色,仅支持 black / white
list Array tab 的列表,详见 list 属性说明,最少 2 个、最多 5 个 tab
position String bottom tabBar 的位置,仅支持 bottom / top
custom Boolean false 自定义 tabBar

各端支持程度如下

属性 微信小程序 百度小程序 字节跳动小程序 支付宝小程序 H5 RN
color ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
selectedColor ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
backgroundColor ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
borderStyle ✔️ ✔️ ✔️ ✔️ ✔️
list ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
position ✔️ ✔️
custom ✔️(基础库 2.5.0 以上)

其中 list 接受一个数组,只能配置最少 2 个、最多 5 个 tab。tab 按数组的顺序排序,每个项都是一个对象,其属性值如下:

属性 类型 必填 描述
pagePath String 页面路径,必须在 pages 中先定义
text String tab 上按钮文字
iconPath String 图片路径,icon 大小限制为 40kb,建议尺寸为 81px * 81px,不支持网络图片。当 position 为 top 时,不显示 icon。
selectedIconPath String 选中时的图片路径,icon 大小限制为 40kb,建议尺寸为 81px * 81px,不支持网络图片。当 position 为 top 时,不显示 icon。

networkTimeout

各类网络请求的超时时间,单位均为毫秒。

属性 类型 必填 默认值 描述
request Number 60000 Taro.request 的超时时间,单位:毫秒
connectSocket Number 60000 Taro.connectSocket 的超时时间,单位:毫秒
uploadFile Number 60000 Taro.uploadFile 的超时时间,单位:毫秒
downloadFile Number 60000 Taro.downloadFile 的超时时间,单位:毫秒
上一页
下一页