iD学习 - 要素及属性

Presets

Preset是iD编辑器预设的要素，Field是Preset的属性，定义文件为JSON类型，存在放在目录data/presets中。

Preset文件

Presets定义文件为JSON类型，存在data/presets/presets目录下。他们有组织的存放于基于k/v结构的目录层次中。
例如, preset的tag为leisure=park，定义文件为 data/presets/presets/leisure/park.json

Preset结构

一个简单的preset结构

{
    // 图标.
    "icon": "maki-park",
    // fields中的属性默认显示在编辑器左侧的属性栏中.
    // 查看fields详细文档了解什么可以写在这里.
    "fields": [
        "address"
    ],
    // moreFields中的属性可以手动添加到属性栏. 
    // 如果属性存在默认会显示在属性栏中.
    "moreFields": [
        "phone",
        "website"
    ],
    // preset合法的几何类型.
    // 可选类型包括 point, area, line, and vertex.
    // vertexes是line中的point, 比如道路中的形状点.
    // lines是不闭合的ways, areas是闭合的ways.
    "geometry": [
        "point", "area"
    ],
    // Terms是preset的同义词
    // 他们会被添加到检索功能. 
    // 查找woodland会返回park要素.
    "terms": [
        "esplanade",
        "village green",
        "woodland"
    ],
    // 当要素被选中时Tags会被默认添加,
    // 同时也用于匹配要素属于哪种类型.
    // 可以使用 "*" 匹配所有类型.
    "tags": {
        "leisure": "park"
    },
    // 这个要素显示的英文名称.
    "name": "Park"
}

完整的要素 JSON 定义可以参考文件 data/presets/schema/preset.json

Preset属性

name

要素的英文名称，它被发送到Transifex，以便转换成本地化语言。
此属性为必须，无默认值。

geometry

要素允许的几何类型数组，要素按顺序进行匹配。

• point：不属于任何道路的点
• vertex：属于一条或者多条道路的点
• line：线状要素
• area：一个闭合的线（首节点和尾节点相同）或者是一个type=multipolygon的关系
• relation：关系
  闭合的路既可以是line也可以是area。如果要素可以是两种类型，当选择area类型是，编辑器会自动添加area=yes标签。
  应按优先顺序列出几何类型。例如，要素leisure=swimming_pool中area在point之前。
  此属性为必须，无默认值。

tags

一个拥有"key": "value"标签的对象必须匹配到一个要素类型。通配符"*"可以匹配这个key的任何value。
一个对象只能匹配到一个要素类型，如果匹配到多个类型，iD会根据matchScore、匹配的标签数量、使用的通配符找到最佳匹配结果。
此属性为必须，无默认值。

addTags

当选择这个要素时可以选择添加的标签。默认值为tags。如果需要，这个属性通常是tags的超集。
iD的validator会建议用户从addTags中添加缺失的标签来匹配要素。例如，Bridge要素有如下属性：

    "tags": {
        "man_made": "bridge"
    },
    "addTags": {
        "man_made": "bridge",
        "layer": "1"
    }

当添加一个Bridge要素，会默认给出man_made=bridge和layer=1标签，用户可以将layer改为3，要素仍然匹配，因为仍然拥有man_made=bridge标签。如果用户删除了layer标签，iD会建议添加回值1。

removeTags

当要素变为其他类型时被删除的属性。默认值为addTags,如果没有定义，默认值则为tags。

Fields / moreFields

这两个属性都是属性路径的数组（例如：description 或者 generator/type），fields默认显示，moreFields在用户手动添加时显示或者有匹配的标签时显示。注意，一些属性的显示有先决条件prerequisiteTag才会显示。
一个要素可以通过中括号引用另一个要素的属性，就像{preset}，例如shop/books引用了shop的属性：

"fields": [
    "{shop}",
    "internet_access"
],
"moreFields": [
    "{shop}",
    "internet_access/fee",
    "internet_access/ssid"
],
"tags": {
    "shop": "books"
}

如果fields和moreFields没有定义，则使用父要素的值。例如，shop/cooonvenience自动使用shop相同的属性。
在显式继承和隐式继承中，有属性定义的要素通常不会继承父要素属性。

icon

本地SVG文件名称。你可以使用下面任何一组图标。使用图标时使用前缀版本名称，例如"icon": "maki-park"或者"icon": "tnp-2009223"。

• iD’s spritesheet (iD-)
• Maki (maki-)，Mapbox地图图标
• Temaki (temaki-)，一个maki的扩展包
  • 如果你要提交一个图标，这里是最好的位置。
• Font Awesome，上千的常用图标
  • 分为免费版和专业版。你可以使用免费版如下样式：
    • Solid (fas-)
    • Regular (far-)
    • Brands (fab-)
