サポート

ブロックは「ブロックサポート」API を使用してエディター内で使用する機能を宣言できます。

anchor や className などいくつかのブロックサポートは属性を適用する場合に save から返される要素に追加の props を加えます。div などのデフォルトの HTML タグ要素であればこれは自動的に動作しますが、save の戻り値がカスタムコンポーネント要素の場合、属性が永続化されるようカスタムコンポーネントがこれらの props を処理する必要があります。

anchor

• タイプ: boolean
• デフォルト値: false

アンカーを使用するとページ上の特定のブロックに直接リンクできます。このプロパティはブロックの ID を定義するフィールドと、ダイレクトリンクをコピーするボタンをを追加します。

// アンカーリンクのサポートを宣言
supports: {
    anchor: true
}

align

• タイプ: boolean または array
• デフォルト値: false

このプロパティはブロックの配置を変更するブロックコントロールを追加します。重要: ダイナミックブロックでは、まだ動作しません。

supports: {
    // ブロックの配置のサポートを宣言
    // すべてのオプションのサポートを追加
    // left (左寄せ), center (中央寄せ), right (右寄せ), wide (幅広), full (全幅)
    align: true
}

supports: {
    // 特定の配置のオプションのサポートを宣言
    align: [ 'left', 'right', 'full' ]
}

ブロックが align サポートを宣言するとブロック属性定義が拡張され、string タイプの align 属性が含まれます。デフォルトでは配置は割り当てられません。ブロックにデフォルトの配置を適用するには、デフォルト値と共に align 属性を指定します。たとえば

attributes: {
    align: {
        type: 'string',
        default: 'right'
    }
}

alignWide

• タイプ: boolean
• デフォルト値: true

このプロパティを使用するとテーマの 幅広揃え を有効化できます。単一ブロックに対してこの機能を無効化するにはこのフラグに false を設定してください。

supports: {
    // 幅広揃えサポートを除去
    alignWide: false
}

className

• タイプ: boolean
• デフォルト値: true

デフォルトでは保存したマークアップの root 要素にクラス .wp-block-your-block-name が追加されます。この結果、テーマやプラグインがブロックをスタイリングする際に利用可能な一貫した機構が実現します。何らかの理由によりこのクラスをマークアップに付加したくない場合、この機能を無効化できます。

supports: {
    // className 生成サポートを除去
    className: false
}

color

• タイプ: Object
• デフォルト値: null
• サブプロパティ:
  • background: タイプ boolean, デフォルト値 true
  • __experimentalDuotone: タイプ string, デフォルト値なし
  • gradients: タイプ boolean, デフォルト値 false
  • link: タイプ boolean, デフォルト値 false
  • text: タイプ boolean, デフォルト値 true

この値はブロックが色に関連するプロパティをサポートすることを通知します。サポートする場合、ブロックエディターはユーザーがプロパティ値を設定できる UI コントロールを表示します。

注意: background キーとtext キーのデフォルト値は true です。color プロパティを宣言するとこれらも有効化されます。

supports: {
    color: { // 同時にテキスト UI コントロールと背景 UI コントロールも有効化
        gradients: true // グラデーション UI コントロールを有効化
    }
}

これらは個別に無効化できます。

supports: {
    color: { // テキスト UI コントロールは有効
        background: false, // 背景 UI コントロールを無効化
        gradients: true // グラデーション UI コントロールを有効化
    }
}

color.background

このプロパティは UI コントロールを追加します。ユーザーは UI コントロールを使用してブロックに背景色を適用できます。

color サポートを宣言すると、background プロパティは text プロパティと共に自動で有効化されます。このため単に color を設定すれば、背景色は有効化されます。

supports: {
    color: true // background と text の両方を有効化
}

他の color サポートは有効化しながら background サポートを無効化するには、false を設定します。

supports: {
    color: {
        // background サポートを無効化。テキスト色のサポートは引き続き有効
        background: false
    }
}

ブロックが color.background のサポートを宣言すると、属性定義が拡張され、2つの新しい属性 backgroundColor と style が含まれます。

