云策 WordPress 开发者社区

插件开发文档

确定插件和内容目录

查看官方原文 ↗
💡 云策文档标注

概述

本文档介绍了在WordPress插件开发中如何正确引用文件和目录路径，避免硬编码。WordPress提供了多种函数来动态获取插件、主题和核心目录的路径和URL，确保兼容性，特别是当用户自定义wp-content目录位置时。

关键要点

  • 使用WordPress提供的函数（如plugins_url()、plugin_dir_path()）来获取路径和URL，而不是硬编码wp-content目录或使用内部常量。
  • WordPress允许用户自定义wp-content目录的位置和名称，因此不能假设插件、上传或主题目录在默认位置。
  • PHP的__FILE__常量能自动解析符号链接，但硬编码路径在符号链接情况下可能失效，应使用WordPress函数。
  • 常见用例包括使用plugins_url()获取插件文件的URL，并结合wp_enqueue_script()或wp_enqueue_style()加载JavaScript或CSS文件。
  • WordPress提供了多种函数用于插件、主题、站点主页、WordPress核心和多站点环境，如get_template_directory_uri()、home_url()、admin_url()等。
  • 避免直接使用WP_CONTENT_DIR、WP_CONTENT_URL等常量，这些仅供内部使用，插件和主题应依赖函数。

代码示例

plugins_url( 'myscript.js', __FILE__ );
📄 原文内容

When coding WordPress plugins you often need to reference various files and folders throughout the WordPress installation and within your plugin or theme.

WordPress provides several functions for easily determining where a given file or directory lives. Always use these functions in your plugins instead of hard-coding references to the wp-content directory or using the WordPress internal constants.

WordPress allows users to place their wp-content directory anywhere they want and rename it whatever they want. Never assume that plugins will be in wp-content/plugins, uploads will be in wp-content/uploads, or that themes will be in wp-content/themes.

PHP’s __FILE__ magic-constant resolves symlinks automatically, so if the wp-content or wp-content/plugins or even the individual plugin directory is symlinked, hardcoded paths will not work correctly.

Common Usage

If your plugin includes JavaScript files, CSS files or other external files, then it’s likely you’ll need the URL to these files so you can load them into the page. To do this you should use the plugins_url() function like so:

plugins_url( 'myscript.js', __FILE__ );

This will return the full URL to myscript.js, such as example.com/wp-content/plugins/myplugin/myscript.js.

To load your plugins’ JavaScript or CSS into the page you should use wp_enqueue_script() or wp_enqueue_style() respectively, passing the result of plugins_url() as the file URL.

Available Functions

WordPress includes many other functions for determining paths and URLs to files or directories within plugins, themes, and WordPress itself. See the individual DevHub pages for each function for complete information on their use.

Plugins

plugins_url()
plugin_dir_url()
plugin_dir_path()
plugin_basename()

Themes

get_template_directory_uri()
get_stylesheet_directory_uri()
get_stylesheet_uri()
get_theme_root_uri()
get_theme_root()
get_theme_roots()
get_stylesheet_directory()
get_template_directory()

Site Home

home_url()
get_home_path()

WordPress

admin_url()
site_url()
content_url()
includes_url()
wp_upload_dir()

Multisite

get_admin_url()
get_home_url()
get_site_url()
network_admin_url()
network_site_url()
network_home_url()

Constants

WordPress makes use of the following constants when determining the path to the content and plugin directories. These should not be used directly by plugins or themes, but are listed here for completeness.

WP_CONTENT_DIR  // no trailing slash, full paths only
WP_CONTENT_URL  // full url 
WP_PLUGIN_DIR  // full path, no trailing slash
WP_PLUGIN_URL  // full url, no trailing slash

// Available per default in MS, not set in single site install
// Can be used in single site installs (as usual: at your own risk)
UPLOADS // (If set, uploads folder, relative to ABSPATH) (for e.g.: /wp-content/uploads)

WordPress Directories:

home_url() Home URL http://www.example.com
site_url() Site directory URL http://www.example.com or http://www.example.com/wordpress
admin_url() Admin directory URL http://www.example.com/wp-admin
includes_url() Includes directory URL http://www.example.com/wp-includes
content_url() Content directory URL http://www.example.com/wp-content
plugins_url() Plugins directory URL http://www.example.com/wp-content/plugins
wp_upload_dir() Upload directory URL (returns an array) http://www.example.com/wp-content/uploads