javascript插件_以正确的方式在插件或主题中包含JavaScript

javascript插件

At the time of writing, more than 33,000 plugins and 2,600 themes are available on WordPress.org, and we can probably add more which are not present on this platform. They can do a lot of different things and, often, they use JavaScript to provide some features.

在撰写本文时， WordPress.org上提供了超过33,000个插件和2,600个主题，我们可能会添加更多在此平台上不存在的插件。 他们可以做很多不同的事情，并且经常使用JavaScript提供某些功能。

Basically, including JavaScript code into a theme or a plugin is not difficult: what WordPress produces is nothing else than HTML so using the script tag with code directly into it or into a file linked thanks to the src attribute might be enough – if you were alone, developing in isolation.

基本上，将JavaScript代码包含到主题或插件中并不难：WordPress生成的内容绝非HTML所致，因此，通过src属性直接将script标记与代码一起使用或链接到文件中，使用src可能就足够了。一个人，孤立地发展。

The fact is you are not alone. People using WordPress can install plugins or themes next to yours, and the developers of these tools can also use JavaScript. Moreover, WordPress itself is using JavaScript. The problem is, if everyone includes their scripts without attention, the resulting page will be unnecessarily heavy.

事实是你并不孤单 。 使用WordPress的人可以在您的旁边安装插件或主题，这些工具的开发人员也可以使用JavaScript。 而且，WordPress本身正在使用JavaScript。 问题是，如果每个人都包括他们的脚本而没有引起注意，则结果页面将不必要地繁重。

问题 (The Problem)

An example will be clearer, and I will take one that I know well: mine.

一个例子将更加清楚，我将举一个我熟知的例子：我的。

I developed the WP Photo Sphere plugin which allows users to add panoramas into their posts. To do that, I needed different JavaScript files: the library used to display this panoramas and the file that retrieves specific tags where panoramas are displayed. Moreover, in this last script, I use jQuery, so I need to include it.

我开发了WP Photo Sphere插件，该插件允许用户将全景照片添加到他们的帖子中。 为此，我需要不同JavaScript文件：用于显示此全景图的库和用于检索显示全景图的特定标签的文件。 此外，在最后一个脚本中，我使用jQuery，因此需要包含它。

If I did not care about users, I could insert these three scripts into all the pages of the websites which means visitors will have to download these files, even if the page does not need it.

如果我不关心用户，则可以将这三个脚本插入网站的所有页面，这意味着即使页面不需要它，访问者也必须下载这些文件。

At this time, the problem is already significant, but it becomes even bigger when we think about jQuery. What if two plugins using this library have this behavior? Not only will users download a useless file, but they will also download it twice!

目前，这个问题已经很严重了，但是当我们想到jQuery时，这个问题甚至变得更大。 如果使用此库的两个插件都有此行为怎么办？ 用户不仅会下载无用的文件，而且还会下载两次！

The heavier a page is, the longer it will take to load. Websites that are too long to load are visited less than faster websites. If your plugin or theme makes the time of loading too long, they won’t be used. That is surely is a great motivation to optimize your tools, right?

页面越重，加载时间越长。 访问时间太长而无法加载的网站比访问速度更快的网站要少。 如果您的插件或主题使加载时间过长，则将不会使用它们。 当然，这是优化工具的巨大动力，对吗？

插入脚本的必然功能 (The Inevitable Function to Insert Scripts)

To avoid the problem of inserting the same file twice or more, WordPress provides us a great function: wp_enqueue_script(). When you want to insert a script, this function must become your best friend.

为了避免两次或多次插入同一文件的问题，WordPress为我们提供了一个很棒的功能： wp_enqueue_script() 。 当您要插入脚本时，此功能必须成为您最好的朋友。

As its name suggests it, this function will add your scripts to a queue and include them at the right moment, into the header or into the footer, so no script tag will be added at the middle of the page.

顾名思义，此函数会将脚本添加到队列中，并在适当的时候将其包括在页眉或页脚中，因此不会在页面中间添加任何script标签。

