README

ACF Composer 是使用 ACF Builder 和 Sage 10 创建字段、区块、小部件和选项页面的终极工具。

功能

🔧 鼓励使用 Sage 10 和 ACF 创建字段的清晰结构。
🚀 使用 CLI 立即生成可用的字段、区块、小部件、部分和选项页面。电池已包含在内。
🖼️ 使用 Blade 完全渲染的区块和小部件，具有原生 Sage 10 风格，以传递视图数据。
⚡ 无缝将区块缓存到 block.json，将字段组缓存到清单中。
📦 自动将旧版小部件与 WP_Widget 钩子连接，使其立即可使用。
🛠️ 自动设置区块、小部件和选项页面上的字段位置。
🌐 全局定义默认字段类型和字段组设置。不再需要在每个选择字段上重复 ['ui' => 1]。

要求

Sage >= 10.0
Acorn >= 3.0
ACF Pro >= 5.8.0

安装

通过 Composer 安装

$ composer require log1x/acf-composer

用法

入门

首先，使用 Acorn 发布 config/acf.php 配置文件

$ wp acorn vendor:publish --tag="acf-composer"

生成字段组

要创建第一个字段组，请从主题目录运行以下生成器命令

$ wp acorn acf:field ExampleField

这将创建 src/Fields/ExampleField.php，您将在其中创建和管理第一个字段组。

查看生成的 ExampleField.php 模板，您会注意到它有一个简单的列表配置。

<?php

namespace App\Fields;

use Log1x\AcfComposer\Builder;
use Log1x\AcfComposer\Field;

class ExampleField extends Field
{
    /**
     * The field group.
     *
     * @return array
     */
    public function fields()
    {
        $fields = Builder::make('example_field');

        $fields
            ->setLocation('post_type', '==', 'post');

        $fields
            ->addRepeater('items')
                ->addText('item')
            ->endRepeater();

        return $fields->build();
    }
}

接下来，检查字段的 添加帖子，以确保一切按预期工作 - 然后开始工作。

生成字段部分

字段部分由可以重用和/或添加到现有字段组的字段组组成。

首先，让我们生成一个名为 ListItems 的部分，我们可以在上面生成的 Example 字段中使用它。

$ wp acorn acf:partial ListItems

<?php

namespace App\Fields\Partials;

use Log1x\AcfComposer\Builder;
use Log1x\AcfComposer\Partial;

class ListItems extends Partial
{
    /**
     * The partial field group.
     *
     * @return array
     */
    public function fields()
    {
        $fields = Builder::make('listItems');

        $fields
            ->addRepeater('items')
                ->addText('item')
            ->endRepeater();

        return $fields;
    }
}

查看 ListItems.php，您会看到它默认包含与您的生成字段中相同的列表重复器。

与普通字段相比的一个关键区别是省略了 ->build()，而是返回 FieldsBuilder 实例本身。

这可以通过将 ::class 常量传递给 ->addPartial() 在我们的 Example 字段中使用。

<?php

namespace App\Fields;

use App\Fields\Partials\ListItems;
use Log1x\AcfComposer\Builder;
use Log1x\AcfComposer\Field;

class Example extends Field
{
    /**
     * The field group.
     *
     * @return array
     */
    public function fields()
    {
        $fields = Builder::make('example');

        $fields
            ->setLocation('post_type', '==', 'post');

        $fields
            ->addPartial(ListItems::class);

        return $fields->build();
    }
}

生成区块

生成区块通常与上述字段生成相同。

首先，使用 Acorn 创建区块字段

$ wp acorn acf:block ExampleBlock

<?php

namespace App\Blocks;

use Log1x\AcfComposer\Block;
use Log1x\AcfComposer\Builder;

class ExampleBlock extends Block
{
    /**
     * The block name.
     *
     * @var string
     */
    public $name = 'Example Block';

