API 列表

命名空间 `$w`

微搭使用 $w 作为统一的作用域引用和命名空间，微搭前端运行时所有能力都可以通过这个命名空间访问到。典型的用法有：

前端实例访问，如：
- 组件实例访问：$w.<COMPONENT_ID> 如 $w.input1.value, $w.input1.setValue("Hello Weda!")
- 数据查询实例访问：$w.<QUERY_ID> 如 $w.query1.data
- 事件流实例访问：$w.<EVENT_FLOW_ID> 如 $w.eventflow1.trigger()

平台方法/属性访问，如：

// 函数表达式
$w.ABS(1)
// 用户权限
$w.auth.currentUser
// 调用数据源等云能力
$w.cloud.callDataSource({ ... })
// 工具方法
$w.utils.showLoading()
// 访问当前页面或者应用实例
$w.app.id // 获取应用 id
$w.page.dataset.params.query1 // 获取当前页面参数

循环作用域中数据和索引（item/index）的访问：$w.index_<postfix>, $w.item_<postfix>

其中平台属性和方法有：

名称	类型	说明
app	object	当前应用实例
page	object	当前页面实例
auth	object	用户权限相关方法和属性
device	object	当前设备信息
env	object	当前环境信息
wedaContext	object	当前上下文信息
cloud	object	数据源等云端能力集合
utils	object	平台工具方法集合
<函数表达式名>	function	平台提供的函数方法集合

实例访问

可通过统一命名空间 $w 对微搭内各种实例进行通用访问，当实例标识相同时，优先访问页面作用域内的实例，在同作用域内依据数据查询、事件流、组件的优先级进行访问。

组件实例

使用组件 ID $w.<COMPONENT_ID> 即可直接引用组件，如 $w.button1, $w.form1。通过组件引用可以获取组件的只读属性及调用方法，如 $w.listView1.refresh() 会刷新 id 为 listView1 的数据列表组件，通过 $w.button1.text 可以直接获取 button1 按钮的文本内容。

需要注意的是，如果某个组件是在一个循环 repeater 当中的话，在该 repeater 外则不能直接获取该组件引用，在同一 repeater 内的其他组件任然可以 $w.<COMPONENT_ID> 来引用兄弟组件或者 repeater 外的组件。

通用属性/方法

微搭中组件会具备一些属性和方法，以下属性和方法是所有组件都具备的：

名称	类型	说明
id	string	组件 ID，微搭中一般由编辑器生成
component	string	组件名，如 `WdButton`
module	string	组件库名，微搭默认组件库名为 `gsd-h5-react`
parent	Component	父组件引用
children	Component[]	子组件集合

更多组件文档请参考具体的组件文档。

不要额外保存组件的引用属性

微搭应用中不要单独使用变量保存某个组件的引用类型属性（对象、方法等）然后直接使用该变量 ，如不要使用：

// Bad
const mySetValue = input1.setValue;
mySetValue("xxx");

因为微搭中同一个组件属性和方法在不同的时候不总是同一个引用，如表单类组件的 setValue 方法，具体某个属性是否会变化依赖该组件的实现，其原因和微搭在 web 默认的 react 实现方式有关

循环展示组件

循环展示组件 repeater 在微搭中是一类较特殊的组件，其内部组件在运行时的实例数量会被创建多份，在使用时会具备一些类似作用域的效果：

循环外部不能直接引用循环内部的实例。
循环中会创建 $w.item_xxx 和 $w.index_xxx 作用域上下文引用。循环展示组件内的组件，可通过 $w.<api> 来访问当前项的数据，索引，或同项的组件实例。具体信息如下：

名称	类型	说明
item_<postfix>	any	当前循环项的数据。数据类型取决于你的循环数据，如 [{name: 'Sarah'}]，即为对象
index_<postfix>	number	当前循环项的索引
<COMPONENT_ID>	string	通过组件 ID 访问同项的组件实例

更多关于如何使用循环展示组件的文档，请参考循环展示组件使用帮助文档。

有对循环进行封装的组件如表格都有类似行为作用域行为。

