amis2/docs/zh-CN/components/nav.md

title	description	type	group	menuName	icon	order
Nav 导航		0	⚙ 组件	Nav		58

用于展示链接导航

基本用法

{
  "type": "nav",
  "stacked": true,
  "className": "w-md",
  "itemBadge": {
    "mode": "ribbon",
    "text": "${customText}",
    "position": "top-left",
    "visibleOn": "this.customText",
    "level": "${customLevel}"
  },
  "links": [
    {
      "label": "Nav 1",
      "to": "/docs/index",
      "icon": "https://suda.cdn.bcebos.com/images%2F2021-01%2Fdiamond.svg",
      "active": true
    },
    {
      "label": "Nav 2",
      "to": "/docs/api",
      "customText": "HOT",
      "customLevel": "danger"
    },
    {
      "label": "Nav 3",
      "to": "/docs/renderers",
      "customText": "SUC",
      "customLevel": "success"
    },
    {
      "label": "外部地址",
      "to": "http://www.baidu.com/",
      "target": "_blank"
    }
  ]
}

配置多层级

{
  "type": "nav",
  "stacked": true,
  "className": "w-md",
  "links": [
    {
      "label": "Nav 1",
      "to": "/docs/index",
      "icon": "fa fa-user",
      "active": true
    },
    {
      "label": "Nav 2",
      "unfolded": true,
      "children": [
        {
          "label": "Nav 2-1",
          "children": [
            {
              "label": "Nav 2-1-1",
              "to": "/docs/api-2-1-1"
            }
          ]
        },
        {
          "label": "Nav 2-2",
          "to": "/docs/api-2-2"
        }
      ]
    },
    {
      "label": "Nav 3",
      "to": "/docs/renderers"
    }
  ]
}

横向摆放

{
  "type": "nav",
  "stacked": false,
  "links": [
    {
      "label": "Nav 1",
      "to": "/docs/index",
      "icon": "fa fa-user"
    },
    {
      "label": "Nav 2",
      "to": "/docs/api"
    },
    {
      "label": "Nav 3",
      "to": "/docs/renderers"
    }
  ]
}

响应式收纳

横向（"stack": false）模式下配置overflow，实现导航响应式收纳。

{
  "type": "nav",
  "stacked": false,
  "overflow": {
    "enable": true
  },
  "links": [
    {
      "label": "Nav 1",
      "to": "?to=nav1"
    },
    {
      "label": "Nav 2",
      "to": "?to=nav1"
    },
    {
      "label": "Nav 3",
      "to": "?to=nav3"
    },
    {
      "label": "Nav 4",
      "to": "?to=nav4"
    },
    {
      "label": "Nav 5",
      "to": "?to=nav5"
    },
    {
      "label": "Nav 6",
      "to": "?to=nav6"
    },
    {
      "label": "Nav 7",
      "to": "?to=nav7"
    },
    {
      "label": "Nav 8",
      "to": "?to=nav8"
    },
    {
      "label": "Nav 9",
      "to": "?to=nav9"
    },
    {
      "label": "Nav 10",
      "to": "?to=nav10"
    },
    {
      "label": "Nav 11",
      "to": "?to=nav11",
      "children": [
        {
          "label": "Nav 13",
          "to": "?to=nav13"
        }
      ]
    },
    {
      "label": "Nav 12",
      "to": "?to=nav12"
    }
  ]
}

设置maxVisibleCount可以自定义强制展示的导航数量，不设置则自动处理。设置overflowIndicator自定义菜单按钮的图标。 设置overflowLabel自定义菜单按钮文本。

{
  "type": "nav",
  "stacked": false,
  "overflow": {
    "enable": true,
    "overflowClassName": "nav-overflow-btn",
    "overflowPopoverClassName": "nav-overflow-popover",
    "overflowIndicator": "fas fa-angle-double-down",
    "overflowLabel": "更多",
    "maxVisibleCount": 5
  },
  "links": [
    {
      "label": "Nav 1",
      "to": "?to=nav1"
    },
    {
      "label": "Nav 2",
      "to": "?to=nav1"
    },
    {
      "label": "Nav 3",
      "to": "?to=nav3"
    },
    {
      "label": "Nav 4",
      "to": "?to=nav4"
    },
    {
      "label": "Nav 5",
      "to": "?to=nav5"
    },
    {
      "label": "Nav 6",
      "to": "?to=nav6"
    },
    {
      "label": "Nav 7",
      "to": "?to=nav7"
    },
    {
      "label": "Nav 8 Nav 8 Nav 8 Nav 8 Nav 8",
      "to": "?to=nav8"
    }
  ]
}

