微信小程序基础

微信小程序-基础

微信小程序官方文档

目录结构

小程序包含一个描述整体程序的 app 和多个描述各自页面的 page。

一个小程序主体部分由三个文件组成，必须放在项目的根目录，如下：

文件	必需	作用
app.js	是	小程序逻辑
app.json	是	小程序公共配置
app.wxss	否	小程序公共样式表

一个小程序页面由四个文件组成，分别是：

文件类型	必需	作用
js	是	页面逻辑
wxml	是	页面结构
json	否	页面配置
wxss	否	页面样式表

注意：为了方便开发者减少配置项，描述页面的四个文件必须具有相同的路径与文件名。

宿主环境

配置

全局配置

属性	类型	必填	描述	最低版本
entryPagePath	string	否	小程序默认启动首页
pages	string[]	是	页面路径列表
window	Object	否	全局的默认窗口表现
tabBar	Object	否	底部 tab 栏的表现
networkTimeout	Object	否	网络超时时间
debug	boolean	否	是否开启 debug 模式，默认关闭
functionalPages	boolean	否	是否启用插件功能页，默认关闭	2.1.0
subpackages	Object[]	否	分包结构配置	1.7.3
workers	string	否	Worker 代码放置的目录	1.9.90
requiredBackgroundModes	string[]	否	需要在后台使用的能力，如「音乐播放」
requiredPrivateInfos	string[]	否	调用的地理位置相关隐私接口
plugins	Object	否	使用到的插件	1.9.6
preloadRule	Object	否	分包预下载规则	2.3.0
resizable	boolean	否	PC 小程序是否支持用户任意改变窗口大小（包括最大化窗口）；iPad 小程序是否支持屏幕旋转。默认关闭	2.3.0
usingComponents	Object	否	全局自定义组件配置	开发者工具 1.02.1810190
permission	Object	否	小程序接口权限相关设置	微信客户端 7.0.0
sitemapLocation	string	是	指明 sitemap.json 的位置
style	string	否	指定使用升级后的 weui 样式	2.8.0
useExtendedLib	Object	否	指定需要引用的扩展库	2.2.1
entranceDeclare	Object	否	微信消息用小程序打开	微信客户端 7.0.9
darkmode	boolean	否	小程序支持 DarkMode	2.11.0
themeLocation	string	否	指明 theme.json 的位置，darkmode为 true 为必填	开发者工具 1.03.2004271
lazyCodeLoading	string	否	配置自定义组件代码按需注入	2.11.1
singlePage	Object	否	单页模式相关配置	2.12.0
supportedMaterials	Object	否	聊天素材小程序打开相关配置	2.14.3
serviceProviderTicket	string	否	定制化型服务商票据
embeddedAppIdList	string[]	否	半屏小程序 appId	2.20.1
halfPage	Object	否	视频号直播半屏场景设置	2.18.0
debugOptions	Object	否	调试相关配置	2.22.1
enablePassiveEvent	Object或boolean	否	touch 事件监听是否为 passive	2.24.1
resolveAlias	Object	否	自定义模块映射规则
renderer	string	否	全局默认的渲染后端	2.25.2

页面配置

app.json 中的部分配置，也支持对单个页面进行配置，可以在页面对应的 .json 文件来对本页面的表现进行配置。

页面中配置项在当前页面会覆盖 app.json 中相同的配置项（样式相关的配置项属于 app.json 中的 window 属性，但这里不需要额外指定 window 字段），具体的取值和含义可参考全局配置文档中说明。

