返回顶部

创建可配置应用程序模板

在本主题中

  1. 创建和配置 web 应用程序模板
  2. 将模板添加到 ArcGIS Online
  3. 将应用程序设置为可配置
  4. 将模板收入组织的图库中

如果您拥有创建内容的权限，则可创建自定义应用程序模板，并将其托管在 web 服务器上。 创建和配置自定义应用程序模板后，将模板添加到 ArcGIS Online 中，以使应用程序能够在 ArcGIS 中被搜索到。 然后，可以将应用程序设置为可配置，以允许自定义应用程序的外观和行为。 如果您的组织计划在其中一个图库中收入您的模板，则可以与应用程序模板群组共享模板。

创建和配置 web 应用程序模板

要创建自定义 web 应用程序模板，可下载一个现有 ArcGIS Configurable Apps 模板并进行修改，也可更新现有 web 应用程序以使用来自 ArcGIS Online 的内容，或使用可从 GitHub 下载的构建应用程序中的代码构建新的 web 应用程序。

注：

ArcGIS Configurable Apps 将于 2025 年弃用。 有关 ArcGIS Configurable Apps 弃用以及如何将可配置应用程序迁移到 ArcGIS Instant Apps 的详细信息，请参阅 ArcGIS 博客文章 ArcGIS Configurable Apps 停用计划。

无论您以何种方式创建应用程序，都要使用 URL 参数和地图。 如果要创建基于群组的应用程序模板，并且要考虑其他要求以便使用 Bing Maps 底图、访问非公开地图和使用需要代理或跨域资源共享 (CORS) 的资源，则可以使用群组。

创建应用程序模板后，可将其托管在 web 服务器上。

URL 参数

当您使用模板时，可通过将 webmap 或 group ID 作为 URL 参数包含在模板中来指定要显示的地图或群组。 使用 webmap 参数来指定 Web 地图 ID，使用 group 参数来指定群组内容。 要为自定义模板使用当前地图或群组，必须将代码包括在应用程序中以便从 URL 中提取当前 web 地图或群组 ID。

例如，可在 Basic Viewer 模板中显示欧洲底图地图。

要执行此操作，从 Basic Viewer URL 开始：

https://www.arcgis.com/apps/View/index.html

复制欧洲底图 URL 的 webmap= 部分：

https://www.arcgis.com/home/webmap/viewer.html?webmap=5421a40574914458892efe74f0149025

并将其添加到 Basic Viewer URL 的末尾：

https://www.arcgis.com/apps/View/index.html?webmap=5421a40574914458892efe74f0149025

ArcGIS API for JavaScript 具有可简化此过程的辅助方法 esri.urlToObject。 此方法将 URL 参数转换为一个对象。

var webmap;
var urlObject = esri.urlToObject(document.location.href);

一旦具有对象形式的 URL 参数，您就可以访问各种输入。 例如，可将 web 地图 URL 参数的值分配到名为 webmap_id 的变量。

var webmap_id = urlObject.query.webmap;
注：

如果应用程序是可配置的，则必须处理名为 appid 的 URL 参数，该参数用于定义配置设置。

Web 地图

注：

此功能仅在 Map Viewer 经典版 中受支持。

应用程序模板旨在使用 Map Viewer 经典版 中当前显示的地图。 模板通常基于在 web 地图 URL 参数中所指定的 web 地图来创建地图。 每个 Web API 都具有一个辅助方法，即使用 web 地图 ID 中的信息来创建地图。 有关使用 API 来处理 web 地图的详细信息，请参阅 ArcGIS API for JavaScript。

例如，您可使用 ArcGIS API for JavaScript esri.arcgis.utils.createMap 方法来基于输入 ID 创建地图。 也可以包含回调函数，该函数在完成对 esri.arcgis.utils.createMap 的同步请求时运行。

esri.arcgis.utils.createMap(webmap,"map",{
   mapOptions:{
     slider:false
   },
   bingMapsKey:bingMapsKey
}).then(function(response){
    map = response.map;
});
注：

如果您的任何 web 地图中包含 Bing Maps 底图，则在使用 createMap 方法时必须指定 Bing Maps 密钥。 还可指定多种其他地图选项，例如是否要显示滑块、导航、属性等等。

