介绍微信公众号菜单自定义相关的功能，包括基本的菜单的分类规则和基本的代码实现方式，也系统性的介绍了自定义菜单相关的接口和支持的功能项

1 说明

1.1 菜单分级和命名说明

• 自定义菜单最多包括3个一级菜单，每个一级菜单最多包含5个二级菜单。
• 一级菜单最多4个汉字，二级菜单最多7个汉字，多出来的部分将会以“…”代替。
• 创建自定义菜单后，菜单的刷新策略是，在用户进入公众号会话页或公众号profile页时，如果发现上一次拉取菜单的求在5分钟以前，就会拉取一下菜单，如果菜单有更新，就会刷新客户端的菜单。
• 测试时可以尝试取消关注公众账号后再次关注，则可以看到创建后的效果。

1.2 权限相关

• 未认证的订阅号不能使用，已认证的订阅号可以使用
• 服务号不论是否认证均可以使用
• 可使用测试号进行测试

1.3 官方开发文档

自定义菜单的说明以及示例可以参照官方的开发文档，地址：官方的开发文档

2 基本实现（基于WxJava）

2.1 构建菜单模型

2.1.1 官方参数：

2.1.2 菜单Bean

GIT地址

public class WxMenuButton implements Serializable {
  private static final long serialVersionUID = -1070939403109776555L;

  private String type;
  private String name;
  private String key;
  private String url;
  @SerializedName("media_id")
  private String mediaId;
  @SerializedName("appid")
  private String appId;
  @SerializedName("pagepath")
  private String pagePath;

  @SerializedName("sub_button")
  private List<WxMenuButton> subButtons = new ArrayList<>();

  @Override
  public String toString() {
    return WxGsonBuilder.create().toJson(this);
  }

2.1.3 组装数据

即按照官方示例组装成JSON格式的数据

private WxMenuButton handle(RData rdata) {
    WxMenuButton button = new WxMenuButton();
             if("click".equals(rdata.getString("menuProperty"))) {
                 button.setType(MenuButtonType.CLICK);
                 button.setName(rdata.getString("name"));
                 button.setKey(rdata.getString("key"));
             }else if("view".equals(rdata.getString("menuProperty"))) {
                 button.setType(MenuButtonType.VIEW);
                 button.setName(rdata.getString("name"));
                 button.setUrl(rdata.getString("url"));
             }else if("miniprogram".equals(rdata.getString("menuProperty"))) {
                 button.setType(MenuButtonType.MINIPROGRAM);
                 button.setName(rdata.getString("name"));
                 button.setAppId(rdata.getString("appId"));
                 button.setPagePath(rdata.getString("pagepath"));
                 button.setUrl(rdata.getString("url"));
             }else {
                 button.setName(rdata.getString("name"));
             }         
    return button;
  }

2.1.4 发送数据

调用方式

this.wxService.switchoverTo("weChatId").getMenuService().menuCreate(WxMenu);

部内实现

