amis/docs/zh-CN/components/tabs.md
2023-05-31 19:28:03 +08:00

24 KiB
Executable File
Raw Blame History

title description type group menuName icon order
Tabs 选项卡 0 ⚙ 组件 Tabs 68

选项卡容器组件。

基本用法

{
    "type": "tabs",
    "swipeable": true,
    "tabs": [
        {
            "title": "Tab 1",
            "tab": "Content 1"
        },
        {
            "title": "Tab 2",
            "tab": "Content 2"
        }
    ]
}

默认想要显示多少选项卡配置多少个 tabs 成员即可。但是有时候你可能会想根据某个数据来动态生成。这个时候需要额外配置 source 属性如。

{
    "type": "page",
    "data": {
        "arr": [
            {
                "a": "收入",
                "b": 199
            },

            {
                "a": "支出",
                "b": 299
            }
        ]
    },

    "body": [
        {
            "type": "tabs",
            "source": "${arr}",
            "tabs": [
                {
                    "title": "${a}",
                    "body": {
                        "type": "tpl",
                        "tpl": "金额:${b|number}元"
                    }
                }
            ]
        }
    ]
}

拖拽排序

{
    "type": "tabs",
    "draggable": true,
    "tabs": [
        {
            "title": "Tab 1",
            "tab": "Content 1"
        },
        {
            "title": "Tab 2",
            "tab": "Content 2"
        },
        {
            "title": "Tab 3",
            "tab": "Content 3"
        }
    ]
}

可增加、删除

tab 设置的 closable 优先级高于整体。使用 addBtnText 设置新增按钮文案

{
    "type": "tabs",
    "closable": true,
    "addable": true,
    "addBtnText": "新增Tab",
    "tabs": [
        {
            "title": "Tab 1",
            "tab": "Content 1",
            "closable": false
        },
        {
            "title": "Tab 2",
            "tab": "Content 2"
        }
    ]
}

可编辑标签名

双击标签名,可开启编辑

{
    "type": "tabs",
    "editable": true,
    "tabs": [
        {
            "title": "Tab 1",
            "tab": "Content 1",
        },
        {
            "title": "Tab 2",
            "tab": "Content 2"
        },
        {
            "title": "双击编辑",
            "tab": "Content 2"
        }
    ]
}

可禁用

{
    "type": "tabs",
    "tabs": [
        {
            "title": "Tab 1",
            "tab": "Content 1"
        },
        {
            "title": "Tab 2",
            "tab": "Content 2",
            "disabled": true
        }
    ]
}

显示提示

{
    "type": "tabs",
    "showTip": true,
    "tabs": [
        {
            "title": "Tab 1",
            "tab": "Content 1"
        },
        {
            "title": "Tab 2",
            "tab": "Content 2"
        }
    ]
}

作为表单项的值

如果在表单里给 tabs 配置了 name它可以作为一个表单提交项的值默认情况下会取 title

{
    "type": "form",
    "debug": true,
    "body": [
        {
            "type": "tabs",
            "name": "tab",
            "tabs": [
                {
                    "title": "Tab 1",
                    "tab": "Content 1"
                },
                {
                    "title": "Tab 2",
                    "tab": "Content 2"
                }
            ]
        }
    ]
}

如果不想使用 title可以给每个 tab 设置 value这样就会取这个 value 作为表单项的值

{
    "type": "form",
    "debug": true,
    "body": [
        {
            "type": "tabs",
            "name": "tab",
            "tabs": [
                {
                    "title": "Tab 1",
                    "tab": "Content 1",
                    "value": 0
                },
                {
                    "title": "Tab 2",
                    "tab": "Content 2",
                    "value": 1
                }
            ]
        }
    ]
}

展示模式

简约

{
    "type": "tabs",
    "tabsMode": "simple",
    "tabs": [
        {
            "title": "简约(10)",
            "body": "选项卡内容1",
            "icon": "fa fa-home"
        },
        {
            "title": "选项卡2",
            "body": "选项卡内容2"
        },
        {
            "title": "选项卡3",
            "body": "选项卡内容3"
        }
    ]
}

加强

{
    "type": "tabs",
    "tabsMode": "strong",
    "tabs": [
        {
            "title": "选项卡1",
            "body": "选项卡内容1"
        },
        {
            "title": "选项卡2",
            "body": "选项卡内容2"
        },
        {
            "title": "选项卡3",
            "body": "选项卡内容3"
        }
    ]
}

