城市简码

什么是简码？ (What Are Shortcodes?)

Shortcodes are a convenient method that WordPress implements which provides a way to generate dynamic and often complex functionality from very little input.

短代码是WordPress实现的一种便捷方法，它提供了一种通过很少的输入生成动态且通常为复杂功能的方法。

While developers often create functionality to provide additional features for a website; they are executed by calling PHP code. Users however, are often not developers, and as such having them interact directly with PHP is not recommended. A solution to this is for developers to create custom shortcodes.

开发人员经常创建功能来为网站提供其他功能； 它们通过调用PHP代码执行。 但是，用户通常不是开发人员，因此不建议让他们直接与PHP交互。 解决方案是让开发人员创建自定义的简码。

Shortcodes provide a level of dynamic content for the user, allowing them to create power features on their website by using pseudo-code that act similar to macros. The shortcode when called will take its arguments (if any) and then run through a function which defines what custom functionality will occur.

简码为用户提供了一定程度的动态内容，从而使他们可以通过使用类似于宏的伪代码在自己的网站上创建强大的功能。 短代码在被调用时将接受其参数(如果有的话)，然后运行通过定义将发生哪些自定义功能的函数。

For example, you may have a basic shortcode that is wrapped around your links to create a pretty button: [pretty_button] Read More! [/pretty_button]

例如，您可能在链接周围包裹了一个基本的短代码，以创建一个漂亮的按钮： [pretty_button] Read More! [/pretty_button] [pretty_button] Read More! [/pretty_button]

谁创建简码？ (Who Creates Shortcodes?)

Shortcodes have to be registered on your website in order for them to be used. There are several ways in which shortcodes can be added to your website, here are a few common methods.

短代码必须在您的网站上注册才能使用。 可以将简码添加到您的网站的几种方法，以下是一些常用方法。

由WordPress本身添加 (Added by WordPress Itself)

WordPress actually comes with a series of shortcodes already defined. These shortcodes are generally used for galleries, captions, audio and video elements and mostly related to the media side of WordPress.

WordPress实际上带有一系列已经定义的短代码。 这些短代码通常用于画廊，字幕，音频和视频元素，并且大多与WordPress的媒体方面有关。

For example, you may want to display an inline video player on your page. By using the video shortcode as follows [video src="video-source.mp4"] you can define that a video player will be outputted on your page / post.

例如，您可能要在页面上显示嵌入式视频播放器。 通过如下使用视频短代码[video src="video-source.mp4"]您可以定义视频播放器将输出到您的页面/帖子上。

There are several shortcodes that are documented on the WordPress codex page

WordPress Codex页面上记录了一些短代码

内置到主题中 (Inbuilt into a Theme)

A lot of theme developers will provide a series of shortcodes that you can use to add a lot of extra functionality to your website. These shortcodes may create interactive elements, display content in visually stunning ways or be very informational.

许多主题开发人员将提供一系列短代码，您可以使用这些短代码为网站添加很多额外的功能。 这些短代码可能会创建交互元素，以视觉上令人惊叹的方式显示内容，或者是非常有用的信息。

When purchasing themes or using popular free themes, the developer will often provide a page on their website that outlines their included shortcodes (along with how to use them and examples). In addition, the theme even may include a shortcode button on the content editor (which allows a simple way to insert your shortcode)

购买主题或使用流行的免费主题时，开发人员通常会在其网站上提供一个页面，概述其包含的短代码(以及如何使用它们和示例)。 另外，主题甚至可以在内容编辑器上包括一个简码按钮(这允许插入简码的简单方法)

However, a theme may also have no extra shortcodes at all.

但是，主题可能也根本没有多余的短代码。

带有插件 (Comes with a Plugin)

Most plugins that offer some sort of content (such as forms, sliders, interactive elements) will come with a shortcode that you either configure on a case by case basis (you add the options inside the shortcode on the desired page) or is configured globally (inside a plugins theme menu for example).

大多数提供某种内容(例如表单，滑块，交互式元素)的插件都会附带一个简短代码，您可以根据具体情况进行配置(在所需页面的简短代码中添加选项)或全局配置(例如，在插件主题菜单中)。

These plugin shortcodes often are well documented on the developers website or the plugin repository for WordPress, giving you an instant idea of what exactly you can do with your shortcode.

这些插件简码通常在开发人员网站或WordPress的插件存储库中都有很好的文档，可让您立即了解使用简码可以做什么。

For example, you may want to show your product cart on a WooCommerce powered website, you could do this by using their cart shortcode [woocommerce_cart]. These shortcodes are outlined on their shortcode documented page.

