微信小程序 root-portal

基础库 2.25.2 开始支持,低版本需做兼容处理。

微信 Windows 版:支持

微信 Mac 版:支持

微信 鸿蒙 OS 版:支持

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)、WebView

功能描述

使整个子树从页面中脱离出来,类似于在 CSS 中使用 fixed position 的效果。主要用于制作弹窗、弹出层等。

属性说明

属性 类型 默认值 必填 说明 最低版本
enable boolean true 否 是否从页面中脱离出来 2.26.1
externalClass string 否 外部样式类 3.9.2

示例代码

在开发者工具中预览效果

page-container

基础库 2.16.0 开始支持,低版本需做兼容处理。

微信 Windows 版:支持

微信 Mac 版:支持

微信 鸿蒙 OS 版:支持

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)、WebView

功能描述

页面容器。

微信小程序如果在页面内进行复杂的界面设计(如在页面内弹出半屏的弹窗、在页面内加载一个全屏的子页面等),用户进行返回操作会直接离开当前页面,不符合用户预期,预期应为关闭当前弹出的组件。 为此提供“假页”容器组件,效果类似于 popup 弹出层,页面内存在该容器时,当用户进行返回操作,关闭该容器不关闭页面。返回操作包括三种情形,右滑手势、安卓物理返回键和调用 navigateBack 接口。

属性说明

属性 类型 默认值 必填 说明 最低版本
show boolean false 否 是否显示容器组件 2.16.0
duration number 300 否 动画时长,单位毫秒 2.16.0
z-index number 100 否 z-index 层级 2.16.0
overlay boolean true 否 是否显示遮罩层 2.16.0
position string bottom 否 弹出位置,可选值为 top bottom right center 2.16.0
round boolean false 否 是否显示圆角 2.16.0
close-on-slide-down boolean false 否 是否在下滑一段距离后关闭 2.16.0
overlay-style string 否 自定义遮罩层样式 2.16.0
custom-style string 否 自定义弹出层样式 2.16.0
bind:beforeenter eventhandle 否 进入前触发 2.16.0
bind:enter eventhandle 否 进入中触发 2.16.0
bind:afterenter eventhandle 否 进入后触发 2.16.0
bind:beforeleave eventhandle 否 离开前触发 2.16.0
bind:leave eventhandle 否 离开中触发 2.16.0
bind:afterleave eventhandle 否 离开后触发 2.16.0
bind:clickoverlay eventhandle 否 点击遮罩层时触发 2.16.0

Bug & Tip

  1. tip: 当前页面最多只有 1 个容器,若已存在容器的情况下,无法增加新的容器
  2. tip: wx.navigateBack 无法在页面栈顶调用,此时没有上一级页面
  3. tip: 鸿蒙 OS 下暂时无法拦截页面返回

示例代码

在开发者工具中预览效果

movable-view

基础库 1.2.0 开始支持,低版本需做兼容处理。

微信 Windows 版:支持

微信 Mac 版:支持

微信 鸿蒙 OS 版:支持

渲染框架支持情况:WebView

功能描述

可移动的视图容器,在页面中可以拖拽滑动。movable-view必须在 movable-area 组件中,并且必须是直接子节点,否则不能移动。

属性说明