• The Noun Project (tnp-)，上百万的常用图标。
  • 根据许可不同。你只能在iD使用public-domain图标。
  • 根据样式不同。避免使用太细或者太细致的图标，他们不适合在小尺寸下使用。
  • 使用图标的数字ID（例如，2009223）。当你在网站中选中图标链接时显示。
  • 不幸的是，需要注册免费的API Key下载图标，即使是public-domain图标。添加一个文件the_noun_project.auth到iD的本地根目录，包含你的认证信息，例如{"consumer_key": "xxxxxx", "consumer_secret": "xxxxxx"}。此文件不受版本控制。

imageURL

远程图片文件URL。并不能完全替换图标，两个图标都可能显示在用户界面中。
例如，imageURL用于从name-suggestion-index中指定品牌预设的logo。
图像至少为100100px以便在高分辨率屏幕上显示5050pt。

searchable

不推荐使用或者通用的要素可设置为"searchable": false，这意味着在编辑现有数据时会使用他们，但在添加新要素时不能作为选项使用。
按照惯例，不可搜索的要素文件名以下划线开头。（例如，data/presets/presets/landuse/_farm.json）

matchSorce

一个要素匹配的排序数字。
例如，一个要素有amenity=cafe和building=commercial标签，会匹配Cafe要素而不是Commercial Building要素，因为Commercial Building的matchSorce比较低。
默认值为1.0。

countryCodes

一个两个字母字符数组，小写城市代码(ISO 3166-1 alpha-2)。要素只有当用户在编辑指定的白名单国家时才能被搜索。不是用户位置或者语言设置，而是编辑的地图位置。
默认所有位置都可编辑

notCountryCodes

一个两个字母字符数组，小写城市代码(ISO 3166-1 alpha-2)。与countryCodes类似的黑名单。

replacement

一个更推荐的要素ID。iD验证器会与此要素设置匹配，推荐用户升级标签。
如果可能，请使用deprecated.json来指定旧标记的升级路径。此属性用于特殊情况，例如具有几何要求的升级。

reference

一个链接到wiki文档的要素的键值。只要要素包含多个标签时才需要。
例如：

"reference": {
    "key": "tower:type",
    "value": "communication"
}

Fields

Fields是可以在要素中复用的元素。

Field文件

Fields定义文件为JSON类型，存在data/presets/fields目录下。
field文件通常根据关联的key命名。例如，标签sport=*存放在文件data/presets/fields/sport.json中。当一个属性有多个版本时，我们在文件名中添加一个后缀：(sport.json, sport_ice.json, sport_racing_moter.json)。
某些key使用冒号（’:’）命名。命名的属性根据其标签嵌套在文件夹中。例如，标签piste:difficulty=*存放在文件data/presets/fields/piste/difficulty.json中。

Field结构

{
    "key": "cuisine",
    "type": "combo",
    "label": "Cuisine"
}

完整的属性 JSON 定义可以参考文件 data/presets/schema/field.json

Field属性

type

指定属性的界面和行为的字符串。必须是以下值之一。

• Text属性
  • text - 简单的单行文本属性
  • number - 拥有上下键的数字输入文本属性（例如width=*）
  • localized - 具有本地化功能的文本字段（例如name=*, name:es=*, etc.）
  • tel - 电话号码输入文本属性（根据位置本地化）
  • email - 邮箱地址输入文本属性
  • url - URLs输入文本属性
  • identifier - 身份证输入文本属性（例如gnis:feature_id）
  • textarea - 多行文本属性（例如description=*）
• Combo/Dropdown属性
  • combo - 从多个选项选择一个选项的下拉框（例如surface=*）
  • typeCombo - 从泛型类别关键字中选择特定类型的下拉框（例如waterway=*，如果未设置，则标记将为waterway=yes，但下拉列表中包含stream、ditch、river等选项）
  • multiCombo - 用于向公用多建添加yes值的下拉框（例如recycling:*-> recycling:glass=yes，recycling:paper=yes，etc）
  • networkCombo - 帮助用户选择路由网络标签的下拉框（根据位置本地化）
  • semiCombo - 用于向分号分隔的列表中添加多个值的下拉框（例如sport=*-> soccer;lacrosse;athletics;field_hockey）
• Checkboxes
  • check - 3个状态的checkbox：yes, no, no tag
  • defaultCheck - 2个状态的checkbox。选中为yes，未选中为no tag
  • onewayCheck - 3个状态的checkbox，用于oneway属性。带有方向转换按钮。
• Radio Buttons
  • radio - 多选radio按钮属性
  • structureRadio - 多选结构按钮属性。道路桥梁有扩展输入。
• Special
  • access - 用于定义高速上的access=*的标签
  • address - 用于输入地址信息的文本和下拉框（根据位置本地化）
  • cycleway - 用于在高速上添加cycleway:left和cycleway:right标签的下拉框
  • maxspeed - 用于输入速度的数字文本属性和"mph/kph"的下拉框
  • restrictions - 用于编辑转向限制的图形属性
  • wikidata - 用于选择Wikidata实体的搜索属性
  • wikipedia - 用于选择wiki语言和Wikipedia页面的属性

