跳至主要內容

按钮 basic-button

2026年7月20日大约 7 分钟

按钮 basic-button

触发交互动作的按钮，支持四态样式（常态 / 悬停 / 点击 / 选中）。

  • 类型串：basic-button　默认尺寸：[120, 40]　分类：控件

实时预览

下面渲染的是真实组件（与编辑器 / 运行时同源）。修改右侧「样式参数」，左侧预览实时更新；点击底部「全页面查看」可放大。

属性

下表为本组件特有的属性；position / size / opacity / background / border / 联动选中 / 筛选等通用参数见组件手册总览。

basic

属性名称类型默认说明
text文本string按钮
text-arrangement文本排列select(radioGroup)horizontal可选：horizontal / vertical
padding内边距vector<上,右,下,左>(unit=px)[8,16,8,16]
show-select启用选中态booleanfalse
checked默认选中booleanfalse

stateStyles

属性名称类型默认说明
text-default-font字体font(gradient=true,underline=true,line-through=true){"family":"","size":16,"color":"#ffffff","bold":false,"it…
font-default-spacing字体间隔number(unit=px)0
text-default-position水平对齐方式select(radioGroup)center可选：left / center / right
text-default-vertical竖直对齐方式select(radioGroup)center可选：top / center / bottom
text-offset-default文字偏移vector<X,Y>(unit=px)[0,0]
font-default-shadow-color外发光颜色color#ffffff
font-default-shadow-blur外发光模糊程度number(unit=px)-1
font-default-shadow-offset发光偏移vector<X,Y>(unit=px)[0,0]
border-default-color边框颜色color#2f7bff
border-default-width边框宽度number(unit=px,min=0)0
border-default-radius圆角半径number(unit=px,min=0)6
border-default-style边框样式select(radioGroup)solid可选：solid / dashed / dotted / none
background-default-color背景颜色color(gradient)#2f7bff
background-default-image背景图/视频file—
background-default-fill-type填充方式select(radioGroup)stretch可选：stretch / tile / none
background-default-image-size图片比例number(unit=%)100
background-default-image-position图片位置vector<X,Y>(unit=px)[0,0]
background-default-blur背景模糊number(unit=px,min=0)0
background-default-use-nine-patch是否使用点九booleanfalse
background-default-nine-patch点九编辑nine-patch{}
show-click启用点击态booleanfalse
text-click-font字体font(gradient=true,underline=true,line-through=true)继承
font-click-spacing字体间隔number(unit=px)继承
text-click-position水平对齐方式select(radioGroup)继承可选：left / center / right
text-click-vertical竖直对齐方式select(radioGroup)继承可选：top / center / bottom
text-offset-click文字偏移vector<X,Y>(unit=px)继承
font-click-shadow-color外发光颜色color继承
font-click-shadow-blur外发光模糊程度number(unit=px)继承
font-click-shadow-offset发光偏移vector<X,Y>(unit=px)继承
border-click-color边框颜色color继承
border-click-width边框宽度number(unit=px,min=0)继承
border-click-radius圆角半径number(unit=px,min=0)继承
border-click-style边框样式select(radioGroup)继承可选：solid / dashed / dotted / none
background-click-color背景颜色color(gradient)继承
background-click-image背景图/视频file继承
background-click-fill-type填充方式select(radioGroup)继承可选：stretch / tile / none
background-click-image-size图片比例number(unit=%)继承
background-click-image-position图片位置vector<X,Y>(unit=px)继承
background-click-blur背景模糊number(unit=px,min=0)继承
background-click-use-nine-patch是否使用点九boolean继承
background-click-nine-patch点九编辑nine-patch继承
animation-click-show开启涟漪动画booleanfalse
animation-click-time动画时长number<float>(step=0.05,unit=秒)0.35
show-hover启用悬停态booleanfalse
text-hover-font字体font(gradient=true,underline=true,line-through=true)继承
font-hover-spacing字体间隔number(unit=px)继承
text-hover-position水平对齐方式select(radioGroup)继承可选：left / center / right
text-hover-vertical竖直对齐方式select(radioGroup)继承可选：top / center / bottom
text-offset-hover文字偏移vector<X,Y>(unit=px)继承
font-hover-shadow-color外发光颜色color继承
font-hover-shadow-blur外发光模糊程度number(unit=px)继承
font-hover-shadow-offset发光偏移vector<X,Y>(unit=px)继承
border-hover-color边框颜色color继承
border-hover-width边框宽度number(unit=px,min=0)继承
border-hover-radius圆角半径number(unit=px,min=0)继承
border-hover-style边框样式select(radioGroup)继承可选：solid / dashed / dotted / none
background-hover-color背景颜色color(gradient)继承
background-hover-image背景图/视频file继承
background-hover-fill-type填充方式select(radioGroup)继承可选：stretch / tile / none
background-hover-image-size图片比例number(unit=%)继承
background-hover-image-position图片位置vector<X,Y>(unit=px)继承
background-hover-blur背景模糊number(unit=px,min=0)继承
background-hover-use-nine-patch是否使用点九boolean继承
background-hover-nine-patch点九编辑nine-patch继承
animation-hover-show开启涟漪动画booleanfalse
animation-hover-time动画时长number<float>(step=0.05,unit=秒)0.35
text-select-font字体font(gradient=true,underline=true,line-through=true)继承
font-select-spacing字体间隔number(unit=px)继承
text-select-position水平对齐方式select(radioGroup)继承可选：left / center / right
text-select-vertical竖直对齐方式select(radioGroup)继承可选：top / center / bottom
text-offset-select文字偏移vector<X,Y>(unit=px)继承
font-select-shadow-color外发光颜色color继承
font-select-shadow-blur外发光模糊程度number(unit=px)继承
font-select-shadow-offset发光偏移vector<X,Y>(unit=px)继承
border-select-color边框颜色color继承
border-select-width边框宽度number(unit=px,min=0)继承
border-select-radius圆角半径number(unit=px,min=0)继承
border-select-style边框样式select(radioGroup)继承可选：solid / dashed / dotted / none
background-select-color背景颜色color(gradient)继承
background-select-image背景图/视频file继承
background-select-fill-type填充方式select(radioGroup)继承可选：stretch / tile / none
background-select-image-size图片比例number(unit=%)继承
background-select-image-position图片位置vector<X,Y>(unit=px)继承
background-select-blur背景模糊number(unit=px,min=0)继承
background-select-use-nine-patch是否使用点九boolean继承
background-select-nine-patch点九编辑nine-patch继承

relationship

属性名称类型默认说明
relationship-field关系字段string—
relationship-value关系值string—

数据绑定

无组件特有数据绑定字段（纯样式 / 布局 / 装饰）。

事件

触发器

触发器在预览 / 播放态生效（编辑态点击 = 选中组件）。写在本组件 options.interactions 的 groups[].trigger 里。

触发器名称触发时机payload（供动作公式 {:字段} 取值）
click点击点击本组件时触发无
mouseEnter鼠标移入指针移入组件时触发无
mouseLeave鼠标移出指针移出组件时触发无
appear入场组件出现时触发（配合进场动画）无
disappear离场组件消失时触发（配合退场动画）无
receiveBehaviorEvent接收行为事件收到 sendBehaviorEvent 动作或宿主 ctx.emit 投递的事件时触发（按 eventName 匹配）发送方携带的 data

动作

触发器命中后执行的动作。本组件既可发起动作（配在自己的交互里），也可作为其它组件动作的目标。

动作名称说明
switchScreen切换页面跳转到指定页面
switchWindow打开 / 关闭窗口开关工程级窗口（弹窗 / 抽屉）
sendBehaviorEvent发送行为事件向目标组件 / 宿主派发自定义事件
executeScript执行脚本派发命令串，由宿主 onScript 接管
editProjectParams修改项目参数改项目参数驱动规则 / 条件样式（千人千面）
requestApi调用接口发 HTTP 请求，结果可回写组件 / 参数
changeOption修改设置把本组件（或其它组件）的某个属性改为静态值 / 公式动态值
switchState切换状态切到多状态里的某个状态（state:"" 回默认态）
appear / disappear进 / 退场动画对目标 opacity 做 0↔100 插值的显隐动画

完整动作清单（switchScreen / switchWindow / openUrl / sendBehaviorEvent / transfer / executeScript / requestApi 等）与持久化写法见事件交互。

示例

{
  "type": "basic-button",
  "uid": "w_basic_button",
  "options": {
    "position": [40, 40],
    "size": [120, 40]
  }
}

组合示例：点击按钮 → 修改文本（事件交互）

预览就是播放态：点下面的按钮，右侧文本会被 changeOption 动作改写（连点切换两种文案由两组触发器示意）。

对应交互 JSON（写在按钮 options.interactions）：

{
  "version": 2,
  "groups": [
    {
      "trigger": {
        "name": "click",
        "options": {}
      },
      "interactions": [
        {
          "alias": "点击→改文本",
          "enable": true,
          "trigger": {
            "name": "click",
            "options": {}
          },
          "action": {
            "name": "changeOption",
            "options": {
              "targetElement": "searchElement",
              "element": [
                {
                  "targetPath": [
                    "screen_preview",
                    "demo_txt"
                  ],
                  "refType": "element"
                }
              ],
              "optionKey": "text",
              "text": "✔ 指令已下发，机组启动中…",
              "start": "meanwhile",
              "delay": 0,
              "duration": 1
            }
          }
        }
      ]
    }
  ]
}

延伸阅读：组件手册总览 · 数据系统 · 事件交互。

上次编辑于: 2026/7/20 16:45:09
贡献者: vjmap