开发带有选项的区块

本教程演示了如何使用 select（下拉）输入类型让作者选择一个区块选项，然后将其应用为单个相应的 CSS 类。

{align="center"}

区块模型

默认 ​选项以空字符串 ("") 表示，而​ 并排 ​选项则使用 "side-by-side"。选项的​ 名称 ​和​ 值 ​不必相同，但​ 值 ​决定了应用于区块级 HTML 的 CSS 类。例如，并排 ​选项的值可以是 layout-10，而不是 side-by-side。然而，最好为 CSS 类使用语义上有意义的名称，以确保选项值的清晰性和一致性。

[/blocks/teaser/_teaser.json]{class="badge neutral" title="下面是代码示例的文件名。"}

...
"fields": [
    {
        "component": "select",
        "name": "classes",
        "value": "",
        "label": "Teaser options",
        "valueType": "string",
        "options": [
            {
                "name": "Default",
                "value": ""
            },
            {
                "name": "Side-by-side",
                "value": "side-by-side"
            }
        ]
    }
]
...

区块 HTML

当作者选择某个选项时，相应的值将作为 CSS 类添加到该区块的 HTML 中

• 如果选择了​ 默认：

  code language-html
  <div class="block teaser"> <!-- Block content here --> </div>

• 如果选择了​ 并排：

  code language-html
  <div class="block teaser side-by-side"> <!-- Block content here --> </div>

这样可以根据所选的选项应用不同的样式和条件式 JavaScript。

本教程中不使用此方法，但它展示了一种替代方案以及更高级的区块配置选项。

select 输入类型允许作者选择一个单一的区块选项，该选项可以选择性地映射到多个 CSS 类。为实现此功能，请将多个 CSS 类以空格分隔的形式列出。

{align="center"}

区块模型

例如，并排 ​选项可以支持不同的变体，其中图像可以显示在左侧 (side-by-side left) 或右侧 (side-by-side right)。

[/blocks/teaser/_teaser.json]{class="badge neutral" title="下面是代码示例的文件名。"}

...
"fields": [
    {
        "component": "select",
        "name": "classes",
        "value": "",
        "label": "Teaser options",
        "valueType": "string",
        "options": [
            {
                "name": "Default",
                "value": ""
            },
            {
                "name": "Side-by-side with Image on left",
                "value": "side-by-side left"
            },
            {
                "name": "Side-by-side with Image on right",
                "value": "side-by-side right"
            }
        ]
    }
]
...

区块 HTML

当作者选择某个选项时，对应的值会作为一组以空格分隔的 CSS 类，应用到该区块的 HTML 中：

• 如果选择了​ 默认：

  code language-html
  <div class="block teaser"> <!-- Block content here --> </div>

• 如果选择了​ 图像在左侧的并排显示：

  code language-html
  <div class="block teaser side-by-side left"> <!-- Block content here --> </div>

• 如果选择了​ 图像在右侧的并排显示：

  code language-html
  <div class="block teaser side-by-side right"> <!-- Block content here --> </div>

这样可以根据所选的选项应用不同的样式和条件式 JavaScript。

本教程中不使用此方法，但它展示了一种替代方案以及更高级的区块配置选项。

"component": "multiselect" 输入类型允许作者同时选择多个选项。这使得通过组合多个设计选项来实现区块外观的复杂变体成为可能。

{align="center"}

区块模型

例如，并排显示、图像在左侧 ​和​ 图像在右侧 ​可以支持图像显示在左侧 (side-by-side left) 或右侧 (side-by-side right) 的不同变体。

[/blocks/teaser/_teaser.json]{class="badge neutral" title="下面是代码示例的文件名。"}

...
"fields": [
    {
        "component": "multiselect",
        "name": "classes",
        "value": [],
        "label": "Teaser options",
        "valueType": "array",
        "options": [
            {
                "name": "Side-by-side",
                "value": "side-by-side"
            },
            {
                "name": "Image on left",
                "value": "left"
            },
            {
                "name": "Image on right",
                "value": "right"
            }
        ]
    }
]
...

区块 HTML

当作者选择多个选项时，对应的值会作为以空格分隔的 CSS 类，应用到区块的 HTML 中：

• 如果选择了​ 并排 ​和​ 图像在左侧：

  code language-none h-1
  <div class="block teaser side-by-side left"> <!-- Block content here --> </div>

• 如果选择了​ 并排 ​和​ 图像在右侧：

  code language-none h-1
  <div class="block teaser side-by-side right"> <!-- Block content here --> </div>