线型

{
    "type": "tabs",
    "tabsMode": "line",
    "tabs": [
        {
            "title": "选项卡1",
            "body": "选项卡内容1"
        },
        {
            "title": "选项卡2",
            "body": "选项卡内容2"
        },
        {
            "title": "选项卡3",
            "body": "选项卡内容3"
        }
    ]
}

卡片

{
    "type": "tabs",
    "tabsMode": "card",
    "tabs": [
        {
            "title": "选项卡1",
            "body": "选项卡内容1"
        },
        {
            "title": "选项卡2",
            "body": "选项卡内容2"
        },
        {
            "title": "选项卡3",
            "body": "选项卡内容3"
        }
    ]
}

仿 Chrome

仿 Chrome tab 样式

{
    "type": "tabs",
    "tabsMode": "chrome",
    "tabs": [
        {
            "title": "选项卡1",
            "body": "选项卡内容1"
        },
        {
            "title": "选项卡2",
            "body": "选项卡内容2"
        },
        {
            "title": "选项卡3",
            "body": "选项卡内容3"
        }
    ]
}

水平铺满

{
    "type": "tabs",
    "tabsMode": "tiled",
    "tabs": [
        {
            "title": "选项卡1",
            "body": "选项卡内容1"
        },
        {
            "title": "选项卡2",
            "body": "选项卡内容2"
        },
        {
            "title": "选项卡3",
            "body": "选项卡内容3"
        },
        {
            "title": "选项卡4",
            "body": "选项卡内容4"
        }
    ]
}

选择器型

{
    "type": "tabs",
    "tabsMode": "radio",
    "tabs": [
        {
            "title": "选项卡1",
            "body": "选项卡内容1"
        },
        {
            "title": "选项卡2",
            "body": "选项卡内容2"
        },
        {
            "title": "选项卡3",
            "body": "选项卡内容3"
        }
    ]
}

垂直

{
    "type": "tabs",
    "tabsMode": "vertical",
    "tabs": [
        {
            "title": "选项卡1",
            "body": "选项卡内容1"
        },
        {
            "title": "选项卡2",
            "body": "选项卡内容2"
        },
        {
            "title": "选项卡3",
            "body": "选项卡内容3"
        }
    ]
}

侧边栏模式

使用 sidePosition 设置标签栏位置。

{
    "type": "tabs",
    "tabsMode": "sidebar",
    "sidePosition": "right",
    "tabs": [
        {
            "title": "按钮",
            "body": "选项卡内容1",
            "icon": "fa fa-square"
        },
        {
            "title": "动作",
            "body": "选项卡内容2",
            "icon": "fa fa-gavel"
        }
    ]
}

配置顶部工具栏

配置toolbar实现顶部工具栏。

{
    "type": "tabs",
    "toolbar": [
        {
            "type": "button",
            "label": "按钮",
            "size": "sm",
            "actionType": "dialog",
            "dialog": {
                "title": "弹窗标题",
                "body": "你点击了"
            }
        }
    ],
    "tabs": [
        {
            "title": "Tab 1",
            "tab": "Content 1"
        },
        {
            "title": "Tab 2",
            "tab": "Content 2"
        }
    ]
}

配置 hash

可以在单个tab下,配置hash属性,支持地址栏#xxx

{
    "type": "tabs",
    "tabs": [
        {
            "title": "Tab 1",
            "hash": "tab1",
            "tab": "Content 1"
        },

        {
            "title": "Tab 2",
            "hash": "tab2",
            "tab": "Content 2"
        }
    ]
}

默认显示某个选项卡

主要配置activeKey属性来实现该效果,共有下面两种方法:

配置 hash 值

支持变量,如 "tab${id}"

{
    "type": "tabs",
    "activeKey": "tab2",
    "tabs": [
        {
            "title": "Tab 1",
            "hash": "tab1",
            "tab": "Content 1"
        },

        {
            "title": "Tab 2",
            "hash": "tab2",
            "tab": "Content 2"
        }
    ]
}

配置索引值

单个tab上不要配置hash属性,配置需要展示的tab索引值,0代表第一个。支持变量,如"${id}"

{
    "type": "tabs",
    "activeKey": 1,
    "tabs": [
        {
            "title": "Tab 1",
            "tab": "Content 1"
        },

        {
            "title": "Tab 2",
            "tab": "Content 2"
        }
    ]
}