Used alone, the wp_enqueue_script() function requires at least two parameters: the name of the script and the URL to it. For example, if I want to include a script needed by my plugin, I add this line into its main file (we will see proper ways to do that below).

wp_enqueue_script()函数单独使用时，至少需要两个参数：脚本的名称和URL。 例如，如果要包含插件所需的脚本，请将此行添加到其主文件中(我们将在下面看到执行此操作的正确方法)。

wp_enqueue_script('test', plugin_dir_url(__FILE__) . 'test.js');

However, three additional parameters let you have more control on the way your script will be included, especially the last parameter which is a boolean: by default, this boolean is set to false and your script will be included in the head tag, but if you set it to true, then your script will be included in the footer.

但是，通过三个附加参数，您可以更好地控制脚本的添加方式，尤其是最后一个参数是布尔值：默认情况下，此布尔值设置为false ，脚本将包含在head标记中，但是如果您将其设置为true ，那么您的脚本将包含在页脚中。

The fourth parameter is useful if you make various versions of your script: it is a string containing the version number which will be concatenated to the end of the URL. Adding a version number ensures that visitors will get the right version of your script, regardless of caching.

如果您制作了不同版本的脚本，则第四个参数很有用：它是一个包含版本号的字符串，该字符串将连接到URL的末尾。 添加版本号可确保访问者无论缓存如何都可获得正确的脚本版本。

The third parameter is one of the most interesting because it lets you indicate dependencies for your script. For example, if your script needs the library jQuery, you can use this parameter.

第三个参数是最有趣的参数之一，因为它使您可以指示脚本的依赖性。 例如，如果您的脚本需要jQuery库，则可以使用此参数。

wp_enqueue_script('test', plugin_dir_url(__FILE__) . 'test.js', array('jquery'));

As you can see, dependencies must be indicated into an array, even if there is only one dependency. The name you indicate into this array is the name of a script registered thanks to a second function: wp_register_script().

如您所见，即使只有一个依赖性，也必须将依赖性表示在数组中。 您在此数组中指定的名称是通过第二个功能wp_register_script()注册的脚本名称。

The use of this second function is exactly the same as the use of the first: you indicate the name of the script, its URL, its dependencies, its version number and whether it must be included into the footer or not. The last three parameters are optional but the others are required.

第二个功能的使用与第一个功能的使用完全相同：您指定脚本的名称，其URL，其依赖项，其版本号以及是否必须将其包含在页脚中。 最后三个参数是可选的，但其他参数是必需的。

wp_register_script('test', plugin_dir_url(__FILE__) . 'test.js', array('jquery'), '1.0', true);

Register a script will not include it. You still have to use the wp_enqueue_script() function to include your scripts, but its use is then simplified: you only have to indicate the name of the script.

注册脚本将不包含它。 您仍然必须使用wp_enqueue_script()函数来包含脚本，但是随后它的使用得以简化：您只需指出脚本的名称。

wp_enqueue_script('test');

Maybe you are asking yourself about the usefulness of the wp_register_script() as the wp_enqueue_script() can do all the job. This function is here to indicate the way a script should be included but does not include it if it is not necessary.

也许您正在问自己关于wp_register_script()的用处，因为wp_enqueue_script()可以完成所有工作。 此功能在此处指示应包含脚本的方式，但在不需要时不包含脚本。

An example will be clearer, so imagine that you have two JavaScript files to include. The first file is a library, and the second file uses this library to do some things. The library needs jQuery to work properly, so we register it as follows:

一个示例将更加清楚，因此，假设您要包含两个JavaScript文件。 第一个文件是一个库，第二个文件使用该库来做一些事情。 该库需要jQuery才能正常工作，因此我们将其注册如下：

wp_register_script('mylib', plugin_dir_url(__FILE__) . 'lib/mylib.js', array('jquery'));

At this time, the library is not included, but if we want to include the main file, then we need to include this library: we indicate it as a dependency.

目前不包括该库，但是如果要包括主文件，则需要包括该库：将其表示为依赖项。

wp_enqueue_script('myfile', plugin_dir_url(__FILE__) . 'myfile.js', array('mylib'));