属性 类型 默认值 必填 说明 最低版本
direction string none 否 movable-view的移动方向,属性值有all、vertical、horizontal、none 1.2.0
inertia boolean false 否 movable-view是否带有惯性 1.2.0
out-of-bounds boolean false 否 超过可移动区域后,movable-view是否还可以移动 1.2.0
x number/string 否 定义x轴方向的偏移,如果x的值不在可移动范围内,会自动移动到可移动范围;改变x的值会触发动画;单位支持px(默认)、rpx; 1.2.0
y number/string 否 定义y轴方向的偏移,如果y的值不在可移动范围内,会自动移动到可移动范围;改变y的值会触发动画;单位支持px(默认)、rpx; 1.2.0
damping number 20 否 阻尼系数,用于控制x或y改变时的动画和过界回弹的动画,值越大移动越快 1.2.0
friction number 2 否 摩擦系数,用于控制惯性滑动的动画,值越大摩擦力越大,滑动越快停止;必须大于0,否则会被设置成默认值 1.2.0
disabled boolean false 否 是否禁用 1.9.90
scale boolean false 否 是否支持双指缩放,默认缩放手势生效区域是在movable-view内 1.9.90
scale-min number 0.1 否 定义缩放倍数最小值 1.9.90
scale-max number 10 否 定义缩放倍数最大值 1.9.90
scale-value number 1 否 定义缩放倍数,取值范围为 0.1 – 10 1.9.90
animation boolean true 否 是否使用动画 2.1.0
bindchange eventhandle 否 拖动过程中触发的事件,event.detail = {x, y, source} 1.9.90
bindscale eventhandle 否 缩放过程中触发的事件,event.detail = {x, y, scale},x和y字段在2.1.0之后支持 1.9.90
htouchmove eventhandle 否 初次手指触摸后移动为横向的移动时触发,如果catch此事件,则意味着touchmove事件也被catch 1.9.90
vtouchmove eventhandle 否 初次手指触摸后移动为纵向的移动时触发,如果catch此事件,则意味着touchmove事件也被catch 1.9.90

bindchange 返回的 source 表示产生移动的原因

值 说明
touch 拖动
touch-out-of-bounds 超出移动范围
out-of-bounds 超出移动范围后的回弹
friction 惯性
空字符串 setData

Bug & Tip

  1. tip: movable-view 必须设置width和height属性,不设置默认为10px
  2. tip: movable-view 默认为绝对定位,top和left属性为0px
  3. tip: 若当前组件所在的页面或全局开启了 enablePassiveEvent 配置项,该内置组件可能会出现非预期表现(详情参考 enablePassiveEvent 文档)

movable-area

基础库 1.2.0 开始支持,低版本需做兼容处理。

微信 Windows 版:支持

微信 Mac 版:支持

微信 鸿蒙 OS 版:支持

渲染框架支持情况:WebView

功能描述

movable-view 的可移动区域。

属性说明

属性 类型 默认值 必填 说明 最低版本
scale-area Boolean false 否 当里面的 movable-view 设置为支持双指缩放时,设置此值可将缩放手势生效区域修改为整个 movable-area 1.9.90

Bug & Tip

  1. tip: movable-area 必须设置 width 和 height 属性,不设置默认为 10px**
  2. tip: 当 movable-view 小于 movable-area 时,movable-view 的移动范围是在 movable-area 内;
  3. tip: 当 movable-view 大于 movable-area 时,movable-view 的移动范围必须包含 movable-area(x 轴方向和 y 轴方向分开考虑)
  4. tip: 若当前组件所在的页面或全局开启了 enablePassiveEvent 配置项,该内置组件可能会出现非预期表现(详情参考 enablePassiveEvent 文档)

示例代码

在开发者工具中预览效果

match-media

基础库 2.11.1 开始支持,低版本需做兼容处理。

微信 Windows 版:支持

微信 Mac 版:支持

微信 鸿蒙 OS 版:支持

渲染框架支持情况:WebView

功能描述

media query 匹配检测节点。可以指定一组 media query 规则,满足时,这个节点才会被展示。

通过这个节点可以实现“页面宽高在某个范围时才展示某个区域”这样的效果。

属性说明

属性 类型 默认值 必填 说明 最低版本
min-width number 否 页面最小宽度( px 为单位) 2.11.1
max-width number 否 页面最大宽度( px 为单位) 2.11.1
width number 否 页面宽度( px 为单位) 2.11.1
min-height number 否 页面最小高度( px 为单位) 2.11.1
max-height number 否 页面最大高度( px 为单位) 2.11.1
height number 否 页面高度( px 为单位) 2.11.1
orientation string 否 屏幕方向( landscape 或 portrait ) 2.11.1

示例代码

<match-media min-width="300" max-width="600">
  <view>当页面宽度在 300 ~ 500 px 之间时展示这里</view>
</match-media>

<match-media min-height="400" orientation="landscape">
  <view>当页面高度不小于 400 px 且屏幕方向为纵向时展示这里</view>
</match-media>

cover-view

目前原生组件均已支持同层渲染,建议使用 view 替代