数据查询（query）

数据查询实例是对数据请求的对象化封装，支持对请求参数监听自动触发/通过方法手动触发，实例上包涵 data、error 属性，记录最后一次数据请求的响应结果。

使用数据查询标识（$w.<QUREY_ID>）可访问定义的数据查询实例，如 $w.query1。通过获取数据查询实例，可以访问当前最新的查询数据 $w.query1.data，或调用实例方法，如$w.query1.trigger()来触发当前实例的查询。

属性方法

名称	类型	说明
id	string	数据查询标识，页面内 query 标识保持唯一，全局 query 不应与任意 query 标识重复。
data	any	数据请求成功时响应结果，默认: null
error	error	数据请求失败时 Error 对象，默认：null
isFetching	boolean	数据请求状态，是否在请求中，默认：false
trigger	function	根据设定参数触发数据请求，类型：(params={}) => any，params 可以再查询中通过绑定表达式 params 进行访问
reset	function	重置 data、error 为 null

运行态约束

作用域，分为全局/页面作用域：
- 全局 query 可被任何作用域访问，query 内（数据请求入参绑定等）只可访问全局数据（$w 上静态方法以及 $app），不可访问 $w.page/$page 等对象
- 页面 query 只可被页面内的对象访问，且因页面变量初始化更早，页面变量初始化方法中不应访问 query 值，页面 query 内可以访问全局数据，页面对象静态数据（$page.id、$page.dataset.xxx），不可访问组件实例（$w.button1）、循环作用域（$w.item_xxx）等更低级作用域内值。
- 触发 query 时可以通过类似 query.trigger({test:10}) 的方式传入额外数据，query 的配置中可以通过绑定表达式 params.test 获取到传入的数据（10），当 query 为自动触发时，params 会获取到{}。
生命周期
- 创建：query 会在应用、页面实例创建时同步创建
- 初始化：针对自动触发（trigger 为 "auto"）类型的 query，将在应用/页面 Load 生命周期前，变量初始化完成后进行初始化，这意味着 query 初始化方法中可以使用应用/页面变量。与变量不同，query 初始化采用全异步方式，不会阻塞任何行为。
- 销毁：当应用/页面实例销毁时，query 实例跟随销毁。

事件流（EventFlow）

在微搭组件上可以对组件时间配置一系列的响应，并且可根据响应函数的成功失败事件再次配置对应的处理方法。事件流是对这种事件编排方式的一种封装，将一系列的基于事件串联起的动作封装为一个整体，可以在页面内进行复用。区别与流程引擎，事件流在客户端本地执行，流程在后端服务器上执行。

属性方法

名称	类型	说明
id	String	事件流标识，页面内标识保持唯一
trigger	Function	通过事件（${id}.start）触发事件流，类型：(data) => any，data 可在事件流入口结点中通过 event.detail 获取

运行态约束

普通事件编排基于每个响应动作再次触发成功失败事件，针对单个事件可配置多个并行的响应函数，最终可以形成一棵多叶子结点的树，与普通的事件编排不同，事件流作为一个整体响应动作被外界触发，要求最终的出口状态唯一，因此每个事件只能配置一个响应动作，不支持多动作并发。
作用域：每个响应动作的配置，只可访问 event、全局数据、页面对象静态数据（意味着不包含组件作用域，循环作用域等），其中入口结点可通过 event.detail来获取触发事件流时传入的数据。

应用实例

微搭前端应用实例，通过 $w.app 访问，也可以使用 $app 做快捷引用。

$w.app

名称	类型	说明
id	string	应用 id
label	string	应用名称
version	string	应用版本
mpAppId	string	小程序 appid
mpAppName	string	小程序名称
dataset	AppDataset	全局数据对象象
common	object	全局 common 方法
setState	function	设置全局变量

页面实例

当前页面实例，通过 $w.page 访问，可以使用 $page 做快捷引用。

$w.page

