返回顶部

使用 URL 参数

在本主题中

  1. 常规参数
  2. 数据相关参数
  3. 微件相关的参数
  4. 登录相关参数
注：

关于 Experience Builder 的 2024 年 2 月发布的版本，不在参数值中的保留 URL 分隔符必须是纯文本，且不能编码。 在 2024 年 2 月版本之前创建的带有编码分隔符的 URL 不再有效。 必须将它们更改为纯文本。

在 Experience Builder 中，可以将 URL 参数添加至您的应用程序。 可以使用 URL 参数增强体验，即通过 URL 设置区域设置、将其定向至特定页面、激活打印预览等。

参数会添加至 URL 的末尾并格式化为以等号连接的键值对。 Experience Builder 应用程序支持查询字符串和片段参数，这意味着这些参数以问号 (?) 或井号 (#) 开头。 要包含多个参数，必须使用与号 (&) 分隔这些参数。 包含参数的体验 URL 结构如下：

 https://<domain>/experience/<AppID>/[?<param1=value>&<param2=value>#<param3=value>...]

以下为示例：

https://experience.arcgis.com/experience/<AppId>?locale=fr#data_s=id%3AdataSource_3-World_Cities_8506%3A1

体验 URL 可以包含下面列出的一个或多个参数。

警告：

在本主题中，方括号 ([]) 表示括起的参数或值为可选项。 请勿向 URL 添加方括号。

常规参数

以下子部分将介绍常规 URL 参数。

切换区域设置

要切换应用程序语言，请使用 locale 参数和双字母 ISO 639-1 语言代码。 Experience Builder 支持 ArcGIS Online 所支持的所有语言，包括以下语言代码：ar、bg、bs、ca、cs、da、de-at、de-de、de-ch、el、en-au、en-ca、en-gb、en-us、es-es、es-mx、et、fi、fr-fr、fr-ch、he、hr、hu、id、it-it、it-ch、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。

要以法语和瑞士法语使用 Experience Builder 应用程序，可以将 locale=fr 追加到 URL，如以下示例所示：

https://experience.arcgis.com/experience/<AppId>/?locale=fr
https://experience.arcgis.com/experience/<AppId>/?locale=fr-ch
注：

如果仅指定语言，而没有详细的区域设置，例如 fr 而不是 fr-ch 或 fr-fr，则可能无法获得预期的日期或数字格式。 这是因为官方语言相同的不同区域设置可能采用不同的日期和数字记法，例如美国 (en-us) 和英国 (en-gb)。

定义 web 地图或 web 场景

要在地图微件中显示地图或场景，请使用后跟地图或场景的项目 ID 的 webmap 或 webscene。

https://experience.arcgis.com/builder/?webmap=<ItemID>
https://experience.arcgis.com/builder/?webscene=<ItemID>
https://experience.arcgis.com/builder/?webmap=3582b744bba84668b52a16b0b6942544

转至页面

要定向至特定页面，使用 page 加页面名称。 在 ArcGIS Online Experience Builder 应用程序中，页面参数不是查询字符串的一部分，因此不以问号开头。 该参数会添加到 URL 路径中，如以下示例所示：

https://experience.arcgis.com/experience/<AppId>/page/Page-4
https://experience.arcgis.com/experience/<AppId>/page/{xxxHome}/

转到区块

要定向至特定区块，使用 block 加 blockID。 以下为示例：

https://experience.arcgis.com/experience/<AppId>/?block_id=layout1_block1

要查找区块的 blockID，您可以在按钮、图像或任何其他支持设置链接的微件上设置指向该区块的链接。 在预览应用程序并单击链接的微件时，blockID 将显示在 URL 中。

转至视图

要定向至特定活动截面视图，使用 views 加视图标注，例如 v1 或 View 1。

https://experience.arcgis.com/experience/<AppId>/?views=View-2
https://experience.arcgis.com/experience/<AppId>/?views=v1

打开窗口

要定向至特定活动窗口，使用 dlg 加窗口 ID 或标注。

https://experience.arcgis.com/experience/<AppId>/?dlg=Window-1

控制窗口焦点

要嵌入带有启动窗口或页面窗口的 Experience Builder 应用程序，而该应用程序不会自动转至这些窗口，可以使用 disable_window_focus 参数。 将以下 URL 添加至托管 web 页面以禁用移动行为。 默认情况下，disable_window_focus 为 false。

https://experience.arcgis.com/experience/<AppId>/?disable_window_focus=true

要控制特定窗口的窗口焦点，请使用 dlg，后跟窗口 ID 或标注以及 disable_window_focus 参数，如下例所示：

https://experience.arcgis.com/experience/<AppId>/?dlg=Window-1&disable_window_focus=true

视图草稿模式

预览应用程序时，会自动添加 draft 参数。 该参数用于获取未发布应用程序的项目资源。

https://experience.arcgis.com/experience/<AppId>/?draft=true
https://experience.arcgis.com/experience/<AppId>/?draft=1

打开打印预览

要激活打印预览模式，使用 print_preview。

https://experience.arcgis.com/experience/<AppId>/?print_preview=true
https://experience.arcgis.com/experience/<AppId>/?print_preview=1

数据相关参数

以下子部分将介绍与数据相关的 URL 参数。

选择数据

要选择数据记录，请在井号 (#) 后使用 data_s 参数。

应用程序中的每个数据源具有其自己的数据源 ID。 当您选择数据记录时，数据源的 ID 以及选择类型和选择条件将添加到应用程序的 URL。 如果有多个选择，则用逗号 (,) 分隔。 以下为示例：

https://experience.arcgis.com/experience/<AppId>/#data_s=<selection type>:<data source ID>:<selection condition>,<selection type>:<data source ID>:<selection condition>,...

共有三种选择类型：id、geometry 和 where。

  • 选择类型是 id 时，您将按要素的 recordID 选择要素。 如果您从同一数据源选择多条记录，则 recordID 用加号 (+) 分隔。 以下为示例：
    https://experience.arcgis.com/experience/<AppId>/#data_s=id:widget_1-dataSource_1-1871234a785-layer-2:1+2+3
  • 当选择类型为 geometry 时，您将根据要素相对于其他要素的位置来选择要素。 多个数据源 ID 通过波形符 (~) 连接。 以下为示例：
    https://experience.arcgis.com/experience/<AppId>/#data_s=geometry:widget_1-dataSource_1-1871234a785-layer-2~widget_1-dataSource_1-1871234a785-layer-3:<the geometry JSON>
  • 选择类型是 where 时，您将根据要素属性选择要素。 以下为示例：
    https://experience.arcgis.com/experience/<AppId>/#data_s=where:widget_1-dataSource_1-1871234a785-layer-2:a>1

可以使用此参数以查找特定于图层的数据源 ID： 例如，可以添加列表微件并将其连接到图层，预览应用程序以及选择列表中的任何记录。 填充的 URL 与以下示例类似：

https://experience.arcgis.com/experience/<AppID>/#data_s=id%3AdataSource_3-World_Cities_8506%3Axxxxxx

id%3A 后面和 %3Axxxx 前面的值为图层的数据源 ID。 如果已知该 ID，则可以将其用于其他参数以过滤数据源或更改版本。

注：

Experience Builder 之前使用 ?data_id 参数来选择数据。 该参数当前仍受支持，但很快就会被弃用。

过滤数据源

要直接过滤数据源，使用 data_filter。 过滤器格式为标准 WHERE 子句语法。 要过滤多个数据源，使用格式 [<dsId:filter>,<dsId:filter>]。

警告：

某些过滤器可能包含作为保留 URL 分隔符的字符（例如 "&"、"="、"'" 和 "?"）。 要确保 URL 能够正确解释值，您必须对不安全的字符进行 URL 编码，方法是将其替换为 % 字符，后跟与其 UTF-8 十六进制等效值相对应的值。

下表列出了参数值中必须编码的常见字符：

不安全的字符编码值

空格

%20

#

%23

%

%25

&

%26

'

%27

,

%2C

：

%3A

=

%3D

?

%3F

注：

您只需对参数值中的不安全字符进行编码。 如果某个字符用作 URL 分隔符，意味着它不在参数值中，因此必须是纯文本，不能被编码。

以下是带有未编码过滤器的 URL，它将不会生成预期结果：

http://experience.arcgis.com/experience/<AppID>/?data_filter=dataSource_1:name='Even&Odd'

以下 URL 是以上 URL 的正确编码版本。 请注意，上表中的某些字符未进行编码。 这是因为它们充当 URL 分隔符。

http://experience.arcgis.com/experience/<AppID>/?data_filter=dataSource_1:name%3D%27Even%26Odd%27

以下是另一个具有两个编码过滤器参数（objectid=1 和 fieldA>2）的示例 URL：

https://experience.arcgis.com/experience/<AppId>/?data_filter=ds1:objectid%3D1,ds2:fieldA%3E2

更改数据源的地理数据库版本

要更改数据源的地理数据库版本，请使用 data_version。

https://experience.arcgis.com/experience/<AppId>/?data_version=<dsId:version>,<dsId:version>
https://experience.arcgis.com/experience/<AppId>/?data_version=dsId1:v1, dsID2:v1

微件相关的参数

您可以通过添加微件 URL 参数，使用应用程序的 URL 来影响微件行为。 虽然不同的参数通过不同的方法实现，但它们通常遵循相同的语法：

https://experience.arcgis.com/experience/<AppId>#widget_1=param1:<value>,param2:<value>&widget_2=param1:<value>&...

微件参数在 URL 中以井号 (#) 开头，并以与号 (&) 连在一起。 如果有多个参数影响同一个微件，则它们之间用逗号分隔。

某些值可能包含作为保留 URL 分隔符的字符（例如 "&"、"="、"'" 和 "?"）。 要确保 URL 能够正确解释值，您必须对不安全的字符进行 URL 编码，方法是将其替换为 % 字符，后跟与其 UTF-8 十六进制等效值相对应的值。 参数值之外的 URL 分隔符必须为纯文本，不能编码。

例如，下面的 center 参数将无法正确运行，因为需要对两个逗号字符进行编码：

https://experience.arcgis.com/experience/<AppId>#map_1=center:-100,100,102100,rotation:45

以下是上述 URL 的正确书写版本：

https://experience.arcgis.com/experience/<AppId>#map_1=center:-100%2C100%2C102100,rotation:45

地图微件参数

以下子部分将介绍地图相关的 URL 参数。 可使用管理 URL 状态下的设置在用户与地图微件交互时让这些参数在 URL 中显示。 所有地图微件参数均前置井号 (#)。

注：

地图微件的 center、scale 和 rotation 参数仅适用于 Web 地图，不适用于 Web 场景。

定义地图微件首次加载时的 web 地图或 web 场景

如果地图微件包含多个 Web 地图或 Web 场景，您可以使用 active_datasource_id 后跟所需项目的数据源 ID 来定义加载应用程序时哪一个处于活动状态。 以下为示例：

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=active_datasource_id:<dataSourceId>
https://experience.arcgis.com/experience/<AppId>#map_1=active_datasource_id:dataSource_4

居中地图

要将地图置于特定位置的中心，请使用 center，后跟所需的坐标和所需坐标系的熟知 ID (WKID)。 以下为示例：

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=center:<x,y,wkid>
https://experience.arcgis.com/experience/<AppId>#map_1=center:-10373125.398783844%2C4598516.55871741%2C102100

定义地图比例

要定义地图比例，请使用 scale 后跟比例值。 以下为示例：

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=scale:<scaleValue>
https://experience.arcgis.com/experience/<AppId>#map_1=scale:19257701.0800833

定义地图旋转

要定义地图旋转，请使用 rotation 后跟度数。 以下为示例：

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=rotation:<rotationValue>
https://experience.arcgis.com/experience/<AppId>#map_1=rotation:45

定义地图视点

要定义视点（即查看地图或场景的位置或照相机位置），请使用 viewpoint。 如果地图微件包含多个地图或场景，则视点参数会影响所有这些地图或场景。

视点及其属性通常以 JSON 格式编写，如下例所示：

 {
  "rotation": 0,
  "scale": 19966005.903731048,
  "targetGeometry": {
    "spatialReference": {
      "latestWkid": 3857,
      "wkid": 102100
    },
    "x": -9870655.016044471,
    "y": 4724533.527708739
  }
}

要使用 URL 定义特定视点，您必须将通常以 JSON 格式编写的所有这些属性编码到 URL 中。 以下为示例：

https://experience.arcgis.com/experience/<AppId>#map_1=viewpoint:%7B"rotation"%3A0%2C"scale"%3A24387741.012671936%2C"targetGeometry"%3A%7B"spatialReference"%3A%7B"latestWkid"%3A3857%2C"wkid"%3A102100%7D%2C"x"%3A-10078461.002935613%2C"y"%3A4523117.553838721%7D%7D

注：
center、scale 和 rotation 参数的优先级高于视点参数，如果您使用与 web 地图相关的多个参数，这些参数将优先使用。
注：

由消息操作引起的地图范围更改的优先级高于由 URL 参数引起的范围更改。 例如，如果您尝试使用上述 URL 参数打开预定义范围内的地图微件，但地图微件也配置为记录选择更改触发器和平移至或缩放至消息操作的目标，则与消息操作相关的范围会取代您使用 URL 参数设置的范围。

定义地图图层的可见性

要定义地图图层的图层可见性，请使用layer_visibility。

图层可见性通常以 JSON 格式编写，如下例所示：

 {
  "widget_1-dataSource_1": {
    "widget_1-dataSource_1-187938b7328-layer-2": false
  },
  "widget_1-dataSource_4": {
    "widget_1-dataSource_4-18a690b433a-layer-4": false
  }
}

要使用 URL 让地图中的图层可见或隐藏，则必须将所有信息编码到 URL 中的 layer_visibility 参数之后。 以下为示例：

https://experience.arcgis.com/experience/<AppId>#map_1=layer_visibility:%7B%22widget_1-dataSource_1%22%3A%7B%22widget_1-dataSource_1-187938b7328-layer-2%22%3Afalse%7D%2C%22widget_1-dataSource_4%22%3A%7B%22widget_1-dataSource_4-18a690b433a-layer-4%22%3Afalse%7D%7D

搜索微件参数

以下小节将介绍与搜索相关的 URL 参数。 可使用管理 URL 状态下的设置在用户执行搜索时让这些参数在 URL 中显示。 搜索微件参数均前置井号 (#)。

显示搜索输入

searchText 参数将显示用户输入用于执行搜索的文本。 下面是包含 searchText 参数的示例 URL：

https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"searchText"%3A"<text>"%7D

显示搜索源

当用户仅使用一些可用搜索源执行搜索时，URL 中将显示以下两个参数之一：

  • 如果在运行时取消选中微件下拉菜单中的至少一个搜索源，serviceEnabledList 参数将显示并定义选中的搜索源。 当选中所有搜索源时，此参数变为隐藏状态。 下面是已编码 URL 示例：
    https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"serviceEnabledList"%3A%5B"<SourceID1>"%2C"<SourceID2>"%5D%7D
  • 如果用户单击搜索建议以应用搜索，"status":{"configId":"<SourceID>"} 参数将显示并定义正在当前搜索中使用的唯一搜索源。 URL 中将显示搜索输入和搜索源。 下面是已编码 URL 示例：
    https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"searchText"%3A"<text>"%2C"status"%3A%7B"configId"%3A"<SourceID>"%7D%7D

如果用户单击定位器源中的搜索建议，URL 将显示与建议关联的 magicKey。 magicKey 为将建议链接到特定地址或地点的唯一 ID。 下面是以 JSON 格式写入的搜索属性和参数的示例：

{
	"searchText": "<text>",
	"status":{
		"configId": "<SourceID>",
		"magicKey": "<key>"
	}
}

下面是以已编码 URL 写入的上述相同属性和参数的示例：

https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"searchText"%3A"<text>"%2C"status"%3A%7B"configId"%3A"<SourceID>"%2C"magicKey"%3A"<key>"%7D%7D

登录相关参数

以下子部分将介绍与登录账户相关的 URL 参数。

通过“嵌入”微件共享身份验证

一些 web 应用程序会提示用户使用 ArcGIS 账户进行登录。 应用程序可能因其共享设置需要进行登录，因为应用程序包含使用高级内容的微件或出于其他原因。

要在 Experience Builder 应用程序中嵌入 ArcGIS web 应用程序，并且这两个应用程序均需要用户进行登录，则可以添加 arcgis-auth-origin 和 arcgis-auth-portal URL 参数以在两个应用程序之间共享身份验证，由此用户仅需登录一次。

要将私有 Experience Builder 应用程序嵌入另一个 Experience Builder 应用程序，请使用 ?arcgis-auth-origin= 来定义主机应用程序域 URL 以进行身份验证。 以下为示例：

https://<orgdomain>/experience/<AppID>/?arcgis-auth-origin=<your host app domain, such as https://localhost:3001>

要嵌入基于 JavaScript API 的应用程序，例如 Web AppBuilder 应用程序，请使用 ?arcgis-auth-origin= 进行主机应用程序域身份认证，并使用 JavaScript 的 ?arcgis-auth-portal= 进行 ArcGIS 门户认证，该门户是基于 JavaScript API 的应用程序所需的身份认证来源。 以下为示例：

https://<orgdomain>/apps/webappviewer/index.html?id=<appID>&arcgis-auth-origin=<your host app domain, such as https://localhost:3001>&arcgis-auth-portal=<orgA URL>
https://www.arcgis.com/apps/dashboards/index.html#/<appID>?arcgis-auth-origin=https://experience.arcgis.com&arcgis-auth-portal=https://<myorg>.maps.arcgis.com

将用户发送到组织登录页面

通常，当用户尝试在 ArcGIS Online 中访问私有 Experience Builder 应用程序时，系统会将其定向到 ArcGIS Online 登录主页。 要改为将用户发送到组织的登录页面，使用 org 加组织简称。

https://experience.arcgis.com/experience/<AppId>/?org=<yourorgshortname>

有关此主题的反馈?

在本主题中
  1. 常规参数
  2. 数据相关参数
  3. 微件相关的参数
  4. 登录相关参数