README

PinkCrab Enqueue类允许在WordPress中排队脚本和样式时有一个干净且流畅的替代方案。

安装

composer require pinkcrab/enqueue

版本

发布 1.3.0

<?php 
add_action('wp_enqueue_scripts', function(){
    
    // Enqueue a script
    Enqueue::script('My_Script')
        ->src('https://url.tld/wp-content/plugins/my_plugn/assets/js/my-script.js')
        ->deps('jquery')
        ->latest_version()
        ->register();
    
    // Enqueue a stylesheet
    Enqueue::style('My_Stylesheet')
        ->src('https://url.tld/wp-content/plugins/my_plugn/assets/css/my-stylesheet.css')
        ->media('all and (min-width: 1200px)')
        ->latest_version()
        ->register();
});

上面的示例将使用wp_enqueue_script()和wp_enqueue_style()函数排队脚本和样式。

特性

\PinkCrab\Enqueue::class的实例化

创建Enqueue对象的实例时，您有两个选项。

<?php

$enqueue_script = new Enqueue( 'my_script', 'script');
$enqueue_style = new Enqueue( 'my_style', 'style');

// OR 

$enqueue_script = Enqueue::script('my_script');
$enqueue_style = Enqueue::style('my_style');

当您使用静态方法script()或style()调用时，将返回当前实例，允许在一个调用中进行链式调用。而不是使用更冗长的方法。

<?php

$enqueue_script = new Enqueue( 'my_script', 'script');
$enqueue_script->src('.....');
$enqueue_script->register();

// OR 

Enqueue::script('my_script')
    ->src('.....')
    ->register();

文件位置

定义的js或css文件的URI可以在这里定义。这必须作为url传递，而不是文件路径。

这对于样式和脚本都是相同的

<?php
Enqueue::script('my_script')
    ->src(PLUGIN_BASE_URL . 'assets/js/my-script.js')
    ->register();

版本

与底层wp_enqueue_script()和wp_enqueue_style()函数一样，我们可以为我们的脚本定义一个版本号。这可以通过ver('1.2.2')方法完成。

这对于样式和脚本都是相同的

<?php
Enqueue::script('my_script')
    ->src(PLUGIN_BASE_URL . 'assets/js/my-script.js')
    ->ver('1.2.2') // Set to your current version number.
    ->register();

然而，在开发时这可能会让人感到沮丧，所以而不是使用当前时间戳作为临时版本。您可以使用latest_version()，这会从定义的脚本或样式中获取最后修改日期，从而减少开发过程中缓存的烦恼。虽然这在开发期间非常方便，但在生产中使用时应将其更改为->ver('1.2.2')。

这对于样式和脚本都是相同的

<?php
Enqueue::script('my_script')
    ->src(PLUGIN_BASE_URL . 'assets/js/my-script.js')
    ->latest_version() 

依赖关系

与所有wp_enqueue_script()和wp_enqueue_style()函数一样，可以调用所需依赖关系。这允许按顺序调用您的脚本和样式。

这对于样式和脚本都是相同的

<?php
Enqueue::script('my_script')
    ->src(PLUGIN_BASE_URL . 'assets/js/my-script.js')
    ->deps('jquery') // Only enqueued after jQuery.

本地化值

在WordPress中排队脚本最有用的部分之一是将值从服务器传递到您的javascript文件中。而使用常规函数时，则需要注册样式、本地化数据然后注册脚本。虽然这完全可行，但它可能有点冗长。

localize()方法允许在单个调用中完成所有这些。

这只能对脚本调用

<?php
Enqueue::script('MyScriptHandle')
    ->src(PLUGIN_BASE_URL . 'assets/js/my-script.js')
    ->localize([ 
        'key1' => 'value1', 
        'key2' => 'value2', 
    ])
    ->register();

在js文件（my-script.js）中的使用

console.log(MyScriptHandle.key1) // value1
console.log(MyScriptHandle.key2) // value2

页脚

默认情况下，所有脚本都在页脚中排队，但如果需要将其放在头部，则可以更改。通过调用footer(false)或header()实现。

这只能对脚本调用

<?php
Enqueue::script('my_script')
    ->src(PLUGIN_BASE_URL . 'assets/js/my-script.js')
    ->footer(false)
    ->register();
// OR 
Enqueue::script('my_script')
    ->src(PLUGIN_BASE_URL . 'assets/js/my-script.js')
    ->header()
    ->register();

媒体

与wp_enqueue_style()一样，您可以为定义样式的媒体指定媒体。接受wp_enqueue_style()的所有相同值

这只能对样式调用

<?php
Enqueue::style('my_style')
    ->src(PLUGIN_BASE_URL . 'assets/js/my-style.css')
    ->media('(orientation: portrait)')
    ->register();

属性

从v1.2.0版本开始，可以向脚本或样式标签添加属性和标志（无值属性）。

<?php
Enqueue::style('my_style')
    ->src('http://www.site.com/my-style.css')
    ->attribute('key', 'value')
    ->register();

// Rendered as
// <link href="[.css/bootstrap.min.css](http://www.site.com/my-style.css)" rel="stylesheet" type="text/css" key="value">

或者

<?php
Enqueue::script('my_style')
    ->src('http://www.site.com/my-scripts.js')
    ->flag('key')
    ->register();

// Rendered as
// <script src="http://www.site.com/my-scripts.js" key type="text/javascript"></script>

异步 & 延迟

还有一些快捷方式可以使任何脚本或样式具有延迟或异步标记。