导航项收纳

垂直（"stack": true）模式下，如果子导航项比较多，也可以给导航项设置收纳模式，配置同overflow，仅支持一次性展开

{
  "type": "nav",
  "stacked": true,
  "expandPosition": "after",
  "style": {
    "width": 200
  },
  "links": [
    {
      "label": [
        {
          "type": "tpl",
          "tpl": "Nav1"
        }
      ],
      "to": "#/"
    },
    {
      "label": "Nav2",
      "unfolded": true,
      "overflow": {
        "enable": true
      },
      "children": [
        {
          "label": "Nav 2-1",
          "to": "#/test2"
        },
        {
          "label": "Nav 2-2",
          "to": "#/test3"
        },
        {
          "label": "Nav 2-3",
          "to": "#/test1"
        },
        {
          "label": "Nav 2-4",
          "to": "#/test4"
        },
        {
          "label": "Nav 2-5",
          "to": "#/test5"
        }
      ]
    }
  ]
}

动态导航

通过配置 source 来实现动态生成导航，source 可以是 api 地址或者变量，比如

{
  "type": "page",
  "data": {
    "nav": [
      {
        "label": "Nav 1",
        "to": "/docs/index",
        "icon": "fa fa-user"
      },
      {
        "label": "Nav 2",
        "to": "/docs/api"
      },
      {
        "label": "Nav 3",
        "to": "/docs/renderers"
      }
    ]
  },
  "body": {
    "type": "nav",
    "stacked": true,
    "source": "${nav}"
  }
}

懒加载

可以一次只加载部分层级，更深层次的选项可以标记为 defer 为 true，这样只有点开的时才会加载。

{
  "type": "nav",
  "stacked": true,
  "source": "/api/options/nav?parentId=${value}"
}

更多操作

{
  "type": "nav",
  "stacked": true,
  "className": "w-md",
  "draggable": true,
  "saveOrderApi": "/api/options/nav",
  "source": "/api/options/nav?parentId=${value}",
  "style": {
    "width": 160
  },
  "itemActions": [
    {
      "type": "icon",
      "icon": "cloud",
      "visibleOn": "this.to === '?cat=1'"
    },
    {
      "type": "dropdown-button",
      "level": "link",
      "icon": "fa fa-ellipsis-h",
      "hideCaret": true,
      "buttons": [
        {
          "type": "button",
          "label": "编辑"
        },
        {
          "type": "button",
          "label": "删除"
        }
      ]
    }
  ]
}

悬浮导航

可以通过设置mode属性来控制导航模式，不设置默认为内联导航模式

{
  "type": "nav",
  "stacked": true,
  "mode": "float",
  "style": {
    "width": "200px"
  },
  "links": [
    {
      "label": "Nav 1",
      "to": "/docs/index",
      "icon": "fa fa-user",
      "active": true
    },
    {
      "label": "Nav 2",
      "unfolded": true,
      "children": [
        {
          "label": "Nav 2-1",
          "children": [
            {
              "label": "Nav 2-1-1",
              "to": "/docs/api-2-1-1"
            }
          ]
        },
        {
          "label": "Nav 2-2",
          "to": "/docs/api-2-2"
        }
      ]
    },
    {
      "label": "Nav 3",
      "to": "/docs/renderers"
    }
  ]
}

导航缩起

collapsed属性控制导航的展开和缩起，缩起状态下，导航内容仅展示图标或第一个文字，悬浮展开全部内容或子导航项