名称	类型	说明
id	string	当前页面的 id
label	string	当前页面的名称
path	string	当前页面的路径
dataset	PageDataset	页面数据对象
handler	object	页面定义 handler 方法
setState	function	设置页面变量
setParams	function	替换页面参数

设备信息

当前设备信息，通过 $w.device 访问。

$w.device

名称	类型	说明
viewport	object	窗口信息
networkType	string	移动端网络类型

环境信息

当前环境信息，通过 $w.env 访问。

$w.env

名称	类型	说明
type	string	环境类型
id	string	环境 id

上下文信息

当前上下文信息，通过 $w.wedaContext 访问。

$w.wedaContext

名称	类型	说明
isEditorMode	boolean	是否在编辑区
platforms	array	应用运行终端 ['WEB', 'MOBILEWEB', 'PCWEB', 'MOBILE', 'MP']

平台方法

微搭提供了一系列的内置前端方法可以在前端中调用。

用户/权限

名称	说明
$w.auth.getUserInfo	获取用户信息
$w.auth.currentUser	用户信息引用
$w.auth.signOut	用户退出登录
$w.auth.loginScope	获取用户登录权限范围

数据源

名称	说明
$w.cloud.callDataSource	调用数据源

流程

名称	说明
$w.cloud.callWorkflow	调用流程

其他云端能力

名称	说明
$w.cloud.getTempFileURL	通过 cloudid 获取静态文件的 http 访问地址
$w.cloud.getCloudInstance	返回云开发 web-sdk 初始化后的实例(无需关心 tcb 环境信息及认证登录的处理), 即 tcb.init 后返回的对象, 可用该对象直接调用 tcb 的各种能力
$w.cloud.callFunction	调用云开发的云函数, 与 $w.cloud.getCloudInstance 示例中的效果大体一致
$w.cloud.getUrlWithOpenidToken	在登录认证源设置中，h5 开启"微信小程序 OPENID 登录"后，使用此函数可以返回带有微信小程序授权登录 token 参数的 h5 跳转链接，可以用于微信小程序 webview 中的 h5 页面 openid 静默授权登录

通用工具/交互方法

名称	说明
$w.utils.showToast	显示提示框
$w.utils.showLoading	显示全局加载中提示
$w.utils.hideLoading	隐藏全局加载中提示
$w.utils.showModal	显示模态弹框
$w.utils.callPhone	拨打电话
$w.utils.scanCode	扫描二维码
$w.utils.setClipboardData	复制到剪贴板码
$w.utils.navigateTo	跳转到应用某个页面
$w.utils.redirectTo	关闭当前页面，跳转到应用内的某个页面
$w.utils.reLaunch	关闭所有页面，打开到应用内的某个页面
$w.utils.relaunchHome	返回首页
$w.utils.navigateBack	关闭当前页面，返回上一页面或多级页面
$w.utils.getEnumValue	获取枚举值
$w.utils.getStorage	读取数据缓存
$w.utils.setStorage	将数据存储在本地缓存中指定的 key 中
$w.utils.removeStorage	从本地缓存中移除指定 key
$w.utils.exportData `WEB`	导出数据为文件
$w.utils.requestSubscribeMessage `小程序`	调起客户端小程序订阅消息界面，返回用户订阅消息的操作结果
$w.utils.openLocation `小程序`	使用微信内置地图查看位置
$w.utils.reserveChannelsLive `小程序`	预约视频号直播
$w.utils.openchannelsUserProfile `小程序`	打开视频号主页
$w.utils.openChannelsLive `小程序`	打开视频号直播
$w.utils.openChannelsEvent `小程序`	打开视频号活动页
$w.utils.openChannelsActivity `小程序`	打开视频号视频
$w.utils.getChannelsLiveNoticeInfo `小程序`	获取视频号直播预告信息
$w.utils.getChannelsLiveInfo `小程序`	获取视频号直播信息

函数表达式

函数表达式是一组静态的逻辑工具方法，主要用来处理转换应用中各种数据。在组件属性绑定表达式区域可以省掉 $w 前缀。

