向模板中添加可配置参数

创建 Web 应用程序模板之后，可选择将其设置为可配置。可配置 Web 应用程序允许用户自定义应用程序的外观和行为。可通过以下四个步骤将应用程序模板设置为可配置：

1. 如果您尚未进行此操作，请创建 Web 应用程序模板。
2. 创建配置文件以定义所需的配置属性。
3. 设置模板以读取配置属性并将属性应用于应用程序。
4. 将配置文件与应用程序模板项目相关联。

创建配置文件

配置文件是 JSON 文件，用于定义应用程序模板的配置选项。请参阅配置文件的完整示例。

注：

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

此配置文件包含一个或多个对选项进行分类的部分。

通过指定一类和一组字段创建每个部分。

{
    "configurationSettings": [
        {
            "category": "",
            "fields": []
        }
    ]
}

使用下表列出的字段类型指定配置选项。创建配置文件时，请确保 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 设置将输入限制为特定范围的值，或者规定输入值的格式。 { "type": "number", "fieldName": "range", "label": "Range:", "tooltip": "", "constraints" :{min:0,max:10,places:0} } 示例输出 range:0.5
选项	创建具有一系列选项的下拉列表。 { "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" } 示例输出 selectionColor:"#829254"
Web 地图对话框	显示一个对话框，可在其中浏览或搜索要在应用程序中显示的新地图。也可以指定一个测试地图的条件。如果未满足该指定条件，则配置面板上会出现一条验证消息，确认地图没有满足要求。有效的条件字符串如下： time - 地图已启用时间 edit - 应用程序至少具有一个可编辑图层 featurelayer - 地图至少具有一个要素图层 filter - 地图中已定义一个交互式过滤器 4x - 地图中包含 ArcGIS API for JavaScript 4x 版本尚不支持的内容 { “type”: “webmap”, “conditions”: [“time”, “edit”, “featurelayer”, “filter”, “4x”] } 示例输出 webmap:"739ef0cf75de432995c77dd44ec8f652"
群组对话框	显示一个对话框，可在其中浏览或搜索要在应用程序中显示的新群组。 { "type": "group" } 示例输出 group:"449d00a4478d4849bbb65612355d6cd1"
多个图层和字段选择器	在地图中显示与受支持类型和几何类型相匹配的图层树视图和字段。 允许应用程序最终用户为每个图层选择多个图层和多个字段。 { "label":"Select search layers and fields", "fieldName":"searchLayers", "type":"multilayerandfieldselector", "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" }]
图层和字段选择器	在地图中显示按所列出类型和几何过滤的图层下拉列表。 还可指定一个或多个字段选择器，以允许用户选择图层和字段。 { "type":"layerAndFieldSelector", "fieldName":"tableLayer", "label":"Layer to display in table", "tooltip":"Layer to display in table", "fields":[ { "multipleSelection":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"] }] }
单选按钮	创建一次只能选择一个选项的单选按钮。所选选项将设置为 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 World 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

配置文件示例

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

{
    "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    }
}

设置模板以读取配置文件信息

如果要将模板设置为可配置，则应用程序必须接受 Web 制图应用程序项目 ID 作为 appid URL 参数值。此 ID 用于进行异步请求以便检索应用程序的配置属性。在 ArcGIS API for JavaScript 中，可使用 esri.request 来检索应用程序配置详细信息。

在此例中，将 esri.arcgis.utils.arcgisUrl 解析为 www.arcgis.com/sharing/content/items。

var requestHandle = esri.request({
    url: esri.arcgis.utils.arcgisUrl + "/" + appid + "/data",
    content: {
        f: "json"
     },
    callbackParamName: "callback",
    load: function (response) {
     for (var key in response.values){
      if(response.values[key]!==undefined)configOptions[key]=response.values[key];
      }
    }, 
});

响应将包括用户使用配置窗格对应用程序进行的更改。之后，可检索更改并将它们应用到应用程序。应用程序应定义配置选项的默认值以便处理未配置模板的情况。

{
    "source": "15a34e2c161b4364860854fbc84262c5",    "folderId": "5705faa4594a4fd09edf01742c16e523",    "values": {
        "webmap": "32f1438789d34b5e8125f0f7c64b8d63",        "layer":"https://sampleserver6.arcgisonline.com/arcgis/rest/services/Water_Network/MapServer/2",        "theme": "green",        "orgname": "Water Points",        "bufferdistance": 3       }
 }

将配置文件信息与应用程序模板项目相关联。

创建配置文件后，即可将其与自定义应用程序模板相关联并将应用程序设置为可配置。

1. 如果尚未进行此操作，请应用程序模板添加为新的应用程序项目：
2. 在应用程序模板的项目页面上，单击设置选项卡，然后找到 Web 制图应用程序部分。
3. 在用途下拉菜单中，选择可配置。
4. 在配置参数字段中宏，粘贴配置文件中的 JSON 代码。

   注：

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

5. 单击保存保存您的设置。

如果要使用组织的 Map Viewer 应用程序库或群组应用程序库中的可配置模板，则需要将项目共享到用于该应用程序库的群组。然后您组织的管理员可以通过配置地图或配置群组来使用包括模板的群组。