{
  "type": "nav",
  "stacked": true,
  "collapsed": true,
  "links": [
    {
      "label": "Nav 1",
      "to": "/docs/index",
      "icon": "fa fa-user"
    },
    {
      "label": "Nav 2",
      "unfolded": true,
      "children": [
        {
          "label": "Nav 2-1",
          "children": [
            {
              "label": "Nav 2-1-1",
              "to": "/docs/api-2-1-1"
            }
          ]
        },
        {
          "label": "Nav 2-2",
          "to": "/docs/api-2-2"
        }
      ]
    },
    {
      "label": "Nav 3",
      "to": "/docs/renderers"
    }
  ]
}

导航分割线

导航项mode属性控制导航项的展示模式，支持divider（分割线）和group（分组）两种模式，不设置默认为普通导航项

{
  "type": "nav",
  "stacked": true,
  "style": {
    "width": "160px"
  },
  "links": [
    {
      "label": "Nav 1",
      "to": "/docs/index",
      "icon": "fa fa-user"
    },
    {
      mode: 'divider'
    },
    {
      "label": "Nav 2",
      "unfolded": true,
      "children": [
        {
          "label": "Nav 2-1",
          "children": [
            {
              "label": "Nav 2-1-1",
              "to": "/docs/api-2-1-1"
            }
          ]
        },
        {
          "label": "Nav 2-2",
          "to": "/docs/api-2-2"
        }
      ]
    },
    {
      "label": "Nav 3",
      "to": "/docs/renderers",
      "disabled": true,
      "disabledTip": "导航项禁用"
    }
  ]
}

导航分组

分组模式（"mode": "group"）的导航项展示为分组标题形式

{
  "type": "nav",
  "stacked": true,
  "links": [
    {
      "label": "Nav 1",
      "to": "/docs/index",
      "icon": "fa fa-user"
    },
    {
      "label": "Nav 2",
      "unfolded": true,
      "mode": "group",
      "children": [
        {
          "label": "Nav 2-1",
          "children": [
            {
              "label": "Nav 2-1-1",
              "to": "/docs/api-2-1-1"
            }
          ]
        },
        {
          "label": "Nav 2-2",
          "to": "/docs/api-2-2"
        }
      ]
    },
    {
      "label": "Nav 3",
      "to": "/docs/renderers",
      "mode": "group",
      "children": [
        {
          "label": "Nav 3-1",
          "to": "/docs/api-2-1"
        }
      ]
    }
  ]
}

默认展开层级

当前导航最大层级为 4，可通过defaultOpenLevel来控制默认 2 层级全部展开

{
  "type": "nav",
  "stacked": true,
  "defaultOpenLevel": "2",
  "links": [
    {
      "label": "Nav 1",
      "to": "/docs/index",
      "icon": "fa fa-user"
    },
    {
      "label": "Nav 2",
      "unfolded": true,
      "children": [
        {
          "label": "Nav 2-1",
          "children": [
            {
              "label": "Nav 2-1-1",
              "to": "/docs/api-2-1-1",
              "children": [
                {
                  "label": "Nav 2-1-1-1",
                  "to": "/docs/api-2-1-1-1"
                }
              ]
            }
          ]
        },
        {
          "label": "Nav 2-2",
          "to": "/docs/api-2-2"
        }
      ]
    },
    {
      "label": "Nav 3",
      "to": "/docs/renderers",
      "children": [
        {
          "label": "Nav 3-1",
          "to": "/docs/api-2-1"
        }
      ]
    }
  ]
}

自定义展开按钮

可以设置expandIcon为 icon 的名称字符串

{
  "type": "nav",
  "stacked": true,
  "expandIcon": "close",
  "links": [
    {
      "label": "Nav 1",
      "to": "/docs/index",
      "icon": "fa fa-user"
    },
    {
      "label": "Nav 2",
      "unfolded": true,
      "children": [
        {
          "label": "Nav 2-1",
          "children": [
            {
              "label": "Nav 2-1-1",
              "to": "/docs/api-2-1-1"
            }
          ]
        },
        {
          "label": "Nav 2-2",
          "to": "/docs/api-2-2"
        }
      ]
    },
    {
      "label": "Nav 3",
      "to": "/docs/renderers",
      "children": [
        {
          "label": "Nav 3-1",
          "to": "/docs/api-2-1"
        }
      ]
    }
  ]
}

也可以将expandIcon设置为SchemaObject