例如，您可能想在WooCommerce支持的网站上显示您的产品购物车，可以使用其购物车[woocommerce_cart] 。 这些简码在其简码文档页面上概述。

简码类型 (Types of Shortcodes)

Now that you know what shortcodes are and how they can be added to your website, we can discuss the two different types of shortcodes and how they differ.

既然您知道什么是简码以及如何将它们添加到您的网站，我们就可以讨论两种不同类型的简码以及它们之间的区别。

非封闭式简码 (Non Enclosed Shortcodes)

Non Enclosed shortcodes are shortcodes that do not contain or wrap other content. These shortcodes exist as a single self closed unit.

非封闭式简码是不包含或包装其他内容的简码。 这些短代码以单个自封闭单元的形式存在。

For example, say you wanted to display a gallery in your post, you would use the [gallery] shortcode. This shortcode would execute and display a gallery that would be outputted on the page.

例如，假设您想在帖子中显示图库，则可以使用[gallery]短代码。 该短代码将执行并显示将在页面上输出的图库。

See how the shortcode exists as a single unit, this is a non enclosed shortcode. These types of shortcodes are similar to self closing HTML elements (such as the <br/> tag)

查看简码如何作为一个整体存在，这是一个非封闭的简码。 这些类型的短代码类似于自动关闭HTML元素(例如<br/>标记)

封闭的简码 (Enclosed Shortcodes)

Enclosed shortcodes are shortcodes that contain other elements or content. These shortcodes look similar to the non enclosed variety of shortcodes, but they will have a beginning and end element.

封闭的简码是包含其他元素或内容的简码。 这些短代码看起来与非封闭的各种短代码相似，但是它们将具有一个begin和end元素。

For example, say that you wanted some text on your page to stand out. You could define a shortcode that takes its wrapped content and applies a set style (such as making it bolder or bigger).

例如，假设您希望页面上的某些文本突出显示。 您可以定义一个短代码，该短代码采用其包装的内容并应用设置的样式(例如使其变粗或变大)。

A shortcode defined as [big_and_bold] when applied to content could look similar to this [big_and_bold] This is big and bold [/big_and_bold]

当应用于内容时，定义为[big_and_bold]简码可能与此类似[big_and_bold] This is big and bold [/big_and_bold]

Notice how we have a start tag and an end tag? All of the content between there will be passed into the shortcode and processed in some way.

注意我们如何有一个开始标签和一个结束标签？ 两者之间的所有内容都将传递到短代码中，并以某种方式进行处理。

Overall, when you are dealing with shortcodes you will deal with one of these two types.

总的来说，当您处理短代码时，将处理这两种类型之一。

创建自己的简码 (Creating Your Own Shortcodes)

Creating shortcodes for use in WordPress is fairly straightforward. It involves a callback function that defines what the shortcode will do and the use of the add_shortcode($name,$callback_function) function that registers the shortcode for use.

创建在WordPress中使用的简码非常简单。 它涉及一个回调函数，该函数定义了短代码将要执行的操作以及add_shortcode($name,$callback_function)函数的使用，该函数注册了要使用的短代码。

To register your own shortcodes you will need to place them inside your functions.php file inside your child theme (or if you have another file that has access to PHP you can use this also).

要注册自己的简码，您需要将它们放置在子主题内的functions.php文件中(或者，如果您有另一个可以访问PHP的文件，您也可以使用此代码)。

Remember to never edit a parent theme directly!

记住不要直接编辑父主题！

定义简码回调函数 (Defining the Shortcodes Callback Function)

The functionality that a shortcode performs is defined inside the callback function.

简码执行的功能在回调函数中定义。

The callback function returns a value and that value is what is displayed to the end user when generating their page/post. This returned value might just be a value wrapped in a container for styling, or it may be as complex as outputting a dynamic form element or slider.

回调函数返回一个值，该值是最终用户在生成其页面/帖子时所显示的值。 此返回值可能只是包装在容器中以进行样式设置的值，或者可能与输出动态表单元素或滑块一样复杂。

The structure of a callback function in its simplest sense is just a function that returns a value:

从最简单的意义上讲，回调函数的结构只是一个返回值的函数：

//defines the callback function used for our shortcode (does nothing)
function my_shortcode_callback_function(){
return;
}

回调函数中的简码参数 (Shortcodes Arguments in the Callback Function)

While shortcodes just need a callback function to operate; shortcodes can take arguments (options) that can be used to dynamically change how the shortcode functions.

