---
url: /v6.2/embed/app-param.md
---
# 使用 appParam 传入参数信息

在仪表盘制作过程中，可以通过[参数控制仪表盘内容的展示](../parameter-control.md)。在嵌入场景下，您可以使用 `appParam` 将参数信息拼接到 URL 后面。页面在展示时会将 `appParam` 中的参数信息携带到最终执行的 SQL 代码中，从而展示不同参数值下的仪表盘数据。

### appParam 结构

`appParam` 是一个数组，可以包含多个参数对象。每个参数对象是一个包含以下键值的 object：

* `appId`: 创建参数的数据包或应用的 ID。
* `id`: 参数的 ID，可通过网络请求消息获取。
* `name`: 参数的名称。
* `value`: 参数的值，类型与参数类型保持一致。
* `sig`: 布尔值，表示是否将该参数作为计算 HMAC 的一部分，见[HMAC 签名参数说明](../security-policy-hmac.md)。

参数可以通过 `id` 或 `name` 来指定，因此 `appParam` 支持以下两种形式：

```json
{"appId": 1, "id": 1, "value": "参数值"}
```

或

```json
{"appId": 1, "name": "参数名称", "value": "参数值"}
```

### URL 拼接格式

将 `appParam` 拼接到嵌入 URL 后的格式如下：

```
<嵌入URL>?appParam=[{"appId":1,"name":"参数名称","value":"参数值"}]
```

> \[!IMPORTANT] 说明
>
> * 格式为 `{url}?appParam={appParam}`。
> * `appParam` 参数的值需要经过 `JSON.stringify` 和 URL 编码后传递，但 `appParam=` 字符本身不需要编码。
> * 您可以使用下方的 [URL 编码工具](#URL-编码) 来方便地生成 URL 编码后的 `appParam` 参数值并完成 URL 拼接。

### appParam 使用提示

1. **参数标识**：`appParam` 中可以使用参数的 `id` 或 `name` 来标识参数，二者选其一即可。
2. **appId 说明**：`appParam` 中的 `appId` 指的是参数创建时的应用 ID，而不是参数使用中的应用 ID。例如，如果参数在数据集市的数据包 A（`appId` 为 3）中创建，但在应用创作中的应用 A（`appId` 为 5）中使用，那么在 `appParam` 中需要输入的 `appId` 为 3。
3. **appId 重要性**：`appId` 和参数的 `id`（或 `name`）共同确定参数。如果省略 `appId`，可能会导致结果不正确。
4. **多参数支持**：`appParam` 支持传入多个参数。

## URL 编码

## appParam 举例

参数控制仪表盘内容展示的方式有很多种，可参照[参数使用场景](../parameter-scenarios.md)中介绍的方法。 下面以[数据集制作图表过程](../parameter-scenarios.md#数据集制作图表)中使用参数为例，介绍如何在嵌入场景下通过 appParam 传入参数。

如图所示，在某医院的就诊信息展示过程中，诊室和出诊医生信息使用科室参数进行内容控制，当改变科室参数时，图表的信息会跟随改变。

![](/images/solutions/solutions-embedded-analytics-001.png)

仪表盘的 URL 地址为

```
https://preview.hengshi.com/app/16743/dashboard/93
```

仪表盘内容如下：

![](/images/solutions/solutions-embedded-analytics-002.png)

科室与地域来源参数均为[开启多值的文本类型固定列表](../parameter.md#参数多值)参数，参数配置如下：

![](/images/solutions/solutions-embedded-analytics-007.png)

此时，可以通过 appParam 传入参数，控制仪表盘内容展示。

1. 场景 1 ：使用 appParam 传入科室参数，仅展示消化内科、神经内科两个科室的信息，appParam JSON 结构为

```json
[
  {
    "appId": 16743,
    "name": "科室",
    "value": [
      "消化内科",
      "神经内科"
    ]
  }
]
```

在 URL 后面拼接 appParam 为

仪表盘展示如下：

![](/images/solutions/solutions-embedded-analytics-003.png)

2. 场景 2：使用 appParam 传入多个参数，如通过科室参数控制科室相关信息，通过地域参数控制就诊用户地域相关信息。appParam JSON 结构为

```json
[
  {
    "appId": 16743,
    "name": "科室",
    "value": [
      "消化内科",
      "神经内科"
    ]
  },
  {
    "appId": 16743,
    "name": "地域来源",
    "value": [
      "北京",
      "天津"
    ]
  }
]
```

此时拼接后的 URL 为

仪表盘展示如下：

![](/images/solutions/solutions-embedded-analytics-004.png)