{
  "type": "nav",
  "stacked": true,
  "expandIcon": {
    "type": "icon",
    "icon": "far fa-address-book"
  },
  "links": [
    {
      "label": "Nav 1",
      "to": "/docs/index",
      "icon": "fa fa-user"
    },
    {
      "label": "Nav 2",
      "unfolded": true,
      "children": [
        {
          "label": "Nav 2-1",
          "children": [
            {
              "label": "Nav 2-1-1",
              "to": "/docs/api-2-1-1"
            }
          ]
        },
        {
          "label": "Nav 2-2",
          "to": "/docs/api-2-2"
        }
      ]
    },
    {
      "label": "Nav 3",
      "to": "/docs/renderers",
      "children": [
        {
          "label": "Nav 3-1",
          "to": "/docs/api-2-1"
        }
      ]
    }
  ]
}

搜索导航项

3.5.0 及以上版本

开启"searchable": true后，支持搜索当前数据源内的导航项，支持自定义匹配函数NavMatchFunc，如果不设置默认模糊匹配导航对象中的label, title 和 key 字段。

{
  "type": "container",
  "className": "w-40",
  "body": [
    {
      "type": "nav",
      "stacked": true,
      "searchable": true,
      "searchConfig": {
        "matchFunc": "return link.searchKey === keyword;"
      },
      "links": [
        {
          "label": "Nav 1",
          "to": "?to=nav1",
          "searchKey": "1"
        },
        {
          "label": "Nav 2",
          "to": "?to=nav2",
          "searchKey": "2",
          "children": [
            {
              "label": "Nav 2-1",
              "to": "?to=nav2-1",
              "searchKey": "2-1",
              "children": [
                {
                  "label": "Nav 2-1-1",
                  "to": "?to=nav2-1-1",
                  "searchKey": "2-1-1"
                }
              ]
            }
          ]
        },
        {
          "label": "Nav 3",
          "to": "?to=nav3",
          "searchKey": "3",
          "children": [
            {
              "label": "Nav 3-1",
              "to": "?to=nav3-1",
              "searchKey": "3-1"
            }
          ]
        },
        {
          "label": "Nav 4",
          "to": "?to=nav4",
          "searchKey": "4"
        },
        {
          "label": "Nav 5",
          "to": "?to=nav5",
          "searchKey": "5"
        }
      ]
    }
  ]
}

属性表

属性名	类型	默认值	说明	版本
type	string	"nav"	指定为 Nav 渲染器
mode	string	"inline"	导航模式，悬浮或者内联，默认内联模式
collapsed	boolean		控制导航是否缩起
indentSize	number	16	层级缩进值，仅内联模式下生效
level	number		控制导航最大展示层级数
defaultOpenLevel	number		控制导航最大默认展开层级
className	string		外层 Dom 的类名
popupClassName	string		当为悬浮模式时，可自定义悬浮层样式
expandIcon	string | SchemaObject		自定义展开按钮
expandPosition	string		展开按钮位置，"before"或者"after"，不设置默认在前面
stacked	boolean	true	设置成 false 可以以 tabs 的形式展示
accordion	boolean		是否开启手风琴模式
source	string 或 API		可以通过变量或 API 接口动态创建导航
deferApi	API		用来延时加载选项详情的接口，可以不配置，不配置公用 source 接口。
itemActions	SchemaNode		更多操作相关配置
draggable	boolean		是否支持拖拽排序
dragOnSameLevel	boolean		仅允许同层级内拖拽
saveOrderApi	string 或 API		保存排序的 api
itemBadge	BadgeSchema		角标
links	Array		链接集合
links[x].label	string		名称
links[x].to	模板		链接地址
links[x].target	string	链接关系
links[x].icon	string		图标
links[x].children	Array<link>		子链接
links[x].unfolded	boolean		初始是否展开
links[x].active	boolean		是否高亮
links[x].activeOn	表达式		是否高亮的条件，留空将自动分析链接地址
links[x].defer	boolean		标记是否为懒加载项
links[x].deferApi	API		可以不配置，如果配置优先级更高
links[x].disabled	boolean		是否禁用
links[x].disabledTip	string		禁用提示信息
links[x].className	string		菜单项自定义样式
links[x].mode	string		菜菜单项模式，分组模式："group"、分割线："divider"
links[x].overflow	NavOverflow		导航项响应式收纳配置
overflow	NavOverflow		响应式收纳配置
overflow.enable	boolean	false	是否开启响应式收纳
overflow.overflowLabel	string | SchemaObject		菜单触发按钮的文字
overflow.overflowIndicator	SchemaIcon	"fa fa-ellipsis"	菜单触发按钮的图标
overflow.maxVisibleCount	number		开启响应式收纳后导航最大可显示数量，超出此数量的导航将被收纳到下拉菜单中，默认为自动计算
overflow.wrapperComponent	string		包裹导航的外层标签名，可以使用其他标签渲染
overflow.style	React.CSSProperties		自定义样式
overflow.overflowClassName	string	""	菜单按钮 CSS 类名
overflow.overflowPopoverClassName	string	""	Popover 浮层 CSS 类名
searchable	boolean	false	是否开启搜索	3.5.0
searchConfig.matchFunc	string	NavMatchFunc	自定义匹配函数, 默认模糊匹配导航对象中的label, title 和 key 字段	3.5.0
searchConfig.className	string	""	搜索框外层 CSS 类名	3.5.0
searchConfig.placeholder	string	false	是否开启搜索	3.5.0
searchConfig.mini	boolean	false	是否为 mini 模式	3.5.0
searchConfig.enhance	boolean	false	是否为增强样式	3.5.0
searchConfig.clearable	boolean	false	是否开启搜索	3.5.0
searchConfig.searchImediately	boolean	false	是否立即搜索	3.5.0