callback 函数提供对响应对象的访问权限，该响应对象提供对地图对象、图层等的访问权限。 有关 Map 类的详细信息，请参阅 ArcGIS API for JavaScript。

分组

群组模板会显示来自应用程序中指定群组的内容。

ArcGIS REST API 提供对 ArcGIS Online 内容的访问权限。 您可以使用它基于输入群组的 ID 来检索群组内容。 有关使用 ArcGIS REST API 的详细信息，请参阅 ArcGIS REST API 概览。

在此示例中，进行查询以查找带有输入 ID 的群组。

var portal = new esri.arcgis.Portal('https://www.arcgis.com');
dojo.connect(portal, 'onLoad',function(){
    portal.queryGroup(groupid).then(function(response){
        var group = response.results[0];
     });
});

查找到该群组后，便可进行查询以从群组中检索项目。

在此示例中，查询该群组，以找到类型为 Web Map 或 Web Mapping Application 的五个项目。

var queryParams = {
    q: 'type:"Web Map" -type:"Web Mapping Application"',
    num: 5
 };
group.queryItems(queryParams).then(function(response){
    var groupItems = response.results;
});

其他考虑因素

Web 应用程序通常旨在处理多种类型的内容，因此您可能需要设置模板以处理带有 Bing Maps 底图、非公开内容等等的地图。 下面列出了特别注意事项。

Bing Maps 密钥

如果您想要显示的地图中的任意地图使用 Bing Maps 底图，则必须将 Bing Maps 密钥添加到应用程序中。 Bing Maps 密钥作为 createMap 方法的参数来提供。

代理和 CORS 支持

因为应用程序将对 ArcGIS Online 进行跨域请求，必须启用 CORS 或向您的应用程序添加代理。

将模板添加到 ArcGIS Online

创建 Web 应用程序模板并将其托管在 Web 服务器上后，将模板添加到 ArcGIS Online，以使应用程序能够在 ArcGIS 中被搜索到。

将模板添加为应用程序项目

将模板作为 web 应用程序项目添加到 ArcGIS Online，并指定应用程序的 URL。 对于用途，选择可配置。 对于 API，选择 JavaScript。

添加模板后，模板项目会显示在您的内容中，您可以编辑其详细信息。 请确保项目中包含描述性的标题和摘要，以便用户在可配置应用程序库中查看此项目时会显示此信息。 也可以创建包含应用程序文件的 .zip 文件并将其附加到项目以提供下载功能。

注册应用程序模板

作为项目添加应用程序模板后，必须注册应用程序。注册应用程序时会向您提供一个唯一的应用程序 ID。 在应用程序中使用应用程序 ID 来收集使用情况统计数据并允许用户使用 OAuth 2.0（一种标准授权框架）登录到平台。 利用应用程序 ID，您的应用程序能够使用与组织相关联的用户内容以及地理编码、路径选择和 GeoEnrichment 等其他 ArcGIS Online 功能。

注册 web 应用程序模板时，将类型设置为浏览器，并重定向 URI，使其指向模板应用程序 URL。

如果您使用的是 ApplicationBase 模板，则设置 config/defaults.js 文件中的可配置 oauthappid 属性。

//sample

 "oauthappid": “h4xZWhfz0an0TvqC"

如果您正在使用的并非 ApplicationBase 模板，则需要使用身份管理器来识别已注册的应用程序 ID。 有关详细信息，请参阅 OAuth 基本和 OAuth 弹出窗口示例。

将应用程序设置为可配置

您可以将 web 应用程序设置为可配置，以允许自定义这一应用程序的外观和行为。 例如，您可以允许用户更改应用程序的颜色或自定义应用程序的其他设置。

将应用程序设置为可配置需要创建配置文件并将配置文件信息与您创建的应用程序模板项目相关联。

创建配置文件

应用程序配置文件是 JSON 文件，用于定义应用程序模板的配置选项。 例如 Basic Viewer 应用程序的配置文件为 configurationPanel.js，位于 Esri Basic Viewer 资料档案库的资源文件夹中。 请参阅配置文件的完整示例。