• backgroundColor: タイプ string の属性。デフォルト値なし。

プリセットのリストからユーザーが背景色を選択すると、プリセットのスラッグが backgroundColor 属性に保存されます。

背景色プリセットは editor-color-palette テーマサポート がソースです。

ブロックはデフォルトのプリセット背景色を適用できます。これには 自身の属性に default で指定します。

attributes: {
    backgroundColor: {
        type: 'string',
        default: 'some-preset-background-slug',
    }
}

• style: タイプ object の属性。デフォルト値なし。

カスタムカラーピッカーを使用するなどして、カスタム背景色を選択すると、カスタムカラー値が style.color.background 属性に保存されます。

ブロックはデフォルトのカスタム背景色を適用できます。これには 自身の属性に default で指定します。

attributes: {
    style: {
        type: 'object',
        default: {
            color: {
                background: '#aabbcc',
            }
        }
    }
}

color.__experimentalDuotone

このプロパティは UI コントロールを追加します。ブロック、またはブロックの一部にデュオトーンフィルターを適用できます。

親のセレクタが、Sass/SCSS でのネストのように自動で追加されます (しかし、& セレクタはサポートされません)。

supports: {
    color: {
        // edit と save 両方の同じセレクタにフィルターを適用する。
        __experimentalDuotone: '> .duotone-img, > .duotone-video',

        // デュオトーンと一緒にデフォルト値を使いたくない場合は、無効化する必要がある
        background: false,
        text: false
    }
}

デュオトーンプリセットは、theme.json の color.duotone がソースです。

ブロックが color.__experimentalDuotone のサポートを宣言すると、属性定義が拡張され、属性 style が含まれます。

• style: タイプ object の属性。デフォルト値なし。

ブロックはデフォルトのデュオトーンカラーを適用できます。これには 自身の属性に default で指定します。

attributes: {
    style: {
        type: 'object',
        default: {
            color: {
                duotone: [
                    '#FFF',
                    '#000'
                ]
            }
        }
    }
}

color.gradients

このプロパティは UI コントロールを追加します。ユーザーは UI コントロールを使用して、ブロックにグラデーション背景を適用できます。

supports: {
    color: {
        gradient: true,

        // グラデーションと一緒にデフォルト値を使いたくない場合は、無効化する必要がある
        background: false,
        text: false
    }
}

グラデーションプリセットは editor-gradient-presets テーマサポート がソースです。

ブロックが color.gradient のサポートを宣言すると、属性定義が拡張され、2つの新しい属性 gradient と style が含まれます。

• gradient: タイプ string の属性。デフォルト値なし。

プリセットのリストからユーザーがグラデーションを選択すると、プリセットのスラッグが gradient 属性に保存されます。

ブロックはデフォルトのグラデーションプリセットを適用できます。これには 自身の属性に default で指定します。

attributes: {
    gradient: {
        type: 'string',
        default: 'some-preset-gradient-slug',
    }
}

• style: タイプ object の属性。デフォルト値なし。

カスタムグラデーションピッカーを使用するなどして、カスタムグラデーションを選択すると、カスタムグラデーション値が style.color.gradient 属性に保存されます。

ブロックはデフォルトのカスタムグラデーションを適用できます。これには 自身の属性に default で指定します。

attributes: {
    style: {
        type: 'object',
        default: {
            color: {
                background: 'linear-gradient(135deg,rgb(170,187,204) 0%,rgb(17,34,51) 100%)',
            }
        }
    }
}

color.link

このプロパティは、ユーザーがブロック内のリンクの色を設定できるブロックコントロールを追加します。デフォルトではリンクの色は無効です。

supports: {
    color: true // Enables only background and text
}

リンクの色のサポートを有効にするには、true に設定します。

supports: {
    color: {
        link: true
    }
}

リンクの色のプリセットは、editor-color-palette テーマサポートをソースとしています。

ブロックが color.link のサポートを宣言すると、属性定義が拡張され、2つの新しい属性 linkColor と style が追加されます。

