用于动态加载 WordPress 脚本和样式并解析依赖关系的实用工具。

概述

此包提供了一个函数，用于将 WordPress 资产（脚本和样式）动态注入到 DOM 中，具备以下特性：

  • 依赖关系解析 – 通过拓扑排序尊重 WordPress 的依赖图
  • 并行加载 – 外部脚本并行加载以提升性能
  • 顺序执行 – 内联脚本按正确顺序执行
  • 内联脚本/样式 – 支持每个 handle 的前/后内联内容
  • WordPress 兼容性 – 模拟 wp_enqueue_script/wp_enqueue_style 的行为

安装

安装模块：

npm install @wordpress/asset-loader --save

用法

基本用法

import loadAssets from '@wordpress/asset-loader';

const assets = {
    scripts: {
        'wp-blocks': {
            src: 'https://example.com/wp-includes/js/dist/blocks.min.js',
            deps: [ 'wp-element', 'wp-data' ],
            version: '1.0.0',
            in_footer: true,
        },
    },
    styles: {
        'wp-block-library': {
            src: 'https://example.com/wp-includes/css/dist/block-library/style.min.css',
            deps: [],
            version: '1.0.0',
            media: 'all',
        },
    },
    inline_scripts: {
        before: {},
        after: {
            'wp-blocks': 'wp.blocks.registerBlockType(...)',
        },
    },
    inline_styles: {
        before: {},
        after: {},
    },
};

await loadAssets(
    assets.scripts,
    assets.inline_scripts,
    assets.styles,
    assets.inline_styles
);

与 @wordpress/core-data 配合使用

import { resolveSelect } from '@wordpress/data';
import { store as coreDataStore } from '@wordpress/core-data';
import { unlock } from './lock-unlock';
import loadAssets from '@wordpress/asset-loader';

async function loadEditorAssets() {
    // 从 REST API 端点获取资产
    const assets = await unlock(
        resolveSelect( coreDataStore )
    ).getEditorAssets();

    // 将它们加载到 DOM 中
    await loadAssets(
        assets.scripts || {},
        assets.inline_scripts || { before: {}, after: {} },
        assets.styles || {},
        assets.inline_styles || { before: {}, after: {} }
    );
}

API

loadAssets(scriptsData, inlineScripts, stylesData, inlineStyles)

加载 WordPress 资产并解析依赖关系。

参数

  • scriptsData Record<string, Script> – 脚本 handle 到脚本数据的映射
  • inlineScripts Record<'before' | 'after', Record<string, string | string[]>> – 内联脚本
  • stylesData Record<string, Style> – 样式 handle 到样式数据的映射
  • inlineStyles Record<'before' | 'after', Record<string, string | string[]>> – 内联样式

返回值

Promise<void> – 当所有资产加载并执行完毕时解决

类型定义

type Script = {
    src: string;
    deps?: string[];
    version?: string;
    in_footer?: boolean;
};

type Style = {
    src: string;
    deps?: string[];
    version?: string;
    media?: string;
};

工作原理

  1. 拓扑排序 – 使用深度优先搜索根据依赖关系对资产进行排序
  2. 样式表加载 – 按依赖顺序加载 CSS 文件及内联样式
  3. 脚本加载 – 根据 in_footer 标志分离头部/主体脚本
  4. 并行执行 – 外部脚本并行加载（使用 async=false 以保持顺序）
  5. 内联脚本 – 在其对应的外部脚本加载后执行

贡献指南

请参阅 CONTRIBUTING.md。

许可证

GPL-2.0-or-later