README

帮助WordPress网站添加脚本的加载器。

安装

使用Composer

composer require underpin/script-loader

手动

此插件使用内置的自动加载器，因此只要它在Underpin之前被要求，就应该按预期工作。

require_once(__DIR__ . '/underpin-scripts/scripts.php');

设置

安装Underpin。请参阅Underpin文档
根据需要注册新的脚本。

示例

一个非常基础的例子可能看起来像这样。

underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description'
] );

或者，您可以扩展Script并直接引用扩展类，如下所示

underpin()->scripts()->add('key','Namespace\To\Class');

队列脚本

要队列一个脚本，运行加载器并引用脚本ID，如下所示

underpin()->scripts()->enqueue('test'); // Enqueue the test script

一个常见的做法是在脚本类中扩展do_actions以添加队列脚本所需的所有操作。如果您不需要使用任何逻辑来队列您的脚本，最简单的方法是使用队列脚本中间件。

本地化脚本

Underpin扩展了脚本本地化的方式。使用wp_localize_script的一个常见问题是本地化脚本所需的所有数据都必须放在一个单独的调用中。Underpin通过使用set_param方法绕过了这个问题。

例如，假设您想本地化ajaxUrl作为您网站的管理员AJAX URL。您可以在任何时候这样做，如下所示

underpin()->scripts()->get( 'test' )->set_param( 'ajaxUrl', admin_url( 'admin-ajax.php' ) );

只要在enqueue触发之前完成此操作，ajaxUrl就会本地化。所有项都位于名为localized_var的对象内部。如果没有指定localized_var，则变量将是handle。

因此，如果您在一个名为example的脚本上队列了ajaxUrl，您将得到类似以下内容

// console.log(example)
{
	ajaxUrl: 'https://www.underpin.com/admin-ajax.php'
}

脚本中间件

有时，有必要本地化同一组参数，甚至跨多个脚本运行相同的操作。这就是脚本中间件发挥作用的地方。

例如，假设您想构建一个利用REST API的脚本，因此需要在脚本中本地化nonce和根URL。在没有脚本的情况下做这件事非常简单，但很冗长

// Register script
underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description'
] );

$script = underpin()->scripts()->get('test');

// Localize script
$script->set_param('nonce', wp_create_nonce('wp_rest'));
$script->set_param('rest_url', get_rest_url());

// Enqueue script
$script->enqueue();

这是WordPress脚本的一个非常常见的场景。由于这个原因，存在一个中间件包来自动处理这个问题。下面的例子会达到完全相同的效果

// Register script
underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description',
        'middlewares' => [
          'Underpin_Rest_Middleware\Factories\Rest_Middleware'
        ]
] );

// Enqueue script
$script = underpin()->scripts()->get('test')->enqueue();

上面例子中的关键部分是middlewares参数。Middlewares是一个包含Script_Middleware项的数组，按提供的顺序运行，旨在自动化设置脚本所需的所有步骤。

使用中间件队列

在某些情况下，如果您始终需要队列脚本，则可以使用提供的队列中间件。

在管理员界面队列

underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description',
        'middlewares' => [
          'Underpin_Scripts\Factories\Enqueue_Admin_Script'
        ]
] );

在前端队列

underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description',
        'middlewares' => [
          'Underpin_Scripts\Factories\Enqueue_Script'
        ]
] );

在登录界面队列

underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description',
        'middlewares' => [
          'Underpin_Scripts\Factories\Enqueue_Login_Script'
        ]
] );

在前端和后端都队列

underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description',
        'middlewares' => [
          'Underpin_Scripts\Factories\Enqueue_Script',
          'Underpin_Scripts\Factories\Enqueue_Admin_Script'
        ]
] );

条件队列

在队列脚本时，一个常见的场景是在特定条件下队列脚本。这可以使用条件中间件通过Underpin::make_class的基于数组的语法来处理

例如，假设您只想在特定的管理员页面上队列一个脚本

underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description',
        'middlewares' => [
          [
            'class' => 'Underpin_Scripts\Factories\Enqueue_Admin_Script_Conditional',
            'args'  => [
              'should_enqueue_callback' => function(Script $script){
                return get_current_screen()->id === 'custom_screen_id';
              }
            ] 
          ]
        ]
] );

另一个例子，假设您只想在主页上队列

underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description',
        'middlewares' => [
          [
            'class' => 'Underpin_Scripts\Factories\Enqueue_Script_Conditional',
            'args'  => [
              'should_enqueue_callback' => 'is_home'
            ] 
          ]
        ]
] );

入队块

在脚本中，将块脚本入队的情况越来越常见。这可以这样做

underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description',
        'middlewares' => [
          'class' => 'Underpin_Scripts\Factories\Enqueue_Block_Script',
        ]
] );

创建您自己的中间件

数组 middlewares 使用 Underpin::make_class 来创建类实例。这意味着您可以通过以下方式传递：

一个字符串，该字符串引用 Script_Middleware 的实例（请参阅上面的示例）。
一个参数数组，用于动态构建 Script_Middleware 的实例。

underpin()->scripts()->add( 'test', [
	'handle'      => 'test',
	'src'         => 'path/to/script/src',
	'name'        => 'test',
	'description' => 'The description',
	'middlewares' => [
		'Underpin_Rest_Middleware\Factories\Rest_Middleware', // Will localize script params.
		'Underpin_Scripts\Factories\Enqueue_Script',          // Will enqueue the script on the front end all the time.
		[                                                     // Will instantiate an instance of Script_Middleware_Instance using the provided arguments
			'name'                => 'Custom setup params',
			'description'         => 'Sets up custom parameters specific to this script',
			'priority'            => 10, // Optional. Default 10.
			'do_actions_callback' => function ( \Underpin_Scripts\Abstracts\Script $loader_item ) {
				// Do actions
			},
		],
	],
] );

underpin / script-loader

维护者

详情