• linkColor: string 型の属性で、デフォルトは割り当てられていません。

ユーザーがプリセットのリンクの色のリストから選択すると、プリセットのスラッグが linkColor 属性に格納されます。

ブロックにデフォルトのプリセットのテキスト色を適用するには、自身の属性にデフォルトを指定します。例:

attributes: {
    linkColor: {
        type: 'string',
        default: 'some-preset-link-color-slug',
    }
}

• style: object 型の属性で、デフォルトは割り当てられていません。

カスタム色ピッカーを使用するなどして、カスタムリンクの色が選択されると、カスタム色の値が style.color.link 属性に格納されます。

ブロックにデフォルトのカスタムリンクの色を適用するには、自身の属性をデフォルトで指定します。

attributes: {
    style: {
        type: 'object',
        default: {
            color: {
                link: '#ff0000',
            }
        }
    }
}

color.text

このプロパティはブロックコントロールを追加します。ユーザーはブロックコントロールを使用してブロックのテキスト色を設定できます。

color サポートを宣言すると、text プロパティは background プロパティと共に自動で有効化されます。このため単に color を設定すれば、テキスト色は有効化されます。

supports: {
    color: true // background と text を有効化。link は有効化しない。
}

他の color サポートは有効化しながら text サポートを無効化するには、false を設定します。

supports: {
    color: {
        // text サポートを無効化。
        text: false
    }
}

テキスト色プリセットは editor-color-palette テーマサポート がソースです。

ブロックが color.text のサポートを宣言すると、属性定義が拡張され、2つの新しい属性 textColor と style が含まれます。

• textColor: タイプ string の属性。デフォルト値なし。

プリセットのリストからユーザーがテキスト色を選択すると、プリセットのスラッグが textColor 属性に保存されます。

ブロックはデフォルトのプリセットテキスト色を適用できます。これには 自身の属性に default で指定します。

attributes: {
    textColor: {
        type: 'string',
        default: 'some-preset-text-color-slug',
    }
}

• style: タイプ object の属性。デフォルト値なし。

カスタムカラーピッカーを使用するなどして、カスタムテキスト色を選択すると、カスタムカラー値が style.color.gradient 属性に保存されます。

ブロックはデフォルトのカスタムテキスト色を適用できます。これには 自身の属性に default で指定します。

attributes: {
    style: {
        type: 'object',
        default: {
            color: {
                text: '#aabbcc',
            }
        }
    }
}

customClassName

• タイプ: boolean
• デフォルト値: true

このプロパティはブロックのラッパーのカスタム classsName を定義するフィールドを追加します。

supports: {
    // カスタム className サポートを除去
    customClassName: false
}

defaultStylePicker

• タイプ: boolean
• デフォルト値: true

スタイルピッカーの表示の際、ユーザーがブロックタイプのデフォルトスタイルを選択できるようドロップダウンが表示されます。ドロップダウンを表示したくない場合にはこのプロパティを false に設定してください。

supports: {
    // デフォルトのスタイルピッカーを除去
    defaultStylePicker: false
}

fontSize

• タイプ: boolean
• デフォルト値: false

この値はブロックが font-size CSS スタイルプロパティをサポートすることを通知します。サポートする場合、ブロックエディターはユーザーがプロパティ値を設定できる UI コントロールを表示します。

このコントロール内に表示される値は editor-font-sizes テーマサポート でテーマが宣言したもの、または指定がなければデフォルトのものになります。

supports: {
    // font-size UI コントールの有効化
    fontSize: true,
}

ブロックが fontSize サポートを宣言すると、attributes の定義も新しい属性 fontSize と style を含むよう拡張されます。

• fontSize: string タイプの属性で、デフォルトの割り当てはありません。ユーザーによるプリセットした値のセットを保存します。ブロックは自身の fontSize 属性とデフォルトを指定することで、デフォルトの fontSize を適用できます。

attributes: {
    fontSize: {
        type: 'string',
        default: 'some-value',
    }
}

