wp_media_insert_url_form()
云策文档标注
概述
wp_media_insert_url_form() 函数用于生成插入外部 URL 媒体(如图像、音频、视频等)的表单 HTML 内容。它根据默认视图参数(如 'image')动态构建表单元素,包括 URL、标题、替代文本、对齐方式等字段,并集成 WordPress 核心功能如翻译、过滤器和选项处理。
关键要点
- 函数返回一个字符串,包含完整的 HTML 表单,用于从外部 URL 插入媒体到 WordPress 内容中。
- 接受一个可选参数 $default_view,默认值为 'image',用于控制表单的视图类型(如 'image-only' 或 'not-image')。
- 内部使用多个 WordPress 核心函数,如 get_option() 获取默认对齐设置,apply_filters() 处理 'disable_captions' 过滤器以决定是否显示标题字段。
- 表单包含必填字段指示器(通过 wp_required_field_indicator() 和 wp_required_field_message() 生成),以及提交按钮(通过 get_submit_button() 生成)。
- 支持多语言翻译,使用 __() 函数对文本进行本地化处理。
- 该函数自 WordPress 2.7.0 版本引入,并被多个已弃用的函数(如 type_url_form_image())调用,用于处理不同类型的媒体插入。
代码示例
function wp_media_insert_url_form( $default_view = 'image' ) {
/** This filter is documented in wp-admin/includes/media.php */
if ( ! apply_filters( 'disable_captions', '' ) ) {
$caption = '<tr><th scope="row" class="label"><label for="caption">' . __( 'Image Caption' ) . '</label></th><td class="field"><textarea id="caption" name="caption"></textarea></td></tr>';
} else {
$caption = '';
}
$default_align = get_option( 'image_default_align' );
if ( empty( $default_align ) ) {
$default_align = 'none';
}
if ( 'image' === $default_view ) {
$view = 'image-only';
$table_class = '';
} else {
$view = 'not-image';
$table_class = $view;
}
return '<div class="media-upload-form-type-url"><h3 class="media-title">' . __( 'Insert from URL' ) . '</h3><div id="media-type-selector" class="hide-if-no-js"><input type="radio" name="media_type" value="image" id="image-only" ' . checked( 'image-only', $view, false ) . '/><label for="image-only">' . __( 'Image' ) . '</label> <input type="radio" name="media_type" value="audio" id="not-image" ' . checked( 'not-image', $view, false ) . '/><label for="not-image">' . __( 'Audio, Video, or Other File' ) . '</label></div>' .
wp_required_field_message() .
'<table class="describe ' . $table_class . '"><tbody><tr><th scope="row" class="label"><label for="src">' . __( 'URL' ) . ' ' . wp_required_field_indicator() . '</label></th><td class="field"><input id="src" name="src" value="" type="url" required /></td></tr><tr><th scope="row" class="label"><label for="title">' . __( 'Title' ) . ' ' . wp_required_field_indicator() . '</label></th><td class="field"><input id="title" name="title" value="" type="text" /></td></tr><tr><td colspan="2" class="help">' . __( 'Link text, e.g. “Ransom Demands (PDF)”' ) . '</td></tr><tr><th scope="row" class="label"><label for="alt">' . __( 'Alternative Text' ) . ' ' . wp_required_field_indicator() . '</label></th><td class="field"><input id="alt" name="alt" value="" type="text" /></td></tr><tr><td colspan="2" class="help">' . __( 'Alt text for the image, e.g. “The Mona Lisa”' ) . '</td></tr>' . $caption . '<tr><th scope="row" class="label"><label>' . __( 'Alignment' ) . '</label></th><td class="field"><fieldset><legend class="screen-reader-text">' . __( 'Alignment' ) . '</legend><input name="align" id="align-none" value="none" type="radio" ' . checked( 'none', $default_align, false ) . '/><label for="align-none">' . __( 'None' ) . '</label><input name="align" id="align-left" value="left" type="radio" ' . checked( 'left', $default_align, false ) . '/><label for="align-left">' . __( 'Left' ) . '</label><input name="align" id="align-center" value="center" type="radio" ' . checked( 'center', $default_align, false ) . '/><label for="align-center">' . __( 'Center' ) . '</label><input name="align" id="align-right" value="right" type="radio" ' . checked( 'right', $default_align, false ) . '/><label for="align-right">' . __( 'Right' ) . '</label></fieldset></td></tr><tr><th scope="row" class="label"><label for="url">' . __( 'Link Image To:' ) . '</label></th><td class="field"><input id="url" name="url" value="" type="url" /></td></tr><tr><td colspan="2" class="help">' . __( 'None' ) . '<br />' . __( 'Link to image' ) . '<br />' . __( 'Enter a link URL or click above for presets.' ) . '</td></tr></tbody></table><div class="media-toolbar"><div class="media-toolbar-secondary"><a href="#" class="button">' . __( 'Cancel' ) . '</a></div><div class="media-toolbar-primary">' . get_submit_button( __( 'Insert into Post' ), '', 'insertonlybutton', false ) . '</div></div></div>';
}注意事项
- 该函数生成的表单主要用于 WordPress 后台的媒体上传界面,开发者不应直接在前端调用,除非自定义媒体处理流程。
- 参数 $default_view 影响表单的初始显示状态,例如设置为 'image' 时,表单默认选中图像类型,并可能隐藏某些非图像相关字段。
- 函数内部依赖多个全局设置和过滤器,如 'disable_captions' 过滤器可以控制是否显示标题字段,需确保这些钩子被正确配置。
- 由于该函数返回大量 HTML 字符串,在性能敏感场景中应谨慎使用,避免不必要的重复调用。
- 相关函数如 type_url_form_image() 已被标记为已弃用(deprecated),建议在新开发中直接使用 wp_media_insert_url_form() 或参考其实现。
原文内容
Creates the form for external url.
Parameters
$default_viewstringrequired
Source
function wp_media_insert_url_form( $default_view = 'image' ) {
/** This filter is documented in wp-admin/includes/media.php */
if ( ! apply_filters( 'disable_captions', '' ) ) {
$caption = '
<tr class="image-only">
<th scope="row" class="label">
<label for="caption"><span class="alignleft">' . __( 'Image Caption' ) . '</span></label>
</th>
<td class="field"><textarea id="caption" name="caption"></textarea></td>
</tr>';
} else {
$caption = '';
}
$default_align = get_option( 'image_default_align' );
if ( empty( $default_align ) ) {
$default_align = 'none';
}
if ( 'image' === $default_view ) {
$view = 'image-only';
$table_class = '';
} else {
$view = 'not-image';
$table_class = $view;
}
return '
<p class="media-types"><label><input type="radio" name="media_type" value="image" id="image-only"' . checked( 'image-only', $view, false ) . ' /> ' . __( 'Image' ) . '</label> <label><input type="radio" name="media_type" value="generic" id="not-image"' . checked( 'not-image', $view, false ) . ' /> ' . __( 'Audio, Video, or Other File' ) . '</label></p>
<p class="media-types media-types-required-info">' .
wp_required_field_message() .
'</p>
<table class="describe ' . $table_class . '"><tbody>
<tr>
<th scope="row" class="label" style="width:130px;">
<label for="src"><span class="alignleft">' . __( 'URL' ) . '</span> ' . wp_required_field_indicator() . '</label>
<span class="alignright" id="status_img"></span>
</th>
<td class="field"><input id="src" name="src" value="" type="text" required onblur="addExtImage.getImageData()" /></td>
</tr>
<tr>
<th scope="row" class="label">
<label for="title"><span class="alignleft">' . __( 'Title' ) . '</span> ' . wp_required_field_indicator() . '</label>
</th>
<td class="field"><input id="title" name="title" value="" type="text" required /></td>
</tr>
<tr class="not-image"><td></td><td><p class="help">' . __( 'Link text, e.g. “Ransom Demands (PDF)”' ) . '</p></td></tr>
<tr class="image-only">
<th scope="row" class="label">
<label for="alt"><span class="alignleft">' . __( 'Alternative Text' ) . '</span> ' . wp_required_field_indicator() . '</label>
</th>
<td class="field"><input id="alt" name="alt" value="" type="text" required />
<p class="help">' . __( 'Alt text for the image, e.g. “The Mona Lisa”' ) . '</p></td>
</tr>
' . $caption . '
<tr class="align image-only">
<th scope="row" class="label"><p><label for="align">' . __( 'Alignment' ) . '</label></p></th>
<td class="field">
<input name="align" id="align-none" value="none" onclick="addExtImage.align='align'+this.value" type="radio"' . ( 'none' === $default_align ? ' checked="checked"' : '' ) . ' />
<label for="align-none" class="align image-align-none-label">' . __( 'None' ) . '</label>
<input name="align" id="align-left" value="left" onclick="addExtImage.align='align'+this.value" type="radio"' . ( 'left' === $default_align ? ' checked="checked"' : '' ) . ' />
<label for="align-left" class="align image-align-left-label">' . __( 'Left' ) . '</label>
<input name="align" id="align-center" value="center" onclick="addExtImage.align='align'+this.value" type="radio"' . ( 'center' === $default_align ? ' checked="checked"' : '' ) . ' />
<label for="align-center" class="align image-align-center-label">' . __( 'Center' ) . '</label>
<input name="align" id="align-right" value="right" onclick="addExtImage.align='align'+this.value" type="radio"' . ( 'right' === $default_align ? ' checked="checked"' : '' ) . ' />
<label for="align-right" class="align image-align-right-label">' . __( 'Right' ) . '</label>
</td>
</tr>
<tr class="image-only">
<th scope="row" class="label">
<label for="url"><span class="alignleft">' . __( 'Link Image To:' ) . '</span></label>
</th>
<td class="field"><input id="url" name="url" value="" type="text" /><br />
<button type="button" class="button" value="" onclick="document.forms[0].url.value=null">' . __( 'None' ) . '</button>
<button type="button" class="button" value="" onclick="document.forms[0].url.value=document.forms[0].src.value">' . __( 'Link to image' ) . '</button>
<p class="help">' . __( 'Enter a link URL or click above for presets.' ) . '</p></td>
</tr>
<tr class="image-only">
<td></td>
<td>
<input type="button" class="button" id="go_button" style="color:#bbb;" onclick="addExtImage.insert()" value="' . esc_attr__( 'Insert into Post' ) . '" />
</td>
</tr>
<tr class="not-image">
<td></td>
<td>
' . get_submit_button( __( 'Insert into Post' ), '', 'insertonlybutton', false ) . '
</td>
</tr>
</tbody></table>';
}
Hooks
- apply_filters( ‘disable_captions’, bool $bool )
-
Filters whether to disable captions.
Changelog
| Version | Description |
|---|---|
| 2.7.0 | Introduced. |