基础库 1.4.0 开始支持,低版本需做兼容处理。

微信 Windows 版:支持

微信 Mac 版:支持

微信 鸿蒙 OS 版:支持

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)、WebView

功能描述

覆盖在原生组件之上的文本视图。

可覆盖的原生组件包括 map、video、canvas、camera、live-player、live-pusher

只支持嵌套 cover-view、cover-image,可在 cover-view 中使用 button。组件属性的长度单位默认为px,2.4.0起支持传入单位(rpx/px)。

属性说明

属性 类型 默认值 必填 说明 最低版本
scroll-top number/string 否 设置顶部滚动偏移量,仅在设置了 overflow-y: scroll 成为滚动元素后生效 2.1.0

Bug & Tip

  1. tip: cover-view和cover-image的aria-role仅可设置为button,读屏模式下才可以点击,并朗读出“按钮”;为空时可以聚焦,但不可点击
  2. tip: 基础库 2.2.4 起支持 touch 相关事件,也可使用 hover-class 设置点击态
  3. tip: 基础库 2.1.0 起支持设置 scale rotate 的 css 样式,包括 transition 动画
  4. tip: 基础库 1.9.90 起 cover-view 支持 overflow: scroll,但不支持动态更新 overflow
  5. tip: 基础库 1.9.90 起最外层 cover-view 支持 position: fixed
  6. tip: 基础库 1.9.0 起支持插在 view 等标签下。在此之前只可嵌套在原生组件map、video、canvas、camera内,避免嵌套在其他组件内。
  7. tip: 基础库 1.6.0 起支持css transition动画,transition-property只支持transform (translateX, translateY)与opacity。
  8. tip: 基础库 1.6.0 起支持css opacity。
  9. tip: 事件模型遵循冒泡模型,但不会冒泡到原生组件。
  10. tip: 文本建议都套上cover-view标签,避免排版错误。
  11. tip: 只支持基本的定位、布局、文本样式。不支持设置单边的border、background-image、shadow、overflow: visible等。
  12. tip: 建议子节点不要溢出父节点
  13. tip: 支持使用 z-index 控制层级
  14. tip: 默认设置的样式有:white-space: nowrap; line-height: 1.2; display: block;
  15. bug: 自定义组件嵌套 cover-view 时,自定义组件的 slot 及其父节点暂不支持通过 wx:if 控制显隐,否则会导致 cover-view 不显示

示例代码

在开发者工具中预览效果

cover-image

目前原生组件均已支持同层渲染,建议使用 image 替代

基础库 1.4.0 开始支持,低版本需做兼容处理。

微信 Windows 版:支持

微信 Mac 版:支持

微信 鸿蒙 OS 版:支持

渲染框架支持情况:Skyline (使用最新 Nightly 工具调试)、WebView

功能描述

覆盖在原生组件之上的图片视图。

可覆盖的原生组件同 cover-view,支持嵌套在 cover-view 里。

通用属性

属性 类型 默认值 必填 说明 最低版本
src string 否 图标路径,支持临时路径、网络地址(1.6.0起支持)、云文件ID(2.2.3起支持)。 1.4.0
referrer-policy string no-referrer 否 格式固定为 https://servicewechat.com/{appid}/{version}/page-frame.html,其中 {appid} 为微信小程序的 appid,{version} 为微信小程序的版本号,版本号为 0 表示为开发版、体验版以及审核版本,版本号为 devtools 表示为开发者工具,其余为正式版本; 2.13.0
合法值 说明
origin 发送完整的 referrer
no-referrer 不发送
bindload eventhandle 否 图片加载成功时触发 2.1.0
binderror eventhandle 否 图片加载失败时触发 2.1.0

支持的格式

格式 iOS Android
JPG √ √
PNG √ √
SVG x x
WEBP √ √
GIF √ √
BASE64 x x

基础类库

console

console.log 方法用于在 console 窗口输出信息。它可以接受多个参数,将它们的结果连接起来输出。

Math

属性

  • E
  • LN10
  • LN2
  • LOG2E
  • LOG10E
  • PI
  • SQRT1_2
  • SQRT2