注：

建议您通过验证器（例如 JSONLint）运行 JSON 代码，从而确保 JSON 格式正确并且不含错误。

执行以下操作来创建配置文件：

  1. 通过指定类别和各个部分的字段集来创建一个或多个部分。
    {
    "configurationSettings": [
        {
            "category": "",
            "fields": []
        }
    ]
}
  2. 使用下表列出的字段类型指定配置选项。 创建配置文件时，请确保 fieldName 属性在配置设置中具唯一性。

    字段类型描述

    段落

    在配置对话框中显示说明文本。

    {
       "type": "paragraph",
       "value": "* These menu items will appear in the application when the web map has layers that require them."
}

    字符串

    接受文本输入。 包括 stringFieldOption 属性，该属性用于指定在屏幕上显示的文本框类型。 值为 textbox、textarea 和 richtext。 textbox 选项为默认值，其形式为单行文本框。 textarea 选项可显示更大的文本框以便输入数据。 richtext 选项显示一个供用户在文本中应用某些格式（例如，将字体设置为粗体或斜体）的富文本编辑器。

    {
        "type": "string",
        "fieldName": "description",
        "label": "Description",
        "tooltip": "",
         "stringFieldOption": richtext || textarea || textbox,
        "placeHolder": "Text that appears in the text box to provide a hint to users on text to enter"
}

    示例输出

    description:"Bike Accidents"

    布尔

    创建指定 true 值或 false 值的复选框。 使用 condition 查看地图中是否包含指定的功能。 如果地图不满足条件，则复选框和标注不会显示在配置面板中。

    {
       "type": "boolean",
       "fieldName": "tool_bookmarks",
       "condition": "bookmark",
       "label": "Bookmarks",
       "tooltip": ""
 }

    示例输出

    tool_bookmarks:false

    数字

    创建接受数值的字段。 如果字段只接受特定范围的值，可以使用 constraints 设置将输入限制为特定范围的值，或者规定输入值的格式。 有关使用 Dojo Number TextBox 创建约束的信息，请参阅 Dojo 文档。

    { 
     "type": "number",
     "fieldName": "range",
     "label": "Range:",
     "tooltip": "",
     "constraints" :{min:0,max:10,places:0}
}

    示例输出

    range:0.5

    日期和时间

    创建包含日期选择的日期选择器。

    {
     "type":"date",
     "fieldName" : "startDate",
     "label" : "Start Date"
}

    创建包含时间选择的时间选择器。

    {
     "type": "time",
     "fieldName": "startTime",
     "label": "Start Time"
}

    日期和时间的示例输出（ISO-8601 格式）

    Start Date and Time: 1970-01-01T21:30:00.000Z

    选项

    创建具有一系列选项的下拉列表。

    {
   "type": "options",
   "fieldName": "theme",
   "tooltip": "Color theme to use",
   "label": "Color Scheme:",
   "options": [{
     "label": "Blue",
     "value": "blue"
   }, {
     "label": "Green",
     "value": "green"
   }, {
     "label": "Orange",
     "value": "orange"
   }]
 }

    示例输出

    theme:"blue"

    颜色选取器

    显示颜色选取器，可在其中从调色板中选择颜色或指定十六进制、rgb 或 hsv 值。 还提供透明度滑块和无颜色选项。

    {
   "type": "color", 
   "label": "Choose a selection color",
   "fieldName": "selectionColor",
   "transparency" : true,
   "noColor" : true
 }

    示例输出

    selectionColor:"#829254"

    Web 地图对话框

    显示一个对话框，可在其中浏览或搜索要在应用程序中显示的新地图。也可以指定一个测试地图的条件。 如果未满足该指定条件，则配置面板上会出现一条验证消息，确认地图没有满足要求。 有效的条件字符串如下：

    • time - 地图已启用时间
    • edit - 应用程序至少具有一个可编辑图层
    • featurelayer - 地图至少具有一个要素图层
    • filter - 地图中已定义一个交互式过滤器
    • 4x - 地图中包含 ArcGIS API for JavaScript 4x 版本尚不支持的内容
    {
   “type”: “webmap”,
   “conditions”: [“time”, “edit”, “featurelayer”, “filter”, “4x”]
 }

    示例输出

    webmap:"739ef0cf75de432995c77dd44ec8f652"

    Web 场景对话框

    显示一个对话框，可在其中浏览或搜索要在应用程序中显示的新 web 场景。

    {
   "type": "webscene"
 }

    示例输出

    webscene:"ab41c86a588748128e6f5d80990a2395"

    群组对话框

    显示一个对话框，可在其中浏览或搜索要在应用程序中显示的新群组。

    {
   "type": "group"

 }

    示例输出

    group:"449d00a4478d4849bbb65612355d6cd1"

    多个图层和字段选择器

    在地图中显示与受支持类型和几何类型相匹配的图层树视图和字段。 允许应用程序最终用户为每个图层选择多个图层和多个字段。

    注：

    如果将 editOnly 设置为 true，则字段列表将仅包含可编辑字段。

     {  
               "label":"Select search layers and fields",
               "fieldName":"searchLayers",
               "type":"multilayerandfieldselector",
               "editOnly":true,  
               "tooltip":"Select layer and fields to search",
               "layerOptions":{  
                  "supportedTypes":[  
                     "FeatureLayer"
                  ],
                  "geometryTypes":[  
                     "esriGeometryPoint",
                     "esriGeometryLine",
                     "esriGeometryPolyline",
                     "esriGeometryPolygon"
                  ]
               },
               "fieldOptions":{  
                  "supportedTypes":[  
                     "esriFieldTypeString"
                  ]
               }
            }

    示例输出

    searchLayers: [{
    "id":"Whittier_Hazards_821",
    "fields":[],
    "type":"FeatureLayer"
}]

    图层和字段选择器

    在地图中显示按所列出类型和几何过滤的图层下拉列表。 还可指定一个或多个字段选择器，允许用户选择图层和字段。

    注：

    如果将 editOnly 设置为 true，则字段列表将仅包含可编辑字段。

      {  
               "type":"layerAndFieldSelector",
               "fieldName":"tableLayer",
               "label":"Layer to display in table",
               "tooltip":"Layer to display in table",
               "fields":[  
                  {  
                     "multipleSelection":true,
                     "editOnly":true,    
                     "fieldName":"hiddenFields",
                     "label":"Hide the selected fields",
                     "tooltip":"Fields to hide in table",
                     "supportedTypes":[  
                        "esriFieldTypeSmallInteger",
                        "esriFieldTypeInteger",
                        "esriFieldTypeSingle",
                        "esriFieldTypeDouble",
                        "esriFieldTypeString"
                     ]
                  }
               ],
               "layerOptions":{  
                  "supportedTypes":[  
                     "FeatureLayer"
                  ],
                  "geometryTypes":[  
                     "esriGeometryPoint",
                     "esriGeometryLine",
                     "esriGeometryPolygon"
                  ]
               }
            }

    示例输出

    tableLayer: {
    id: "2014CyclingAccidents_All_874",
    fields: [{
        id: "urlField",
        fields: ["Casualty_Severity"]   
    }]
}

    Radio

    创建一次只能选择一个选项的单选按钮。 所选选项将设置为 true。

    {
   "type": "radio",
   "fieldName": "layout",
   "tooltip": "Custom Layout",
   "label": "Custom Layout:",
   "items": [{
     "label": "Sidebar",
     "value": "sidebarmenu"
   }, {
     "label": "FullWidth",
     "value": "fullwidth"
   }, {
     "label": "default",
     "value": "Default",
     "checked": true
   }]
 }

    示例输出

    customLayout:"fullmap"

    底图

    显示包含所有已命名的 Esri 底图的下拉列表。

    {
  “type”: “basemaps”,
   “fieldname” :”my_basemap”,
   “label”: “Alternate Basemap”
}

    示例输出

    my_basemap:"satellite"

    条件分析

    基于真或假条件显示或隐藏内容。 例如，如果取消选中显示图层列表复选框，则图层列表和所有相关选项（例如在图层列表中包括子图层）均会隐藏。

       {
               "type":"conditional",
               "condition": false,
               "fieldName":"showtitle",
               "label":"Display Map Title",
               "items":[
                 {
                    "placeHolder":"Defaults to web map title",
                    "label":"Title:",
                    "fieldName":"title",
                    "type":"string",
                    "tooltip":"Defaults to web map title"
                 },{
                      "type":"paragraph",
                      "value":"Enter a value to override the default title font size "
                   },
                   {
                      "type":"string",
                      "label":"Title font size",
                      "tooltip":"Specify title font size",
                      "fieldName":"titlefontsize",
                      "placeHolder":"20px"
                   }
               ]
            }
}

    搜索

    配置搜索窗格以使用定位器在要素图层或地址的字段中查找要素。 在配置要素搜索时，用户可以选择要素图层和搜索字段。

       {
“type”: “Search”,
  “fieldName”: “searchConfig”,
“label”: “Configure Search Options”
}

    示例输出

    searchConfig: {
sources: [{
locator: {
    url: "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer",
    _url: {
        path: "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer",
        query: null
    },
        normalization: true
    },
    url: "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer",
    name: "ArcGIS Geocoding service",
    enableSuggestions: true,
    singleLineFieldName: "SingleLine",
    enable: true,
    id: "dojoUnique3"
}],
activeSourceIndex: 0,
enableSearchingAll: false
}

    比例表

    显示用户可选择的预定义比例级别的列表。 例如，Countries、States、State、Counties、County、Metro、City、Town、Neighborhood。

    {
    “type”: “scaleList”,
    “fieldName”: “customUrlLayerZoomScale”,
    “label”: “Choose zoom level”
}

    示例输出

    “customUrlLayerZoomScale”: 12000

    ExtentMap

    创建带有地图中心和缩放级别选项的选择器。

    {
   "type":"extentMap",
   "label": "Select center and zoom",
   "fieldName": "mapExtent"
}

    示例输出

    mapExtent: {
  level: 2,
  coords: {
     latitude: 51.304,
     longitude: -98.7231
     }
}

