alleyinteractive/wp-asset-manager

资产管理器是一个用于管理前端资产的工具包，可以更紧密地控制它们的位置、时间和加载方式。

维护者

详细信息

github.com/alleyinteractive/wp-asset-manager

源代码

问题

安装次数: 49,344

依赖项: 2

建议者: 0

安全: 0

星标: 24

关注者: 39

分支: 6

开放问题: 6

类型:wordpress-plugin

v1.3.7 2024-03-22 16:11 UTC

Requires (Dev)

GPL-2.0-only 6a892e030400487e828d5d25602200ccf1605740

  • Alley Interactive <info.woop@alley.com>

wordpresswordpress-plugin

This package is auto-updated.

Last update: 2024-08-26 18:32:12 UTC

README

资产管理器是一个用于管理前端资产的工具包，可以更紧密地控制它们的位置、时间和加载方式。

在WordPress项目中使用资产管理器

要开始，只需下载并将此插件安装到您的插件目录中，然后在插件屏幕上激活它。

入队函数

am_enqueue_* 函数将根据其 load_method 值附加额外的属性来入队一个资产。选项可以作为数组或单个参数传递。

am_enqueue_script

// Enqueue a JavaScript asset.
am_enqueue_script(
  [
    'handle'      => 'footer-script',
    'src'         => 'js/script.js',
    'deps'        => [],
    'condition'   => 'global',
    'load_method' => 'sync', // 'sync', 'inline', 'async', 'defer', 'async-defer'
    'version'     => '1.0.0',
    'load_hook'   => 'wp_footer',
  ]
);

使用 am_modify_load_method 修改已入队的脚本的加载方法。

// Defer an enqueued JavaScript asset.
am_modify_load_method(
  [
    'handle'      => 'footer-script', 
    'load_method' => 'defer',
  ]
);

am_enqueue_style

// Load a CSS asset asynchronously.
am_enqueue_style(
  [
    'handle'      => 'site-styles',
    'src'         => 'css/styles.css',
    'deps'        => [],
    'condition'   => 'global',
    'load_method' => 'async', // 'sync', 'inline', 'async', 'defer', 'preload'
    'version'     => '1.0.0',
    'load_hook'   => 'wp_head',
    'media'       => 'all', // 'print', 'screen', or any valid media query
  ]
);

条件

condition 参数决定了资产在什么条件下加载。

include

string|array

要求所有条件都必须为真，资产才能加载。

如果 condition 参数是字符串或字符串数组，则隐含了 include 属性；否则，condition 参数必须包含 include 属性。

include_any

string|array

允许任何条件为真，而不仅仅是所有条件。

exclude

string|array

要求所有条件都必须为假，资产才能加载。如果既不是 include 也不是 include_any 为真，则跳过此操作。

自定义条件

默认包含几个内置条件

使用 am_asset_conditions 过滤器添加或替换条件。

function asset_conditions( $conditions ) {
  return array_merge(
    $conditions,
    [
      'home'    => ( is_home() || is_front_page() ),
      'archive' => is_archive(),
      'page'    => is_page(),
    ]
  );
}

add_filter( 'am_asset_conditions', 'asset_conditions', 10 );

内联资产

使用具有绝对 src 路径的 load_method => inline 与任一入队函数一起打印文件的全部内容到文档头。

打印文件内容

// Print the contents of this CSS asset into a <style> tag.
// Also works with `am_enqueue_script` for printing a JavaScript asset into a <script> tag.
am_enqueue_style(
  [
    'handle'      => 'inline-styles',
    'src'         => 'css/styles.css',
    'condition'   => 'global',
    'load_method' => 'inline',
  ]
);

打印内联全局变量

将值数组作为 src 传递以打印全局JavaScript变量到文档头。

// Add JavaScript values to a property on the `window.amScripts` object.
am_enqueue_script(
  [
    'handle'      => 'inline-vars',
    'src'         => [
      'myGlobalVar' => true,
    ],
    'load_method' => 'inline',
  ]
);