  @Override
  public String menuCreate(WxMenu menu) throws WxErrorException {
    String menuJson = menu.toJson();
    String url = API_URL_PREFIX + "/create";
    if (menu.getMatchRule() != null) {
      url = API_URL_PREFIX + "/addconditional";
    }
    String result = this.wxMpService.post(url, menuJson);
    if (menu.getMatchRule() != null) {
      return new JsonParser().parse(result).getAsJsonObject().get("menuid").getAsString();
    }

    return null;
  }

post方法：

public <T, E> T executeInternal(RequestExecutor<T, E> executor, String uri, E data) throws WxErrorException {
    E dataForLog = DataUtils.handleDataWithSecret(data);
    if (uri.contains("access_token=")) {
      throw new IllegalArgumentException("uri参数中不允许有access_token: " + uri);
    }
    String accessToken = getAccessToken(false);
    String uriWithAccessToken = uri + (uri.contains("?") ? "&" : "?") + "access_token=" + accessToken;
    try {
      T result = executor.execute(uriWithAccessToken, data);
      this.log.debug("\n【请求地址】: {}\n【请求参数】：{}\n【响应数据】：{}", uriWithAccessToken, dataForLog, result);
      return result;
    } catch (WxErrorException e) {
      WxError error = e.getError();
      /*
       * 发生以下情况时尝试刷新access_token
       * 40001 获取access_token时AppSecret错误，或者access_token无效
       * 42001 access_token超时
       * 40014 不合法的access_token，请开发者认真比对access_token的有效性（如是否过期），或查看是否正在为恰当的公众号调用接口
       */
      if (error.getErrorCode() == 42001 || error.getErrorCode() == 40001 || error.getErrorCode() == 40014) {
        // 强制设置wxMpConfigStorage它的access token过期了，这样在下一次请求里就会刷新access token
        this.getWxMpConfigStorage().expireAccessToken();
        if (this.getWxMpConfigStorage().autoRefreshToken()) {
          return this.execute(executor, uri, data);
        }
      }

      if (error.getErrorCode() != 0) {
      }
      return null;
    } catch (IOException e) {
    }
  }

3 自定义菜单说明

依据官方文档，自定义菜单操作主要包括

1. 菜单创建
2. 菜单查询
3. 菜单删除
4. 个性化菜单
5. 自定义菜单配置

公众号菜单设置分为常规菜单以及个性化菜单。其中个性化菜单会根据访问用户的属性不同显示不同的菜单。

3.1 公众号菜单类型

目前公众号菜单支持以下10种类型

1. click：点击推事件用户点击click类型按钮后，微信服务器会通过消息接口推送消息类型为event的结构给开发者（参考消息接口指南），并且带上按钮中开发者填写的key值，开发者可以通过自定义的key值与用户进行交互；

1. view：跳转URL用户点击view类型按钮后，微信客户端将会打开开发者在按钮中填写的网页URL，可与网页授权获取用户基本信息接口结合，获得用户基本信息。
2. scancode_push：扫码推事件用户点击按钮后，微信客户端将调起扫一扫工具，完成扫码操作后显示扫描结果（如果是URL，将进入URL），且会将扫码的结果传给开发者，开发者可以下发消息。
3. scancode_waitmsg：扫码推事件且弹出“消息接收中”提示框用户点击按钮后，微信客户端将调起扫一扫工具，完成扫码操作后，将扫码的结果传给开发者，同时收起扫一扫工具，然后弹出“消息接收中”提示框，随后可能会收到开发者下发的消息。
4. pic_sysphoto：弹出系统拍照发图用户点击按钮后，微信客户端将调起系统相机，完成拍照操作后，会将拍摄的相片发送给开发者，并推送事件给开发者，同时收起系统相机，随后可能会收到开发者下发的消息。
5. pic_photo_or_album：弹出拍照或者相册发图用户点击按钮后，微信客户端将弹出选择器供用户选择“拍照”或者“从手机相册选择”。用户选择后即走其他两种流程。
6. pic_weixin：弹出微信相册发图器用户点击按钮后，微信客户端将调起微信相册，完成选择操作后，将选择的相片发送给开发者的服务器，并推送事件给开发者，同时收起相册，随后可能会收到开发者下发的消息。
7. location_select：弹出地理位置选择器用户点击按钮后，微信客户端将调起地理位置选择工具，完成选择操作后，将选择的地理位置发送给开发者的服务器，同时收起位置选择工具，随后可能会收到开发者下发的消息。
8. media_id：下发消息（除文本消息）用户点击media_id类型按钮后，微信服务器会将开发者填写的永久素材id对应的素材下发给用户，永久素材类型可以是图片、音频、视频、图文消息。请注意：永久素材id必须是在“素材管理/新增永久素材”接口上传后获得的合法id。
9. view_limited：跳转图文消息URL用户点击view_limited类型按钮后，微信客户端将打开开发者在按钮中填写的永久素材id对应的图文消息URL，永久素材类型只支持图文消息。请注意：永久素材id必须是在“素材管理/新增永久素材”接口上传后获得的合法id。
10. miniprogram跳转到小程序

概括而言，以类型划分，菜单可分为五类，即

• view：跳转到对应的URL(可集合网页授权接口，获取用户信息)。
• 点击类型：基于设置的key触发EVENT事件，与后台进行交互
• 小程序：设置跳转到小程序
• 图文素材(未认证下使用)：在不具备推送条件下使用，进行图文推送
• 其他：包括扫码，拍照，位置选择

3.2 菜单创建

接口请求说明

http请求方式：
POST（请使用https协议）
https://api.weixin.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN

格式：

