# list_selector

# 组件介绍

list_selector 属于交互组件的一种，可用于内容块的extra字段和交互块的actions字段。

选项配置：用于配置下拉选择的选项和选中时的值

{
   "options": [
        {
          "text": {
            "content": "选项1",
            "tag": "plain_text"
          },
          "value": "1"
        },
        {
          "text": {
            "content": "选项2",
            "tag": "plain_text"
          },
          "value": "2"
        },
        {
          "text": {
            "content": "选项3",
            "tag": "plain_text"
          },
          "value": "3"
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

回传交互：配置 callBacks 字段，将用户选择的内容POST到应用配置的“消息卡片请求地址”。同button使用
二次确认：对于需要二次确认的回传交互，通过配置 confirm 字段弹出二次确认的弹窗。

# 字段定义

字段	必须	类型	取值	说明
tag	是	String	`list_selector`	元素标签固定为`list_selector`
placeholder	是	Struct	text对象	默认提示文案，与`initialOption`至少有一个
initialOption	否	String		选项的初始value字段值。
options	是	Struct	options对象	选项列表
callBacks	是	Json	仅支持key-value[]形式的json结构，且key，value为String类型。 `详细参考文末注意事项-2`	点击后返回业务方
confirm	否	Struct	confirm对象	二次确认的弹框

# 交互示例

回传交互（POST 数据到服务端的交互）

第 1 步：检查是否已配置“消息卡片请求网址”，用于接收用户提交的内容

注意

“消息卡片请求网址”和“事件订阅”不在一个模块下，请在“应用能力->机器人”模块下配置
首次配置时，需要校验地址的合法性，请参考订阅事件-配置&验证进行校验

第 2 步：配置list_selector元素

 {
  "tag": "actions",
  "actions": [
    {
      "tag": "list_selector",
      "placeholder": {
        "content": "默认提示文本",
        "tag": "plain_text"
      },
      "callBacks": [
        {
          "key": "key1",
          "value": "value1"
        },
        {
          "key": "key2",
          "value": "value2"
        }
      ],
      "options": [
        {
          "text": {
            "content": "选项1",
            "tag": "plain_text"
          },
          "value": "1"
        },
        {
          "text": {
            "content": "选项2",
            "tag": "plain_text"
          },
          "value": "2"
        },
        {
          "text": {
            "content": "选项3",
            "tag": "plain_text"
          },
          "value": "3"
        }
      ]
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

第 3 步：用户点击list_selector的一个选项 业务方会在第 1 步中预留的消息卡片请求网址收到含如下信息的 POST 请求，标识用户交互信息：

{
  "uuid": "ac8dbd31-5b29-e950-9c58-48f90d631ae9",
  "openId": "ou_sdfimx9948345",
  "userId": "sd923r0sdf5",
  "userIdType": "user_id",
  "messageId": "om_abcdefg1234567890",
  "tenantKey": "d3200picker",
  "token": "c-xxxx",
  "action": {
    "value": {
      "key1": "value1",
      "key2": "value2"
    },
    "tag": "list_selector",
    "option": "joy"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

第 4 步：响应 POST 请求 收到开放平台向“消息卡片请求网址”的 POST 请求后，你可以通过以下 2 种方式更新卡片，反馈用户的操作： (1) 立即更新：可以立即响应 POST 请求，返回要更新的卡片内容。

(1) 立即更新: 开发者在收到卡片的回传交互请求后，通过响应该请求来更新卡片内容，具体操作：

在3秒内以HTTP 200状态码响应该请求
将新卡片的内容以String类型设置到HTTP Body中

"{\"modules\":[{\"tag\":\"actions\",\"actions\":[{\"tag\":\"list_selector\",\"placeholder\":{\"content\":\"默认提示文本\",\"tag\":\"plain_text\"},\"callBacks\":[{\"key\":\"key\",\"value\":\"value\"}],\"options\":[{\"text\":{\"content\":\"选项1\",\"tag\":\"plain_text\"},\"value\":\"joy\"},{\"text\":{\"content\":\"选项2\",\"tag\":\"plain_text\"},\"value\":\"2\"},{\"text\":{\"content\":\"选项3\",\"tag\":\"plain_text\"},\"value\":\"3\"}]}]}]}"

注意：

如果 POST 请求失败，或「立即更新」操作超时，客户端会提示“操作失败”或“网络超时”，卡片不刷新。需要关注排查：

(1)是否配置了消息卡片请求网址
(2)是否在3秒内以HTTP 200状态码响应卡片的点击事件卡片不限制更新次数，但只允许在卡片发送后30天内更新卡片。如果卡片的更新时机不由消息卡片的交互组件触发（比如用户在企业自建的审批系统内，而不是消息卡片上完成审批操作），可以调用更新应用发送的消息方法，请求更新卡片。跳转交互（跳转指定地址的交互）

# 注意事项

WARNING

下拉组件在移动端默认占满一行，无法调整宽度。
交互元素的value字段值仅支持key-value[]形式的json结构，且key，value为String类型，示例如下：

"callBacks":[
  {
    "key":"key1",
    "value": "string1"
  },
  {
    "key":"key2",
    "value": "string2"
  },
  	······
]

1
2
3
4
5
6
7
8
9
10
11

# 图片示例

# json 示例

{
  "modules": [
    {
      "tag": "div",
      "text": {
        "content": "这是新的消息卡片，现在你可以像搭建乐高一样来搭建消息卡片，同时还可以添加button、下拉交互，赶快来尝试吧！",
        "tag": "plain_text"
      },
      "extra": {
        "tag": "list_selector",
        "placeholder": {
          "content": "默认提示文本",
          "tag": "plain_text"
        },
        "callBacks": [
          {
            "key": "key",
            "value": "value"
          }
        ],
        "options": [
          {
            "text": {
              "content": "选项1",
              "tag": "plain_text"
            },
            "value": "1"
          },
          {
            "text": {
              "content": "选项2",
              "tag": "plain_text"
            },
            "value": "2"
          },
          {
            "text": {
              "content": "选项3",
              "tag": "plain_text"
            },
            "value": "3"
          }
        ]
      }
    },
    {
      "tag": "actions",
      "actions": [
        {
          "tag": "list_selector",
          "placeholder": {
            "content": "默认提示文本",
            "tag": "plain_text"
          },
          "callBacks": [
            {
              "key": "key",
              "value": "value"
            }
          ],
          "options": [
            {
              "text": {
                "content": "选项1",
                "tag": "plain_text"
              },
              "value": "1"
            },
            {
              "text": {
                "content": "选项2",
                "tag": "plain_text"
              },
              "value": "2"
            },
            {
              "text": {
                "content": "选项3",
                "tag": "plain_text"
              },
              "value": "3"
            }
          ]
        },
        {
          "tag": "list_selector",
          "placeholder": {
            "content": "默认提示文本",
            "tag": "plain_text"
          },
          "callBacks": [
            {
              "key": "key",
              "value": "value"
            }
          ],
          "options": [
            {
              "text": {
                "content": "选项1",
                "tag": "plain_text"
              },
              "value": "1"
            },
            {
              "text": {
                "content": "选项2",
                "tag": "plain_text"
              },
              "value": "2"
            },
            {
              "text": {
                "content": "选项3",
                "tag": "plain_text"
              },
              "value": "3"
            }
          ]
        }
      ]
    }
  ],
  "header": {
    "text": {
      "content": "这是卡片的标题",
      "tag": "plain_text"
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

← button card_link →