在 Gatsby 中使用 Advanced Custom Fieldsgatsby-source-wordpress 与 WPGraphQL for ACF 完整实战指南【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsbyAdvanced Custom FieldsACF是 WordPress 生态中最流行的自定义字段插件本指南基于gatsby-source-wordpress官方教程完整演示如何将 ACF Field Group 暴露到 WPGraphQL Schema再通过 Gatsby 的 GraphQL API 查询 ACF 数据。读完本文你将掌握 ACF Field Group 的 GraphQL 配置方法、WPGraphQL 与 Gatsby 两套查询的写法差异以及 gatsby-source-wordpress 底层如何通过 Schema 合并自动继承 WPGraphQL 扩展数据。前置条件本教程假设你已经搭建好一个可运行的 Gatsby 站点gatsby-source-wordpress已激活并指向一个由 WPGraphQL了解数据在两端之间如何流动。在开始之前你还需要一个可用的 WordPress 实例并已安装激活 WPGraphQL 与 WPGatsby 两个必需插件详见 安装与快速开始在gatsby-config.js中将gatsby-source-wordpress的url配置指向 WordPress 的 GraphQL 端点例如https://yoursite.com/graphql安装免费的 Advanced Custom Fields 插件以及免费的WPGraphQL for Advanced Custom Fieldswp-graphql-acfWordPress 插件。什么是 Advanced Custom FieldsAdvanced Custom Fields简称 ACF是一款 WordPress 插件它允许开发者通过图形化界面构建表单在 WordPress 后台为文章、页面、自定义文章类型等对象编辑额外内容。ACF 并非创建自定义字段的唯一选择但它是最流行的方案之一并且拥有与 WPGraphQL 的官方集成因此成为 Gatsby 站点从 WordPress 获取结构化扩展数据的首选路径。让 ACF 字段进入 WPGraphQL SchemaWPGraphQL for ACF 是 WPGraphQL 的官方扩展插件。安装并激活它之后你便可以在 ACF 的 Field Group 设置中决定该字段组是否以及以什么名字出现在 WPGraphQL Schema 中。官方文档同时将WPGraphQL for Advanced Custom Fields列在“已确认可用的 WPGraphQL 扩展”清单中见 与主流 WPGraphQL 扩展的配合使用即该扩展产出的数据已被 gatsby-source-wordpress 在生产站点中验证可用。为什么 ACF 数据能自动被 Gatsby 使用gatsby-source-wordpress 之所以能“无感”继承 ACF 数据源于其核心的 Schema 合并机制。从源码看该插件首先通过 GraphQL introspection 拉取 WordPress 端完整的 Schema 副本在 introspect-remote-schema.js 中introspectAndStoreRemoteSchema向 WordPress 的 GraphQL 端点发送introspectionQuery将返回结果按${pluginOptions.url}--introspection-data作为键写入持久化缓存在 create-schema-customization/index.js 中插件遍历 introspection 得到的__schema.types把其中“被实际拉取过数据”fieldOfTypeWasFetched且未被排除typeIsExcluded的 Object、Interface、Union、Enum 类型逐一构建为 Gatsby 侧对应的 GraphQL Type。这意味着只要 WPGraphQL for ACF 往 WPGraphQL Schema 中注册了新的字段或类型它们就会出现在 introspection 结果里从而被 gatsby-source-wordpress 自动复制到 Gatsby 的 Schema 中。正如 GraphQL、WordPress 与 Gatsby 所述“任何 WPGraphQL 扩展都会自动成为一个 Gatsby Source 插件”——ACF 只是其中一个典型的例子。实战示例配置一个 ACF Field Group 并查询数据下面我们完整走一遍“在 WordPress 后台创建 ACF 字段组 → 暴露到 GraphQL → 在 WPGraphQL 查询 → 在 Gatsby 查询”的流程。第一步创建 ACF Field GroupACF 提供了可视化的字段组配置界面。在 WordPress 后台进入“自定义字段 → 字段组 → 添加新字段组”然后命名 Field Group 为Test Post Fields添加一个Text文本框字段字段名为text_field设置Location Rules为 “Post Type is equal to Post”使该字段组仅出现在文章编辑页。第二步将 Field Group 暴露到 GraphQL在 Field Group 设置底部ACF 提供了与 GraphQL 相关的两个配置项配置项本示例取值作用Show in GraphQLYes决定该字段组是否进入 WPGraphQL SchemaGraphQL Field NametestPostFields该字段组在 GraphQL 查询中使用的字段名发布该 Field Group 后ACF 会把该字段组挂载到 Post 编辑屏幕WPGraphQL for ACF 会根据 Location Rules 推断把testPostFields这个字段注册到 GraphQL Schema 的Post类型上。第三步在文章中写入 ACF 数据接下来编辑一篇文章你会看到 “Test Post Fields” 字段组出现在编辑页面上。在 “Text Field” 中输入Test field value...并保存数据即写入 WordPress。第四步用 WPGraphQL 验证查询打开 WordPress 后台的 GraphiQL IDE用下面的查询验证字段是否可查示例中文章的数据库 ID 为2068{ post(id: 2068, idType: DATABASE_ID) { id title testPostFields { textField } } }注意 WPGraphQL 侧使用的是post(id: 2068, idType: DATABASE_ID)这种“服务端过滤参数”写法这是 WPGraphQL 与 Gatsby GraphQL API 的重要差异之一。第五步在 Gatsby 中查询 ACF 字段现在切换到 Gatsby 侧。启动gatsby develop后打开 Gatsby 的 GraphiQL 界面开发服务器默认在http://localhost:8000/___graphql使用同样的 ACF 字段查询{ wpPost(databaseId: { eq: 2068 }) { id title testPostFields { textField } } }查询成功返回testField value...说明 ACF 数据已经被 gatsby-source-wordpress 拉取进 Gatsby 的 Node 层前端可以直接基于该字段构建页面或组件。理解 WPGraphQL 与 Gatsby 查询的差异从上面的两条查询可以看出同一份 ACF 数据在两端有着不同的查询语法。根据 GraphQL、WordPress 与 Gatsby 的说明两者主要有以下区别Schema 前缀gatsby-source-wordpress 会为来自 WPGraphQL 的类型加上Wp前缀可通过 plugin options 中的schema.typePrefix修改因此 WPGraphQL 的Post在 Gatsby 中是WpPost连接命名Gatsby 用all前缀表示节点列表WPGraphQL 的根字段post/posts在 Gatsby 中对应wpPost/allWpPost查询参数WPGraphQL 的输入参数如idType: DATABASE_ID会直接影响服务端返回结果而 Gatsby 查询的是本地 Node 层输入参数是 Gatsby 的过滤器语法如databaseId: { eq: 2068 }两者并不等价查询时不能混用。提示两套 Schema 的差异比较细微建议同时使用 WordPress 后台 GraphiQL 和 Gatsby GraphiQL 熟悉各自的字段与参数。在 Gatsby 页面中使用 ACF 数据ACF 字段进入 Gatsby 的 Node 层之后就可以像使用任何 Gatsby 数据一样使用它。例如在页面查询Page Query中获取 ACF 字段query PostPage($id: String!) { wpPost(id: { eq: $id }) { id title testPostFields { textField } } }然后在 React 组件中读取data.wpPost.testPostFields.textField渲染即可。由于 gatsby-source-wordpress 在构建期间已经把 WordPress 数据完整复制到 Gatsby 的 Node 层详见 数据抓取流程 与 introspect-remote-schema.js页面渲染时不会再有额外的网络请求回源到 WordPress。进阶扩展类型的注意事项ACF 的 Text 等标量字段Scalar在 Gatsby 中“开箱即用”。但如果某个 WPGraphQL 扩展暴露的不只是标量字段而是 Node 和 Connection如 ACF 的关系字段、重复字段组等更复杂的结构则该扩展应遵循 GraphQL Relay 规范才能真正与 gatsby-source-wordpress 良好协作Node 应能通过 Root Query 独立查询同时也能作为连接的一部分从类型 A 关联到类型 B层级数据如父子关系应尽量以扁平列表返回并提供parentId/parentDatabaseId字段。满足这些约束后gatsby-source-wordpress 才能正确地把关联节点链接到 Gatsby 侧对应的 Node 上而不是重复拉取数据。小结通过 WPGraphQL for ACF 这座桥梁ACF 的字段组可以一键进入 WPGraphQL Schema并借助 gatsby-source-wordpress 的 introspection Schema 合并机制自动出现在 Gatsby 的 GraphQL API 中。整个链路无需编写额外的 Gatsby 插件或 PHP 代码只需在 WordPress 后台完成 Field Group 的创建与 “Show in GraphQL” 配置即可在 Gatsby 中查询并渲染 ACF 数据。相关源码与文档可供继续深入教程原文见 using-advanced-custom-fields.mdSchema 合并原理见 features/graphql-wordpress-and-gatsby.md源码实现见 src/steps/ingest-remote-schema/introspect-remote-schema.js 与 src/steps/create-schema-customization/index.js。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 在 Gatsby 中使用 Advanced Custom Fields：gatsby-source-wordpress 与 WPGraphQL for ACF 完整实战指南
在 Gatsby 中使用 Advanced Custom Fieldsgatsby-source-wordpress 与 WPGraphQL for ACF 完整实战指南【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsbyAdvanced Custom FieldsACF是 WordPress 生态中最流行的自定义字段插件本指南基于gatsby-source-wordpress官方教程完整演示如何将 ACF Field Group 暴露到 WPGraphQL Schema再通过 Gatsby 的 GraphQL API 查询 ACF 数据。读完本文你将掌握 ACF Field Group 的 GraphQL 配置方法、WPGraphQL 与 Gatsby 两套查询的写法差异以及 gatsby-source-wordpress 底层如何通过 Schema 合并自动继承 WPGraphQL 扩展数据。前置条件本教程假设你已经搭建好一个可运行的 Gatsby 站点gatsby-source-wordpress已激活并指向一个由 WPGraphQL了解数据在两端之间如何流动。在开始之前你还需要一个可用的 WordPress 实例并已安装激活 WPGraphQL 与 WPGatsby 两个必需插件详见 安装与快速开始在gatsby-config.js中将gatsby-source-wordpress的url配置指向 WordPress 的 GraphQL 端点例如https://yoursite.com/graphql安装免费的 Advanced Custom Fields 插件以及免费的WPGraphQL for Advanced Custom Fieldswp-graphql-acfWordPress 插件。什么是 Advanced Custom FieldsAdvanced Custom Fields简称 ACF是一款 WordPress 插件它允许开发者通过图形化界面构建表单在 WordPress 后台为文章、页面、自定义文章类型等对象编辑额外内容。ACF 并非创建自定义字段的唯一选择但它是最流行的方案之一并且拥有与 WPGraphQL 的官方集成因此成为 Gatsby 站点从 WordPress 获取结构化扩展数据的首选路径。让 ACF 字段进入 WPGraphQL SchemaWPGraphQL for ACF 是 WPGraphQL 的官方扩展插件。安装并激活它之后你便可以在 ACF 的 Field Group 设置中决定该字段组是否以及以什么名字出现在 WPGraphQL Schema 中。官方文档同时将WPGraphQL for Advanced Custom Fields列在“已确认可用的 WPGraphQL 扩展”清单中见 与主流 WPGraphQL 扩展的配合使用即该扩展产出的数据已被 gatsby-source-wordpress 在生产站点中验证可用。为什么 ACF 数据能自动被 Gatsby 使用gatsby-source-wordpress 之所以能“无感”继承 ACF 数据源于其核心的 Schema 合并机制。从源码看该插件首先通过 GraphQL introspection 拉取 WordPress 端完整的 Schema 副本在 introspect-remote-schema.js 中introspectAndStoreRemoteSchema向 WordPress 的 GraphQL 端点发送introspectionQuery将返回结果按${pluginOptions.url}--introspection-data作为键写入持久化缓存在 create-schema-customization/index.js 中插件遍历 introspection 得到的__schema.types把其中“被实际拉取过数据”fieldOfTypeWasFetched且未被排除typeIsExcluded的 Object、Interface、Union、Enum 类型逐一构建为 Gatsby 侧对应的 GraphQL Type。这意味着只要 WPGraphQL for ACF 往 WPGraphQL Schema 中注册了新的字段或类型它们就会出现在 introspection 结果里从而被 gatsby-source-wordpress 自动复制到 Gatsby 的 Schema 中。正如 GraphQL、WordPress 与 Gatsby 所述“任何 WPGraphQL 扩展都会自动成为一个 Gatsby Source 插件”——ACF 只是其中一个典型的例子。实战示例配置一个 ACF Field Group 并查询数据下面我们完整走一遍“在 WordPress 后台创建 ACF 字段组 → 暴露到 GraphQL → 在 WPGraphQL 查询 → 在 Gatsby 查询”的流程。第一步创建 ACF Field GroupACF 提供了可视化的字段组配置界面。在 WordPress 后台进入“自定义字段 → 字段组 → 添加新字段组”然后命名 Field Group 为Test Post Fields添加一个Text文本框字段字段名为text_field设置Location Rules为 “Post Type is equal to Post”使该字段组仅出现在文章编辑页。第二步将 Field Group 暴露到 GraphQL在 Field Group 设置底部ACF 提供了与 GraphQL 相关的两个配置项配置项本示例取值作用Show in GraphQLYes决定该字段组是否进入 WPGraphQL SchemaGraphQL Field NametestPostFields该字段组在 GraphQL 查询中使用的字段名发布该 Field Group 后ACF 会把该字段组挂载到 Post 编辑屏幕WPGraphQL for ACF 会根据 Location Rules 推断把testPostFields这个字段注册到 GraphQL Schema 的Post类型上。第三步在文章中写入 ACF 数据接下来编辑一篇文章你会看到 “Test Post Fields” 字段组出现在编辑页面上。在 “Text Field” 中输入Test field value...并保存数据即写入 WordPress。第四步用 WPGraphQL 验证查询打开 WordPress 后台的 GraphiQL IDE用下面的查询验证字段是否可查示例中文章的数据库 ID 为2068{ post(id: 2068, idType: DATABASE_ID) { id title testPostFields { textField } } }注意 WPGraphQL 侧使用的是post(id: 2068, idType: DATABASE_ID)这种“服务端过滤参数”写法这是 WPGraphQL 与 Gatsby GraphQL API 的重要差异之一。第五步在 Gatsby 中查询 ACF 字段现在切换到 Gatsby 侧。启动gatsby develop后打开 Gatsby 的 GraphiQL 界面开发服务器默认在http://localhost:8000/___graphql使用同样的 ACF 字段查询{ wpPost(databaseId: { eq: 2068 }) { id title testPostFields { textField } } }查询成功返回testField value...说明 ACF 数据已经被 gatsby-source-wordpress 拉取进 Gatsby 的 Node 层前端可以直接基于该字段构建页面或组件。理解 WPGraphQL 与 Gatsby 查询的差异从上面的两条查询可以看出同一份 ACF 数据在两端有着不同的查询语法。根据 GraphQL、WordPress 与 Gatsby 的说明两者主要有以下区别Schema 前缀gatsby-source-wordpress 会为来自 WPGraphQL 的类型加上Wp前缀可通过 plugin options 中的schema.typePrefix修改因此 WPGraphQL 的Post在 Gatsby 中是WpPost连接命名Gatsby 用all前缀表示节点列表WPGraphQL 的根字段post/posts在 Gatsby 中对应wpPost/allWpPost查询参数WPGraphQL 的输入参数如idType: DATABASE_ID会直接影响服务端返回结果而 Gatsby 查询的是本地 Node 层输入参数是 Gatsby 的过滤器语法如databaseId: { eq: 2068 }两者并不等价查询时不能混用。提示两套 Schema 的差异比较细微建议同时使用 WordPress 后台 GraphiQL 和 Gatsby GraphiQL 熟悉各自的字段与参数。在 Gatsby 页面中使用 ACF 数据ACF 字段进入 Gatsby 的 Node 层之后就可以像使用任何 Gatsby 数据一样使用它。例如在页面查询Page Query中获取 ACF 字段query PostPage($id: String!) { wpPost(id: { eq: $id }) { id title testPostFields { textField } } }然后在 React 组件中读取data.wpPost.testPostFields.textField渲染即可。由于 gatsby-source-wordpress 在构建期间已经把 WordPress 数据完整复制到 Gatsby 的 Node 层详见 数据抓取流程 与 introspect-remote-schema.js页面渲染时不会再有额外的网络请求回源到 WordPress。进阶扩展类型的注意事项ACF 的 Text 等标量字段Scalar在 Gatsby 中“开箱即用”。但如果某个 WPGraphQL 扩展暴露的不只是标量字段而是 Node 和 Connection如 ACF 的关系字段、重复字段组等更复杂的结构则该扩展应遵循 GraphQL Relay 规范才能真正与 gatsby-source-wordpress 良好协作Node 应能通过 Root Query 独立查询同时也能作为连接的一部分从类型 A 关联到类型 B层级数据如父子关系应尽量以扁平列表返回并提供parentId/parentDatabaseId字段。满足这些约束后gatsby-source-wordpress 才能正确地把关联节点链接到 Gatsby 侧对应的 Node 上而不是重复拉取数据。小结通过 WPGraphQL for ACF 这座桥梁ACF 的字段组可以一键进入 WPGraphQL Schema并借助 gatsby-source-wordpress 的 introspection Schema 合并机制自动出现在 Gatsby 的 GraphQL API 中。整个链路无需编写额外的 Gatsby 插件或 PHP 代码只需在 WordPress 后台完成 Field Group 的创建与 “Show in GraphQL” 配置即可在 Gatsby 中查询并渲染 ACF 数据。相关源码与文档可供继续深入教程原文见 using-advanced-custom-fields.mdSchema 合并原理见 features/graphql-wordpress-and-gatsby.md源码实现见 src/steps/ingest-remote-schema/introspect-remote-schema.js 与 src/steps/create-schema-customization/index.js。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考