And all the magic appears. The myfile.js file is included, but it needs the mylib.js file to work: that’s the job of the dependency which will include this file. But! The mylib.js file needs jQuery, so jQuery is included too. Three files included in one line.

所有的魔力出现了。 包含了myfile.js文件，但是它需要mylib.js文件才能起作用：这就是依赖关系的工作，它将包括此文件。 但！ mylib.js文件需要jQuery，因此也包含jQuery。 一行中包含三个文件。

But that’s not the only advantage of the wp_register_script() function: if you register your scripts, other plugins will be able to use it. So if you want to make various plugins, with one which defines some libraries, the others will be able to include them.

但这不是wp_register_script()函数的唯一优点：如果您注册脚本，其他插件将可以使用它。 因此，如果您想制作各种插件，并且其中一个定义了一些库，则其他插件将能够包含它们。

The biggest advantage of the wp_enqueue_script() function is that it won’t include the same script twice. For example, imagine that two files need jQuery: this files indicate it as a dependency and WordPress will include the library when the first file is included. Then the time to include the second script is here. WordPress sees jQuery as a dependency, but the library is already included, so including it again is not needed: WordPress won’t do that.

wp_enqueue_script()函数的最大优点是它不会两次包含相同的脚本。 例如，假设有两个文件需要jQuery：此文件将其表示为依赖项，当包含第一个文件时，WordPress将包括该库。 然后是时候包含第二个脚本了。 WordPress将jQuery视为依赖项，但是该库已经包含在内，因此不需要再次包含它：WordPress不会这样做。

The same behavior appears when you try to enqueue two scripts with different names but with the same URL. In the below example, WordPress will include the file once.

当您尝试使两个具有不同名称但具有相同URL的脚本入队时，会出现相同的行为。 在以下示例中，WordPress将一次包含该文件。

wp_enqueue_script('myfile', plugin_dir_url(__FILE__) . 'myfile.js', array('mylib'));
wp_enqueue_script('myotherfile', plugin_dir_url(__FILE__) . 'myfile.js');

However, be careful: this behavior is limited: if you indicate a version number in at least one wp_enqueue_script() call, the script will be included twice, even if this version number is the same. The below example seems to be the same as the previous one, but it will include the file twice.

但是，请小心：此行为是有限的：如果在至少一个wp_enqueue_script()调用中指定了版本号，则即使该版本号相同，脚本也会被包含两次。 下面的示例似乎与上一个示例相同，但是它将包含该文件两次。

wp_enqueue_script('myfile', plugin_dir_url(__FILE__) . 'myfile.js', array('mylib'), '1.0');
wp_enqueue_script('myotherfile', plugin_dir_url(__FILE__) . 'myfile.js', array(), '1.0');

That said, in general, you haven’t any reason to enqueue one script with different names. But it was necessary to clarify this case.

也就是说，一般而言，您没有任何理由让一个脚本使用不同的名称。 但是有必要澄清这种情况。

As you can see, this two functions are the best way to manage dependencies: you register them and WordPress will care of the rest, automatically.

如您所见， 这两个功能是管理依赖项的最佳方法 ：注册它们，WordPress将自动处理其余部分。

Note that we used the name “jquery” to indicate that we want to include jQuery with our own files, but we did not register it. This name is already registered by WordPress: when you download the CMS, it contains jQuery.

请注意，我们使用名称“ jquery ”来表示我们希望将jQuery包含在我们自己的文件中，但是我们没有注册它。 该名称已经由WordPress注册：下载CMS时，它包含jQuery。

This library is not the only one: you can find all the scripts registered by WordPress in this page. You can enqueue them directly or via a dependency, and the cool thing is that you haven’t to provide the files, so every plugin or theme which uses this scripts will use the same files: in our example, if another plugin uses jQuery, the library will only be included once.

这个库不是唯一的一个库：您可以在此页面中找到WordPress注册的所有脚本。 您可以直接将它们排入队列，也可以通过依赖关系入队，但很酷的是，您不必提供文件，因此，使用此脚本的每个插件或主题都将使用相同的文件：在我们的示例中，如果另一个插件使用jQuery，该库将只包含一次。