简码只需要一个回调函数即可操作； 简码可以带有可用于动态更改简码功能的参数(选项)。

There are three main arguments that can be passed into the function that displays the shortcode. These variables are all optional but are frequently used. These variables are $atts, $content and $name; they are called sequentially into the call back functions as such:

可以将三个主要参数传递给显示短代码的函数。 这些变量都是可选的，但经常使用。 这些变量是$atts ， $content和$name ； 它们被依次调用到回调函数中，如下所示：

//defines the callback function used for our shortcode (does nothing). Takes in three arguments
function my_shortcode_callback_function($atts, $content, $name){
return;
}

$ atts(选项) ($atts (the options))

The $attsvariable is an associative array of options or settings that you would like your shortcode to have access to.

$atts变量是您希望您的短代码可以访问的选项或设置的关联数组。

Shortcodes will often provide the user with a series of settings which they can pass into the shortcode to give them the ability to alter the output.

简码通常会为用户提供一系列设置，他们可以将其传递给简码，以使他们能够更改输出。

For example, consider the inbuilt audio shortcode .

例如，考虑内置音频简码 。

This shortcode (since WordPress 3.6) gives the user the ability to embed a HTML5 audio player into the page.

此短代码(自WordPress 3.6起)使用户能够将HTML5音频播放器嵌入到页面中。

By default you can use the shortcode just as it is. However you can also customise its options by passing in arguments such as the following . This allows you to set the audio to pre-load as soon as the page loads, along with automatically triggering the audio (and once the audio is finished it will loop). These settings along with others can be customised by passing in values.

默认情况下，您可以使用 简码原样。 但是，您也可以通过传入以下参数来自定义其选项 。 这使您可以将音频设置为在页面加载后立即预加载，以及自动触发音频(音频完成后将循环播放)。 这些设置以及其他设置可以通过传入值进行自定义。

Let’s go through a basic example where we want a shortcode that takes in an option and outputs content conditionally based on its selection:

让我们看一个基本的示例，在该示例中，我们需要一个短代码，该短代码接受一个选项并根据其选择有条件地输出内容：

//based on the passed in profession, return a statement
//Shortcodes functions and information
function display_my_profession_callback($atts,$content,$tag){
//collect values, combining passed in values and defaults
$values = shortcode_atts(array(
'profession_type' => 'other'
),$atts);
//based on input determine what to return
$output = '';
if($values['profession_type'] == 'developer'){
$output = 'You are an amazing developer!';
}
else if($values['profession_type'] == 'designer'){
$output = 'You are an epic designer!';
}
else if($values['profession_type'] == 'other'){
$output = 'You are a great person';
}
else{
$output = 'I am not sure what you are';
}
return $output;
}
add_shortcode('display_profession','display_my_profession_callback');

The first thing you will see is that we called a function named shortcode_atts(). This function is used to return an associative array of values for you to use. This function takes in your $atts variable and also defines nice default options for you to use (this takes the hassle out of merging arrays and controlling data yourself).

您会看到的第一件事是我们调用了一个名为shortcode_atts()的函数。 此函数用于返回值的关联数组供您使用。 此函数接受$atts变量，还定义了不错的默认选项供您使用(这消除了合并数组和自己控制数据的麻烦)。

In our example $values will have access to one value called profession_type, however, if we defined more default values we could also access them.

在我们的示例中， $values可以访问一个称为profession_type值，但是，如果我们定义更多的默认值，我们也可以访问它们。

The default value for profession_type is other. This value can be over-ridden in the shortcode itself by simply supplying a value, for example [display_profession type='designer']

为默认值profession_type是other 。 只需提供一个值即可在短代码本身中覆盖此值，例如[display_profession type='designer']

Once we determine the value for profession_type we format a string and return it for display to the end user.

一旦确定了profession_type的值，便会格式化字符串并将其返回以显示给最终用户。

$ content(内容) ($content (the content))

The $content variable is used for enclosed shortcodes and this value represents any content that exists between the opening and closing tag of the shortcode.

$content变量用于enclosed shortcodes ，此值表示在简码的开始和结束标记之间存在的任何内容。

For example, if you have a shortcode that makes selected text really small such as [small_text] This text will be small [/small_text]. The value of $content will be ‘This text will be small’. This variable gives the shortcode access to the content and it is how shortcodes directly apply styles and functionality to the selected areas.

例如，如果您有一个使所选文本非常小的简码，例如[small_text] This text will be small [/small_text] 。 $content的值将为“此文本将很小”。 此变量使短代码可以访问内容，这是短代码如何将样式和功能直接应用于所选区域的方式。

