Title: 属性
Author: Akira Tachibana
Published: 2020年6月20日
Last modified: 2025年9月13日

---

# 属性

## この投稿内

 * [タイプの検証](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#タイプの検証)
 * [enum の検証](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#enum-の検証)
 * [値のソース](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#値のソース)
    - [attribute ソース](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#attribute-ソース)
    - [text ソース](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#text-ソース)
    - [html ソース](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#html-ソース)
    - [query ソース](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#query-ソース)
    - [meta ソース (非推奨)](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#meta-ソース-非推奨)
 * [デフォルト値](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#デフォルト値)
 * [role](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#role)

[↑ ページの先頭へ戻る](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#wp--skip-link--target)

「ブロック属性」は、ブロックによって保存されるデータについての情報を提供します。
例えば、リッチコンテンツ、画像 URL のリスト、背景色、ボタンのタイトルなどです。

ブロックは任意の数の属性を含むことができ、属性は `attributes` フィールドで指定さ
れます。この `attributes` フィールドは、属性名をキー、属性定義を値にもつオブジェクト
です。

属性定義には、最低でも `type` または `enum` のいずれかが含まれ、オプションで追加
のフィールドを含みます。

_例_: 3つの属性 `url`、`title`、`size` を定義する属性オブジェクト

    ```notranslate
    {
    	url: {
    		type: 'string',
    		source: 'attribute',
    		selector: 'img',
    		attribute: 'src',
    	},
    	title: {
    		type: 'string',
    	},
    	size: {
    		enum: [ 'large', 'small' ],
    	},
    }
    ```

ブロックが解析される際、ブロックのコンテンツからデータを抽出するためにこの属性定義
が使用されます。合致するものはすべて、`attributes` prop を通してブロックで利用でき
ます。

解析プロセスは、以下のような流れになります。

 1. `source` から値を取り出す。
 2. 値が `type` と合致するかをチェックする。または、`enum` 値の一つであるかをチェック
    する。

_例_: 上の属性定義を使用して、`edit` や関数で利用される属性

    ```notranslate
    function YourBlockEdit( { attributes } ) {
    	return (
    		<p>URL is { attributes.url }, title is { attributes.title }, and size is { attributes.size }.</p>
    	)
    }
    ```

ブロックには、`save` 関数を使用して、`source` フィールドを持つすべての属性を、属性
定義に従って保存する責任があります。これは自動的には行われません。

一方、`source` のない属性は、自動的にブロックの[コメントデリミタ](https://ja.wordpress.org/team/handbook/block-editor/explanations/architecture/key-concepts#data-attributes)
に保存されます。

例えば、上の属性定義を使用する場合、`save` 関数で、`url` 属性に対応する img タグ
があることを確認する必要があります。一方、`title` と `size` 属性は、コメントデリミタ
に保存されます。

_例_: `url` 属性を含む、サンプルの `save` 関数

    ```notranslate
    function YourBlockSave( { attributes } ) {
    	return (
    		<img src={ attributes.url } />
    	)
    }
    ```

保存されたHTMLには、コメントデリミタに `title` と `size` が、`img` ノードに `url`
が含まれます。

    ```notranslate
    <!-- block:your-block {"title":"hello world","size":"large"} -->
    <img src="/image.jpg" />
    <!-- /block:your-block -->
    ```

属性が時間の経過とともに変化する場合は、[非推奨プロセス](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-deprecation/)
に従って、古い属性から移行するか、完全に削除できます。

## 󠀁[タイプの検証](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#タイプの検証)󠁿

`type` は属性に格納されているデータの種類を示します。`type` はデータがどこに保存
されているかは示しません。これは `source` フィールドによって定義されます。

`enum` が提供されない限り、`type` は必須です。`type` は `enum` と一緒に使用できます。

`type` フィールドは以下でなければなりません。

 * `null`
 * `boolean`
 * `object`
 * `array`
 * `string`
 * `integer`
 * `number` (`integer` と同じ)

`object` の検証は、`source` によって決定されることに注意してください。例として、
以下の「query」の詳細を参照してください。

## 󠀁[enum の検証](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#enum-の検証)󠁿

属性は固定された値のセットの一つとして定義できます。これには `enum` を指定し、許可
される値の配列を含めます。

_例_: `enum` の例

    ```notranslate
    {
    	size: {
    		enum: [ 'large', 'small', 'tiny' ]
    	}
    }
    ```

## 󠀁[値のソース](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#値のソース)󠁿

「属性ソース」は、保存された投稿コンテンツから、どのように属性値を取り出すかを定義
します。属性ソースは、保存されたマークアップから、ブロックのJavaScript表現にマッピング
するメカニズムを提供します。

可能な `source` の値は以下のとおりです。

値:

 * `(値なし)` – `source` が指定されていない場合、データはブロックの[コメントデリミタ](https://ja.wordpress.org/team/handbook/block-editor/explanations/architecture/key-concepts#data-attributes)
   に保存されます。
 * `attribute` – データは、HTML 要素の属性に保存されます。
 * `text` – データは、HTML テキストに保存されます。
 * `html` – データは、HTML に保存されます。この典型的な使用例は `RichText` です。
 * `query` – データは、オブジェクトの配列に保存されます。
 * `meta` – データは、投稿メタに保存されます (非推奨)。

`source`フィールドは通常、`selector` フィールドと組み合わせて使用します。`selector`
が指定されていない場合、ソース定義はブロックのルートノードに対して実行されます。`
selector` がある場合は、ブロック内の合致する要素に対して実行されます。

`selector`には、HTMLタグのほか、[querySelector](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector)
で問い合わせ可能なもの、たとえば class や id 属性などを指定できます。以下に例を示し
ます。

例えば、`img` の `selector` は `img` 要素に合致し、`img.class` は、クラス `class`
を持つ `img` 要素に合致します。

実装から見た場合、属性ソースは [hpq](https://github.com/aduth/hpq) によって提供さ
れる機能の上位セットとなる小さなライブラリーです。HTML マークアップを解析してオブジェクト
形式にクエリーします。

まとめると、`source` はコンテンツのどこにデータが保存されるかを決定し、`type` は
そのデータが何であるかを決定します。保存されるデータの量を減らすには、通常、できるだけ
多くのデータを、コメントデリミタ内の属性としてではなく、HTML 内に保存した方がよい
でしょう。

### 󠀁[attribute ソース](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#attribute-ソース)󠁿

マークアップ内の属性から値を取り出すには、`attribute` ソースを使用します。このとき、`
attribute` フィールドで指定される属性を必ず供給する必要があります。

_例_: ブロックのマークアップ内の画像から `src` 属性を取り出す。

保存されたコンテンツ:

    ```notranslate
    <div>
    	Block Content

    	<img src="https://lorempixel.com/1200/800/" />
    </div>
    ```

属性定義:

    ```notranslate
    {
    	url: {
    		type: 'string',
    		source: 'attribute',
    		selector: 'img',
    		attribute: 'src',
    	}
    }
    ```

ブロック内で利用可能な属性:

    ```notranslate
    { "url": "https://lorempixel.com/1200/800/" }
    ```

マークアップからのほとんどの属性のタイプは `string` です。HTML の数字の属性も文字
列として保存され、自動では変換されません。

_例_: ブロックのマークアップにある画像から `width` 属性を取り出す。

保存されたコンテンツ:

    ```notranslate
    <div>
    	Block Content

    	<img src="https://lorempixel.com/1200/800/" width="50" />
    </div>
    ```

属性定義:

    ```notranslate
    {
    	width: {
    		type: 'string',
    		source: 'attribute',
    		selector: 'img',
    		attribute: 'width',
    	}
    }
    ```

ブロック内で利用可能な属性:

    ```notranslate
    { "width": "50" }
    ```

例外は `button` の `disabled` 属性のような、属性の存在を確認する場合です。この場合
にはタイプ `boolean` を使用でき、保存した値も boolean になります。

_例_: ブロックのマークアップにあるボタンから、`disabled` 属性を取り出す。

保存されたコンテンツ:

    ```notranslate
    <div>
    	Block Content

    	<button type="button" disabled>Button</button>
    </div>
    ```

属性定義:

    ```notranslate
    {
    	disabled: {
    		type: 'boolean',
    		source: 'attribute',
    		selector: 'button',
    		attribute: 'disabled',
    	}
    }
    ```

ブロック内で利用可能な属性:

    ```notranslate
    { "disabled": true }
    ```

### 󠀁[text ソース](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#text-ソース)󠁿

マークアップから内部のテキストを取り出すには、`text` を使用します。注意: HTML は
[`textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent)
のルールに基づいて返されます。

_例_: ブロックのマークアップにある figcaption 要素から、`content` 属性を取り出す。

保存されたコンテンツ:

    ```notranslate
    <figure>
    	<img src="/image.jpg" />

    	<figcaption>The inner text of the figcaption element</figcaption>
    </figure>
    ```

属性定義:

    ```notranslate
    {
    	content: {
    		type: 'string',
    		source: 'text',
    		selector: 'figcaption',
    	}
    }
    ```

ブロック内で利用可能な属性:

    ```notranslate
    { "content": "The inner text of the figcaption element" }
    ```

次の例では source として `text`、selector として `.my-content` クラスを使用してテキスト
を抽出しています。

_例_: ブロックのマークアップにある `.my-content` クラス付きの要素から、`content`
属性を取り出す。

保存されたコンテンツ:

    ```notranslate
    <div>
    	<img src="/image.jpg" />

    	<p class="my-content">The inner text of .my-content class</p>
    </div>
    ```

属性定義:

    ```notranslate
    {
    	content: {
    		type: 'string',
    		source: 'text',
    		selector: '.my-content',
    	}
    }
    ```

ブロック内で利用可能な属性:

    ```notranslate
    { "content": "The inner text of .my-content class" }
    ```

### 󠀁[html ソース](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#html-ソース)󠁿

マークアップから内部の HTML を取り出すには、`html` を使用します。注意: テキストは
[`innerHTML`](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML)
のルールに基づいて返されます。

_例_: ブロックのマークアップにある figcaption 要素から `content` 属性を取り出す。

保存されたコンテンツ:

    ```notranslate
    <figure>
    	<img src="/image.jpg" />

    	<figcaption>The inner text of the <strong>figcaption</strong> element</figcaption>
    </figure>
    ```

属性定義:

    ```notranslate
    {
    	content: {
    		type: 'string',
    		source: 'html',
    		selector: 'figcaption',
    	}
    }
    ```

ブロック内で利用可能な属性:

    ```notranslate
    { "content": "The inner text of the <strong>figcaption</strong> element" }
    ```

### 󠀁[query ソース](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#query-ソース)󠁿

マークアップから値の配列を取り出すには `query` を使用します。配列のエントリーは `
selector` 引数によって決定されます。このとき、ブロック内で合致した各要素は、2番目
の引数である属性ソースのオブジェクトに対応するエントリー構造を持ちます。

`query`フィールドは、事実上、ネストされたブロック属性定義です。必ずしも推奨はしま
せんが、さらに入れ子にすることも可能です。

_例_: ブロックのマークアップ内の各画像要素から `src` と `alt` を取り出す。

保存されたコンテンツ:

    ```notranslate
    <div>
    	<img src="https://lorempixel.com/1200/800/" alt="large image" />
    	<img src="https://lorempixel.com/50/50/" alt="small image" />
    </div>
    ```

属性定義:

    ```notranslate
    {
    	images: {
    		type: 'array',
    		source: 'query',
    		selector: 'img',
    		query: {
    			url: {
    				type: 'string',
    				source: 'attribute',
    				attribute: 'src',
    			},
    			alt: {
    				type: 'string',
    				source: 'attribute',
    				attribute: 'alt',
    			},
    		}
    	}
    }
    ```

ブロック内で利用可能な属性:

    ```notranslate
    {
    	"images": [
    		{ "url": "https://lorempixel.com/1200/800/", "alt": "large image" },
    		{ "url": "https://lorempixel.com/50/50/", "alt": "small image" }
    	]
    }
    ```

### 󠀁[meta ソース (非推奨)](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#meta-ソース-非推奨)󠁿

**注意**
投稿の meta から属性を取得できますが、meta 属性ソースは非推奨です。代わり
に [EntityProvider と関連するフック API](https://github.com/WordPress/gutenberg/blob/c367c4e2765f9e6b890d1565db770147efca5d66/packages/core-data/src/entity-provider.js)
を使用してください。「[メタブロックの作成](https://ja.wordpress.org/team/handbook/block-editor/how-to-guides/metabox/#step-2-add-meta-block)」
も参照してください。

属性は保存された投稿コンテンツ内のブロック表現からだけでなく、投稿のメタ情報から
も取り出すこともできます。このとき属性は 対応するメタキーを `meta` キーに指定する
必要があります。

属性定義:

    ```notranslate
    {
    	author: {
    		type: 'string',
    		source: 'meta',
    		meta: 'author'
    	},
    },
    ```

メタ属性は任意の属性と同じインターフェースを使用してブロックから読み書きできます。

    ```notranslate
    edit( { attributes, setAttributes } ) {
    	function onChange( event ) {
    		setAttributes( { author: event.target.value } );
    	}

    	return <input value={ attributes.author } onChange={ onChange } type="text" />;
    },
    ```

#### 󠀁[考慮点](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#考慮点)󠁿

デフォルトではメタフィールドは投稿オブジェクトのメタから除外されます。これを回避
するにはフィールドを明示的に見えるようにします。

    ```notranslate
    function gutenberg_my_block_init() {
    	register_post_meta( 'post', 'author', array(
    		'show_in_rest' => true,
    	) );
    }
    add_action( 'init', 'gutenberg_my_block_init' );
    ```

さらに WordPress のデフォルトに注意してください。

 * 1つのメタデータを単一として扱わず、代わりに値の配列を返します。
 * データを文字列として扱います。

どちらの動きも希望しない場合には、同じ `register_post_meta` を `single` かつまたは`
type` パラメータを指定して呼び出します。

    ```notranslate
    function gutenberg_my_block_init() {
    	register_post_meta( 'post', 'author_count', array(
    		'show_in_rest' => true,
    		'single' => true,
    		'type' => 'integer',
    	) );
    }
    add_action( 'init', 'gutenberg_my_block_init' );
    ```

引数にオブジェクトまたは配列を使用したい場合には `string` 属性タイプを登録し JSON
を中継役に使用します。まず構造化データを JSON にシリアライズして保存し、サーバー
側で JSON 文字列をデシリアライズします。このときデータの整合性に責任があることに
注意してください。適切なサニタイズや失われたデータの調節などが必要です。

最後に属性を設定する差にはデータのタイプを尊重してください。なぜならフレームワーク
は自動でメタの型変換を実行しないためです。ブロック属性の誤った型は保存した後も投稿
を dirty のままにします (_参照_ `isEditedPostDirty`、`hasEditedAttributes`)。たとえば`
authorCount` が integer なら、イベントハンドラは異なる種類のdataを渡す可能性がある
ため、値を明示的に型変換する必要があります。

    ```notranslate
    function onChange( event ) {
    	props.setAttributes( { authorCount: Number( event.target.value ) } );
    }
    ```

## 󠀁[デフォルト値](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#デフォルト値)󠁿

ブロック属性にはデフォルト値を持てます。`type` と `source` がブロックコンテンツ内
のいずれにも合致しない場合に使用されます。

値は `default` フィールドで提供され、この値は属性に期待されるフォーマットと合致する
必要があります。

_例_: `default` 値の例

    ```notranslate
    {
    	type: 'string',
    	default: 'hello world'
    }
    ```

    ```notranslate
    {
    	type: 'array',
    	default: [
    		{ "url": "https://lorempixel.com/1200/800/", "alt": "large image" },
        	{ "url": "https://lorempixel.com/50/50/", "alt": "small image" }
    	]
    }
    ```

    ```notranslate
    {
    	type: 'object',
    	default: {
    		width: 100,
    		title: 'title'
    	}
    }
    ```

## 󠀁[role](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-attributes/?output_format=md#role)󠁿

`role` プロパティは、属性に特定の概念タイプを指定します。このプロパティは任意の属性
に適用でき、属性の処理についてセマンティックな意味を付与します。

`content` は、属性をユーザーが編集可能なコンテンツとして指定します。`content` と
マークした属性を持つブロックは、コンテンツのみがロックされた場合などの特別な状況
において、特権的な編集を有効化される可能性があります。

`local` は、属性を一時的で永続化不可としてマークします。`local` とマークした属性
は、ブロックシリアライザーによって無視され、投稿コンテンツには保存されません。

_例_: 段落ブロックに使用した `content` ロール

    ```notranslate
    {
        content: {
            type: 'string',
            source: 'html',
            selector: 'p',
            role: 'content',
        }
    }
    ```

_例_: 一時的なデータに使用した `local` ロール。

    ```notranslate
    {
        blob: {
            type: 'string',
            role: 'local',
        }
    }
    ```

詳細については [WordPress 6.7 dev note](https://make.wordpress.org/core/2024/10/20/miscellaneous-block-editor-changes-in-wordpress-6-7/#stabilized-role-property-for-block-attributes)
を参照してください。

[原文](https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/block-api/block-attributes.md)

公開日

2020年6月20日

最終更新

2025年9月13日

[  前へ: Migrating Blocks for iframe Editor Compatibility](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-api-versions/block-migration-for-iframe-editor-compatibility/)

[  次へ: Bindings](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/block-api/block-bindings/)