 {
     "button":[
     {    
          "type":"click",
          "name":"今日歌曲",
          "key":"V1001_TODAY_MUSIC"
      },
      {
           "name":"菜单",
           "sub_button":[
           {    
               "type":"view",
               "name":"搜索",
               "url":"http://www.soso.com/"
            },
            {
                 "type":"miniprogram",
                 "name":"wxa",
                 "url":"http://mp.weixin.qq.com",
                 "appid":"wx286b93c14bbf93aa",
                 "pagepath":"pages/lunar/index"
             },
            {
               "type":"click",
               "name":"赞一下我们",
               "key":"V1001_GOOD"
            }]
       }]
 }

3.3 菜单查询

请求说明

http请求方式：GET
https://api.weixin.qq.com/cgi-bin/menu/get?access_token=ACCESS_TOKEN

返回说明
使用接口创建自定义菜单后，开发者还可使用接口查询自定义菜单的结构。另外请注意，在设置了个性化菜单后，使用本自定义菜单查询接口可以获取默认菜单和全部个性化菜单信息。
注意：通过页面配置的菜单，本接口将无法返回菜单配置数据

示例：
有个性化菜单时：
注：menu为默认菜单，conditionalmenu为个性化菜单列表。字段说明请见个性化菜单接口页的说明。

{
    "menu": {
        "button": [
            {
                "type": "click", 
                "name": "今日歌曲", 
                "key": "V1001_TODAY_MUSIC", 
                "sub_button": [ ]
            }
        ], 
        "menuid": 208396938
    }, 
    "conditionalmenu": [
        {
            "button": [
                {
                    "type": "click", 
                    "name": "今日歌曲", 
                    "key": "V1001_TODAY_MUSIC", 
                    "sub_button": [ ]
                }, 
                {
                    "name": "菜单", 
                    "sub_button": [
                        {
                            "type": "view", 
                            "name": "搜索", 
                            "url": "http://www.soso.com/", 
                            "sub_button": [ ]
                        }, 
                        {
                            "type": "view", 
                            "name": "视频", 
                            "url": "http://v.qq.com/", 
                            "sub_button": [ ]
                        }, 
                        {
                            "type": "click", 
                            "name": "赞一下我们", 
                            "key": "V1001_GOOD", 
                            "sub_button": [ ]
                        }
                    ]
                }
            ], 
            "matchrule": {
                "group_id": 2, 
                "sex": 1, 
                "country": "中国", 
                "province": "广东", 
                "city": "广州", 
                "client_platform_type": 2
            }, 
            "menuid": 208396993
        }
    ]

3.5 菜单删除

使用接口创建自定义菜单后，开发者还可使用接口删除当前使用的自定义菜单。另请注意，在个性化菜单时，调用此接口会删除默认菜单及全部个性化菜单。
请求说明

http请求方式：GET
https://api.weixin.qq.com/cgi-bin/menu/delete?access_token=ACCESS_TOKEN

3.6 菜单事件推送

用户点击自定义菜单后，微信会将点击事件上报后台(点击一级菜单显示二级菜单将不会上报)。

事件推送事件处理

接收信息

  WxMpXmlMessage inMessage = WxMpXmlMessage.fromXml(requestBody);
  WxMpXmlOutMessage outMessage = this.wxService.route(inMessage);

处理信息

 @Override
  public WxMpXmlOutMessage handle(WxMpXmlMessage wxMessage,
                                  Map<String, Object> context, WxMpService weixinService,
                                  WxSessionManager sessionManager) {
    String msg = String.format("type:%s, event:%s, key:%s",
      wxMessage.getMsgType(), wxMessage.getEvent(),
      wxMessage.getEventKey());
    if (WxConsts.MenuButtonType.VIEW.equals(wxMessage.getEvent())) {
      return null;
    }
    return WxMpXmlOutMessage.TEXT().content(msg)
      .fromUser(wxMessage.getToUser()).toUser(wxMessage.getFromUser())
      .build();
  }

3.6.1 参数说明

3.6.2 微信上报事件数据示例

扫码

<xml><ToUserName><![CDATA[gh_e136c6e50636]]></ToUserName>
<FromUserName><![CDATA[oMgHVjngRipVsoxg6TuX3vz6glDg]]></FromUserName>
<CreateTime>1408090502</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[scancode_push]]></Event>
<EventKey><![CDATA[6]]></EventKey>
<ScanCodeInfo><ScanType><![CDATA[qrcode]]></ScanType>
<ScanResult><![CDATA[1]]></ScanResult>
</ScanCodeInfo>
</xml>

跳转

<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>123456789</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[VIEW]]></Event>
<EventKey><![CDATA[www.qq.com]]></EventKey>
<MenuId>MENUID</MenuId>
</xml>

3.7 个性化菜单

为了帮助公众号实现灵活的业务运营，微信公众平台新增了个性化菜单接口，开发者可以通过该接口，让公众号的不同用户群体看到不一样的自定义菜单。该接口开放给已认证订阅号和已认证服务号。

开发者可以通过以下条件来设置用户看到的菜单：

