README

一个用于管理 WordPress 资源的辅助开发插件。它可以用来注册和按默认值和哈希名称排队样式表，以及通过使用 WordPress 的原生 wp_enqueue/register_style/script() 和 wp_add_inline_script() 方法配置内联集成，如 Google Analytics、Rollbar 等。这可以正确地将它们加载到网站上，避免冲突，并将它们暴露给资产钩子以进行更深入的配置。

安装
用法
文档
排队内联辅助函数
ACF 选项页面插件集成
查询监视器插件集成

使用 Composer 安装

$1 此软件包使用 Composer Installers 在 必须使用 插件目录中安装软件包（/wp-content/mu-plugins）

$ composer require nyco/wp-assets

未使用 Composer？ 下载代码存档并将其放入 mu-plugins 目录。

$2 在 mu-plugins 目录内创建一个代理 PHP 加载文件，或使用插件中包含的文件

$ mv wp-content/mu-plugins/wp-assets/autoloader-sample.php wp-content/mu-plugins/wp-assets.php

用法

快速入门。在 functions.php（或任何 PHP 文件）中声明命名空间并实例化。

use NYCO\WpAssets as WpAssets;

$WpAssets = new WpAssets();

// The general pattern for all methods is $WpAssets->{{ method }}()
$WpAssets->addScript();

迁移块...

wp_register_script('main', '/wp-content/themes/theme/assets/js/main.831f1593.js', [], null, true);
wp_enqueue_script('main');

... 可以用...

$WpAssets->addScript('main');

假设 main.831f1593.js 是一个编译的脚本文件，831f1593 是基于脚本内容的哈希，如果文件内容更改，则文件名将更改。这对于缓存破坏很有用，而无需强制浏览器在每次加载时都加载脚本，使用查询变量 ?ver=831f1593。然而，WordPress 没有硬编码的源将无法找到脚本。->addScript('main') 将注册并排队找到的第一个脚本文件，其哈希内容在 main. 和 .js 之间。

注意。自动加载示例将 WpAssets 实例设置为全局范围，也可以使用；

$GLOBALS['wp_assets']->addScript();

文档

插件的核心是一个具有几个方法的单个类，在实例化后可用。有关方法的完整描述，请参阅源代码。

类（包括命名空间）

NYCO\WpAssets

添加脚本

->addScript( ...args )

根据其名称注册和/或排队哈希脚本。默认情况下，文件名应匹配 script.{{ hash }}.js 模式。文件名和哈希之间的分隔符可以配置。

...参数

String $handle 没有哈希名称的文件名。默认: 'scripts'
Boolean $enqueue 是否排队文件。默认: true
Array $deps 映射到 wp_register|enqueue_script $deps 参数。默认: array()
String $ver 映射到 wp_register|enqueue_script $ver 参数。默认: null
布尔型 $in_footer 映射到 wp_register|enqueue_script 的 $in_footer 参数。默认值：true
字符串 $sep 基础名称和哈希值之间的分隔符。默认值：'.'

返回值 包含 wp_register_script 响应、wp_enqueue_script 响应和文件源 URI 的键/值对。

示例

$WpAssets->addScript();

这将使用默认模式 script.{{ hash }}.js 扫描当前主题的默认脚本资源目录 assets/scripts/，使用处理程序 script 注册脚本并将其排队。要选择名为 main.{{ hash }}.js 的不同脚本，请执行以下操作；

$WpAssets->addScript('main');

此脚本将被加载到文档的页脚中，并可供 script_loader_tag 过滤器使用；

add_filter('script_loader_tag', function($tag, $handle) {
  if ($handle === 'main') {
    // do something to $tag like add attributes, disable for certain views, etc.
  }

  return $tag;
});

返回顶部

添加样式

->addStyle( ...args )

根据其名称注册和/或排队基于哈希的样式。文件名应与模式 styles.{{ hash }}.css 匹配。文件名和哈希值之间的分隔符可以配置。

...参数

字符串 $handle 不包含哈希名的文件名。默认值：'styles'
Boolean $enqueue 是否排队文件。默认: true
数组 $deps 映射到 wp_register|enqueue_style 的 $deps 参数。默认值：array()
字符串 $ver 映射到 wp_register|enqueue_style 的 $ver 参数。默认值：null
字符串 $media 映射到 wp_register|enqueue_style 的 $media 参数。默认值：'all'
字符串 $sep 基础名称和哈希值之间的分隔符。默认值：'.'

返回值 包含 wp_register_style 响应、wp_enqueue_style 响应和文件源 URI 的键/值对。

示例

$WpAssets->addStyle();

这将使用默认模式 style.{{ hash }}.css 扫描当前主题的默认样式资源目录 assets/styles/，使用处理程序 style 注册样式并将其排队。要选择名为 site.{{ hash }}.css 的不同样式，请执行以下操作；

$WpAssets->addStyle('site');

返回顶部

添加属性

->addAttr( ...args )

使用 script_loader_tag 过滤器向特定脚本添加属性和值。例如；crossorigin="anonymous"。属性值可以是字符串。要添加布尔属性（如 async 或 defer），请传递 true。

...参数

字符串 $name 脚本名称。
字符串 $attr 属性名称。
字符串|布尔型 $value 属性的值。

示例

$WpAssets->addAttr('script', 'async', true);

返回顶部

加载集成

->loadIntegrations( ...args )

此操作从 MU 插件目录检索集成配置文件。默认情况下，它将在 config/integrations.yml 中查找 YAML 文件，该文件包含一个包含单个配置对象的数组，然后将其转换为 PHP 数组并返回。此操作与 ->enqueueInline( ...args ) 方法一起使用。

