微信开发者工具
-
微信开发者工具
-
WebStorm
-
VS Code
微信开发者工具快捷键
快捷键 | 功能 |
---|---|
Shift+Alt+F | 格式化代码 |
Ctrl+B | 编译 |
Ctrl+D | 选中匹配 |
Ctrl+P | 跳转文件 |
微信小程序文件结构
小程序包含一个描述整体程序的 app 和多个描述各自页面的 page。
主体文件结构
一个小程序主体部分由 2 到 3 个文件组成,必须放在项目的根目录,如下:
文件 | 必填 | 作用 |
---|---|---|
app.js | 是 | 小程序逻辑 |
app.json | 是 | 小程序公共设置 |
app.wxss | 否 | 小程序公共样式表 |
注意:微信小程序根目录下,app.js 和 app.json 文件是必需的。
页面文件结构
一个小程序页面由 2 到 4 个文件组成,分别是:
文件类型 | 必填 | 作用 |
---|---|---|
js | 是 | 页面逻辑 ( 微信小程序没有window和document对象 ) |
wxml | 是 | 页面结构 ( XML语法,不是HTML语法 ) |
wxss | 否 | 页面样式表 ( 拓展了rpx尺寸单位,微信专属响应式像素 ) |
json | 否 | 页面配置 ( 不能写注释,否则编译报错 ) |
注意:微信小程序页面目录下,.js 和 .wxml 文件是必需的。
小程序四大标准
-
JSON 配置 JavaScript Object Notation(JavaScript对象表示法)
-
WXML 结构 WeiXin Markup Language(WeiXin标记语言)
-
WXSS 样式 Weixin Style Sheet
-
JS 脚本 JavaScript
Web三大标准
-
HTML 结构 HyperText Markup Language
-
WXSS 样式 Cascading Style SheetJS
-
脚本 JavaScript
JSON - 小程序配置文件
app.json
文件用来对微信小程序进行全局配置,决定页面文件的路径、窗口表现、设置网络超时时间、设置多 tab 等。
以下是一个包含了所有配置选项的 app.json
:
{
"pages": [
"pages/index/index",
"pages/logs/index"
],
"window": {
"navigationBarTitleText": "Demo"
},
"tabBar": {
"list": [{
"pagePath": "pages/index/index",
"text": "首页"
}, {
"pagePath": "pages/logs/logs",
"text": "日志"
}]
},
"networkTimeout": {
"request": 10000,
"downloadFile": 10000
},
"debug": true
}
app.json 全局配置
属性 | 类型 | 必填 | 描述 |
---|---|---|---|
pages | String Array | 是 | 设置页面路径 |
window | Object | 否 | 设置默认页面的窗口表现 |
tabBar | Object | 否 | 设置底部 tab 的表现 |
networkTimeout | Object | 否 | 设置网络超时时间 |
debug | Boolean | 否 | 设置是否开启 debug 模式 |
pages 配置项
用于设置小程序的页面组成,接受一个数组,每一项都是字符串。
以下是 app.json 中 pages 的配置示例:
{
"pages":[
"pages/index/index",
"pages/logs/logs"
]
}
注意:
1. 数组的第一项代表小程序的初始页面。
2. 小程序中新增/减少页面,都需要对 pages 数组进行修改。
3. 文件名不需要写文件后缀,因为框架会自动去寻找路径下 .json, .js, .wxml, .wxss 四个文件进行整合。
window 配置项
用于设置小程序的状态栏、导航条、标题、窗口背景色。
属性 | 类型 | 默认值 | 描述 |
---|---|---|---|
navigationBarBackgroundColor | HexColor | #000000 | 导航栏背景颜色,如"#000000" |
navigationBarTextStyle | String | white | 导航栏标题颜色,仅支持 black/white |
navigationBarTitleText | String | 导航栏标题文字内容 | |
backgroundColor | HexColor | #ffffff | 窗口的背景色 |
backgroundTextStyle | String | dark | 下拉背景字体、loading 图的样式,仅支持 dark/light |
enablePullDownRefresh | Boolean | false | 是否开启下拉刷新,详见页面相关事件处理函数。 |
onReachBottomDistance | Number | 50 | 页面上拉触底事件触发时距页面底部距离,单位为px |
以下是 app.json 中 window 的配置示例:
{
"window":{
"navigationBarBackgroundColor": "#ffffff",
"navigationBarTextStyle": "black",
"navigationBarTitleText": "微信接口功能演示",
"backgroundColor": "#eeeeee",
"backgroundTextStyle": "light"
}
}
tabBar 配置项
在pages里面的页面放在第一个是显示的页面,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 | 可选值 bottom、top,设置成top是无图标 |
其中 list 接受一个数组,数组中的每个项都是一个对象,其属性值如下:
属性 | 类型 | 必填 | 说明 |
---|---|---|---|
pagePath | String | 是 | 页面路径,必须在 pages 中先定义 |
text | String | 是 | tab 上按钮文字 |
iconPath | String | 否 | 图片路径,icon 大小限制为40kb,建议尺寸为 81px * 81px,当 postion 为 top 时,此参数无效 |
selectedIconPath | String | 否 | 选中时的图片路径,icon 大小限制为40kb,建议尺寸为 81px * 81px ,当 postion 为 top 时,此参数无效 |
以下是 app.json 中 tabbar 的配置示例:
"tabBar": {
"color": "#ddd",
"selectedColor": "#3cc51f",
"backgroundColor": "#fff",
"borderStyle": "black",
"list": [
{
"pagePath": "pages/components",
"text": "组件",
"iconPath": "images/icon_components@3x.png",
"selectedIconPath": "images/icon_components_active@3x.png"
},
{
"pagePath": "pages/interface",
"text": "接口",
"iconPath": "images/icon_interface@3x.png",
"selectedIconPath": "images/icon_interface_active@3x.png"
}
]
}
注意:
1. 当设置 position 为 top 时,将不会显示 icon。
2. tabBar 中的 list 是一个数组,只能配置最少2个、最多5个 tab,tab 按数组的顺序排序。
networkTimeout 配置项
可以设置各种网络请求的超时时间。
属性说明:
属性 | 类型 | 必填 | 说明 |
---|---|---|---|
request | Number | 否 | wx.request的超时时间,单位毫秒,默认为:60000 |
connectSocket | Number | 否 | wx.connectSocket的超时时间,单位毫秒,默认为:60000 |
uploadFile | Number | 否 | wx.uploadFile的超时时间,单位毫秒,默认为:60000 |
downloadFile | Number | 否 | wx.downloadFile的超时时间,单位毫秒,默认为:60000 |
debug 配置项
可以在开发者工具中开启 debug 模式,在开发者工具的控制台面板,调试信息以 info 的形式给出,其信息有Page的注册
,页面路由
,数据更新
,事件触发
。 可以帮助开发者快速定位一些常见的问题。
page.json 页面配置
每一个小程序页面也可以使用.json
文件来对本页面的窗口表现进行配置。 页面的配置比app.json
全局配置简单得多,只是设置 app.json 中的 window 配置项的内容,页面中配置项会覆盖 app.json 的 window 中相同的配置项。
属性 | 类型 | 默认值 | 描述 | |
---|---|---|---|---|
navigationBarBackgroundColor | HexColor | #000000 | 导航栏背景颜色,如"#000000" | |
navigationBarTextStyle | String | white | 导航栏标题颜色,仅支持 black/white | |
navigationBarTitleText | String | 导航栏标题文字内容 | ||
backgroundColor | HexColor | #ffffff | 窗口的背景色 | |
backgroundTextStyle | String | dark | 下拉 loading 的样式,仅支持 dark/light | |
enablePullDownRefresh | Boolean | false | 是否开启下拉刷新,详见页面相关事件处理函数。 | |
disableScroll | Boolean | false | 设置为 true 则页面整体不能上下滚动;只在 page.json 中有效,无法在 app.json 中设置该项 | |
onReachBottomDistance | Number | 50 | 页面上拉触底事件触发时距页面底部距离,单位为px |
{
"navigationBarBackgroundColor": "#ffffff",
"navigationBarTextStyle": "black",
"navigationBarTitleText": "微信接口功能演示",
"backgroundColor": "#eeeeee",
"backgroundTextStyle": "light"
}
注意:页面的.json只能设置 window 相关的配置项,以决定本页面的窗口表现,所以无需写 window 这个键,
WXML - 小程序结构文件
WXML(WeiXin Markup Language)是框架设计的一套标签语言,结合基础组件、事件系统,可以构建出页面的结构。
WXML 组件语法
-
双标记组件
<组件名> 内容 </组件名>
-
单标记组件
<组件名 />
注意:
1. 所有组件与属性都是小写,以连字符 - 连接。
2. 所有组件必须闭合。
组件共同属性类型
所有组件都有的属性:
属性名 | 类型 | 描述 | 注解 |
---|---|---|---|
id | String | 组件的唯一标示 | 保持整个页面唯一 |
class | String | 组件的样式类 | 在对应的 WXSS 中定义的样式类 |
style | String | 组件的内联样式 | 可以动态设置的内联样式 |
hidden | Boolean | 组件是否显示 | 所有组件默认显示 |
data-* | Any (任意属性) | 自定义属性 | 组件上触发的事件时,会发送给事件处理函数 |
bind* / catch* | EventHandler | 组件的事件 | 详见事件 |
WXML常用布局组件
框架为开发者提供了一系列基础组件,开发者可以通过组合这些基础组件进行快速开发。组件是视图层的基本组成单元。
容器组件
<view>
是最常用的视图容器组件,类似于HTML中的 <div>
标签。
<view> </view>
属性名 | 类型 | 默认值 | 说明 |
---|---|---|---|
hover-class | String | none | 指定按下去的样式类。当 hover-class="none" 时,没有点击态效果 |
hover-start-time | Number | 50 | 按住后多久出现点击态,单位毫秒 (开始时间) |
hover-stay-time | Number | 400 | 手指松开后点击态保留时间,单位毫秒 (持续时间) |
注意:
1. 如果需要使用滚动视图,请使用 <scroll-view> 组件。
2. 目前支持 hover-class 属性的组件有三个:view、button、navigator。
3. 支持 hover-class 属性的组件,同时也支持 hover-start-time、hover-stay-time。
文本组件
微信小程序的文本默认是不能复制的,<text>组件是唯一可以复制的文本的主键,需要加下面的一个属性为'true',长按可选中。
小程序支持转义符,在文本中直接加\n可以换行。
<text>
是最常用的基础内容组件,类似于HTML中的 <span>
标签。
<text> </text>
属性名 | 类型 | 默认值 | 说明 |
---|---|---|---|
selectable | Boolean | false | 文本是否可选 |
注意:
1. 支持转义符 "\" ,可通过 "\n" 实现文本换行。
2. <text> 组件内只支持 <text> 嵌套。
3. 除了 <text> 组件以外的其他组件都无法长按选中。
图片组件
<image>
是最常用的媒体组件,类似于HTML中的 <img>
标签。
<image src="图片资源地址" />
属性名 | 类型 | 默认值 | 说明 | 最低版本 |
---|---|---|---|---|
src | String | 图片资源地址 | ||
mode | String | 'scaleToFill' | 图片裁剪、缩放的模式 | |
lazy-load | Boolean | false | 图片懒加载。只针对page与scroll-view下的image有效 | 1.5.0 |
binderror | HandleEvent | 当错误发生时,发布到 AppService 的事件名,事件对象event.detail = {errMsg: 'something wrong'} | ||
bindload | HandleEvent | 当图片载入完毕时,发布到 AppService 的事件名,事件对象event.detail = {height:'图片高度px', width:'图片宽度px'} |
mode 有效值:
mode 有 13 种模式,其中 4 种是缩放模式,9 种是裁剪模式。
模式 | 值 | 说明 |
---|---|---|
缩放 | scaleToFill | 不保持纵横比缩放图片,使图片的宽高完全拉伸至填满 image 元素 |
缩放 | aspectFit | 保持纵横比缩放图片,使图片的长边能完全显示出来。也就是说,可以完整地将图片显示出来。 |
缩放 | aspectFill | 保持纵横比缩放图片,只保证图片的短边能完全显示出来。也就是说,图片通常只在水平或垂直方向是完整的,另一个方向将会发生截取。 |
缩放 | widthFix | 宽度不变,高度自动变化,保持原图宽高比不变 |
裁剪 | 可选值 "top","bottom","center","left","right","top left","top right","bottom left","bottom right",不缩放图片,显示图片的指定区域。 |
注意:
1. image 组件必须闭合。
2. image 组件有默认宽度 300px、高度 225px。
3. 小程序样式表无法获取本地资源,本地图片资源优先使用 <image> 代替 background-image 。
<image style='width:100%' mode='widthFix' src='/upload/banner1.png' />
页面导航组件
<text>
是页面链接/导航组件,类似于HTML中的 <a>
标签。
<navigator url="跳转链接" open-type="navigate"> </navigator>
页面链接。
属性名 | 类型 | 默认值 | 说明 |
---|---|---|---|
url | String | 应用内的跳转链接 | |
open-type | String | navigate | 跳转方式,可选值 'navigate','switchTab','redirect' |
delta | Number | 当 open-type 为 'navigateBack' 时有效,表示回退的层数 | |
hover-class | String | navigator-hover | 指定点击时的样式类,当hover-class="none" 时,没有点击态效果 |
注意:
1. navigator-hover 默认为 {background-color: rgba(0, 0, 0, 0.1); opacity: 0.7;}。
2. navigate 跳转方式,保留当前页面,跳转到应用内的某个页面,使用 wx.navigateBack 可以返回到原页面。
3. switchTab 跳转方式,跳转到 tabBar 页面,并关闭其他所有非 tabBar 页面。
4. redirect 跳转方式,关闭当前页面,跳转到应用内的某个页面。
表单组件
表单组件目前包括:button,input,checkbox,radio,slider,switch,label,textarea,form,picker,picker-view,用于构建与用户交互的表单。
文本框组件
<input type="" />
属性名 | 类型 | 默认值 | 说明 | 最低版本 |
---|---|---|---|---|
value | String | 输入框的初始内容 | ||
type | String | "text" | input 的类型 | |
placeholder | String | 输入框为空时占位符 |
文本域组件
<textarea> </textarea>
单选框、复选框组件
<radio-group> </radio-group>
<radio value="" />
<checkbox-group> </checkbox-group>
<checkbox value="" />
switch组件
label组件
picker组件
form组件
button组件
form组件
silder组件
地图组件
<map> </map>
媒体组件
audio
video
camera
WXSS
WXSS(WeiXin Style Sheets)是一套样式语言,用于描述 WXML 的组件样式。
WXSS 用来决定 WXML 的组件应该怎么显示。
为了适应广大的前端开发者,WXSS 具有 CSS 大部分特性。同时为了更适合开发微信小程序,WXSS 对 CSS 进行了扩充以及修改。
与 CSS 相比,WXSS 扩展的特性有:
-
尺寸单位
-
样式导入
尺寸单位
-
rpx(responsive pixel): 可以根据屏幕宽度进行自适应。规定屏幕宽为750rpx。如在 iPhone6 上,屏幕宽度为375px,共有750个物理像素,则750rpx = 375px = 750物理像素,1rpx = 0.5px = 1物理像素。
设备 | rpx换算px (屏幕宽度/750) | px换算rpx (750/屏幕宽度) |
---|---|---|
iPhone5 | 1rpx = 0.42px | 1px = 2.34rpx |
iPhone6 | 1rpx = 0.5px | 1px = 2rpx |
iPhone6 Plus | 1rpx = 0.552px | 1px = 1.81rpx |
建议: 开发微信小程序时设计师可以用 iPhone6 作为视觉稿的标准。
注意: 在较小的屏幕上不可避免的会有一些毛刺,请在开发时尽量避免这种情况。
样式导入
使用@import
语句可以导入外联样式表,@import
后跟需要导入的外联样式表的相对路径,用;
表示语句结束。
示例代码:
/** common.wxss **/
.small-p {
padding:5px;
}
/** app.wxss **/
@import "common.wxss";
.middle-p {
padding:15px;
}
内联样式
框架组件上支持使用 style、class 属性来控制组件的样式。
-
style:静态的样式统一写到 class 中。style 接收动态的样式,在运行时会进行解析,请尽量避免将静态的样式写进 style 中,以免影响渲染速度。
<view style="color:{{color}};" />
-
class:用于指定样式规则,其属性值是样式规则中类选择器名(样式类名)的集合,样式类名不需要带上
.
,样式类名之间用空格分隔。
<view class="normal_view" />
选择器
目前支持的选择器有:(官方公布)
选择器 | 样例 | 样例描述 |
---|---|---|
.class | .intro | 选择所有拥有 class="intro" 的组件 |
#id | #firstname | 选择拥有 id="firstname" 的组件 |
element | view | 选择所有 view 组件 |
element, element | view, checkbox | 选择所有文档的 view 组件和所有的 checkbox 组件 |
::after | view::after | 在 view 组件后边插入内容 |
::before | view::before | 在 view 组件前边插入内容 |
经过测试得出可用选择器:(以后框架升级迭代可能会发生变化)
实际可用的 wxss 选择器 | 样例 | 样例描述 |
---|---|---|
element element | view text | 选择 view 组件内部的所有 text 组件 |
:active | view:active | 点击 view 组件时的状态 |
:focus | input:focus | 选择获得焦点的 input 组件 |
:first-child | view:first-child | 选择属于父组件的第一个子组件的每个 view 组件。 |
:last-child | view:last-child | 选择属于其父组件最后一个子组件每个 view 组件。 |
:first-of-type | view:first-of-type | 选择属于其父组件的首个 view 组件的每个 view 组件。 |
:last-of-type | view:last-of-type | 选择属于其父组件的最后 view 组件的每个 view 组件。 |
可能存在兼容问题选择器:(以后框架升级迭代可能会发生变化)
可能存在兼容问题选择器 | |
---|---|
element > element | element + element |
element ~ element | |
:nth-of-type(n) | :nth-last-of-type(n) |
:nth-child(n) | :nth-last-child(n) |
:hover | :visited |
:enabled | :disabled |
:checked | |
:not(selected) | ::selection |
[attribute] | [attribute=value] |
全局样式与局部样式
定义在 app.wxss 中的样式为全局样式,作用于每一个页面。在 page 的 wxss 文件中定义的样式为局部样式,只作用在对应的页面,并会覆盖 app.wxss 中相同的选择器。
JS
项目案例:(样式设置)
主页:
<!-- 搜索框 -->
<view class="searchbar">
<view class="searchbar-in">
<!-- <view class="icon-search"></view> -->
<image class="icon-search" src="/images/icon_search@2x.png"></image>
<text>搜索</text>
</view>
</view>
<!-- 首页轮播图 -->
<!-- <view data-num="{{ num + 12 }}">一段文字 {{ msg + "拼接字符串" }} {{num}}</view> -->
<!-- <view wx:for="{{array}}">
{{index}}: {{item.message}}
</view> -->
<swiper class="index-swiper" indicator-dots="{{ true }}" indicator-color="rgba(255,255,255,.5)" indicator-active-color="#ffffff" interval="2500" autoplay="true" circular="true">
<block wx:for="{{ swiperArr }}" wx:for-index="i" wx:for-item="item" wx:key="">
<swiper-item>
<image class="index-swiper-img" src="{{ item.image_src }}" data-index="{{ i }}"></image>
</swiper-item>
</block>
</swiper>
<!-- 首页导航分区 -->
<view class="index-nav">
<!--
wx:if 与 hidden
wx:if 在初始渲染的时候性能更好,
hidden 在切换显示隐藏的时候性能更好
-->
<navigator class="index-nav-item" hover-class="none" url="">
<image class="index-nav-img" src="/upload/icon_index_nav_1@2x.png"></image>
</navigator>
<navigator class="index-nav-item" hover-class="none" url="">
<image class="index-nav-img" src="/upload/icon_index_nav_2@2x.png"></image>
</navigator>
<navigator class="index-nav-item" hover-class="none" url="">
<image class="index-nav-img" src="/upload/icon_index_nav_3@2x.png"></image>
</navigator>
<navigator class="index-nav-item" hover-class="none" url="">
<image class="index-nav-img" src="/upload/icon_index_nav_4@2x.png"></image>
</navigator>
</view>
<!-- 首页楼层 -->
<view class='floor'>
<!-- 首页标题 -->
<view class='floor-head' bindtap='testHandle'>
<navigator url='/pages/home/home' catchtap='sonHandle' class='floor-head-link' data-para='函数参数'>
<image class='floor-head-img' src='/upload/pic_floor01_title@2x.png'></image>
</navigator>
</view>
<!-- 楼层主体 -->
<view class='floor-body'>
<!-- 主体左侧大图 -->
<view class='floor-body-left'>
<navigator class='floor-body-img-link' url=''>
<image class='floor-body-left-img' src='/upload/pic_floor01_1@2x.png'></image>
</navigator>
</view>
<!-- 主体右侧小图 -->
<view class='floor-body-right'>
<navigator class='floor-body-img-link' url=''>
<image class='floor-body-right-img' src='/upload/pic_floor01_2@2x.png'></image>
</navigator>
<navigator class='floor-body-img-link' url=''>
<image class='floor-body-right-img' src='/upload/pic_floor01_3@2x.png'></image>
</navigator>
<navigator class='floor-body-img-link' url=''>
<image class='floor-body-right-img' src='/upload/pic_floor01_4@2x.png'></image>
</navigator>
<navigator class='floor-body-img-link' url=''>
<image class='floor-body-right-img' src='/upload/pic_floor01_5@2x.png'></image>
</navigator>
</view>
</view>
</view>
搜索框样式:
.searchbar{
background-color: #ff2d4a;
padding: 20rpx 16rpx;
}
.searchbar-in{
height: 60rpx;
color: #bbb;
background-color: #fff;
/* text-align: center;
line-height: 60rpx; */
border-radius: 5rpx;
/* flex伸缩盒布局 */
display: flex;
/* 1. 水平居中对齐 */
justify-content: center;
/* 2. 垂直居中对齐 */
align-items: center;
}
.icon-search{
width: 32rpx;
height: 32rpx;
/* background-color: pink; */
/* display: inline-block; */
margin-right: 16rpx;
/* background: url("/images/icon_search@2x.png"); */
}
轮播图样式:
/* 2. 轮播图分区 */
.index-swiper{
height: 340rpx;
}
.index-swiper-img{
width: 750rpx;
height: 340rpx;
}
导航样式:
.index-nav{
display: flex;
padding: 24rpx 0 29rpx 0 ;
background-color: #fff;
}
.index-nav-item{
flex: 1;
display: flex;
justify-content: center;
}
.index-nav-img{
width: 128rpx;
height: 140rpx;
}
首页楼层样式:
/* 首页楼层 */
.floor{
margin-top: 30rpx;
}
.floor-head-img{
width: 750rpx;
height: 59rpx;
}
.floor-body{
background-color: #fff;
padding: 20rpx 0 10rpx 16rpx;
display: flex;
}
.floor-body-right{
display: flex;
flex-wrap: wrap;
}
.floor-body-img-link{
margin: 0 10rpx 10rpx 0 ;
}
.floor-body-left-img{
width: 232rpx;
height: 386rpx;
}
.floor-body-right-img{
width: 233rpx;
height: 188rpx;
}