不要到处排队脚本！ (Do Not Enqueue Your Scripts Everywhere!)

The wp_enqueue_script() function ensures that a script is not included twice and includes it properly in the header or in the footer. But what if the displayed page does not even need your script?

wp_enqueue_script()函数可确保不两次包含脚本，并将其正确包含在页眉或页脚中。 但是，如果显示的页面甚至不需要您的脚本怎么办？

使用动作/过滤器API (Use the Action/Filter API)

Take the example of adding a media button to the content editor: the JavaScript file is only needed when the user is on the editor. In fact, when an average visitor is reading an article, they don’t need this script: including it is useless and make the page heavier.

以向内容编辑器添加媒体按钮为例：仅当用户在编辑器上时，才需要JavaScript文件。 实际上，当普通访问者阅读文章时，他们不需要此脚本：包括该脚本是没有用的，并且会使页面变重。

That’s why, when you want to include a script into a page, ask yourself the following question: when is this script needed? Of course, the answer to this question will be different depending on what your script does.

因此，当您要将脚本包含到页面中时，请问自己以下问题：什么时候需要此脚本？ 当然，根据脚本的作用，此问题的答案将有所不同。

But once you find this answer, try to find a corresponding action. The WordPress Codex provides us a list of available actions, so you can find the one you search at this place. Found it? Great, create a new function which will enqueue your script(s), in the main file of your plugin or in the functions.php file or your theme for example.

但是，一旦找到此答案，请尝试找到相应的操作。 WordPress Codex为我们提供了可用操作的列表 ，因此您可以在此处找到要搜索的操作。 找到了？ 太好了，在插件的主文件中或在functions.php文件或主题中，创建一个新的函数来排队您的脚本。

function enqueue_my_scripts() {
    wp_enqueue_script('script0', plugin_dir_url(__FILE__) . 'lib/myscript.js', array('jquery'));
    wp_enqueue_script('script1', plugin_dir_url(__FILE__) . 'another-script.js');
}

Then, make it run when your action is triggered:

然后，使其在触发操作时运行：

add_action('the_right_action', 'enqueue_my_scripts');

For example, when we wanted to add a media button, we used the wp_enqueue_media action, which was perfect:

例如，当我们想添加一个媒体按钮时，我们使用了wp_enqueue_media操作，这是完美的：

add_action('wp_enqueue_media', 'include_media_button_js_file');

If you tried to search this action in the reference linked above, you probably found nothing: at the time or writing this lines, wp_enqueue_media is not listed. This list is not exhaustive, but it is a good place to begin with.

如果您尝试在上面链接的参考中搜索此操作，则可能找不到任何内容：在当时或编写此wp_enqueue_media ，未列出wp_enqueue_media 。 此列表并不详尽，但是它是一个很好的起点。

If you don’t find the right action, maybe you can find another which has a close behavior, or maybe you should try to search in the filters instead.

如果找不到正确的操作，则可能会找到另一个行为接近的操作，或者您应该尝试在过滤器中进行搜索。

使用WordPress功能的强大功能！ (Use the Power of WordPress’ Functions!)

Often, plugins are made for a specific reason, one that cannot use the Action/Filter API, or not completely. For instance, a plugin can modify some elements into a post, but not in all of them: shortcodes are a typical example of this.

通常，插件是出于特定原因而制作的，这些原因不能使用Action / Filter API，或者不能完全使用。 例如，插件可以将某些元素修改为帖子，但不能将所有元素都修改为： 短代码是这种情况的典型示例。

Assume that your plugin needs some scripts used by the code which replaces a shortcode. There is no action or filter which will precisely target your shortcode. But there is a place where you can be sure that your shortcode has been found, where you can be sure that your scripts are needed.

假设您的插件需要替换短代码的代码使用的一些脚本。 没有任何操作或过滤器可以精确定位您的短代码。 但是在某个地方，您可以确保找到了您的短代码，并且可以在其中确保需要脚本。

This place is the callback function called by WordPress each time your shortcode is found. Call wp_enqueue_script() into this callback function and your scripts won’t be included unless there are needed.