以上属性的具体使用请参考 ES5 标准。

方法

  • abs
  • acos
  • asin
  • atan
  • atan2
  • ceil
  • cos
  • exp
  • floor
  • log
  • max
  • min
  • pow
  • random
  • round
  • sin
  • sqrt
  • tan

以上方法的具体使用请参考 ES5 标准。

JSON

方法

  • stringify(object): 将 object 对象转换为 JSON 字符串,并返回该字符串。
  • parse(string): 将 JSON 字符串转化成对象,并返回该对象。

示例代码:


console.log(undefined === JSON.stringify());
console.log(undefined === JSON.stringify(undefined));
console.log("null"===JSON.stringify(null));

console.log("111"===JSON.stringify(111));
console.log('"111"'===JSON.stringify("111"));
console.log("true"===JSON.stringify(true));
console.log(undefined===JSON.stringify(function(){}));

console.log(undefined===JSON.parse(JSON.stringify()));
console.log(undefined===JSON.parse(JSON.stringify(undefined)));
console.log(null===JSON.parse(JSON.stringify(null)));

console.log(111===JSON.parse(JSON.stringify(111)));
console.log("111"===JSON.parse(JSON.stringify("111")));
console.log(true===JSON.parse(JSON.stringify(true)));

console.log(undefined===JSON.parse(JSON.stringify(function(){})));

Number

属性

  • MAX_VALUE
  • MIN_VALUE
  • NEGATIVE_INFINITY
  • POSITIVE_INFINITY

以上属性的具体使用请参考 ES5 标准。

Date

属性

  • parse
  • UTC
  • now

以上属性的具体使用请参考 ES5 标准。

Global

属性

  • NaN
  • Infinity
  • undefined

以上属性的具体使用请参考 ES5 标准。

方法

  • parseInt
  • parseFloat
  • isNaN
  • isFinite
  • decodeURI
  • decodeURIComponent
  • encodeURI
  • encodeURIComponent

以上方法的具体使用请参考 ES5 标准。

数据类型

WXS 语言目前共有以下几种数据类型:

  • number : 数值
  • string :字符串
  • boolean:布尔值
  • object:对象
  • function:函数
  • array : 数组
  • date:日期
  • regexp:正则

number

语法

number 包括两种数值:整数,小数。

var a = 10;
var PI = 3.141592653589793;

属性

  • constructor:返回字符串 "Number"。

方法

  • toString
  • toLocaleString
  • valueOf
  • toFixed
  • toExponential
  • toPrecision

以上方法的具体使用请参考 ES5 标准。

string

语法

string 有两种写法:

'hello world';
"hello world";

属性

  • constructor:返回字符串 "String"。
  • length

除constructor外属性的具体含义请参考 ES5 标准。

方法

  • toString
  • valueOf
  • charAt
  • charCodeAt
  • concat
  • indexOf
  • lastIndexOf
  • localeCompare
  • match
  • replace
  • search
  • slice
  • split
  • substring
  • toLowerCase
  • toLocaleLowerCase
  • toUpperCase
  • toLocaleUpperCase
  • trim

以上方法的具体使用请参考 ES5 标准。

boolean

语法

布尔值只有两个特定的值:true 和 false。

属性

  • constructor:返回字符串 "Boolean"。

方法

  • toString
  • valueOf

以上方法的具体使用请参考 ES5 标准。

object

语法

object 是一种无序的键值对。使用方法如下所示:

var o = {} //生成一个新的空对象

//生成一个新的非空对象
o = {
  'string'  : 1,  //object 的 key 可以是字符串
  const_var : 2,  //object 的 key 也可以是符合变量定义规则的标识符
  func      : {}, //object 的 value 可以是任何类型
};

//对象属性的读操作
console.log(1 === o['string']);
console.log(2 === o.const_var);

//对象属性的写操作
o['string']++;
o['string'] += 10;
o.const_var++;
o.const_var += 10;

//对象属性的读操作
console.log(12 === o['string']);
console.log(13 === o.const_var);

属性

  • constructor:返回字符串 "Object"。
console.log("Object" === {k:"1",v:"2"}.constructor)

方法

  • toString:返回字符串 "[object Object]"。