Let’s look at a coding example to illustrate this.

让我们看一个编码示例来说明这一点。

We can create a shortcode that takes in its wrapped around content and formats it via a span tag:

我们可以创建一个短代码，将其包裹在内容中并通过span标签对其进行格式化：

//take the wrapped around content of the shortcode and style it
function wrap_content_shortcode_callback($atts, $content, $tag){
$output = '<span style="font-size: 120%;">' . $content . '</span>';
return $output;
}
add_shortcode('wrap_shortcode','wrap_content_shortcode_callback');

The returned content will be styled differently, wrapped around by a span.

返回的内容将设置为不同的样式，并用跨度环绕。

On a related note, if you are creating shortcodes that use the $content variable, you can also use the do_shortcode($content) function. This function will take the content and run any other shortcodes inside of it. If you don’t include this and you wrap a shortcode inside another shortcode, the inner most shortcode will simply display text instead of being transformed.

与此相关的是，如果要创建使用$content变量的短代码，则还可以使用do_shortcode($content)函数。 此函数将获取内容并在其中运行任何其他短代码。 如果您不包含此代码，而是将一个短代码包装在另一个短代码中，则最里面的短代码将仅显示文本，而不进行转换。

$ tag(简码名称) ($tag (the shortcode name))

The $tag variable contains the name of the shortcode itself. This is often used for shortcodes that share the same callback function.

$tag变量包含简码本身的名称。 这通常用于共享相同回调函数的短代码。

When you define multiple shortcodes and use the same function to handle all of them you can use the $tag variable to distinguish what shortcode is being called.

当您定义多个短代码并使用相同的函数来处理所有短$tag可以使用$tag变量来区分正在调用的短$tag 。

Let’s look at a practical example where a single callback function is used for two shortcodes:

让我们看一个实际的示例，其中一个回调函数用于两个短代码：

//this callback function performs many actions depending on which shortcode ($tag) calls it
function display_my_shortcode($atts, $content, $tag){
//if called from the 'my_primary_shortcode' shortcode
if($tag == 'my_primary_shortcode'){
return 'This is the primary shortcode';
}
//if called from the 'my_secondary_shortcode' shortcode
else if($tag == 'my_secondary_shortcode'){
return 'This is the secondary shortcode';
}
//default
else{
return 'This is something else';
}
}
add_shortcode('my_primary_shortcode','display_my_shortcode');
add_shortcode('my_secondary_shortcode','display_my_shortcode');

Depending on what shortcode you call (either [my_primary_shortcode] or [my_secondary_shortcode] the content will differ.

根据您调用的短代码( [my_primary_shortcode]或[my_secondary_shortcode] ，内容会有所不同。

使用add_shortcode()函数注册简码 (Registering the shortcode with the add_shortcode() function)

To register a shortcode all you need to do is call the add_shortcode($name, $callback_name) function.

要注册一个简码，您需要做的就是调用add_shortcode($name, $callback_name)函数。

This function takes two parameters; the name of the shortcode (the name that will be used in the editor) and the name of the callback function that returns the output (that does the actual processing)

该函数有两个参数： 简码的名称(将在编辑器中使用的名称)和返回输出的回调函数的名称(进行实际处理)

As an example, look at the following:

例如，请查看以下内容：

//callback function for the 'clear_content' shortcode
function clear_content_callback_function($atts, $content, $tag){
return '<div style="clear: both; float: left">' . $content '</div>';
}
//add the new 'clear_content' shortcode
add_shortcode('clear_content','clear_content_callback_function');

The shortcode name itself should be all lowercase and with only digits and underscores.

短代码名称本身应全部为小写字母，并且只能包含数字和下划线。

There have been long standing issues with the use of hyphens in shortcodes so I would simply define your shortcodes without them, but you are free to do so if you are feeling adventurous.

在短代码中使用连字符存在长期存在的问题，因此我将简单地在没有短代码的情况下定义您的短代码，但是如果您喜欢冒险，可以随意这样做。

结论 (In Conclusion)

Now that you have a thorough understanding of how shortcodes work and how they can be used to provide non developers with extensible options, you can create your own shortcodes and really extend your upcoming WordPress websites.

现在，您已经对短代码如何工作以及如何使用它们为非开发人员提供可扩展的选项有了透彻的了解，您可以创建自己的短代码并真正扩展即将到来的WordPress网站。

翻译自: https://www.sitepoint.com/custom-shortcodes-for-wordpress/

城市简码