每次找到您的短代码时，此地方就是WordPress调用的回调函数。 在此回调函数中调用wp_enqueue_script()除非需要，否则不会包含您的脚本。

But, what if your shortcode has been found twice or more? The answer is simple: nothing.

但是，如果您的简码被发现两次或更多次怎么办？ 答案很简单：没有。

In fact, try to call the wp_enqueue_script() function twice, with the same script: this script will only be included once, and that’s why this function is a very good tool.

实际上，请尝试使用相同的脚本两次调用wp_enqueue_script()函数：该脚本仅被包含一次，因此这是一个非常好的工具。

So you can insert this call into your callback function or into every other part of your plugin or theme where you can be sure that your scripts are needed: even if they are needed several times, they will only be included once.

因此，您可以将此调用插入回调函数或插件或主题的所有其他部分，以确保需要使用脚本：即使多次需要使用它们，它们也只会被包含一次。

Note that, depending on the place where your wp_enqueue_script() call is done, it can be too late to ask WordPress to include them into the head tag: your only choice will be the footer. If your script must be in the head tag for an obscure reason, think about it.

请注意，根据完成wp_enqueue_script()调用的位置，要求WordPress将它们包括在head标签中可能为时已晚：您唯一的选择将是页脚。 如果您的脚本出于某种晦涩的原因而必须放在head标记中，请考虑一下。

Maybe you have a question now: when is it too late?

也许您现在有一个问题：什么时候为时已晚？

Every theme must use two specific functions: wp_head() and wp_footer(). When the former is called, WordPress will add automatically all the lines needed in the head tag: if you asked for the inclusion of your scripts in the head tag, they will be included when wp_head() is called, so if you ask this inclusion after the wp_head() call, your scripts won’t be included in the head tag.

每个主题必须使用两个特定的函数： wp_head()和wp_footer() 。 调用前者时，WordPress将自动添加head标记中所需的所有行：如果您要求将脚本包含在head标记中，则在wp_head()时将包含它们，因此，如果您要求包含在wp_head()调用之后，您的脚本将不会包含在head标签中。

But WordPress is smart, and your scripts will still be included: you will be able to retrieve them in the footer, when the wp_footer() function is called and when the scripts which must be included at this place are included.

但是WordPress很聪明，并且您的脚本仍将包括在内：当wp_footer()函数以及必须包含在此位置的脚本时，您将可以在页脚中检索它们。

So you have your answer: if you absolutely want to include your script in the head tag, ask for the inclusion before the wp_head() call which should be at the end of the head tag in the theme. The wp_footer() call should be at the very end of the document, before the end of the body tag.

因此，您有一个答案：如果您绝对希望将脚本包含在head标记中，请在wp_head()调用之前要求将其包含在主题中的head标记的末尾。 wp_footer()调用应位于文档的末尾，位于body标记的末尾。

结论 (Conclusion)

Your scripts are useful for what your plugin or theme does in a specific place, but including them into pages where they are not needed will make this same pages unnecessarily heavier.

您的脚本对于您的插件或主题在特定位置的作用很有用，但将脚本包含在不需要的页面中会使这些页面不必要地变重。

WordPress provides us with several tools to let us include our scripts properly, only when they are needed. The only question to ask when you want to use these tools is the following: when or where are my scripts needed? The rest depends on the answer: finding an action or a filter, placing the wp_enqueue_script() call into the right function, using the power of this function, or combining all of that.

WordPress为我们提供了几种工具，让我们仅在需要时才正确包含脚本。 何时要使用这些工具时要问的唯一问题是：什么时候需要我的脚本？ 其余的取决于答案：找到一个动作或一个过滤器，将wp_enqueue_script()调用放到正确的函数中，使用此函数的功能，或将所有这些功能组合在一起。

You can retrieve some examples described above in a test plugin available right here. It enqueues a script and a ‘library’, and it creates a shortcode using another useless script.

您可以在此处提供的测试插件中检索上述示例。 它排队一个脚本和一个“库”，并使用另一个无用的脚本创建一个简码。

翻译自: https://www.sitepoint.com/including-javascript-in-plugins-or-themes/

javascript插件