1、用户标签（开发者的业务需求可以借助用户标签来完成）
2、性别
3、手机操作系统
4、地区（用户在微信客户端设置的地区）
5、语言（用户在微信客户端设置的语言）

个性化菜单接口说明：

1、个性化菜单要求用户的微信客户端版本在iPhone6.2.2，Android 6.2.4以上，暂时不支持其他版本微信
2、菜单的刷新策略是，在用户进入公众号会话页或公众号profile页时，如果发现上一次拉取菜单的请求在5分钟以前，就会拉取一下菜单，如果菜单有更新，就会刷新客户端的菜单。测试时可以尝试取消关注公众账号后再次关注，则可以看到创建后的效果
3、普通公众号的个性化菜单的新增接口每日限制次数为2000次，删除接口也是2000次，测试个性化菜单匹配结果接口为20000次
4、出于安全考虑，一个公众号的所有个性化菜单，最多只能设置为跳转到3个域名下的链接
5、创建个性化菜单之前必须先创建默认菜单（默认菜单是指使用普通自定义菜单创建接口创建的菜单）。如果删除默认菜单，个性化菜单也会全部删除
6、个性化菜单接口支持用户标签，请开发者注意，当用户身上的标签超过1个时，以最后打上的标签为匹配

个性化菜单匹配规则说明：

个性化菜单的更新是会被覆盖的。
例如公众号先后发布了默认菜单，个性化菜单1，个性化菜单2，个性化菜单3。那么当用户进入公众号页面时，将从个性化菜单3开始匹配，如果个性化菜单3匹配成功，则直接返回个性化菜单3，否则继续尝试匹配个性化菜单2，直到成功匹配到一个菜单。
根据上述匹配规则，为了避免菜单生效时间的混淆，决定不予提供个性化菜单编辑API，开发者需要更新菜单时，需将完整配置重新发布一轮。

3.7.1 参数说明

请求

http请求方式：POST（请使用https协议）
https://api.weixin.qq.com/cgi-bin/menu/addconditional?access_token=ACCESS_TOKEN

参数：

{
    "button": [
       //与默认参数相同
    ], 
    "matchrule": {
        "tag_id": "2", 
        "sex": "1", 
        "country": "中国", 
        "province": "广东", 
        "city": "广州", 
        "client_platform_type": "2", 
        "language": "zh_CN"
    }
}

参数说明

• matchrule共六个字段，均可为空，但不能全部为空，至少要有一个匹配信息是不为空的。
• country、province、city组成地区信息，将按照country、province、city的顺序进行验证，要符合地区信息表的内容。
• 地区信息从大到小验证，小的可以不填，即若填写了省份信息，则国家信息也必填并且匹配，城市信息可以不填。 例如 “中国 广东省 广州市”、“中国 广东省”都是合法的地域信息，而“中国 广州市”则不合法，因为填写了城市信息但没有填写省份信息。

3.7.2 操作说明

1. 创建见上
2. 删除：可基于menUid进行删除
3. 测试匹配结果：传入微信ID，返回菜单匹配结果
4. 删除所有菜单和查询个性化菜单使用默认菜单的接口操作

3.8 获取自定义菜单配置

本接口将会提供公众号当前使用的自定义菜单的配置，如果公众号是通过API调用设置的菜单，则返回菜单的开发配置，而如果公众号是在公众平台官网通过网站功能发布菜单，则本接口返回运营者设置的菜单配置。

请注意：

1、第三方平台开发者可以通过本接口，在旗下公众号将业务授权给你后，立即通过本接口检测公众号的自定义菜单配置，并通过接口再次给公众号设置好自动回复规则，以提升公众号运营者的业务体验。
2、本接口与自定义菜单查询接口的不同之处在于，本接口无论公众号的接口是如何设置的，都能查询到接口，而自定义菜单查询接口则仅能查询到使用API设置的菜单配置。
3、认证/未认证的服务号/订阅号，以及接口测试号，均拥有该接口权限。
4、从第三方平台的公众号登录授权机制上来说，该接口从属于消息与菜单权限集。
5、本接口中返回的图片/语音/视频为临时素材（临时素材每次获取都不同，3天内有效，通过素材管理-获取临时素材接口来获取这些素材），本接口返回的图文消息为永久素材素材（通过素材管理-获取永久素材接口来获取这些素材）。

接口调用请求说明

http请求方式: 
GET（请使用https协议）https://api.weixin.qq.com/cgi-bin/get_current_selfmenu_info?access_token=ACCESS_TOKEN

返回结果说明
如果公众号是在公众平台官网通过网站功能发布菜单，则本接口返回的自定义菜单配置。