URL 参数

可以通过有效使用 URL 参数来增强仪表盘。 URL 参数是由其作者添加到仪表盘配置的属性，可用于触发操作。 URL 参数可以通过这种方法以规定的方式显示仪表盘。 当仪表盘嵌入到另一个应用程序中时，URL 参数也大有作用。 在这种情况下，可使用托管应用程序更改仪表盘的当前视图。

学习如何配置对 URL 参数的操作

注：

除内置 locale 参数外，在运行时更改仪表盘的参数不会导致在大多数现代浏览器中重新加载仪表盘。

URL 参数是名称-值对。 在每个参数中，名称和值由等号 (=) 分隔。 在运行时，可将参数添加到仪表盘 URL 的结尾处，具体形式是在井号 (#) 后加参数。

例如，包含参数的仪表盘 URL 可以是 <scheme>://<yourURL>/apps/dashboards/<id>#param=value。

对于多个参数，请在每个参数之间添加与号 (&)：<scheme>://<yourURL>/apps/dashboards/<id>#param=value&param2=value2

提示：

参数的顺序无关紧要。 例如，param=value&param2=value2 和 param2=value2&param=value 的结果相同。

参数名称由 ASCII 字母数字字符组成。 可以在除第一个位置之外的任意位置使用短划线 (-) 和下划线( _ )。 如果字符无效，则会在设计时阻止该字符，并显示验证警告。 最佳做法是避免使用长参数名称。

注：

某些参数名称由仪表盘保留，例如 mode 和 edit。 创建参数时，如果使用的名称已被保留，则会显示已使用验证警告。

警告：

URL 参数和选择器均用于提供仪表盘元素之间的交互。 如果目标是同一元素，则它们会互相矛盾，并产生意外结果。 在设计仪表盘的交互时需要注意这一点。

URL 编码

在运行时向仪表盘传递参数时，确保对其值进行编码。 编码可确保将无效字符替换为 %，并后跟其十六进制等效项。

例如，通过 URL 参数传递值 Main Street 将如下所示：

<scheme>://<yourURL>/apps/dashboards/<id>#param=Main%20Street

将 URL 参数作为逗号分隔的值列表传递时，请记住以下几点：

• 单独对每个值进行编码。

  正确

  param=Main%20Street,Broadway%20Avenue

  不正确。 请勿对用于分隔值的逗号进行编码。

  param=Main%20Street%2CBroadway%20Avenue

• 不要在值之间包含空格。

  正确

  param=Main%20Street,Broadway%20Avenue

  不正确

  param=Main%20Street, Broadway%20Avenue

URL 参数类型

URL 参数有五种类型：类别、数字、日期、要素和几何。 有关各种参数类型可触发的操作类型的信息，请参阅配置 URL 参数的操作。

类别参数

您可以使用类别参数将过滤操作应用于一个或多个元素。 在设计时，将指定参数的名称，输入是否为字符串或数字类型，以及过滤器查询是包含还是排除传入的值。

在运行时，类别参数接受单个值或由逗号分隔的多个值。 请勿在逗号后添加空格。

传入单个值时，查询使用比较运算符等于或不等于来过滤目标元素。 传入多个值时，将使用逻辑运算符 IN 或 NOT IN。

示例

下表表示类别参数被配置为预期接受字符串还是数字：

参数	备注
status=DAMAGED	字符串
status=DAMAGED,DESTROYED	具有多个值的字符串
category=1	数值
category=1,2	具有多个值的数字

特例

不会始终设置数据类别，在某些情况下，字符串可能为空。 因此，类别参数支持以下四种特殊情况：

• ((null))
• ((notnull))
• ((empty))
• ((notempty))

参数	备注
status=((null))	过滤 NULL 值。
status=((notnull)	过滤 NOT NULL 值。
status=((empty))	过滤空值。
status=((notempty))	过滤非空值。
status=DAMAGED,((null))	过滤单个传入值或 NULL 值。
status=DAMAGED,DESTROYED,((null))	过滤多个传入值或 NULL 值。

数字参数

可使用数字参数对一个或多个目标元素应用过滤操作。 在设计时，将指定参数的名称以及预期的输入值是单个值，还是表示一个范围的两个值。 使用单个值时，参数配置为应用以下比较运算符之一：

• 相等
• 不等于
• 小于
• 小于或等于
• 大于
• 大于或等于

提示：

相比于范围值类型提供的内容，如果想要获得更加精细的控制，可创建两个单个的数值参数，然后应用满足您需求的过滤条件（运算符）。 在运行的过程中，将过滤器应用于目标元素时，单个参数将与逻辑运算符 AND 组合。

在运行时，数字参数作为单个值或由逗号分隔的两个值传入。

示例

下表表示数字参数被配置为预期接受单个值还是范围：

参数	备注
meas=10	单一值
meas=10,15	范围

特例

不会始终设置数据中的数值。 因此，数字参数支持两种特殊情况：((null)) 和 ((notnull))。 这些特殊情况标注既可用于单个值工作流，又可用于数值范围方案。

参数	备注
meas=((null))	单日期值或数值范围 过滤 NULL 值。
meas=((notnull))	单日期值或数值范围 过滤 NOT NULL 值。
meas=10,((null))	单个值。 过滤值或 NULL 值。
meas=10,15,((null))	数值范围。 过滤范围内的数字或 NULL 值。

另一种特殊情况是数字参数需要一个范围，但在运行时只提供一个值。

参数	备注
meas=,10	左侧开放。 将过滤小于或等于此值的值。
meas=10,	右侧开放。 将过滤大于或等于此值的值。
meas=10	右侧开放。 将过滤大于或等于此值的值。
meas=10,((null))	右侧开放。 过滤大于或等于此值的值或 NULL 值。

日期参数

可使用日期参数对一个或多个目标元素应用过滤操作。 在设计时，将指定参数的名称以及预期的输入值是 ISO 8601 日期字符串还是 UNIX 时间。

可以将日期参数配置为处理表示日期范围的单个值或两个值。 使用单个值时，参数配置为应用以下比较运算符之一：

• 为
• 不等于
• 早于
• 等于或早于
• 晚于
• 等于或晚于

提示：

相比于范围值类型提供的内容，如果想要获得更加精细的控制，可创建两个单个的日期参数，然后应用满足您需求的过滤条件（运算符）。 在运行的过程中，将过滤器应用于目标元素时，单个日期参数将与逻辑运算符 AND 组合。

在运行时，日期参数作为单个值或由逗号分隔的两个值传入。 日期参数为 UNIX 时间时，必须提供 32 位有符号整数。 如果为字符串，则日期格式必须为 YYYY-MM-DD 或 YYYYMMDD。 日期使用公历输入，由年、月和日组成。

• YYYY - 四位年份 (YYYY)
• MM - 两位月份（01 到 12）
• DD - 两位日（01 到 31）

提示：

日期参数支持的日期格式列表与解析日期的序列图表支持的日期格式列表不同。

时间部分也可以包含在日期中。 时间使用 24 小时制输入，由小时、分钟和秒组成。 可以将其格式化为 hh:mm:ss 或 hhmmss。 如果日期中不包含时间部分，则表示在 00:00:00 到 23:59:59 之间的整天。

• hh - 00 到 24 之间的零填充小时
• mm - 00 到 59 之间的零填充分钟
• ss - 00 到 59 之间的零填充秒

如果指定，则时间部分与日期部分之间使用空格或大写 分隔。 以下是作为字符串传递的有效日期：

日期型	备注
2018-10-31	仅日期
20181031	仅日期（备用格式）
2018-10-31T23:14:42	由 T 分隔的日期和时间
20181031T231442	由 T 分隔的日期和时间（备用格式）
2018-10-31 23:14:42	由空格分隔的日期和时间
20181031 231442	由空格分隔的日期和时间（备用格式）

提示：

建议使用大写 T 分隔日期和时间。 如果使用空格，请对其进行编码。

在运行时将日期传递到仪表盘时，假定其时间组件在本地时区（即运行浏览器的计算机或设备的时区）中指定。 为控制更多内容，可将时间指定为协调世界时间 (UTC) 或 UTC 偏移。 要以 UTC 指定时间，可在时间后直接添加字母 Z，无需添加空格。 Z 是对零 UTC 偏移指定的区域。 UTC 偏移会以 ±hh:mm、±hhmm 或 ±hh 的格式追加到时间中。

日期型	备注
2018-10-31T23:14:42Z	UTC
2018-10-31T23:14:42+01:00	比 UTC 早一个小时
2018-10-31T23:14:42+0100	比 UTC 早一个小时
2018-10-31T23:14:42+01	比 UTC 早一个小时
2018-10-31T23:14:42-05:00	比 UTC 晚五个小时
2018-10-31T23:14:42-0500	比 UTC 晚五个小时
2018-10-31T23:14:42-05	比 UTC 晚五个小时

从日期参数构造过滤器时，仪表盘会检查目标元素的数据源，以获取时区信息。 如果找到时区信息，将以该时区发送查询。 如果未找到时区信息，则假定目标数据源为 UTC。 在任何一种情况下，仪表盘可能都需要转换输入时间以匹配目标的输入时间。

提示：

如果仪表盘收到的时间参数采用不可识别的格式，则会在运行时忽略该参数。

示例

下表中的注释表示日期参数被配置为预期接受单个日期还是日期范围。 提供 UNIX 时间和日期字符串示例。

参数	备注
created=1541027682	使用 UNIX 时间的单个值。
created=2018-10-31	使用表示全天的日期字符串的单个值。
created=2018-10-31T23:14:42	使用带时间的日期字符串的单个值。 表示使用本地时区。
created=2018-10-31T23:14:42Z	使用带 UTC 时间的日期字符串的单个值。

特例

不会始终设置日期值。 因此，日期参数支持两种特殊情况：((null)) 和 ((notnull))。 这两种特殊情况标签既可以用于单个值工作流，又可以用于日期范围工作流。

参数	备注
created=((null))	单日期值或日期范围 过滤 NULL 日期。
created=((notnull))	单日期值或日期范围 过滤 NOT NULL 日期。
created=2018-10-31,((null))	单个日期值。 过滤 10 月 31 日或 NULL 日期。
created=2018-10-31,2018-11-05,((null))	日期范围。 过滤范围中的日期或 NULL 日期。

另一种特殊情况是日期参数需要一个范围，但在运行时只提供一个值。

参数	备注
created=,2018-10-31	左侧开放。 过滤早于或等于该日期的日期。
created=2018-10-31,	右侧开放。 过滤晚于或等于该日期的日期。
created=2018-10-31,((null))	右侧开放。 过滤晚于或等于该日期的日期或 NULL 日期。

要素参数

要素参数用于将一个或多个要素 ID 传递到仪表盘。 要素参数可用于过滤仪表盘的元素，也可用于向仪表盘的地图应用位置操作 - 缩放、平移、显示弹出窗口和闪烁。

在设计时，将指定参数的名称并选择数据源。 必须标识数据源的唯一 ID 字段。 如果未能选择包含非唯一值的字段，则会在运行时出现异常行为。

提示：

如果所选数据源包含面，则该数据源可用于向目标元素应用空间过滤器。

在运行时，如果目标图层中的值是字符串，请确保使用 URL 对要素 ID 进行编码。 可以使用逗号分隔多个要素 ID，从而传入这些内容，例如 #asset=1240,1241,1242。 请勿在各个逗号后添加空格。

示例

参数	备注
id=11033	单一值
id=11033,23034,34035	多个值

几何参数

几何参数有两种类型：点和范围。 当类型为点时，几何参数用于缩放、平移或闪烁一个或多个仪表盘地图上的位置。 当类型为范围时，可使用几何参数设置仪表盘的地图范围或过滤其他元素。 在设计时，在配置任何操作之前，请指定参数的名称并选择几何类型。

在运行时，所有几何坐标均以逗号分隔的 World Geodetic System 1984 (WGS84) 值传入。 对于点参数，格式为 x,y。 对于范围参数，格式为 leftX,leftY,rightX,rightY。 在所有情况下，逗号后面都没有空格。

示例

参数	备注
pt=-75.6971931,45.4215296	几何参数需要一个点
ext=-80.6,40.6,-70.7,47.7	几何参数需要一个范围

切换区域设置

仪表盘具有一个名为区域设置的内置 URL 参数，用于在显示内容时切换语言、数字和日期格式。 将 #locale=<language code> 参数添加到仪表盘 URL 末尾。 使用与号 (&) 分隔多个 URL 参数，此内置参数可与任意作者配置的 URL 参数一起使用。

下表列出了支持的语言代码：

语言代码	语言
ar	阿拉伯语
bs	波斯尼亚语
ca	加泰罗尼亚语
cs	捷克语
da	丹麦语
de	德语
el	希腊语
zh-cn	英语
es	西班牙语
et	爱沙尼亚语
fi	芬兰语
fr	法语
he	希伯来语
hr	克罗地亚语
hu	匈牙利语
ID	印度尼西亚语
it	意大利语
ja	日语
ko	朝鲜语
lt	立陶宛语
lv	拉脱维亚语
nb	挪威克默尔语
nl	荷兰语
pl	波兰语
pt-br	巴西葡萄牙语
pt-pt	葡萄牙语
ro	罗马尼亚语
ru	俄语
sk	斯洛伐克语
sl	斯洛文尼亚语
sr	塞尔维亚语
sv	瑞典语
th	泰语
tr	土耳其语
uk	乌克兰语
vi	越南语
zh-cn	简体中文
zh-hk	中文（香港繁体）
zh-tw	中文（台湾繁体）

以下是设置数字和日期格式的区域设置的列表：

区域设置	数字和日期格式
en-au	英语（澳大利亚）
en-ca	英语（加拿大）
en-gb	英语（英国）
es-es	西班牙语(西班牙)
es-mx	西班牙语（墨西哥）
fr-ch	法语（瑞士）
de-ch	德语（瑞士）
it-ch	意大利语（瑞士）

以下 URL 显示了指定法语-瑞士区域的一个示例：

<scheme>://<yourURL>/apps/dashboards/4f539791b2f1418cb5403891f1a7be50#locale=fr-ch