基本概念

组件（Widgets） API 是微搭运行框架内置的一种核心 API，它在微搭的作用，类似 Web的 DOM API，可以快捷去获取或操作组件的属性。

使用场景

场景1：读取修改组件属性

例如单行输入组件，当想读取或修改用户当前已输入的值时，微搭可以通过 Widgets API 读取和修改输入值：

::: js
获取和设置组件属性值 - 图1page.widgets.idInput.value = ‘xxx’ // 修改当前输入框的值
:::


其中 idInput 是单行输入组件的组件 ID。

组件 ID 的获取方式，如下图组件配置面板所示：

获取和设置组件属性值 - 图2

场景2：主动调用组件 API

例如 Form 表单容器组件，常规需要添加一个<button type="submit">Submit</button>具备提交属性的按钮，才可以触发 form 的 onSubmit 事件。而利用 Widgets API，则可以通过任何组件在任何时刻主动提交表单内容：

::: JS
$page.widgets.idForm.submit() // 主动校验并提交表单
:::-

API 详细用法

自定义属性

如下文本组件 id17 的属性，微搭将自动生成内置对象 $page.widgets.id17，可通过此对象读取该组件的所有属性，属性 Key 可参见 console 面板：
获取和设置组件属性值 - 图3

快速修改/读取组件的某一属性：

::: JS
$page.widgets.id17. =
:::

内置属性

各组件除了本身的属性，还包含以下内置公共属性：

属性名 读写性 说明
style 可写 设置 CSS 组件的样式，与 H5 的 DOM API 一致，如修改组件字体的颜色：$page.widgets.id17.style.color='red'
classList 可写 组件是 CSS class 列表，类似 H5 的 DOM API，但类型是数组，如新增一个 class：$page.widgets.id17.classList.push('active')
parent 只读 返回组件的父节点 widget 对象
children 只读 组件的子节点 widget 数组，包含所有 slot。注意：children 的顺序与组件实际顺序不保证一致

内置方法

方法名 说明 类型
findWidgets 用于筛选并获取子节点 widgets，第一个参数是函数方法，可递归向下查找所有符合条件的 widgets 节点，第二参数是是否包含已经被 IF 隐藏的 widgets 节点 (fn: (node: Widget) => boolean, isGetHiddenWidgets: boolean) => Widgets
getWidgetsByType 用于筛选并获取子节点 widgets，第一个参数是 widgetType，第二参数是是否包含已经被 IF 隐藏的 widgets 节点 (widgetType: string, isGetHiddenWidgets: boolean) => Widgets
getDom 返回当前组件的 Dom 节点对象 () => Promise<Dom>
getConfig 返回当前组件的配置 () => any
on 监听方法，第一个参数是事件名(类型)，第二个参数是监听函数方法 (type: string, fn: Function) => void
off 取消监听方法，第一个参数是事件名(类型)，第二个参数是监听函数方法 (type: string, fn: Function) => void

获取和设置组件样式的示例

例如获取一个文本组件的内容，以及设置该文本的样式（例如文字颜色），参见下图所示：
获取和设置组件属性值 - 图4