动态设置选项卡

{
  "type": "page",
    "data": {
    "key": 2
  },
  "body": [
    {
      "type": "radios",
      "name": "key",
      "mode": "inline",
      "label": "激活的选项卡",
      "options": [
        {
          "label": "Tab 1",
          "value": 0
        },
        {
          "label": "Tab 2",
          "value": 1
        },
        {
          "label": "Tab 3",
          "value": 2
        }
      ]
    },
    {
      "type": "tabs",
      "activeKey": "${key|toInt}",
      "tabs": [
        {
          "title": "Tab 1",
          "tab": "Content 1"
        },
        {
          "title": "Tab 2",
          "tab": "Content 2"
        },
        {
          "title": "Tab 3",
          "tab": "Content 3"
        }
      ]
    }
  ]
}

初始化设置默认选项卡

2.7.1 以上版本

{
  "type": "page",
  "data": {
    "defaultKey": 1,
    "activeKey": 2
  },
  "body": [
    {
      "type": "radios",
      "name": "key",
      "mode": "inline",
      "label": "激活的选项卡",
      "options": [
        {
          "label": "Tab 1",
          "value": 0
        },
        {
          "label": "Tab 2",
          "value": 1
        },
        {
          "label": "Tab 3",
          "value": 2
        }
      ]
    },
    {
      "type": "tabs",
      "activeKey": "${activeKey|toInt}",
      "defaultKey": "${defaultKey|toInt}",
      "tabs": [
        {
          "title": "Tab 1",
          "tab": "Content 1"
        },
        {
          "title": "Tab 2",
          "tab": "Content 2"
        },
        {
          "title": "Tab 3",
          "tab": "Content 3"
        }
      ]
    }
  ]
}

初始化组件时 defaultKey 优先级高于 activeKey,但 defaultKey 仅作用于组件初始化时,不会响应上下文数据变化。

图标

通过 icon 可以设置 tab 的图标,可以是 fontawesome 或 URL 地址。

{
    "type": "tabs",
    "tabs": [
        {
            "title": "Tab 1",
            "tab": "Content 1",
            "icon": "https://suda.cdn.bcebos.com/images%2F2021-01%2Fdiamond.svg"
        },

        {
            "title": "Tab 2",
            "tab": "Content 2"
        }
    ]
}

配置超出折叠

通过配置 collapseOnExceed 可以用来实现超出折叠,额外还能通过 collapseBtnLabel 配置折叠按钮的文字

{
    "type": "tabs",
    "tabsMode": "tiled",
    "tabs": [
        {
            "title": "Tab 1",
            "tab": "Content 1",
        },

        {
            "title": "Tab 2",
            "tab": "Content 2"
        },

        {
            "title": "Tab 3",
            "tab": "Content 3",
        },

        {
            "title": "Tab 4",
            "tab": "Content 4"
        },

        {
            "title": "Tab 5",
            "tab": "Content 5"
        }
    ],

    "collapseOnExceed": 3
}

mountOnEnter

只有在点击卡片的时候才会渲染,在内容较多的时候可以提升性能,但第一次点击的时候会有卡顿。

unmountOnExit

如果你想在切换 tab 时,自动销毁掉隐藏的 tab请配置"unmountOnExit": true

监听切换事件

{
    "type": "tabs",
    "activeKey": "tab2",
    "onSelect": "alert(key)",
    "tabs": [
      {
        "title": "Tab 1",
        "hash": "tab1",
        "tab": "Content 1"
      },
      {
        "title": "Tab 2",
        "hash": "tab2",
        "tab": "Content 2"
      }
    ]
  }

会传递 key 参数和 props

属性表

