WP_Block_List
云策文档标注
概述
WP_Block_List 是 WordPress 5.5.0 引入的类，用于表示块实例的列表。它实现了 Iterator、ArrayAccess 和 Countable 接口，提供对块数据的迭代、数组式访问和计数功能。
关键要点
- WP_Block_List 类用于管理块实例列表，支持通过数组索引或迭代器方式操作块。
- 构造函数接受块数据数组、可用上下文和块类型注册表参数，自动初始化内部属性。
- 实现了 ArrayAccess 接口的方法（offsetExists、offsetGet、offsetSet、offsetUnset），允许像数组一样访问和修改块。
- 实现了 Iterator 接口的方法（rewind、current、key、next、valid），支持遍历块列表。
- 实现了 Countable 接口的 count 方法，返回列表中块的数量。
- 在 offsetGet 方法中，如果块数据是数组，会自动转换为 WP_Block 实例并缓存，提高性能。
原文内容
Class representing a list of block instances.
Methods
Source
class WP_Block_List implements Iterator, ArrayAccess, Countable {
/**
* Original array of parsed block data, or block instances.
*
* @since 5.5.0
* @var array[]|WP_Block[]
*/
protected $blocks;
/**
* All available context of the current hierarchy.
*
* @since 5.5.0
* @var array
*/
protected $available_context;
/**
* Block type registry to use in constructing block instances.
*
* @since 5.5.0
* @var WP_Block_Type_Registry
*/
protected $registry;
/**
* Constructor.
*
* Populates object properties from the provided block instance argument.
*
* @since 5.5.0
*
* @param array[]|WP_Block[] $blocks Array of parsed block data, or block instances.
* @param array $available_context Optional array of ancestry context values.
* @param WP_Block_Type_Registry $registry Optional block type registry.
*/
public function __construct( $blocks, $available_context = array(), $registry = null ) {
if ( ! $registry instanceof WP_Block_Type_Registry ) {
$registry = WP_Block_Type_Registry::get_instance();
}
$this->blocks = $blocks;
$this->available_context = $available_context;
$this->registry = $registry;
}
/**
* Returns true if a block exists by the specified block offset, or false
* otherwise.
*
* @since 5.5.0
*
* @link https://www.php.net/manual/en/arrayaccess.offsetexists.php
*
* @param int $offset Offset of block to check for.
* @return bool Whether block exists.
*/
#[ReturnTypeWillChange]
public function offsetExists( $offset ) {
return isset( $this->blocks[ $offset ] );
}
/**
* Returns the value by the specified block offset.
*
* @since 5.5.0
*
* @link https://www.php.net/manual/en/arrayaccess.offsetget.php
*
* @param int $offset Offset of block value to retrieve.
* @return WP_Block|null Block value if exists, or null.
*/
#[ReturnTypeWillChange]
public function offsetGet( $offset ) {
$block = $this->blocks[ $offset ];
if ( isset( $block ) && is_array( $block ) ) {
$block = new WP_Block( $block, $this->available_context, $this->registry );
$this->blocks[ $offset ] = $block;
}
return $block;
}
/**
* Assign a block value by the specified block offset.
*
* @since 5.5.0
*
* @link https://www.php.net/manual/en/arrayaccess.offsetset.php
*
* @param int $offset Offset of block value to set.
* @param array|WP_Block $value Block value.
*/
#[ReturnTypeWillChange]
public function offsetSet( $offset, $value ) {
if ( is_null( $offset ) ) {
$this->blocks[] = $value;
} else {
$this->blocks[ $offset ] = $value;
}
}
/**
* Unset a block.
*
* @since 5.5.0
*
* @link https://www.php.net/manual/en/arrayaccess.offsetunset.php
*
* @param int $offset Offset of block value to unset.
*/
#[ReturnTypeWillChange]
public function offsetUnset( $offset ) {
unset( $this->blocks[ $offset ] );
}
/**
* Rewinds back to the first element of the Iterator.
*
* @since 5.5.0
*
* @link https://www.php.net/manual/en/iterator.rewind.php
*/
#[ReturnTypeWillChange]
public function rewind() {
reset( $this->blocks );
}
/**
* Returns the current element of the block list.
*
* @since 5.5.0
*
* @link https://www.php.net/manual/en/iterator.current.php
*
* @return WP_Block|null Current element.
*/
#[ReturnTypeWillChange]
public function current() {
return $this->offsetGet( $this->key() );
}
/**
* Returns the key of the current element of the block list.
*
* @since 5.5.0
*
* @link https://www.php.net/manual/en/iterator.key.php
*
* @return int|null Key of the current element.
*/
#[ReturnTypeWillChange]
public function key() {
return key( $this->blocks );
}
/**
* Moves the current position of the block list to the next element.
*
* @since 5.5.0
*
* @link https://www.php.net/manual/en/iterator.next.php
*/
#[ReturnTypeWillChange]
public function next() {
next( $this->blocks );
}
/**
* Checks if current position is valid.
*
* @since 5.5.0
*
* @link https://www.php.net/manual/en/iterator.valid.php
*/
#[ReturnTypeWillChange]
public function valid() {
return null !== key( $this->blocks );
}
/**
* Returns the count of blocks in the list.
*
* @since 5.5.0
*
* @link https://www.php.net/manual/en/countable.count.php
*
* @return int Block count.
*/
#[ReturnTypeWillChange]
public function count() {
return count( $this->blocks );
}
}
Changelog
| Version | Description |
|---|---|
| 5.5.0 | Introduced. |