NavMatchFunc

interface NavMatchFunc {
  (
    /* 导航项对象 */
    link: Link,
    /* 搜索关键字 */
    keyword: string
  ): boolean;
}

事件表

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

事件名称	事件参数	说明
loaded	items: item[] 数据源 item?: object 懒加载时所点击导航项	异步加载数据源完成时触发
collapsed	collapsed: boolean 缩起展开状态	导航缩起展开时触发
toggled	item: object 导航项数据 open: boolean 展开状态	点击导航展开按钮时触发
change	value: item[] 选中导航项数据	导航项选中有变化时触发
click	item: object 点击导航项数据	手动点击导航项时触发

loaded

数据源加载完成，可以尝试将source配置为 api 地址或者开启懒加载。

{
  "type": "page",
  "body": [
    {
      "type": "action",
      "label": "刷新",
      "onEvent": {
        "click": {
          "actions": [
            {
              "actionType": "reload",
              "componentId": "test"
            }
          ]
        }
      }
    },
    {
      "id": "test",
      "type": "nav",
      "stacked": true,
      "valueField": "label",
      "source": "/api/options/nav?parentId=${value}",
      "onEvent": {
        "loaded": {
          "actions": [
            {
              "actionType": "toast",
              "args": {
                "msg": "已加载${event.data.items.length}条记录"
              }
            }
          ]
        }
      }
    }
  ]
}

collapsed

导航缩起，可以尝试修改导航的collapsed属性。

{
  "type": "nav",
  "stacked": true,
  "collapsed": true,
  "links": [
    {
      "label": "Nav 1",
      "to": "/docs/index",
      "icon": "fa fa-user"
    },
    {
      "label": "Nav 2",
      "unfolded": true,
      "children": [
        {
          "label": "Nav 2-1",
          "children": [
            {
              "label": "Nav 2-1-1",
              "to": "/docs/api-2-1-1"
            }
          ]
        },
        {
          "label": "Nav 2-2",
          "to": "/docs/api-2-2"
        }
      ]
    },
    {
      "label": "Nav 3",
      "to": "/docs/renderers"
    }
  ],
  "onEvent": {
    "collapsed": {
      "actions": [
        {
          "actionType": "toast",
          "args": {
            "msg": "${event.data.collapsed ? '导航缩起' : '导航展开'}"
          }
        }
      ]
    }
  }
}

toggled

导航项收起展开，可以尝试点击导航项展开按钮。