属性	类型	默认值	描述	最低版本
navigationBarBackgroundColor	HexColor	#000000	导航栏背景颜色，如 #000000
navigationBarTextStyle	string	white	导航栏标题颜色，仅支持 black / white
navigationBarTitleText	string		导航栏标题文字内容
navigationStyle	string	default	导航栏样式，仅支持以下值： default 默认样式 custom 自定义导航栏，只保留右上角胶囊按钮。	iOS/Android 微信客户端 7.0.0，Windows 微信客户端不支持
homeButton	boolean	false	在非首页、非页面栈最底层页面或非 tabbar 内页面中的导航栏展示 home 键	微信客户端 8.0.24
backgroundColor	HexColor	#ffffff	窗口的背景色
backgroundTextStyle	string	dark	下拉 loading 的样式，仅支持 dark / light
backgroundColorTop	string	#ffffff	顶部窗口的背景色，仅 iOS 支持	微信客户端 6.5.16
backgroundColorBottom	string	#ffffff	底部窗口的背景色，仅 iOS 支持	微信客户端 6.5.16
enablePullDownRefresh	boolean	false	是否开启当前页面下拉刷新。 详见 Page.onPullDownRefresh
onReachBottomDistance	number	50	页面上拉触底事件触发时距页面底部距离，单位为px。 详见 Page.onReachBottom
pageOrientation	string	portrait	屏幕旋转设置，支持 auto / portrait / landscape 详见 响应显示区域变化	2.4.0 (auto) / 2.5.0 (landscape)
disableScroll	boolean	false	设置为 true 则页面整体不能上下滚动。 只在页面配置中有效，无法在 app.json 中设置
usingComponents	Object	否	页面自定义组件配置	1.6.3
initialRenderingCache	string		页面初始渲染缓存配置，支持 static / dynamic	2.11.1
style	string	default	启用新版的组件样式	2.10.2
singlePage	Object	否	单页模式相关配置	2.12.0
restartStrategy	string	homePage	重新启动策略配置	2.8.0
handleWebviewPreload	string	static	控制预加载下个页面的时机。支持 static / manual / auto	2.15.0
visualEffectInBackground	string	否	切入系统后台时，隐藏页面内容，保护用户隐私。支持 hidden / none，若对页面单独设置则会覆盖全局的配置，详见 全局配置	2.15.0
enablePassiveEvent	Object或boolean	否	事件监听是否为 passive，若对页面单独设置则会覆盖全局的配置，详见 全局配置	2.24.1
renderer	string	否	渲染后端	2.25.2

• 注：并不是所有 app.json 中的配置都可以在页面覆盖或单独指定，仅限于本文档包含的选项。
• 注：iOS/Android 客户端 7.0.0 以下版本，navigationStyle 只在 app.json 中生效。

page

WXML

数据绑定

Page({
    data: {
        name: "小明",
        age: 18,
        address: "北京市",
        score: 85
    }
})

<view>
  姓名：{{name}} 年龄：{{age}} 地址：{{address}}
</view>

条件渲染

Page({
    data: {
        score: 85
    }
})

<view wx:if="{{score<60}}">成绩不及格</view>
<view wx:elif="{{score>60 && score<80}}">成绩合格</view>
<view wx:elif="{{score>80 && score<100}}">成绩优秀</view>
<view wx:else>100分</view>

列表渲染

Page({
  data: {
    studentList: [{
        name: "Jake",
        age: 22,
        address: "beijing"
      },
      {
        name: "Tom",
        age: 23,
        address: "shanghai"
      },
      {
        name: "Jane",
        age: 24,
        address: "guangzhou"
      }
    ]
  }
})

<view>学生列表：</view>
<view wx:for="{{studentList}}" wx:key="index">
  {{index}} - {{item.name}} - {{item.age}} - {{item.address}}
</view>

<view>学生列表2：</view>
<view wx:for="{{studentList}}" wx:for-index="i" wx:for-item="obj" wx:key="i">
  {{i}} - {{obj.name}} - {{obj.age}} - {{obj.address}}
</view>

事件绑定和传参

<button bindtap="onClick" data-msg1="hello" data-msg2="world">点击</button>
<button bindtap="onClick2" data-name="年龄" data-value="18">点击</button>