结果将作为一个对象添加到 window.amScripts[$handle] 对象中

<script class="wp-asset-manager inline-vars" type="text/javascript">window.amScripts = window.amScripts || {}; window.amScripts["inline-vars"] = {"myGlobalVar":true}</script>

使用 am_inline_script_context 过滤器更改全局对象名称。

add_filter(
  'am_inline_script_context',
  function() {
    return 'myContext'; // window.myContext[$handle]
  }
);

入队选项

am_enqueue_* 函数使用与它们的WordPress核心入队等价函数相同的参数，但脚本除外；使用 'load_hook'（以下详细说明）代替。

附加选项

预加载函数

使用 am_preload 预加载任何支持的类型的资产。

// `as` and `mime_type` options will be automatically added for CSS, but are included here for clarity.
am_preload(
  [
    'handle'    => 'preload-styles',
    'src'       => 'css/styles.css',
    'condition' => 'global',
    'version'   => '1.0.0',
    'as'        => 'style'
    'mime_type' => 'text/css',
  ]
);

结果

<link rel="preload" href="http://client/css/test.css?ver=1.0.0" class="wp-asset-manager preload-styles" as="style" media="all" type="text/css" />

am_preload 函数修补了常用用例（CSS、JavaScript 和 WOFF2 字体）的 as 和 mime_type 选项值，但如果任何其他文件类型缺少 as 选项，则将抛出错误。

来自 规范

为了确保正确的优先级、请求匹配、应用正确的内容安全策略政策以及设置适当的 Accept 请求头，[as] 属性是必要的。

此函数还将自动为字体添加 crossorigin 属性，即使它们实际上不是跨源请求，在预加载字体时也是必需的。

预加载选项

SVG精灵

通过创建注册符号的精灵并提供显示它们的辅助函数，允许对 WordPress 模板中的 SVG 资产进行精细控制。

如果以下条件满足，资产管理器将添加 SVG 文件的到精灵中：

  1. 符号通过 am_register_symbol 以唯一句柄和有效文件路径注册
  2. 符号的 condition 为真

有关资产管理器的条件和如何更新它们的更多信息，请参阅 条件。

设置

精灵通过 wp_body_open 钩子打印，因此请确保您的模板在文档的 <body> 元素的顶部有 wp_body_open() 函数。

管理页面

通过 in_admin_header 钩子将精灵打印到管理页面，这是与 wp_body_open 最相似的管理钩子。不匹配管理页面的条件注册的符号将不会被添加到精灵中。

/**
 * Add SVG symbols to the admin page content.
 */
function print_admin_sprite() {
  if ( class_exists( 'Asset_Manager_SVG_Sprite' ) ) {
    Asset_Manager_SVG_Sprite::instance()->print_sprite_sheet();
  }
}
add_action( 'in_admin_header', 'print_admin_sprite' );

注册符号

使用 am_register_symbol 函数将符号添加到精灵中。类似于 wp_register_script 和 wp_register_style，将现有句柄重新注册符号的尝试将被忽略。

符号应通过在 wp_body_open 之前触发的操作注册。

am_register_symbol(
  [
    'handle'    => 'logomark',
    'src'       => 'svg/logomark.svg',
    'condition' => 'global',
  ]
);

选项可以作为数组或单个参数传入。

$handle

字符串

资产句柄。应该是唯一的。

$src

字符串

SVG 文件的绝对路径，或基于当前主题根的相对路径。使用 am_modify_svg_directory 过滤器更新将完成的相对路径的目录。

$condition

string|array

加载条件，当匹配时，将允许资产被添加到精灵中。

$attributes

数组

要添加到渲染的每个 <svg> 中的 HTML 属性名称和值的数组。

验证符号是否已注册

am_symbol_is_registered( $handle = '' );

$handle

字符串

注册符号时应使用的句柄。

返回

布尔值

符号是否已注册。