• style: object タイプの属性で、デフォルトの割り当てはありません。ユーザーによるプリセットした値のセットを保存します。ブロックは自身の style 属性とデフォルトを指定することで、デフォルトのスタイルを適用できます。

attributes: {
    style: {
        type: 'object',
        default: {
            typography: {
                fontSize: 'value'
            }
        }
    }
}

html

• タイプ: boolean
• デフォルト値: true

デフォルトではブロックのマークアップは個別に編集できます。この動きを止めるには html に false を設定してください。

supports: {
    // HTML モードサポートを除去
    html: false
}

inserter

• タイプ: boolean
• デフォルト値: true

デフォルトではすべてのブロックはインサーターに表示されます。ブロックをインサーターには表示せず、プログラム的にのみ挿入可能にするには inserter に false を設定してください。

supports: {
    // このブロックをインサーターに表示しない
    inserter: false
}

lineHeight

• タイプ: boolean
• デフォルト値: false

この値はブロックが line-height CSS スタイルプロパティをサポートすることを通知します。サポートする場合、テーマがサポートを宣言するなら、ブロックエディターはユーザーがプロパティ値を設定できる UI コントロールを表示します。

supports: {
    // line-height の UI コントロールを有効化
    lineHeight: true,
}

When the block declares support for lineHeight, the attributes definition is extended to include a new attribute style of object type with no default assigned. It stores the custom value set by the user. The block can apply a default style by specifying its own style attribute with a default e.g.:

ブロックが lineHeight プロパティのサポートを宣言すると、attributes の定義も新しい属性 style を含むよう拡張されます。style は obuject タイプの属性で、デフォルトの割り当てはありません。ユーザーによるプリセットした値のセットを保存します。ブロックは自身の style 属性とデフォルトを指定することで、デフォルトの style を適用できます。

attributes: {
    style: {
        type: 'object',
        default: {
            typography: {
                lineHeight: 'value'
            }
        }
    }
}

multiple

• タイプ: boolean
• デフォルト値: true

非 multiple ブロックは各投稿に1回だけ挿入できます。たとえば組み込みの「続きを読む」ブロックは、編集中の投稿にすでに存在する場合は挿入できません。非 multiple ブロックのアイコンはクリックできないよう自動的にグレイアウトされ、複数インスタンスの作成を回避します。

supports: {
    // ブロックは投稿ごとに1度だけ使用できる
    multiple: false
}

reusable

• タイプ: boolean
• デフォルト値: true

ブロックを再利用可能なブロックに変換する機能を無効化したい場合があります。デフォルトではすべてのブロックは再利用可能ブロックに変換できます。reusable サポートを false に設定すると、再利用可能ブロックするに変換するオプションが表示されません。

supports: {
    // 再利用可能ブロックへの変換を許可しない
    reusable: false
}

spacing

• タイプ: Object
• デフォルト値: null
• サブプロパティ:
  • margin: タイプ boolean または array, デフォルト値 false
  • padding: タイプ boolean または array, デフォルト値 false

この値はブロックがスペースに関連する CSS スタイルプロパティをサポートすることを通知します。テーマがサポートを宣言するなら、ブロックエディターはユーザーがプロパティ値を設定できる UI コントロールを表示します。

supports: {
    spacing: {
        margin: true,  // margin UI コントロールを有効化
        padding: true, // padding UI コントロールを有効化
}

ブロックが spacing プロパティのサポートを宣言すると、attributes の定義も style 属性を含むよう拡張されます。

• style: デフォルトの割り当てのない object タイプの属性。margin または padding サポートを宣言すると追加されます。ユーザーによるカスタム値のセットを保存します。

supports: {
    spacing: {
        margin: [ 'top', 'bottom' ], // 任意のサイドのマージンを有効化する。
        padding: true,               // すべてのサイドのパディングを有効化する。
    }
}

spacing プロパティは構成可能なサイドの配列を定義することもできます。任意のサイドが UI コントロールに定義されると、そのサイドが表示されます。

原文

最終更新日: 2021年7月2日