    /**
     * The block description.
     *
     * @var string
     */
    public $description = 'Lorem ipsum...';

    /**
     * The block category.
     *
     * @var string
     */
    public $category = 'common';

    /**
     * The block icon.
     *
     * @var string|array
     */
    public $icon = 'star-half';

    /**
     * Data to be passed to the block before rendering.
     *
     * @return array
     */
    public function with()
    {
        return [
            'items' => $this->items(),
        ];
    }

    /**
     * The block field group.
     *
     * @return array
     */
    public function fields()
    {
        $fields = Builder::make('example_block');

        $fields
            ->addRepeater('items')
                ->addText('item')
            ->endRepeater();

        return $fields->build();
    }

    /**
     * Return the items field.
     *
     * @return array
     */
    public function items()
    {
        return get_field('items') ?: [];
    }
}

您还可以向上述命令传递 --construct 以生成在 attributes 方法中设置区块属性的模板。这可以用于本地化等。

$ wp acorn acf:block Example --construct

当运行区块生成器时，与通用字段相比的一个区别是在 resources/views/blocks 目录中生成了一个相应的 View。

@if ($items)
  <ul>
    @foreach ($items as $item)
      <li>{{ $item['item'] }}</li>
    @endforeach
  </ul>
@else
  <p>No items found!</p>
@endif

<div>
  <InnerBlocks />
</div>

与字段生成器一样，示例区块包含一个简单的列表重复器，并且默认即可使用。

区块预览视图

虽然 $block->preview 是一个在编辑器中显示时条件修改您区块的选项，您还可以使用单独的视图来渲染您的区块。

只需复制您现有的视图，并在其前面加上 preview- 前缀（例如，preview-example.blade.php）。

生成小工具

重要

从 WordPress 5.8 版本开始，区块现在可以用作小工具，这使得此功能变得有些过时，因为您只需创建一个区块即可。

如果您使用的是最新版本的 WordPress 并且希望使用 ACF Composer 的经典小工具功能，您需要退出小工具区块编辑器。

使用 ACF Composer 创建侧边栏小工具非常简单。小工具会自动加载和渲染，并使用 Blade，同时也会注册 WP_Widget，这通常很烦人。

首先使用 Acorn 创建一个小工具

$ wp acorn acf:widget ExampleWidget

<?php

namespace App\Widgets;

use Log1x\AcfComposer\Builder;
use Log1x\AcfComposer\Widget;

class ExampleWidget extends Widget
{
    /**
     * The widget name.
     *
     * @var string
     */
    public $name = 'Example Widget';

    /**
     * The widget description.
     *
     * @var string
     */
    public $description = 'Lorem ipsum...';

    /**
     * Data to be passed to the widget before rendering.
     *
     * @return array
     */
    public function with()
    {
        return [
            'items' => $this->items(),
        ];
    }

    /**
     * The widget title.
     *
     * @return string
     */
    public function title() {
        return get_field('title', $this->widget->id);
    }

    /**
     * The widget field group.
     *
     * @return array
     */
    public function fields()
    {
        $fields = Builder::make('example_widget');

        $fields
            ->addText('title');

        $fields
            ->addRepeater('items')
                ->addText('item')
            ->endRepeater();

        return $fields->build();
    }

    /**
     * Return the items field.
     *
     * @return array
     */
    public function items()
    {
        return get_field('items', $this->widget->id) ?: [];
    }
}

与区块类似，小工具也有一个在 resources/views/widgets 中生成的视图。

@if ($items)
  <ul>
    @foreach ($items as $item)
      <li>{{ $item['item'] }}</li>
    @endforeach
  </ul>
@else
  <p>No items found!</p>
@endif

默认情况下，Example 小工具已经准备好，应该会出现在后端。

生成选项页面

创建一个选项页面类似于创建一个常规的字段组，另外还有一些可用于自定义页面（其中大部分是可选的）的配置选项。

首先使用 Acorn 创建一个选项页面