属性名 类型 默认值 说明
type string "tabs" 指定为 Tabs 渲染器
defaultKey string / number 组件初始化时激活的选项卡hash 值或索引值,支持使用表达式 2.7.1 以上版本
activeKey string / number 激活的选项卡hash 值或索引值,支持使用表达式,可响应上下文数据变化
className string 外层 Dom 的类名
tabsMode string 展示模式,取值可以是 linecardradioverticalchromesimplestrongtiledsidebar
tabsClassName string Tabs Dom 的类名
tabs Array tabs 内容
source string tabs 关联数据,关联后可以重复生成选项卡
toolbar SchemaNode tabs 中的工具栏
toolbarClassName string tabs 中工具栏的类名
tabs[x].title string Tab 标题
tabs[x].icon icon Tab 的图标
tabs[x].iconPosition left / right left Tab 的图标位置
tabs[x].tab SchemaNode 内容区
tabs[x].hash string 设置以后将跟 url 的 hash 对应
tabs[x].reload boolean 设置以后内容每次都会重新渲染,对于 crud 的重新拉取很有用
tabs[x].unmountOnExit boolean 每次退出都会销毁当前 tab 栏内容
tabs[x].className string "bg-white b-l b-r b-b wrapper-md" Tab 区域样式
tabs[x].closable boolean false 是否支持删除,优先级高于组件的 closable
tabs[x].disabled boolean false 是否禁用
mountOnEnter boolean false 只有在点中 tab 的时候才渲染
unmountOnExit boolean false 切换 tab 的时候销毁
addable boolean false 是否支持新增
addBtnText string 增加 新增按钮文案
closable boolean false 是否支持删除
draggable boolean false 是否支持拖拽
showTip boolean false 是否支持提示
showTipClassName string '' 提示的类
editable boolean false 收否可编辑标签名
scrollable boolean true 是否导航支持内容溢出滚动。(属性废弃)
sidePosition left / right left sidebar 模式下,标签栏位置
collapseOnExceed number 当 tabs 超出多少个时开始折叠
collapseBtnLabel string more 用来设置折叠按钮的文字
swipeable boolean false 是否开启手势滑动切换(移动端生效)

事件表

当前组件会对外派发以下事件,可以通过onEvent来监听这些事件,并通过actions来配置执行的动作,在actions中可以通过${事件参数名}${event.data.[事件参数名]}来获取事件产生的数据,详细请查看事件动作

[name]表示当前组件绑定的名称,即name属性,如果没有配置name属性,则通过value取值。

事件名称 事件参数 说明
change value: number | string 选项卡索引 切换选项卡时触发

change

{
    "type": "tabs",
    "mode": "line",
    "tabs": [
    {
        "title": "选项卡1",
        "body": "选项卡内容1"
    },
    {
        "title": "选项卡2",
        "body": "选项卡内容2"
    },
    {
        "title": "选项卡3",
        "body": "选项卡内容3"
    }
    ],
    "onEvent": {
        "change": {
            "actions": [
                {
                    "actionType": "toast",
                    "args": {
                    "msgType": "info",
                    "msg": "切换至选项卡${event.data.value}"
                    }
                }
            ]
        }
    }
}

动作表

当前组件对外暴露以下特性动作,其他组件可以通过指定actionType: 动作名称componentId: 该组件id来触发这些动作,动作配置可以通过args: {动作配置项名称: xxx}来配置具体的参数,详细请查看事件动作

动作名称 动作配置 说明
changeActiveKey activeKey: number | string 选项卡索引 激活指定的选项卡

changeActiveKey

可以尝试点击下方按钮,实现选项卡激活。

[
    {
      "type": "action",
      "label": "激活选项卡1",
      "className": "mr-3 mb-3",
      "onEvent": {
        "click": {
          "actions": [
            {
              "actionType": "changeActiveKey",
              "componentId": "tabs-change-receiver",
              "args": {
                "activeKey": 1
              }
            }
          ]
        }
      }
    },
    {
      "type": "action",
      "label": "激活选项卡2",
      "className": "mr-3 mb-3",
      "onEvent": {
        "click": {
          "actions": [
            {
              "actionType": "changeActiveKey",
              "componentId": "tabs-change-receiver",
              "args": {
                "activeKey": 2
              }
            }
          ]
        }
      }
    },
    {
      "type": "action",
      "label": "激活选项卡3",
      "className": "mr-3 mb-3",
      "onEvent": {
        "click": {
          "actions": [
            {
              "actionType": "changeActiveKey",
              "componentId": "tabs-change-receiver",
              "args": {
                "activeKey": 3
              }
            }
          ]
        }
      }
    },
    {
      "id": "tabs-change-receiver",
      "type": "tabs",
      "mode": "line",
      "tabs": [
        {
          "title": "选项卡1",
          "body": "选项卡内容1"
        },
        {
          "title": "选项卡2",
          "body": "选项卡内容2"
        },
        {
          "title": "选项卡3",
          "body": "选项卡内容3"
        }
      ]
    }
]