Page({
    onClick(event) {
        const {
            msg1,
            msg2
        } = event.currentTarget.dataset
        console.log(msg1, msg2)
    },
    onClick2(e) {
        let name = e.currentTarget.dataset["name"]
        let value = e.currentTarget.dataset.value
        console.log(name, value);
    },
})

WXSS

使用样式

<view class="box1">
  hello world
</view>

.box1 {
  width: 200px;
  height: 100px;
  border: 1px solid red;
  border-radius: 5px;
  margin: 50px;
}

使用rpx

rpx（responsive pixel）: 可以根据屏幕宽度进行自适应。规定屏幕宽为750rpx。如在 iPhone6 上，屏幕宽度为375px，共有750个物理像素，则750rpx = 375px = 750物理像素，1rpx = 0.5px = 1物理像素。

<view class="box2">
  hello world2
</view>

.box2 {
  width: 400rpx;
  height: 200rpx;
  border: 1rpx solid red;
  border-radius: 10rpx;
  margin: 100rpx;
}

引入样式

在当前目录下新建my.wxss文件

.myTextStyle {
  font-size: 30px;
  color: blue;
  border: 1px solid red;
  border-radius: 50px;
  margin: 50px;
}

在index.wxss文件重引入

@import "./my.wxss";

这样就可以在index.wxml中使用了

<view class="myTextStyle">
  hello world3
</view>

WXS

WXS（WeiXin Script）是小程序的一套脚本语言，结合 WXML，可以构建出页面的结构。

WXS 与 JavaScript 是不同的语言，有自己的语法，不支持ES6规范，并不和 JavaScript 一致。

语法文档

在WXML使用

新建date.wxs文件

function handleDate(time) {
  var oDate = getDate(time);
  return oDate.getFullYear() + "-" + (oDate.getMonth() + 1) + "-" + oDate.getDate();
}

module.exports = handleDate

<wxs src="./date.wxs" module="handleCurrentDate" />
<text>{{handleCurrentDate()}}</text>

新建studentList.wxs文件

function filterScore(studentList) {
  return studentList.filter(function (item) {
    return item.age > 18
  })
}

function filterAge(studentList) {
  return studentList.filter(function (item) {
    return item.score > 60
  })
}

module.exports = {
  filterScore: filterScore,
  filterAge: filterAge
};

<view>过滤score大于60的</view>
<wxs src="./studentUtils.wxs" module="studentUtils" />
<view wx:for="{{studentUtils.filterScore(studentList)}}" wx:key="index">
  {{item.name}} - {{item.score}}
</view>
<view>过滤age大于18的</view>
<view wx:for="{{studentUtils.filterAge(studentList)}}">
  {{item.name}} - {{item.age}}
</view>

data

Page({
    data: {
        message: "hello world"
    }
})

获取

this.data.message

设置

this.setData({
      message: "hello 微信小程序"
})

生命周期

页面生命周期

Page({
  /**
   * 生命周期函数--监听页面加载
   */
  onLoad(options) {
    console.log("index onLoad");
  },

  /**
   * 生命周期函数--监听页面初次渲染完成
   */
  onReady() {
    console.log("index onReady");
  },

  /**
   * 生命周期函数--监听页面显示
   */
  onShow() {
    console.log("index onShow");
  },

  /**
   * 生命周期函数--监听页面隐藏
   */
  onHide() {
    console.log("index onHide");
  },

  /**
   * 生命周期函数--监听页面卸载
   */
  onUnload() {
    console.log("index onUnload");
  }
})

App生命周期

App({
  // 生命周期回调——监听小程序初始化。
  onLaunch(options) {
    console.log("App onLaunch");
  },
  // 生命周期回调——监听小程序初始化。
  onShow(options) {
    console.log("App onShow");
  },
  // 生命周期回调——监听小程序切后台。
  onHide() {
    console.log("App onHide");
  },
  // 错误监听函数。
  onError(msg) {
    console.log("App onError");
  }
})