key / keys

将要编辑的属性的属性名称。像address这样的复合属性在keys属性中需要一个key数组。

universal

如果属性定义中包含"universal": true，则这个属性出现在所有要素的添加属性列表中。

geometry

如果指定，则仅显示此类几何。point, vertex, line, area。

default

属性的默认值。例如，building_area.json会自动添加属性building=yes到当前选择的building要素（仅当要素为闭合区域）

{
    "key": "building",
    "type": "combo",
    "default": "yes",
    "geometry": "area",
    "label": "Building"
}

options

Combo类型属性可以通过options数组提供下拉框值域。用户可以从下拉框选择也可以自己输入。

{
    "key": "diaper",
    "type": "combo",
    "label": "Diaper Changing Available",
    "options": ["yes", "no", "room", "1", "2", "3", "4", "5"]
}

string

Combo类型属性可以在string属性使用name-value对。当属性有固定数量的选项，并且你想提供翻译描述时，这将非常有用。使用string属性时，用户不能输入自己的值，必须从选项中选择。

{
    "key": "smoothness",
    "type": "combo",
    "label": "Smoothness",
    "placeholder": "Thin Rollers, Wheels, Off-Road...",
    "strings": {
        "options": {
            "excellent": "Thin Rollers: rollerblade, skateboard",
            "good": "Thin Wheels: racing bike",
            "intermediate": "Wheels: city bike, wheelchair, scooter",
            "bad": "Robust Wheels: trekking bike, car, rickshaw",
            "very_bad": "High Clearance: light duty off-road vehicle",
            "horrible": "Off-Road: heavy duty off-road vehicle",
            "very_horrible": "Specialized off-road: tractor, ATV",
            "impassable": "Impassable / No wheeled vehicle"
        }
    }
}

如果Combo属性没有指定options或者strings，该属性将从Taginfo服务获取公共标签值用作下拉框。

snake_case

用于Combo属性，如果snake_case为true则标签中的空格替换为下划线。
默认值为true

caseSensitive

用于Combo属性，如果caseSensitive为true，则允许大小写敏感。
默认值为false

min_value

用于number属性，最小有效值。
无默认值

max_value

用于number属性，最大有效值。
无默认值

prerequisiteTag

先决条件标签。一些标签达到先决条件才会显示。
应包含如下属性：

• key：必须的标签key
  可以选择性的选择如下属性之一：
• value：key必须含有的值
• valueNot：key必须不含有的值
  或者，对象可以包含单个属性：
• keyNot：不能出现的key
  例如，只有当internet_access属性不是no的时候，显示Internet Access Fee属性。

"prerequisiteTag": {
    "key": "internet_access",
    "valueNot": "no"
}

如果某个要素具有此属性的一个或多个key的值，则无论prerequisiteTag属性如何，都将显示属性。

countryCodes

一个两个字母字符数组，小写城市代码(ISO 3166-1 alpha-2)。属性只有当用户在编辑指定的白名单国家时才能被使用。不是用户位置或者语言设置，而是编辑的地图位置。
默认所有位置都可使用

notCountryCodes

一个两个字母字符数组，小写城市代码(ISO 3166-1 alpha-2)。与countryCodes类似的黑名单。

urlFormat

用于identifier属性，外部记录的永久链接URL。必须包含一个{value}占位符用于替换标签值。

pattern

用于identifier属性，正则表达式匹配有效值。

编译

编译presets，只需要执行npm run build。
下列文件将自动生成，重新编译时被替换：

• data/presets/categories.json
• data/presets/fields.json
• data/presets/presets.json
• data/presets.yaml
• data/taginfo.json
• dist/locales/en.json

自定义preset

iD支持部署自定义preset集合，你可以通过preset访问器提供presets。

var id = iD.coreContext().presets({
    presets: { ... },
    fields: { ... },
    defaults: { ... },
    categories: { ... }
});

必须提供所有四个部分（presets、fields、defaults和categories）。此外，必须包括几个基本presets和fields。
必须包含基本的几何，以便每个要素至少能匹配到一个preset，例如：

"area": {
    "name": "Area",
    "tags": {},
    "geometry": ["area"],
    "matchScore": 0.1
},
"line": {
    "name": "Line",
    "tags": {},
    "geometry": ["line"],
    "matchScore": 0.1
},
"point": {
    "name": "Point",
    "tags": {},
    "geometry": ["point", "vertex"],
    "matchScore": 0.1
},
"relation": {
    "name": "Relation",
    "tags": {},
    "geometry": ["relation"],
    "matchScore": 0.1
}

必须包含一个name属性：

"name": {
    "key": "name",
    "type": "localized",
    "label": "Name",
    "placeholder": "Common name (if any)"
}