<?php
Enqueue::style('my_style')
    ->src('http://www.site.com/my-style.css')
    ->async()
    ->register();

// Rendered as
// <link href="http://www.site.com/my-style.css" rel="stylesheet" type="text/css" async="">

或者

<?php
Enqueue::script('my_style')
    ->src('http://www.site.com/my-scripts.js')
    ->defer()
    ->register();

// Rendered as
// <script src="http://www.site.com/my-scripts.js" defer="" type="text/javascript"></script>

注册

一旦填充了Enqueue对象，只需要调用register()即可调用wp_enqueue_script()或wp_enqueue_style()。您可以选择内联执行所有这些操作（如第一个示例），或者仅在需要时填充Enqueue对象。

这对于样式和脚本都是相同的

<?php
class My_Thingy{
    /**
     * Returns a partly finalised Enqueue scripts, with defined url.
     * 
     * @param string $script The file location.
     * @return Enqueue The populated enqueue object.
     */ 
    protected function enqueue($script): Enqueue {
        return Enqueue::script('My_Script')
            ->src($script)
            ->deps('jquery')
            ->latest_version();
    } 

    /**
     * Called to initialize the class.
     * Registers our JS based on a conditional.
     * 
     * @return void
     */
    public function init(): void {
        if(some_conditional()){
            add_action('wp_enqueue_scripts', function(){
                $this->enqueue(SOME_FILE_LOCATION_CONSTANT)->register()
            });
        } else {
            add_action('wp_enqueue_scripts', function(){
                $this->enqueue(SOMEOTHER_FILE_LOCATION_CONSTANT)->register()
            });
        }
    }
}

add_action('wp_loaded', [new My_Thingy, 'init']);

Gutenberg

在为Gutenberg块注册脚本和样式时，有必要在调用wp_enqueue_scripts钩子之前仅注册资产。要做到这一点，只需设置for_block()。

add_action('init', function(){
    Enqueue::script('my_style')
        ->src('http://www.site.com/my-scripts.js')
        ->defer()
        ->for_block()
        ->register();

    // Register block as normal
});

公共方法

/**
  * Creates an Enqueue instance.
  *
  * @param string $handle
  * @param string $type
  */
 public function __construct( string $handle, string $type )

/**
  * Creates a static instance of the Enqueue class for a script.
  *
  * @param string $handle
  * @return self
  */
 public static function script( string $handle ): self

/**
  * Creates a static instance of the Enqueue class for a style.
  *
  * @param string $handle
  * @return self
  */
 public static function style( string $handle ): self

/**
  * Defined the SRC of the file.
  *
  * @param string $src
  * @return self
  */
 public function src( string $src ): self

/**
  * Defined the Dependencies of the enqueue.
  *
  * @param string ...$deps
  * @return self
  */
 public function deps( string ...$deps ): self

/**
  * Defined the version of the enqueue
  *
  * @param string $ver
  * @return self
  */
 public function ver( string $ver ): self

/**
  * Define the media type.
  *
  * @param string $media
  * @return self
  */
 public function media( string $media ): self

/**
  * Sets the version as last modified file time.
  *
  * @return self
  */
 public function lastEditedVersion(): self

/**
  * Should the script be called in the footer.
  *
  * @param boolean $footer
  * @return self
  */
 public function footer( bool $footer = true ): self

/**
  * Should the script be called in the inline.
  *
  * @param boolean $inline
  * @return self
  */
 public function inline( bool $inline = true ):self

/**
  * Pass any key => value pairs to be localised with the enqueue.
  *
  * @param array $args
  * @return self
  */
 public function localize( array $args ): self

/**
  * Adds a Flag (attribute with no value) to a script/style tag
  *
  * @param string $flag
  * @return self
  */
 public function flag( string $flag ): self 

/**
  * Adds an attribute tto a script/style tag
  *
  * @param string $key
  * @param string $value
  * @return self
  */
 public function attribute( string $key, string $value ): self 

/**
  * Marks the script or style as deferred loaded.
  *
  * @return self
  */
 public function defer(): self 

/**
  * Marks the script or style as async loaded.
  *
  * @return self
  */
 public function async(): self 

/**
 * Set denotes the script type.
 *
 * @param string $script_type  Denotes the script type.
 * @return self
 */
public function script_type( string $script_type ): self

/**
  * Set if being enqueued for a block.
  *
  * @param bool $for_block Denotes if being enqueued for a block.
  * @return self
  */
 public function for_block( bool $for_block = true ): self

/**
  * Registers the file as either enqueued or inline parsed.
  *
  * @return void
  */
 public function register(): void

这显然可以在不同的类/函数之间传递

变更日志

• 1.3.0 - 更新以支持 PHP 8，包括自定义脚本类型设置，将 lastest_version() 重命名为 latest_version() 并设置了弃用通知。
• 1.2.1：现在支持块使用。如果为块定义，则脚本和样式将只会注册，不会入队。
• 1.2.0：增加了属性和标志支持，并提供异步和延迟的辅助函数。

贡献

如果您想为此小类提出建议或做出贡献，请随时提交拉取请求或联系我。邮箱：glynn@pinkcrab.co.uk glynn@pinkcrab.co.uk。

WordPress 核心函数

此包使用以下 wp 核心函数。要使用 PHP Scoper，请添加以下函数：['wp_enqueue_style', 'wp_register_script', 'wp_add_inline_script', 'wp_localize_script', 'wp_enqueue_script']