名称	说明
$w.ABS	计算传入数字的绝对值
$w.Min	返回一组数字中的最小值
$w.Max	返回一组数字中的最大值
$w.Average	返回一组数字中的平均值
$w.Sum	计算一组数字的和
$w.Floor	返回传入数字向下取整的结果
$w.Ceiling	返回传入数字向上取整的结果
$w.Round	返回传入数字四舍五入后的结果
$w.Rand	返回一个指定范围的伪随机整数
$w.If	按判断条件进行逻辑比较，满足时返回一个值，不满足时返回另一个值
$w.IsEmpty	判断输入值是否为空，如果结果为数组类型，还会判断结果数组项是否全为空
$w.And	用于确定所有判断条件是否为真
$w.Or	任意一个判断条件为真，则结果为真；所有条件为否，结果才为否
$w.DateText	格式化日期时间为指定格式的文本
$w.DateTimeValue	将日期时间文本根据指定格式转化为日期时间
$w.Now	返回当前系统时间，通常与其他日期时间函数搭配使用
$w.GetDate	根据输入的年月日数值返回一个日期类型的数据
$w.Timestamp	根据输入的日期时间返回时间戳
$w.Second	根据输入的日期时间返回该时间的秒数
$w.Minute	根据输入的日期时间返回该时间的分钟部分
$w.Hour	根据输入的日期时间返回该时间的小时部分，24 小时制
$w.Day	根据输入的日期时间返回该时间的日部分，范围为 1-31
$w.DayOfWeek	根据输入的日期时间返回该时间的星期数
$w.Month	根据输入的日期时间返回该时间的月份
$w.Year	根据输入的日期时间返回该时间的年份
$w.Age	根据输入的两个日期时间计算出年龄
$w.AgeOfNow	计算当前年龄
$w.DateAdd	在传入的日期时间上增加 X 天，支持负数
$w.MonthAdd	在传入的日期和时间上增加 X 月，支持负数
$w.YearAdd	在传入的日期和时间上增加 X 年，支持负数
$w.YearDiff	返回两个日期时间字段之间的年数差，如果为同一年，差数为零
$w.MonthDiff	返回两个日期时间字段之间的月数差，如果为同一月，差数为零
$w.DateDiff	返回两个日期时间字段之间的天数差，如果为同一天，差数为零
$w.HourDiff	返回两个日期时间字段之间的小时差，如果为同一小时，差数为零
$w.MinuteDiff	返回两个日期时间字段之间的分钟差，如果为同一分钟，差数为零
$w.SecondDiff	返回两个日期时间字段之间的秒数差，如果为同一秒，差数为零
$w.IsToday	判断传入的日期时间是否为今天
$w.TimeText	格式化时间为指定格式的文本
$w.Len	获取传入文本的字符数
$w.Contains	判断文本 1 是否包含文本 2
$w.Split	根据传入的文本 2，将文本 1 拆分成文本数组
$w.Trim	删除文本开头和结尾的所有空格和制表符，文本中间的空格和制表符不会删除
$w.Upper	将传入的文本转为全大写文本
$w.Lower	将传入的文本转为全小写文本
$w.Concat	返回多个文本拼接后的新文本

命名空间 $w​

实例访问​

组件实例​

通用属性/方法​

循环展示组件​

数据查询（query）​

属性方法​

运行态约束​

事件流（EventFlow）​

属性方法​

运行态约束​

应用实例​

$w.app​

页面实例​

$w.page​

设备信息​

$w.device​

环境信息​

$w.env​

上下文信息​

$w.wedaContext​

平台方法​

用户/权限​

数据源​

流程​

其他云端能力​

通用工具/交互方法​

函数表达式​

命名空间 `$w`

实例访问

组件实例

通用属性/方法

循环展示组件

数据查询（query）

属性方法

运行态约束

事件流（EventFlow）

属性方法

运行态约束

应用实例

$w.app

页面实例

$w.page

设备信息

$w.device

环境信息

$w.env

上下文信息

$w.wedaContext

平台方法

用户/权限

数据源

流程

其他云端能力

通用工具/交互方法

函数表达式