跳到主要内容

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>

其中平台属性和方法有：

名称类型说明
appobject当前应用实例
pageobject当前页面实例
authobject用户权限相关方法和属性
deviceobject当前设备信息
envobject当前环境信息
wedaContextobject当前上下文信息
cloudobject数据源等云端能力集合
aiobjectAI+ 能力集合
utilsobject平台工具方法集合
<函数表达式名>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 外的组件。

通用属性/方法​

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

名称类型说明
idstring组件 ID，微搭中一般由编辑器生成
componentstring组件名，如 WdButton
modulestring组件库名，微搭默认组件库名为 gsd-h5-react
parentComponent父组件引用
childrenComponent[]子组件集合

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

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

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

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

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

循环展示组件​

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

  1. 循环外部不能直接引用循环内部的实例。
  2. 循环中会创建 $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()来触发当前实例的查询。

属性方法​

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

运行态约束​

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

事件流（EventFlow）​

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

属性方法​

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

运行态约束​

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

应用实例​

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

$w.app​

名称类型说明
idstring应用 id
labelstring应用名称
versionstring应用版本
mpAppIdstring小程序 appid
mpAppNamestring小程序名称
datasetAppDataset全局数据对象象
commonobject全局 common 方法
setStatefunction设置全局变量

页面实例​

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

$w.page​

名称类型说明
idstring当前页面的 id
labelstring当前页面的名称
pathstring当前页面的路径
datasetPageDataset页面数据对象
handlerobject页面定义 handler 方法
setStatefunction设置页面变量
setParamsfunction替换页面参数

设备信息​

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

$w.device​

名称类型说明
viewportobject窗口信息
networkTypestring移动端网络类型

环境信息​

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

$w.env​

名称类型说明
typestring环境类型
idstring环境 id

上下文信息​

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

$w.wedaContext​

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

平台方法​

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

用户/权限​

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

数据源​

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

AI​

名称说明
$w.ai.LLM.chat大模型进行对话，支持流式与非流式对话
$w.ai.bot.sendMessage与 Agent 进行流式对话，返回文本流与 SSE 事件流
$w.ai.bot.getRecommendQuestions获取 Agent 推荐的问题建议，返回文本流与 SSE 事件流
$w.ai.bot.get获取某个 Agent 的信息
$w.ai.bot.list批量获取多个 Agent 的信息
$w.ai.bot.getChatRecords获取聊天记录
$w.ai.bot.sendFeedback发送对某条聊天记录的反馈信息
$w.ai.bot.getFeedback获取已存在的反馈信息
$w.ai.bot.createConversation创建与Agent的新对话
$w.ai.bot.getConversation获取对话列表
$w.ai.bot.deleteConversation删除指定对话
$w.ai.bot.speechToText语音转文字
$w.ai.bot.textToSpeech文字转语音
$w.ai.bot.getTextToSpeechResult获取文字转语音的结果

流程​

名称说明
$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返回多个文本拼接后的新文本