设计

公交卡支持模板渲染。如果未定义模板,系统将使用默认模板。

模板

卡券模板在类级别定义,用于显示与类相关联的任何对象。该模板可定义在卡券的不同部分显示哪些字段。

该模板分为以下几个部分:

卡片标题

卡片标题部分

卡片标题部分会显示公交运营商的徽标和名称以及旅程摘要。所有这三个要素都是必需的,用于填充这些要素的字段引用以及这些要素的位置都不能更改。

但是,渲染逻辑可使顶行具有一定的灵活性。卡片的顶行(表示旅程摘要)由单路段旅程 TransitObject 中的以下字段控制:

  • object.tripType
  • object.ticketLeg.originName
  • object.ticketLeg.destinationName
  • object.ticketLeg.originStationCode
  • object.ticketLeg.destinationStationCode

卡片的渲染方式取决于哪些字段是非空的。它可以通过以下方式进行渲染:

  • 仅显示出发地名称:出发地名称是卡片上显示的唯一信息。这对于覆盖某个区域而非特定旅程的车票特别有用。
  • 显示出发地和目的地:出发地位于左侧,目的地位于右侧。两者之间的符号取决于旅行的类型。出发地和目的地会以下列其中一种方式显示:
    • 显示名称和站点代码:我们会在顶部用较小的文本显示站点代码和名称。
    • 仅显示名称:我们会显示名称。
    • 仅显示站点代码:我们会显示站点代码。

多路段 TransitObject 对象的工作方式非常相似。在这种情况下,不要使用 object.ticketLeg,必须改用 object.ticketLegs[] 列表。必须定义出发地和目的地。在每个路段中使用的名称或站点代码必须保持一致。显示的出发地是数组中第一个要素的出发地,而显示的目的地是数组中最后一个要素的目的地。

卡券的背景颜色不是必填字段,可以在类级别和对象级别进行定义。对象字段具有更高的优先级,可用于替换类字段。

卡片模板

卡片模板部分用于显示额外的行,以对顶行中的旅程摘要进行补充。这些行可以包含文本型结构化数据字段或文本模块字段。

您可以在 class.classTemplateInfo.cardTemplateOverride.cardRowTemplateInfos[] 列表中指定用于定义对象数的行数。该列表至少需要一个要素,并且最多可以接受两个要素。每个要素必须是以下类型之一:

  • oneItem,接受一项内容:
    • item
  • twoItems,接受两项内容:
    • startItem
    • endItem
  • threeItems,接受三项:
    • startItem
    • midItem
    • endItem

每项内容可以定义为一个字段选择器 (.firstValue)、两个字段选择器(.firstValue.secondValue)或预定义项 (.predefinedItem)。系统会同时显示所选字段的值及其对应的标签。当您定义两个字段选择器时,系统会使用“/”分隔符将所选字段的值分隔开。所选字段的标签也是如此。预定义项用于定义更为复杂的呈现。

如果某项为空,则不会显示该项。如需了解详情,请参阅字段引用。如果某行中的所有项均为空,则不显示该行。如果某行中某些项(而非所有项)为空,系统会重新排列非空项并将其显示为项数较少的行。

如果您没有替换卡片模板,则使用默认行数、默认项数和默认字段引用。如需了解详情,请参阅默认模板

如果定义了主打图片,并且 cardRowTemplateInfos 列表中包含多行,则主打图片将显示在第一行之后。如果只有一行,主打图片将显示在该行上方。

卡片条形码

卡片条形码元素

卡片条形码部分用于在条形码上方和下方显示额外的文本或图片。此部分中的所有字段都不是必填字段。

有三个字段选择器,可用于定义两个并排字段(在条形码上方)和另外一个字段(位于条形码下方)。这些字段不显示标签,可以是文本型结构化数据字段、文本模块字段或图片模块字段。如果您使用图片,则应遵循品牌推广指南

条形码由类型和值定义。要查看受支持的条形码类型的列表,请参阅引用。此外,文本可以显示在条形码的正下方。此文本旨在协助条形码扫描,但还可以改为用于其他用途。

如果您没有替换条形码部分,系统则使用默认的条形码字段。如需了解详情,请参阅默认模板

详细信息模板

详细信息模板部分

详细信息模板部分是多个项 (class.classTemplateInfo.detailsTemplateOverride.detailsItemInfos[]) 的列表。这些项可以包含任何类型的结构化数据字段、文本模块字段、链接模块字段、图片模块字段或消息。