更改 SVG 目录

使用 am_modify_svg_directory 过滤器更新将完成的相对路径的目录。

默认值：当前主题根。

add_filter(
  'am_modify_svg_directory',
  function( $theme_root ) {
    return $theme_root . '/svg/';
  }
);

设置全局属性

使用 am_global_svg_attributes 过滤器添加将适用于所有符号的全局属性。

默认值：[]

add_filter(
  'am_global_svg_attributes',
  function() {
    return [
      'aria-hidden' => 'true',
      'focusable'   => 'false',
    ];
  }
);

更新 $sprite_allowed_tags

使用 am_sprite_allowed_tags 过滤在转义精灵时使用的元素和属性，例如某些已弃用的属性、脚本标签和事件处理器。

add_filter(
  'am_sprite_allowed_tags',
  function( $sprite_allowed_tags ) {
    $sprite_allowed_tags['path']['onclick'] = true;

    return $sprite_allowed_tags;
  }
);

删除符号

使用 am_deregister_symbol 移除已注册的符号。

这应通过在用于 am_register_symbol 的操作之后或在较低优先级触发的操作中添加。

am_deregister_symbol( $handle = '' );

$handle

字符串

注册符号时使用的句柄。

返回

布尔值

符号是否已被注销并从精灵中移除。成功时返回 true，或者如果符号之前未被注册；失败时返回 false。

替换符号

在重新注册符号之前，请验证要替换的符号尚未注册。

if ( am_deregister_symbol( 'logomark' ) ) {
  am_register_symbol(
    [
      'handle'    => 'logomark',
      'src'       => 'svg/logomark-alt.svg',
      'condition' => 'global',
    ]
  );
}

显示符号

am_use_symbol 打印具有指定属性的 <svg> 元素。

am_use_symbol( $handle = '', $attributes = [] );

$handle

字符串

注册符号时使用的句柄。

$attributes

数组

要添加到结果 SVG 标记的属性值对数组。

在此处声明新值以覆盖全局属性，或通过 am_register_symbol 定义的那些属性；通过传递一个假值来完全删除它。

关于SVG尺寸的说明

资产管理器将尝试为每个 SVG 建立默认大小，如果只传递了 height 或 width 中的一个或两个，则将使用此大小来计算维度。

默认大小基于（按顺序）

  1. 在符号的 am_register_symbol 属性数组中设置的值
  2. SVG 的 height 和 width 属性
  3. viewBox 属性的值

如果资产管理器无法确定符号的尺寸，则需要在传递给 am_use_symbol 的 attributes 数组中声明 height 和 width。

确保 SVG 的大小如预期，最简单的方法是验证每个文件的 <svg> 元素要么同时具有 height 和 width 属性，要么具有 viewBox 属性。

示例:

am_use_symbol(
  'logomark',
  [
    'width' => 200,
    'class' => 'header-logo',
  ]
);

输出:

<svg width="200" height="27.67" class="header-logo" aria-hidden="true" focusable="false">
  <use href="#am-symbol-logomark"></use>
</svg>

获取符号

am_get_symbol 返回包含指定属性的 <svg> 元素的字符串。

$symbol_markup = am_get_symbol( $handle = '', $attributes = [] );

此函数使用与 am_use_symbol 相同的参数。

示例:

$logomark_svg_markup = am_get_symbol(
  'logomark',
  [
    'width' => 200,
    'class' => 'header-logo',
  ]
);

需求

  • WordPress: 5.2.0+
  • PHP: 7.4+

下载和版本控制。

您可以在这里查看资产管理器的官方发布版本。

GitHub 上的 develop 分支包含“前沿”发布（alpha、beta、RC）。production 分支是最新稳定版本。

为开发做出贡献

资产管理器的开发在 GitHub 上进行。资产管理器的问题应在 GitHub 的问题队列中解决，增强功能或错误修复应以拉取请求的形式提交，这些请求总是受欢迎的。