README

🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨

此插件已经历完全的重构，此存储库将很快被存档。

我们建议您尽快升级到新版的WPGraphQL for ACF v2.0+。

新版本包含重大更改，请谨慎更新。以下是帮助资源：

• 升级指南： https://acf.wpgraphql.com/upgrade-guide
• 新插件存储库： https://github.com/wp-graphql/wpgraphql-acf
• WordPress.org上的新插件： https://wordpress.org/plugins/wpgraphql-acf
• Composer上的新插件： https://packagist.org.cn/packages/wp-graphql/wpgraphql-acf
• WPPACKAGIST上的新插件： https://wpackagist.org/search?q=wpgraphql-acf&type=any&search=

🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨

WPGraphQL for Advanced Custom Fields自动将ACF字段暴露给WPGraphQL模式。

• 安装和激活
  • 从Github安装
  • 使用Composer安装
• 依赖项
• 将字段添加到WPGraphQL模式
• 支持的字段
  • 手风琴
  • 按钮组
  • 复选框
  • 克隆
  • 颜色选择器
  • 日期选择器
  • 日期/时间选择器
  • 电子邮件
  • 文件
  • 灵活内容
  • 画廊
  • 谷歌地图
  • 组
  • 图片
  • 链接
  • 消息
  • 数字
  • Oembed
  • 页面链接
  • 密码
  • 文章对象
  • 单选按钮
  • 范围
  • 关系
  • 重复
  • 选择
  • 标签页
  • 分类法
  • 文本
  • 文本区域
  • 时间选择器
  • 真/假
  • URL
  • 用户
  • 所见即所得
• 选项页面
• 位置规则

安装和激活

由于WPGraphQL for Advanced Custom Fields目前不在WordPress.org存储库中，您必须从Github或Composer下载。

从Github安装

要从Github安装插件，您可以 下载最新的发布zip文件，将zip文件上传到您的WordPress安装，并激活插件。

点击此处 了解如何从zip文件安装WordPress插件。

使用Composer安装

composer require wp-graphql/wp-graphql-acf

依赖项

为了使用WPGraphQL for Advanced Custom Fields，您必须已安装并激活WPGraphQL和Advanced Custom Fields（免费或专业版）。

将字段添加到WPGraphQL模式

TL;DR： 这是一个视频，展示了用法概述。

高级自定义字段，简称 ACF，允许用户通过图形用户界面（GUI）、PHP 代码或本地 JSON 向 WordPress 控制面板中的各种屏幕添加字段组，例如编辑帖子、编辑用户和编辑术语屏幕等。

无论您使用哪种方法将 ACF 字段注册到您的 WordPress 网站中，都应该与 WPGraphQL for Advanced Custom Fields 一起工作。为了简化起见，以下文档将主要使用图形用户界面进行示例。

将 ACF 字段添加到 WPGraphQL 架构中

使用 ACF 与 WPGraphQL 一起使用的第一步是 创建一个 ACF 字段组。

默认情况下，字段组不会被暴露给 WPGraphQL。您必须选择将您的 ACF 字段组以及字段暴露给 WPGraphQL 架构，因为一些由您的 ACF 字段管理的信息可能不打算在可查询的 API（如 WPGraphQL）中公开。

在 GraphQL 设置中显示

要使您的 ACF 字段组在 WPGraphQL 架构中显示，您需要将字段组配置为“在 GraphQL 中显示”。

使用 ACF 图形用户界面

当使用 ACF 图形用户界面创建字段时，WPGraphQL for Advanced Custom Fields 会向字段组添加一个“在 GraphQL 中显示”字段。

将此字段的值设置为“是”将在 WPGraphQL 架构中显示该字段组，前提是已设置 GraphQL 字段名称。

在 PHP 中注册字段

在 PHP 中注册 ACF 字段时，您需要在定义字段组时添加 `show_in_graphql` 和 `graphql_field_name`。以下是一个示例。

function my_acf_add_local_field_groups() {

	acf_add_local_field_group(array(
		'key' => 'group_1',
        'title' => 'My Group',
        'show_in_graphql' => true,
        'graphql_field_name' => 'myGroup',
		'fields' => array (
			array (
				'key' => 'field_1',
				'label' => 'Sub Title',
				'name' => 'sub_title',
				'type' => 'text',
			)
		),
		'location' => array (
			array (
				array (
					'param' => 'post_type',
					'operator' => '==',
					'value' => 'post',
				),
			),
		),
	));

}

add_action('acf/init', 'my_acf_add_local_field_groups');

每个字段都将从提供的 `name` 标签继承其 GraphQL 名称。在这个例子中，当通过 GraphQL 请求时，`sub_title` 将变为 `subTitle`。如果您想有更细致的控制，也可以为每个字段传递 `graphql_field_name`。

支持的字段

为了记录与 GraphQL 中的字段交互，已创建了一个包含每种类型一个字段的示例字段组。

要复制这里记录的相同字段组，您可以下载 示例字段组 并 将其导入 到您的环境中。

为了文档的目的，此示例字段组已将 位置规则 设置为“帖子类型等于帖子”，这将允许在 WordPress 控制面板中创建和编辑帖子时输入字段，并将字段暴露给 WPGraphQL 架构中的 `Post` 类型。

选项页面

参考: https://www.advancedcustomfields.com/add-ons/options-page/

要添加选项页面并将其暴露给 GraphQL 架构，只需在注册选项页面时添加 'show_in_graphql' => true 即可。

示例用法

function register_acf_options_pages() {

    // check function exists
    if ( ! function_exists( 'acf_add_options_page' ) ) {
        return;
    }

    // register options page
    $my_options_page = acf_add_options_page(
        array(
            'page_title'      => __( 'My Options Page' ),
            'menu_title'      => __( 'My Options Page' ),
            'menu_slug'       => 'my-options-page',
            'capability'      => 'edit_posts',
            'show_in_graphql' => true,
        )
    );
}

add_action( 'acf/init', 'register_acf_options_pages' )
Example Query
query GetMyOptionsPage {
    myOptionsPage {
        someCustomField
    }
}

或者，您还可以查看字段 API 参考文档，了解如何将自定义字段暴露给架构。

位置规则

通过分配“位置规则”，高级自定义字段字段组被添加到 WordPress 控制面板。

WPGraphQL for Advanced Custom Fields 使用位置规则来确定字段组/字段应在 GraphQL 架构的何处添加到架构中。

例如，如果将字段组分配给“文章类型等于文章”，则该字段组将在WPGraphQL模式中的文章类型中显示，允许您在任何可以与Schema中的文章类型交互的地方查询文章的ACF字段。

支持的位置

@todo：记录支持的位置规则以及它们如何从ACF映射到WPGraphQL模式

为什么不是所有位置规则都受支持？

您可能会注意到一些位置规则没有向模式添加字段。这是因为一些位置规则基于在GraphQL模式生成时不存在上下文。

例如，如果您有一个只在特定页面上显示字段组的规则，那么这将如何暴露给Schema呢？Schema中没有表示单个特定页面的类型。

如果您在Schema中没有看到字段组，请查看位置规则，并考虑如何将字段组添加到Schema中，该Schema不了解上下文，例如您在哪个管理页面，文章分配给哪个类别等。

如果您有关于如何在WPGraphQL中处理这些特定上下文规则的创意，请提交问题，以便我们可以考虑如何最好地支持它！