內容簡介
WordPress原生支援特色圖片，使得使用者可以用不同的方式來將圖片與文章做結合，以符合所使用佈景主題的需求。本外掛可類似地支援音訊特色，讓所有使用WordPress來發佈音訊的人，都能以更有結構性的方式，在文章或頁面中特色呈現音訊檔案。每個文章和頁面都會有一個「特色音訊 metabox」，用戶可以透過這個方塊，上傳或從媒體庫中選擇要顯示特色的音訊檔案。
預設情況下，特色音訊會顯示在文章或頁面的頂部（在 the_content 內）。開發人員可以透過以下幾種 API 函數，新增佈景主題對於特色音訊的相關支援：
為何要使用特色音訊而非直接將音訊嵌入文章中呢？透過特色音訊的結構方式，可以使得您能夠隨意地自定義用戶在您的網站中聆聽音訊所體驗的方式，而具有無窮的可能性。本外掛附帶了一個特色音訊播放清單 widget 的例子，只要將此 widget 加入側邊欄，它就會自動顯示目前可以檢視到的所有已發佈文章中所顯示的音訊播放清單（如在主網誌頁面或類別頁面中顯示多則文章的檢視畫面）；本外掛也支援最新音訊播放清單 widget，操作方式類似於最新文章 widget。
如果您需要更全面的方法來進行WordPress音樂管理，特別是需要在音訊旁邊加入譜面，可以參考Sheet Music Library外掛。
以下為開發人員所使用的API函數：
新增佈景主題支援
add_theme_support( 'featured-audio' )
透過新增佈景主題的特色音訊支援，即可決定是否要讓本外掛自動在內容中新增特色音訊。如果不想要，您可以透過 the_featured_content() 函數 (詳細請參閱以下內容) 在文章中特別指定位置新增特色音訊。
更改支援的文章類型
預設支援「文章」和「頁面」的文章類型。您可以使用 featured_audio_post_types 中所提供的過濾器來修改該列表，例如：
add_filter( 'featured_audio_post_types', 'prefix_featured_audio_post_types' );
function prefix_featured_audio_post_types( $post_types ) {
//新增對 sheet_music 文章類型的支援
$post_types[] = 'sheet_music';
// 覆寫整個列表，並刪除頁面支援
$post_types = array( 'post' );
return $post_types;
}
the_featured_audio( $args )
透過這個函數可顯示特色音訊，假如它存在於文章中。
參數：
$args array 顯示選項。
$args['id'] int 文章ID（選用）。預設值為目前文章ID。
$args['album_art'] boolean 是否顯示特色音訊的唱片封面圖片。預設值：false。
$args['album_art_size'] string 唱片封面圖片的尺寸。預設值：縮略圖。
$args['title'] boolean 是否顯示音訊附件標題。預設值為 false。
get_the_featured_audio( $args )
透過此函數可取得特色音訊，假如它存在於文章中，並且以字串的方式呈現，與 the_featured_audio() 函數具有相同參數。
get_featured_audio_src( $id )
如果存在特色音訊檔案，此函數可回傳特色音訊檔案的URL。
參數：
$id int 文章ID（選用）。預設值為目前文章ID。
get_featured_audio_attachment_id( $id )
如果存在特色音訊附件，此函數可回傳該音訊附件的ID。
參數：
$id int 文章ID（選用）。預設值為目前文章ID。
get_the_featured_audio_playlist()
此函數會回傳可以顯示的最新音訊播放清單。
外掛標籤
開發者團隊
原文外掛簡介
WordPress supports featured images out of the box, allowing images to represent posts in various ways defined by the theme. This plugin adds similar support for audio, allowing musicians, podcasters, and anyone who publishes audio with WordPress to feature audio files on posts and pages in a structured way. Each post and page gets a featured audio metabox where an audio file can be uploaded or selected from the media library.
By default, featured audio is displayed at the top of posts and pages (within the_content). Developers can change this by adding theme support for featured-audio, via several API functions listed below.
Why use featured audio instead of embeding audio directly into posts? Featured audio organizes the content in a structured way, alowing infinite possibilities to customize the way users experience audio content on your site. The plugin ships with one example of this – the featured audio playlist widget. Add this widget to your sidebar and it’ll automatically display a playlist of all of the audio files featured on posts shown on the current view, on views with more than one post such as the main blog page or a category page. The plugin also supports a recent audio playlist widget, which behaves similarly to a latest posts widget.
For a more comprehensive way to manage music with WordPress, particularly if you need to include sheet music alongisde audio, see the Sheet Music Library plugin.
Developer API Functions
Add Theme Support
add_theme_support( 'featured-audio' )
Adding theme support for featured audio tells the plugin not to add the featured audio to the content automatically. Instead, you can add featured audio exactly where you want it with the_featured_content() (see below for details).
Change Supported Post Types
By default, the post and page post types are supported. You can use the featured_audio_post_types filter to modify this list. For example:
add_filter( 'featured_audio_post_types', 'prefix_featured_audio_post_types' );
function prefix_featured_audio_post_types( $post_types ) {
// Add support to the sheet_music post type.
$post_types[] = 'sheet_music';
// Overwrite the entire list to remove support on pages.
$post_types = array( 'post' );
return $post_types;
}
the_featured_audio( $args )
Display the featured audio, if it exists.
Parameters:
$args array Display options.
$args['id'] int Post id (optional). Defaults to current post id.
$args['album_art'] boolean Whether to display the album art for the featured audio cycle. Default: false.
$args['album_art_size'] string Size to use for the album art picture. Default: thumbnail.
$args['title'] boolean Whether to display the title of the audio attachment. Default: false.
get_the_featured_audio( $args )
Get the featured audio, if it exists, as a string. Has the same arguments as the_featured_audio().
get_featured_audio_src( $id )
Returns the url of the featured audio file, if it exists.
Parameter:
$id int Post id (optional). Defaults to current post id.
get_featured_audio_attachment_id( $id )
Returns the id of the featured audio attachment, if it exists.
Parameter:
$id int Post id (optional). Defaults to current post id.
get_the_featured_audio_playlist()
Get the featured audio playlist, if there are multiple posts with featured audio in the current query. Used by the featured audio playlist widget.
the_featured_audio_playlist()
Displays (echoes) get_the_featured_audio_playlist().