每项内容可以定义为一个字段选择器 (.firstValue)、两个字段选择器(.firstValue.secondValue)或预定义项 (.predefinedItem)。系统会同时显示所选字段的值及其对应的标签。当您定义两个字段选择器时,系统会使用“/”分隔符将所选字段的值分隔开。所选字段的标签也是如此。预定义项用于定义更为复杂的呈现。图片模块字段以全宽图片呈现,没有标签。

如果某项为空,则不会显示该项。如需了解详情,请参阅字段引用

如果您没有替换详细信息模板,则系统会显示默认的引用字段(按默认顺序)列表。如需了解详情,请参阅默认模板

如果旅程包含多个路段,则会在该部分的顶部显示一个简单的行程,并且无法移动该行程。如果旅程仅包含一个路段,则可以通过设置 class.enableSingleLegItinerary 来显示简单的行程。

列表模板

列表模板部分

列表模板部分用于选择要在 Google Pay 应用的“卡券”视图中显示的字段。卡券在列表中以徽标、背景颜色和三行表示。

第一行会显示旅程摘要。摘要可以采用以下格式之一:

  • originAndDestinationCodes
  • originAndDestinationNames
  • originName

可以使用字段选择器定义第二行和第三行。显示的字段没有标签。对于已分组的卡券,第二行始终会显示出发日期,第三行始终会显示已分组卡券的数量。

标签

所有结构化数据字段都有 Google 提供的标签。Google 负责以支持的所有语言为每个标签提供译文。

您可以使用其中某个 class.custom<name_of_the_field>Label 字段自定义其中某些标签。当您自定义某个标签时,您将负责以您希望支持的所有语言为该特定标签提供译文。

字段引用

字段引用用在模板的不同部分中,其格式为 class.classTemplateInfo.*.fields[]。字段引用包含结构化数据字段、文本模块字段、链接模块字段、图片模块字段或消息的路径列表。

并非所有类型的路径都在每个字段引用中受支持。例如,某些字段引用仅允许文本型结构化数据字段或文本模块字段的路径。文本型结构化字段是字符串、本地化字符串、日期或货币类型的结构化数据字段。

该列表可用于实现回退逻辑。这意味着如果列表中的第一个路径解析为空白字段,则系统会评估下一个路径。回退逻辑主要针对文本型结构化数据字段或文本模块字段。请勿在同一列表中混合使用不同类型的字段。使用回退逻辑时应谨慎,并且只能在特定情况下(例如,您需要在部分对象而无需在其他对象中遵循一致的字段格式)使用该逻辑。大多数情况下,为不同的用例创建单独的类更容易。

如果字段引用列表中的所有路径都解析为空白字段,则系统不会显示使用该字段引用的项。如果您希望使用该字段引用的项始终存在,请确保至少有一个路径不为空。我们建议您将某个字段设置为特殊字符(例如“-”)以表示空值,即使某些字段允许只包含空格的字符串也是如此。

要引用列表中包含的字段,您需要使用引用 ID。可供引用的列表中的所有项都具有 .id 字段。在字段引用字符串中使用与列表索引相同的 ID,如下面的示例所示:

  • object.imageModulesData[0].id = my-id
  • class.detailsTemplateOverride.detailsItemInfos[0].item.firstValue.fields[0].fieldPath = object.imageModulesData[‘my-id’]

在此示例中,卡券的详细信息部分中的第一项是在对象中声明的第一张图片。

默认模板

默认模板部分

对于图片模块字段,我们在类和对象中只能显示一个图片模块字段。如果您在任一级别需要多个图片模块字段,请替换默认模板。

对于文本模块字段,我们在类和对象中最多只能显示 10 个文本模块字段。这些字段的显示顺序与在数组中定义它们的顺序相同。如果您在任一级别需要 10 个以上文本模块字段,请替换默认模板。

对于消息,我们在类和对象中最多只能显示 10 条消息。无法保证这些消息的顺序。如果您在任一级别需要 10 条以上消息,或需要顺序有保证,请替换默认模板。

对于链接模块字段,您可以定义的 URI 数量没有限制。对于每个级别(类或对象),URI 按以下顺序进行显示和分组:

  1. 地图坐标,
  2. 电话号码,
  3. 电子邮件地址,
  4. 网页。
对于每个组,URI 的显示顺序与在数组中定义它们顺序相同。如果您需要不同的顺序,请替换默认模板。

默认列表模板部分