{
  "type": "nav",
  "stacked": true,
  "links": [
    {
      "label": "Nav 1",
      "to": "/docs/index",
      "icon": "fa fa-user"
    },
    {
      "label": "Nav 2",
      "unfolded": true,
      "children": [
        {
          "label": "Nav 2-1",
          "children": [
            {
              "label": "Nav 2-1-1",
              "to": "/docs/api-2-1-1"
            }
          ]
        },
        {
          "label": "Nav 2-2",
          "to": "/docs/api-2-2"
        }
      ]
    },
    {
      "label": "Nav 3",
      "to": "/docs/renderers"
    }
  ],
  "onEvent": {
    "toggled": {
      "actions": [
        {
          "actionType": "toast",
          "args": {
            "msg": "${event.data.item.label}${event.data.open ? '展开' : '收起'}"
          }
        }
      ]
    }
  }
}

change

导航项选中，可以尝试手动修改任意导航项的active属性。

{
  "type": "nav",
  "stacked": true,
  "links": [
    {
      "label": "Nav 1",
      "to": "/docs/index",
      "icon": "fa fa-user"
    },
    {
      "label": "Nav 2",
      "unfolded": true,
      "children": [
        {
          "label": "Nav 2-1",
          "children": [
            {
              "label": "Nav 2-1-1",
              "to": "/docs/api-2-1-1"
            }
          ]
        },
        {
          "label": "Nav 2-2",
          "to": "/docs/api-2-2"
        }
      ]
    },
    {
      "label": "Nav 3",
      "to": "/docs/renderers"
    }
  ],
  "onEvent": {
    "change": {
      "actions": [
        {
          "actionType": "toast",
          "args": {
            "msg": "${event.data.value.length}项选中"
          }
        }
      ]
    }
  }
}

click

导航项点击，可以尝试手动点击任意导航项。

{
  "type": "nav",
  "stacked": true,
  "links": [
    {
      "label": "Nav 1",
      "icon": "fa fa-user"
    },
    {
      "label": "Nav 2",
      "children": [
        {
          "label": "Nav 2-1",
          "children": [
            {
              "label": "Nav 2-1-1"
            }
          ]
        },
        {
          "label": "Nav 2-2"
        }
      ]
    },
    {
      "label": "Nav 3"
    }
  ],
  "onEvent": {
    "click": {
      "actions": [
        {
          "actionType": "toast",
          "args": {
            "msg": "${event.data.item.label}被点击了，但不一定选中"
          }
        }
      ]
    }
  }
}

动作表

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

动作名称	动作配置	说明
updateItems	value: string或value: item[]	更新导航数据源为指定导航项的子导航数据
reset		重置导航数据源，和 updateItems 搭配使用，没有经过 updateItems 操作的，执行 reset 无效果

updateItems / reset

{
  "type": "page",
  "data": {
    "items": [
      {
        "label": "Nav 1",
        "to": "/docs/index",
        "icon": "fa fa-user"
      },
      {
        "label": "Nav 2",
        "unfolded": true,
        "active": true,
        "children": [
          {
            "label": "Nav 2-1",
            "children": [
              {
                "label": "Nav 2-1-1",
                "to": "/docs/api-2-1-1"
              }
            ]
          },
          {
            "label": "Nav 2-2",
            "to": "/docs/api-2-2"
          }
        ]
      },
      {
        "label": "Nav 3",
        "to": "/docs/renderers"
      }
    ]
  },
  "body": {
    "type": "container",
    "body": [
      {
        "type": "action",
        "label": "设置数据源",
        "onEvent": {
          "click": {
            "actions": [
              {
                "actionType": "updateItems",
                "args": {
                  "value": "Nav 2"
                },
                "componentId": "asideNav"
              }
            ]
          }
        }
      },
      {
        "type": "action",
        "label": "重置数据源",
        "className": "mx-1",
        "onEvent": {
          "click": {
            "actions": [
              {
                "actionType": "reset",
                "componentId": "asideNav"
              }
            ]
          }
        }
      },
      {
        "type": "container",
        "body": [
          {
            "type": "nav",
            "stacked": true,
            "source": "${items}",
            "id": "asideNav"
          }
        ]
      }
    ]
  }
}