$ wp acorn acf:options ExampleOptions

<?php

namespace App\Options;

use Log1x\AcfComposer\Builder;
use Log1x\AcfComposer\Options as Field;

class ExampleOptions extends Field
{
    /**
     * The option page menu name.
     *
     * @var string
     */
    public $name = 'Example Options';

    /**
     * The option page document title.
     *
     * @var string
     */
    public $title = 'Example Options | Options';

    /**
     * The option page field group.
     *
     * @return array
     */
    public function fields()
    {
        $fields = Builder::make('example_options');

        $fields
            ->addRepeater('items')
                ->addText('item')
            ->endRepeater();

        return $fields->build();
    }
}

可选地，您可以将 --full 传递给上述命令以生成包含额外配置示例的存根。

$ wp acorn acf:options Options --full

完成后，您应该会在后端看到一个选项页面。

注册的所有字段都将自动将其位置设置为该页面。

缓存区块与字段

从 v3 版本开始，ACF Composer 现在可以使用 CLI 自动将注册的区块缓存到本地的 block.json 文件，并将字段组缓存到一个平面文件 JSON 清单中。

这可以显著提高项目（无论大小）的性能，尤其是在加载包含多个自定义区块的帖子时。

注意

一旦缓存，对区块或字段的更改将不会生效，直到清除或重新缓存。

最佳操作时间是在部署期间，可以使用 acf:cache 命令完成。

$ wp acorn acf:cache [--status]

可以使用 acf:clear 命令清除缓存

$ wp acorn acf:clear

如上所述，可以使用 acf:cache --status 中的 --status 或运行 wp acorn about 来查找 ACF Composer 缓存状态。

自定义存根生成

要自定义 ACF Composer 生成的存根，您可以使用 Acorn轻松发布 stubs 目录

$ wp acorn acf:stubs

发布命令默认生成所有可用的存根。然而，每个存根文件都是可选的。当存根文件不存在于 stubs/acf-composer 目录中时，将使用包提供的默认存根。

默认字段设置

ACF Composer 独有的一个有用功能是能够设置字段类型以及字段组默认值。当然，全局设置的默认值可以简单地通过在单个字段上设置来覆盖。

全局

查看 config/acf.php，您将看到一些预配置的默认值

'defaults' => [
    'trueFalse' => ['ui' => 1],
    'select' => ['ui' => 1],
],

当将 trueFalse 和 select 设置为默认 ui 为 1 时，就不再需要在您的字段上重复设置 'ui' => 1。这将在全局范围内生效，并且可以通过在字段上设置不同的值来覆盖。

字段组

还可以在单个字段组上定义默认值。这是通过在您的字段类中简单地定义 $defaults 来完成的。

/**
 * Default field type settings.
 *
 * @return array
 */
protected $defaults = ['ui' => 0];

我的默认值

以下是我个人使用的几个默认值。任何以 acfe_ 开头的都与ACF Extended 相关。

'defaults' => [
    'fieldGroup' => ['instruction_placement' => 'acfe_instructions_tooltip'],
    'repeater' => ['layout' => 'block', 'acfe_repeater_stylised_button' => 1],
    'trueFalse' => ['ui' => 1],
    'select' => ['ui' => 1],
    'postObject' => ['ui' => 1, 'return_format' => 'object'],
    'accordion' => ['multi_expand' => 1],
    'group' => ['layout' => 'table', 'acfe_group_modal' => 1],
    'tab' => ['placement' => 'left'],
    'sidebar_selector' => ['default_value' => 'sidebar-primary', 'allow_null' => 1]
],

错误报告

如果您在 ACF Composer 中发现了一个错误，请提交问题。

贡献

无论通过提交PR、报告问题还是提出建议，都受到鼓励并受到赞赏。

许可证

ACF Composer是在MIT许可证下提供的。

log1x / acf-composer

维护者

详细信息