...参数

字符串 $path 接受对 Must Use 插件目录中集成文件的自定义路径。默认 'config/integrations.yml'

返回值 包含单个配置对象的数组。

$integrations = $WpAssets->loadIntegrations();

配置文件可能包含具有以下参数的多个对象。

- handle: rollbar
  path: https://remote/url/to/integration/source.js
  dep: CONSTANT_THIS_SCRIPT_IS_DEPENDENT_ON
  localize:
    - ARRAY_OF_CONSTANTS_TO_LOCALIZE_IN_SCRIPT
    - CONSTANT_MY_SCRIPT_IS_DEPENDENT_ON
  in_footer: true/false
  inline:
    path: config/integrations/scripts/a-config-script-for-the-source.js
    position: before
  body_open:
    path: config/integrations/body/a-html-tag-to-include-in-the-body.html
  attrs:
    crossorigin: 'anonymous'
    async: true

- handle: google-analytics
  path: https://#/gtag/js?id={{ GOOGLE_ANALYTICS }}
  dep: GOOGLE_ANALYTICS
  localize:
    - GOOGLE_ANALYTICS
  in_footer: false
  inline:
    path: config/integrations/scripts/google-analytics.js
    position: after

返回顶部

添加内联

->addInline( ...args )

使用 wp_register/enqueue_script() 和 wp_add_inline_script() 注册和排队内联脚本及其源。

对于配置在客户端的云服务集成（如 Google Analytics、Webtrends、Rollbar.js 等），这些集成需要加载远程源，但配置了内联脚本代码块。

如果配置需要，还可以排队内联样式。默认情况下这是不可能的，它使用在这篇文章中描述的技术。

...参数

Array $script 接受一个配置的单键/值数组。请参阅 ->loadIntegrations( ...args ) 方法。

返回相同的数组，并附加内联脚本内容。

示例

$integrations = $WpAssets->loadIntegrations();

if ($integrations) {
  $index = array_search('google-analytics', array_column($integrations, 'handle'));

  $WpAssets->addInline($integrations[$index]);
}

这将加载 'google-analytics' 集成。以下是在 config/integrations.yml 中的 Google Analytics 配置...

- handle: google-analytics
  path: https://#/gtag/js?id={{ GOOGLE_ANALYTICS }}
  dep: GOOGLE_ANALYTICS
  localize:
    - GOOGLE_ANALYTICS
  in_footer: false
  inline:
    path: config/integrations/scripts/google-analytics.js
    position: after
  attrs:
    async: true

config/integrations/scripts/google-analytics.js 脚本应包含以下内容：

function gtag() { dataLayer.push(arguments); }

gtag('js', new Date());

gtag('config', '{{ GOOGLE_ANALYTICS }}');

常量 GOOGLE_ANALYTICS 应在配置的另一个部分中定义（wp-config.php、functions.php 或此插件与 nyco-wp-config 插件配合良好）；

define('GOOGLE_ANALYTICS', 'GTM-9A9A9A9');

以下将在文档的头部打印：

<script async type="text/javascript" src="https://#/gtag/js?id=GTM-9A9A9A9">
<script>
  function gtag() { dataLayer.push(arguments); }
  gtag('js', new Date());
  gtag('config', 'GTM-9A9A9A9');
</script>

返回顶部

注册 Rest 路由

->registerRestRoutes( ...args )

使用配置对象数组来注册 WP Rest 路由，这些路由作为 JavaScript 文件而不是内联脚本执行。

...参数

Array $scripts 集成对象数组（使用 ->loadIntegrations() 获取它们）。
Function $auth 用于路由的认证函数（作为 'permission_callback' 参数传递给 register_rest_route()）。

返回包含所有 rest 路由详细信息的集成对象数组。

返回顶部

排队内联辅助函数

使用包含的 enqueue_inline( ...handle... ) 辅助函数快速添加集成。它封装了上面的示例，以便更容易根据 config/integrations.yml 文件中的处理程序调用集成。示例自动加载器自动包含辅助函数。

add_action('wp_enqueue_scripts', function() {
  enqueue_inline('google-analytics');
});

ACF 选项页面插件集成

此插件附带一个集成选项页面插件，允许 WordPress 管理员开启或关闭集成。它 需要 Advanced Custom Fields 来显示选项页面。在您的 mu-plugins 目录中创建插件的副本。

$ mv wp-content/mu-plugins/wp-assets/integrations-options.php wp-content/mu-plugins/wp-assets-integrations.php

然后该页面将出现在集成菜单项下。

查询监视器插件集成

此插件还附带一个用于 Query Monitor 的插件，该插件显示可用集成到加载集成方法，并将其与已注册的集成进行比较。它使用相同的方法来显示 config/integrations.yml 文件的详细信息。示例自动加载器自动包含该插件。

纽约市经济机会办公室（NYC Opportunity）致力于共享我们在产品中使用的开源软件。请随时提问和分享反馈。 有兴趣贡献吗？ 请参阅我们在 buildwithnyc.github.io 上的开放职位。在 Github 上关注我们的团队（如果您是 @cityofnewyork 组织的一部分）或在 Github 上浏览我们的工作。

nyco / wp-assets

维护者

详细信息

README

使用 Composer 安装

用法

文档

类（包括命名空间）

方法

添加脚本

示例

添加样式

示例

添加属性

示例

加载集成

添加内联

示例

注册 Rest 路由

排队内联辅助函数

ACF 选项页面插件集成

查询监视器插件集成