虽然多选功能提供了更高的灵活性，但也增加了管理设计变体的复杂度。如果没有限制，冲突的选择可能导致功能异常或偏离品牌规范的体验。

例如：

• 如果选择了​ 图像在左侧 ​或​ 图像在右侧，但未选择​ 并排显示，则会隐式地将它们应用到​ 默认，该选项始终会将图像设置为背景，因此左侧和右侧的对齐方式无关紧要。
• 同时选择​ 图像在左侧 ​和​ 图像在右侧 ​是相互矛盾的。
• 选择​ 并排 ​而不选择​ 图像在左侧 ​或​ 图像在右侧 ​可能会被视为不明确，因为图像的位置未指定。

为避免出现问题及作者在使用多选时产生困惑，请确保选项设计合理且对所有组合情况进行充分测试。多选功能最适合用于简单且不冲突的增强选项，如“large”（大号）或“highlight”（高亮），而不适用于改变布局的选择。

本教程中不使用此方法，但它展示了一种替代方案以及更高级的区块配置选项。

在通用编辑器中，添加新区块实例时，可以将区块选项设置为默认值。这是通过在区块定义中设置 classes 属性的默认值来实现。

区块定义

在下面的示例中，通过将 classes 字段的 value 属性设置为 side-by-side，将默认选项设为​ 并排显示。区块模型中对应的区块选项输入是可选的。

您也可以为同一个区块定义多个条目，每个条目拥有不同的名称和类。这使得通用编辑器能够显示不同的区块条目，每个条目都预先配置了特定的区块选项。虽然在编辑器中它们表现为独立的区块，但代码库实际上只包含一个区块，该区块会根据所选选项动态渲染内容。

[/blocks/teaser/_teaser.json]{class="badge neutral" title="下面是代码示例的文件名。"}

{
    "definitions": [{
      "title": "Teaser",
      "id": "teaser",
      "plugins": {
        "xwalk": {
          "page": {
            "resourceType": "core/franklin/components/block/v1/block",
            "template": {
              "name": "Teaser",
              "model": "teaser",
              "classes": "side-by-side",
              "textContent_text": "<h2>Enter a title</h2><p>...and body text here!</p>",
              "textContent_cta": "/",
              "textContent_ctaText": "Click me!"
            }
          }
        }
      }
    }],
    "models": [... from previous section ...],
    "filters": []
}

以下是选择了​ 并排 ​区块选项的 Teaser 区块的 DOM，这是使用 JavaScript 和 CSS 进行装饰的目标对象。

...
<body>
    <header/>
    <main>
        <div>
            <!-- Start block HTML -->
            <div class="teaser block side-by-side" data-block-name="teaser" data-block-status="loaded">
                <div>
                    <div>
                    <picture>
                        <source type="image/webp" srcset="./media_15ba2b455e29aca38c1ca653d24c40acaec8a008f.jpeg?width=2000&format=webply&optimize=medium" media="(min-width: 600px)">
                        <source type="image/webp" srcset="./media_15ba2b455e29aca38c1ca653d24c40acaec8a008f.jpeg?width=750&format=webply&optimize=medium">
                        <source type="image/jpeg" srcset="./media_15ba2b455e29aca38c1ca653d24c40acaec8a008f.jpeg?width=2000&format=jpeg&optimize=medium" media="(min-width: 600px)">
                        <img loading="eager" alt="Woman looking out over a river." src="./media_15ba2b455e29aca38c1ca653d24c40acaec8a008f.jpeg?width=750&format=jpeg&optimize=medium" width="1600" height="900">
                    </picture>
                    </div>
                </div>
                <div>
                    <div>
                    <h2 id="wknd-adventures">WKND Adventures</h2>
                    <p>Join us on one of our next adventures. Browse our list of curated experiences and sign up for one when you're ready to explore with us.</p>
                    <p>Terms and conditions: By signing up, you agree to the rules for participation and booking.</p>
                    <p class="button-container"><a href="/" title="View trips" class="button">View trips</a></p>
                    </div>
                </div>
            </div>
            <!-- End block HTML -->
        </div>
    </main>
    <footer/>
</body>
...

要查找需要装饰的 DOM，请在本地开发环境中打开包含该区块的页面，使用 Web 浏览器的开发人员工具选择该区块，并检查其 DOM 结构。这样您就可以识别出需要装饰的相关元素。

{align="center"}