function

语法

function 支持以下的定义方式:

//方法 1
function a (x) {
  return x;
}

//方法 2
var b = function (x) {
  return x;
}

function 同时也支持以下的语法(匿名函数,闭包等):

var a = function (x) {
  return function () { return x;}
}

var b = a(100);
console.log( 100 === b() );

arguments

function 里面可以使用 arguments 关键词。该关键词目前只支持以下的属性:

  • length: 传递给函数的参数个数。
  • [index]: 通过 index 下标可以遍历传递给函数的每个参数。

示例代码:

var a = function(){
  console.log(3 === arguments.length);
  console.log(100 === arguments[0]);
  console.log(200 === arguments[1]);
  console.log(300 === arguments[2]);
};
a(100,200,300);

属性

  • constructor:返回字符串 "Function"。
  • length:返回函数的形参个数。

方法

  • toString:返回字符串 "[function Function]"。

示例代码:

var func = function (a,b,c) { }

console.log("Function" === func.constructor);
console.log(3 === func.length);
console.log("[function Function]" === func.toString());

array

语法

array 支持以下的定义方式:

var a = [];      //生成一个新的空数组

a = [1,"2",{},function(){}];  //生成一个新的非空数组,数组元素可以是任何类型

属性

  • constructor:返回字符串 "Array"。
  • length

除constructor外属性的具体含义请参考 ES5 标准。

方法

  • toString
  • concat
  • join
  • pop
  • push
  • reverse
  • shift
  • slice
  • sort
  • splice
  • unshift
  • indexOf
  • lastIndexOf
  • every
  • some
  • forEach
  • map
  • filter
  • reduce
  • reduceRight

以上方法的具体使用请参考 ES5 标准。

date

语法

生成 date 对象需要使用 getDate函数, 返回一个当前时间的对象。

getDate()
getDate(milliseconds)
getDate(datestring)
getDate(year, month[, date[, hours[, minutes[, seconds[, milliseconds]]]]])
  • 参数
    • milliseconds: 从1970年1月1日00:00:00 UTC开始计算的毫秒数
    • datestring: 日期字符串,其格式为:”month day, year hours:minutes:seconds”

语句

if 语句

在微信小程序 WXS 中,可以使用以下格式的 if 语句 :

  • if (expression) statement : 当 expression 为真值时,执行 statement。

  • if (expression) statement1 else statement2 : 当 expression 为真值时,执行 statement1。 否则,执行 statement2

  • if ... else if ... else statementN 通过该句型,可以在 statement1 到 statementN 之间选择其中一个执行。

示例语法:

// if ...

if (表达式) 语句;

if (表达式)
  语句;

if (表达式) {
  代码块;
}

// if ... else

if (表达式) 语句;
else 语句;

if (表达式)
  语句;
else
  语句;

if (表达式) {
  代码块;
} else {
  代码块;
}

// if ... else if ... else ...

if (表达式) {
  代码块;
} else if (表达式) {
  代码块;
} else if (表达式) {
  代码块;
} else {
  代码块;
}

switch 语句

示例语法:

switch (表达式) {
  case 变量:
    语句;
  case 数字:
    语句;
    break;
  case 字符串:
    语句;
  default:
    语句;
}
  • default 分支可以省略不写。
  • case 关键词后面只能使用:变量,数字,字符串。

示例代码:

var exp = 10;

switch ( exp ) {
case "10":
  console.log("string 10");
  break;
case 10:
  console.log("number 10");
  break;
case exp:
  console.log("var exp");
  break;
default:
  console.log("default");
}

输出:

number 10

for 语句

示例语法:

for (语句; 语句; 语句)
  语句;

for (语句; 语句; 语句) {
  代码块;
}
  • 支持使用 break,continue 关键词。

示例代码:

for (var i = 0; i < 3; ++i) {
  console.log(i);
  if( i >= 1) break;
}

输出:

0
1

while 语句

示例语法:

while (表达式)
  语句;

while (表达式){
  代码块;
}

do {
  代码块;
} while (表达式)
  • 当表达式为 true 时,循环执行语句或代码块。
  • 支持使用 break,continue 关键词。