关联配置信息与模板项目

创建配置文件后，必须关联 JSON 配置信息与您的应用程序模板，以将模板设置为可配置。

  1. 在应用程序模板的项目页面上，单击设置选项卡，然后单击顶部的 Web 制图应用程序链接。
  2. 在配置参数框中，粘贴配置文件中的 JSON 代码。
    注：

    配置参数框需要有效的 JSON。 建议您通过验证器（例如 JSONLint）运行 JSON，从而确保 JSON 格式正确并且不含错误。

  3. 保存您的设置。

配置文件示例

以下为完整的配置文件示例：

{
    "configurationSettings": [
        {
            "category": "General Settings",
            "fields": [
                {
                    "type": "options",
                    "fieldName": "theme",
                    "tooltip": "Color theme to use",
                    "label": "Color Scheme:",
                    "options": [
                        {
                            "label": "Blue",
                            "value": "blue"
                        },
                        {
                            "label": "Green",
                            "value": "green"
                        },
                        {
                            "label": "Orange",
                            "value": "orange"
                        }
                    ]
                },
                {
                    "type": "string",
                    "fieldName": "layer",
                    "label": "Analysis Layer",
                    "tooltip": "Feature Layer with Facilities to search"
                },
                {
                    "type": "string",
                    "fieldName": "orgname",
                    "label": "Organization Name:",
                    "tooltip": "",
                    "stringFieldOption": "richtext",
                    "placeHolder": "Organization Name"
                },
                {
                    "type": "number",
                    "fieldName": "bufferdistance",
                    "label": "Search Distance (miles)",
                    "value": "1"
                }
            ]
        }
    ],
    "values": {
        "theme": "orange",
        "bufferdistance": 1
    }
}

将模板收入组织的图库中

要使用组织的 Configurable Apps 库或群组应用程序库中的模板，请与所有人和使用该库的群组共享项目。 然后您组织的管理员可以通过配置地图或配置群组来使用包括模板的群组。

有关此主题的反馈?

在本主题中
  1. 创建和配置 web 应用程序模板
  2. 将模板添加到 ArcGIS Online
  3. 将应用程序设置为可配置
  4. 将模板收入组织的图库中