以下是多种方法，从简单到高级，帮助您为WordPress图片添加自定义属性。
方法1：通过媒体库直接添加自定义属性（最简单）
// 在functions.php中添加
// 1. 在媒体上传时添加自定义字段
function add_image_attachment_fields_to_edit($form_fields, $post) {
if (substr($post->post_mime_type, 0, 5) == 'image') {
// 自定义链接文本
$form_fields['custom_link_text'] = array(
'label' => '链接文本',
'input' => 'text',
'value' => get_post_meta($post->ID, '_custom_link_text', true),
'helps' => '鼠标悬停时显示的文本'
);
// 自定义CSS类
$form_fields['custom_css_class'] = array(
'label' => 'CSS类名',
'input' => 'text',
'value' => get_post_meta($post->ID, '_custom_css_class', true),
'helps' => '为图片添加自定义CSS类'
);
// 延迟加载控制
$lazy_value = get_post_meta($post->ID, '_lazy_loading', true);
$lazy_value = empty($lazy_value) ? 'auto' : $lazy_value;
$form_fields['custom_lazy_loading'] = array(
'label' => '延迟加载',
'input' => 'html',
'html' => '<select name="attachments['.$post->ID.'][custom_lazy_loading]">
<option value="auto" '.selected($lazy_value, 'auto', false).'>自动</option>
<option value="enabled" '.selected($lazy_value, 'enabled', false).'>启用</option>
<option value="disabled" '.selected($lazy_value, 'disabled', false).'>禁用</option>
</select>',
'helps' => '控制图片延迟加载行为'
);
// 自定义数据属性
$form_fields['custom_data_src'] = array(
'label' => '数据源 (data-src)',
'input' => 'text',
'value' => get_post_meta($post->ID, '_custom_data_src', true),
'helps' => '用于延迟加载的高清图片URL'
);
// 自定义Alt文本（覆盖默认）
$alt_text = get_post_meta($post->ID, '_custom_alt', true);
if (empty($alt_text)) {
$alt_text = get_post_meta($post->ID, '_wp_attachment_image_alt', true);
}
$form_fields['custom_alt_text'] = array(
'label' => '自定义Alt文本',
'input' => 'textarea',
'value' => $alt_text,
'helps' => '图片的替代文本（重要SEO属性）'
);
}
return $form_fields;
}
add_filter('attachment_fields_to_edit', 'add_image_attachment_fields_to_edit', 10, 2);
// 2. 保存自定义字段
function save_image_attachment_fields($post, $attachment) {
if (substr($post['post_mime_type'], 0, 5) == 'image') {
// 保存链接文本
if (isset($attachment['custom_link_text'])) {
update_post_meta($post['ID'], '_custom_link_text', sanitize_text_field($attachment['custom_link_text']));
}
// 保存CSS类
if (isset($attachment['custom_css_class'])) {
update_post_meta($post['ID'], '_custom_css_class', sanitize_text_field($attachment['custom_css_class']));
}
// 保存延迟加载设置
if (isset($attachment['custom_lazy_loading'])) {
update_post_meta($post['ID'], '_custom_lazy_loading', sanitize_text_field($attachment['custom_lazy_loading']));
}
// 保存数据源
if (isset($attachment['custom_data_src'])) {
update_post_meta($post['ID'], '_custom_data_src', esc_url_raw($attachment['custom_data_src']));
}
// 保存自定义Alt文本
if (isset($attachment['custom_alt_text'])) {
update_post_meta($post['ID'], '_custom_alt', sanitize_text_field($attachment['custom_alt_text']));
// 同时更新标准的Alt文本
update_post_meta($post['ID'], '_wp_attachment_image_alt', sanitize_text_field($attachment['custom_alt_text']));
}
}
return $post;
}
add_filter('attachment_fields_to_save', 'save_image_attachment_fields', 10, 2);
// 3. 在图片输出时应用自定义属性
function add_custom_image_attributes($attr, $attachment, $size) {
$attachment_id = $attachment->ID;
// 添加自定义CSS类
$custom_class = get_post_meta($attachment_id, '_custom_css_class', true);
if ($custom_class) {
if (isset($attr['class'])) {
$attr['class'] .= ' ' . $custom_class;
} else {
$attr['class'] = $custom_class;
}
}
// 添加自定义data-src属性
$data_src = get_post_meta($attachment_id, '_custom_data_src', true);
if ($data_src) {
$attr['data-src'] = $data_src;
}
// 添加自定义延迟加载
$lazy_loading = get_post_meta($attachment_id, '_custom_lazy_loading', true);
if ($lazy_loading && $lazy_loading !== 'auto') {
$attr['loading'] = $lazy_loading === 'enabled' ? 'lazy' : 'eager';
}
// 添加自定义链接文本（title属性）
$link_text = get_post_meta($attachment_id, '_custom_link_text', true);
if ($link_text && !isset($attr['title'])) {
$attr['title'] = esc_attr($link_text);
}
// 使用自定义Alt文本
$custom_alt = get_post_meta($attachment_id, '_custom_alt', true);
if ($custom_alt && !isset($attr['alt'])) {
$attr['alt'] = esc_attr($custom_alt);
}
// 添加自定义数据属性
$custom_data = get_post_meta($attachment_id, '_custom_data_attributes', true);
if ($custom_data && is_array($custom_data)) {
foreach ($custom_data as $key => $value) {
if (!empty($key) && !empty($value)) {
$attr['data-' . sanitize_key($key)] = esc_attr($value);
}
}
}
return $attr;
}
add_filter('wp_get_attachment_image_attributes', 'add_custom_image_attributes', 10, 3);方法2：批量编辑功能（增强媒体库）
// 1. 添加快捷编辑字段
function add_quick_edit_custom_fields($column_name, $post_type) {
if ($post_type == 'attachment' && $column_name == 'custom_alt') {
wp_nonce_field('quick_edit_custom_fields', 'custom_fields_nonce');
?>
<fieldset class="inline-edit-col-right">
<div class="inline-edit-col">
<label>
<span class="title">Alt文本</span>
<span class="input-text-wrap">
<input type="text" name="custom_alt" class="ptitle" value="" />
</span>
</label>
<label>
<span class="title">CSS类</span>
<span class="input-text-wrap">
<input type="text" name="custom_css_class" class="ptitle" value="" />
</span>
</label>
</div>
</fieldset>
<?php
}
}
add_action('quick_edit_custom_box', 'add_quick_edit_custom_fields', 10, 2);
// 2. 保存快速编辑数据
function save_quick_edit_custom_fields($post_id) {
if (!isset($_POST['custom_fields_nonce']) ||
!wp_verify_nonce($_POST['custom_fields_nonce'], 'quick_edit_custom_fields')) {
return;
}
if (defined('DOING_AUTOSAVE') && DOING_AUTOSAVE) {
return;
}
if (!current_user_can('edit_post', $post_id)) {
return;
}
if (isset($_POST['custom_alt'])) {
update_post_meta($post_id, '_custom_alt', sanitize_text_field($_POST['custom_alt']));
update_post_meta($post_id, '_wp_attachment_image_alt', sanitize_text_field($_POST['custom_alt']));
}
if (isset($_POST['custom_css_class'])) {
update_post_meta($post_id, '_custom_css_class', sanitize_text_field($_POST['custom_css_class']));
}
}
add_action('save_post_attachment', 'save_quick_edit_custom_fields');
// 3. 在媒体列表添加自定义列
function add_custom_media_columns($columns) {
$columns['custom_alt'] = '自定义Alt';
$columns['custom_class'] = 'CSS类';
return $columns;
}
add_filter('manage_media_columns', 'add_custom_media_columns');
function display_custom_media_columns($column_name, $post_id) {
if ($column_name == 'custom_alt') {
$alt = get_post_meta($post_id, '_custom_alt', true);
echo $alt ? esc_html($alt) : '<em>未设置</em>';
}
if ($column_name == 'custom_class') {
$class = get_post_meta($post_id, '_custom_css_class', true);
echo $class ? esc_html($class) : '<em>未设置</em>';
}
}
add_action('manage_media_custom_column', 'display_custom_media_columns', 10, 2);方法3：Gutenberg编辑器集成
// 1. 为Gutenberg图片块添加自定义属性面板
function register_image_custom_attributes() {
wp_register_script(
'image-custom-attributes',
get_stylesheet_directory_uri() . '/js/image-custom-attributes.js',
array('wp-blocks', 'wp-element', 'wp-editor', 'wp-components'),
'1.0.0',
true
);
register_block_type('custom/image-attributes', array(
'editor_script' => 'image-custom-attributes',
));
}
add_action('init', 'register_image_custom_attributes');
// 2. 对应的JavaScript文件 (js/image-custom-attributes.js)
// 由于代码较长，这里只给出PHP部分，JS文件内容见下文// js/image-custom-attributes.js
const { addFilter } = wp.hooks;
const { createHigherOrderComponent } = wp.compose;
const { Fragment } = wp.element;
const { InspectorControls } = wp.blockEditor;
const { PanelBody, TextControl, TextareaControl, SelectControl } = wp.components;
// 添加自定义属性控制面板
const withImageCustomAttributes = createHigherOrderComponent((BlockEdit) => {
return (props) => {
if (props.name !== 'core/image') {
return <BlockEdit {...props} />;
}
const { attributes, setAttributes } = props;
const { customClass, dataAttributes, lazyLoading } = attributes;
return (
<Fragment>
<BlockEdit {...props} />
<InspectorControls>
<PanelBody title="自定义属性" initialOpen={false}>
<TextControl
label="CSS类名"
value={customClass || ''}
onChange={(value) => setAttributes({ customClass: value })}
help="为图片添加额外的CSS类"
/>
<SelectControl
label="延迟加载"
value={lazyLoading || 'auto'}
options={[
{ label: '自动', value: 'auto' },
{ label: '启用', value: 'lazy' },
{ label: '禁用', value: 'eager' },
]}
onChange={(value) => setAttributes({ lazyLoading: value })}
/>
<TextareaControl
label="数据属性 (JSON格式)"
value={dataAttributes || ''}
onChange={(value) => setAttributes({ dataAttributes: value })}
help="格式: {"modal": "gallery", "index": "1"}"
/>
</PanelBody>
</InspectorControls>
</Fragment>
);
};
}, 'withImageCustomAttributes');
addFilter('editor.BlockEdit', 'custom/image-attributes', withImageCustomAttributes);
// 保存时添加自定义属性
addFilter('blocks.getSaveContent.extraProps', 'custom/image-attributes/save-props', (extraProps, blockType, attributes) => {
if (blockType.name !== 'core/image') {
return extraProps;
}
const { customClass, dataAttributes, lazyLoading } = attributes;
if (customClass) {
if (extraProps.className) {
extraProps.className += ' ' + customClass;
} else {
extraProps.className = customClass;
}
}
if (lazyLoading && lazyLoading !== 'auto') {
extraProps.loading = lazyLoading;
}
if (dataAttributes) {
try {
const dataAttrs = JSON.parse(dataAttributes);
Object.keys(dataAttrs).forEach(key => {
if (dataAttrs[key]) {
extraProps['data-' + key] = dataAttrs[key];
}
});
} catch (e) {
console.error('数据属性JSON格式错误:', e);
}
}
return extraProps;
});方法4：高级自定义属性管理器（完整类实现）
<?php
/**
* WordPress图片自定义属性管理器
*/
class WP_Image_Attributes_Manager {
private static $instance = null;
// 支持的属性类型
private $supported_attributes = array(
'data-src' => '数据源URL',
'data-srcset' => '响应式图片源集',
'data-sizes' => '图片尺寸',
'data-action' => '点击动作',
'data-modal' => '模态框ID',
'data-gallery' => '相册分组',
'data-index' => '索引编号',
'data-description'=> '详细描述',
'data-copyright' => '版权信息',
'data-credit' => '图片来源',
'data-caption' => '扩展标题',
);
public static function get_instance() {
if (null === self::$instance) {
self::$instance = new self();
}
return self::$instance;
}
private function __construct() {
// 初始化
add_action('admin_init', array($this, 'init_admin'));
add_action('wp_enqueue_media', array($this, 'enqueue_media_scripts'));
add_filter('wp_get_attachment_image_attributes', array($this, 'add_custom_attributes'), 10, 3);
add_filter('image_send_to_editor', array($this, 'filter_editor_image'), 10, 8);
add_action('add_attachment', array($this, 'save_default_attributes'));
add_action('edit_attachment', array($this, 'save_custom_attributes'));
// REST API支持
add_action('rest_api_init', array($this, 'register_rest_fields'));
}
/**
* 初始化后台
*/
public function init_admin() {
// 添加媒体库自定义字段
add_filter('attachment_fields_to_edit', array($this, 'add_custom_fields'), 10, 2);
add_filter('attachment_fields_to_save', array($this, 'save_custom_fields'), 10, 2);
// 添加快捷编辑
add_action('quick_edit_custom_box', array($this, 'add_quick_edit_fields'), 10, 2);
add_action('save_post_attachment', array($this, 'save_quick_edit'));
// 添加媒体列
add_filter('manage_media_columns', array($this, 'add_media_columns'));
add_action('manage_media_custom_column', array($this, 'display_media_columns'), 10, 2);
}
/**
* 添加媒体库自定义字段
*/
public function add_custom_fields($form_fields, $post) {
if (!wp_attachment_is_image($post->ID)) {
return $form_fields;
}
// 添加属性管理区域
$form_fields['custom_attributes_heading'] = array(
'label' => '自定义属性',
'input' => 'html',
'html' => '<h3>自定义数据属性</h3>',
);
// 为每个支持的属性添加字段
foreach ($this->supported_attributes as $attr => $label) {
$meta_key = '_custom_' . str_replace('-', '_', $attr);
$value = get_post_meta($post->ID, $meta_key, true);
$form_fields[$meta_key] = array(
'label' => $label,
'input' => 'text',
'value' => $value,
'helps' => 'HTML属性: ' . $attr
);
}
// 添加高级属性编辑器
$advanced_attrs = get_post_meta($post->ID, '_custom_advanced_attributes', true);
$form_fields['custom_advanced_attributes'] = array(
'label' => '高级属性',
'input' => 'textarea',
'value' => $advanced_attrs,
'helps' => 'JSON格式: {"data-zoom": "true", "data-group": "gallery1"}'
);
return $form_fields;
}
/**
* 保存自定义字段
*/
public function save_custom_fields($post, $attachment) {
if (!wp_attachment_is_image($post['ID'])) {
return $post;
}
// 保存支持的属性
foreach ($this->supported_attributes as $attr => $label) {
$meta_key = '_custom_' . str_replace('-', '_', $attr);
$field_key = 'attachments[' . $post['ID'] . '][' . $meta_key . ']';
if (isset($_REQUEST['attachments'][$post['ID']][$meta_key])) {
$value = sanitize_text_field($_REQUEST['attachments'][$post['ID']][$meta_key]);
update_post_meta($post['ID'], $meta_key, $value);
}
}
// 保存高级属性
if (isset($_REQUEST['attachments'][$post['ID']]['custom_advanced_attributes'])) {
$advanced_attrs = sanitize_textarea_field($_REQUEST['attachments'][$post['ID']]['custom_advanced_attributes']);
update_post_meta($post['ID'], '_custom_advanced_attributes', $advanced_attrs);
}
return $post;
}
/**
* 添加快捷编辑字段
*/
public function add_quick_edit_fields($column_name, $post_type) {
if ($post_type !== 'attachment' || $column_name !== 'custom_data') {
return;
}
wp_nonce_field('quick_edit_image_attrs', 'image_attrs_nonce');
?>
<fieldset class="inline-edit-col-right">
<div class="inline-edit-col">
<h3>自定义属性</h3>
<label>
<span class="title">数据源</span>
<input type="text" name="custom_data_src" class="widefat" />
</label>
<label>
<span class="title">CSS类</span>
<input type="text" name="custom_css_class" class="widefat" />
</label>
<label>
<span class="title">延迟加载</span>
<select name="custom_lazy_loading">
<option value="auto">自动</option>
<option value="lazy">启用</option>
<option value="eager">禁用</option>
</select>
</label>
</div>
</fieldset>
<?php
}
/**
* 保存快速编辑
*/
public function save_quick_edit($post_id) {
if (!isset($_POST['image_attrs_nonce']) ||
!wp_verify_nonce($_POST['image_attrs_nonce'], 'quick_edit_image_attrs')) {
return;
}
if (defined('DOING_AUTOSAVE') && DOING_AUTOSAVE) {
return;
}
if (!current_user_can('edit_post', $post_id)) {
return;
}
$fields = array(
'custom_data_src' => '_custom_data_src',
'custom_css_class' => '_custom_css_class',
'custom_lazy_loading' => '_custom_lazy_loading',
);
foreach ($fields as $input => $meta) {
if (isset($_POST[$input])) {
update_post_meta($post_id, $meta, sanitize_text_field($_POST[$input]));
}
}
}
/**
* 添加媒体列
*/
public function add_media_columns($columns) {
$columns['custom_data'] = '自定义属性';
$columns['custom_class'] = 'CSS类';
return $columns;
}
public function display_media_columns($column_name, $post_id) {
if ($column_name === 'custom_data') {
$data_src = get_post_meta($post_id, '_custom_data_src', true);
if ($data_src) {
echo '<div><strong>数据源:</strong> ' . esc_html($data_src) . '</div>';
}
$attrs = array();
foreach ($this->supported_attributes as $attr => $label) {
$meta_key = '_custom_' . str_replace('-', '_', $attr);
$value = get_post_meta($post_id, $meta_key, true);
if ($value) {
$attrs[] = $attr . '="' . esc_attr($value) . '"';
}
}
if (!empty($attrs)) {
echo '<div class="custom-attrs-list">' . implode('<br>', $attrs) . '</div>';
}
}
if ($column_name === 'custom_class') {
$css_class = get_post_meta($post_id, '_custom_css_class', true);
echo $css_class ? '<code>' . esc_html($css_class) . '</code>' : '-';
}
}
/**
* 为图片添加自定义属性
*/
public function add_custom_attributes($attr, $attachment, $size) {
$attachment_id = $attachment->ID;
// 添加自定义CSS类
$custom_class = get_post_meta($attachment_id, '_custom_css_class', true);
if ($custom_class) {
$attr['class'] = isset($attr['class']) ? $attr['class'] . ' ' . $custom_class : $custom_class;
}
// 添加支持的属性
foreach ($this->supported_attributes as $attr_name => $label) {
$meta_key = '_custom_' . str_replace('-', '_', $attr_name);
$value = get_post_meta($attachment_id, $meta_key, true);
if ($value) {
$attr[$attr_name] = esc_attr($value);
}
}
// 添加高级属性
$advanced_attrs = get_post_meta($attachment_id, '_custom_advanced_attributes', true);
if ($advanced_attrs) {
try {
$attrs_array = json_decode($advanced_attrs, true);
if (is_array($attrs_array)) {
foreach ($attrs_array as $key => $value) {
if (is_string($value)) {
$attr[sanitize_key($key)] = esc_attr($value);
}
}
}
} catch (Exception $e) {
// JSON解析失败，忽略
}
}
// 处理延迟加载
$lazy_loading = get_post_meta($attachment_id, '_custom_lazy_loading', true);
if ($lazy_loading && $lazy_loading !== 'auto') {
$attr['loading'] = $lazy_loading;
}
return $attr;
}
/**
* 过滤器：编辑器中插入的图片
*/
public function filter_editor_image($html, $id, $caption, $title, $align, $url, $size, $alt) {
$attributes = array();
// 获取自定义属性
$custom_class = get_post_meta($id, '_custom_css_class', true);
if ($custom_class) {
$attributes['class'] = $custom_class;
}
foreach ($this->supported_attributes as $attr_name => $label) {
$meta_key = '_custom_' . str_replace('-', '_', $attr_name);
$value = get_post_meta($id, $meta_key, true);
if ($value) {
$attributes[$attr_name] = $value;
}
}
// 如果有自定义属性，修改HTML
if (!empty($attributes)) {
$doc = new DOMDocument();
@$doc->loadHTML(mb_convert_encoding($html, 'HTML-ENTITIES', 'UTF-8'));
$imgs = $doc->getElementsByTagName('img');
foreach ($imgs as $img) {
foreach ($attributes as $key => $value) {
if ($key === 'class') {
$existing_class = $img->getAttribute('class');
$img->setAttribute('class', $existing_class . ' ' . $value);
} else {
$img->setAttribute($key, $value);
}
}
}
$html = $doc->saveHTML($doc->getElementsByTagName('img')->item(0));
}
return $html;
}
/**
* 保存默认属性
*/
public function save_default_attributes($attachment_id) {
if (!wp_attachment_is_image($attachment_id)) {
return;
}
// 设置默认值
update_post_meta($attachment_id, '_custom_lazy_loading', 'auto');
// 自动从文件名生成Alt文本
$filename = get_post_field('post_name', $attachment_id);
if ($filename) {
$alt_text = ucwords(str_replace(array('-', '_'), ' ', $filename));
update_post_meta($attachment_id, '_wp_attachment_image_alt', $alt_text);
}
}
/**
* 保存自定义属性
*/
public function save_custom_attributes($attachment_id) {
if (!wp_attachment_is_image($attachment_id)) {
return;
}
// 这里可以添加更多的保存逻辑
}
/**
* 注册REST API字段
*/
public function register_rest_fields() {
register_rest_field('attachment', 'custom_attributes', array(
'get_callback' => array($this, 'get_rest_custom_attributes'),
'update_callback' => array($this, 'update_rest_custom_attributes'),
'schema' => array(
'description' => '图片自定义属性',
'type' => 'object',
'context' => array('view', 'edit'),
),
));
}
public function get_rest_custom_attributes($object) {
$attachment_id = $object['id'];
$attributes = array();
foreach ($this->supported_attributes as $attr => $label) {
$meta_key = '_custom_' . str_replace('-', '_', $attr);
$value = get_post_meta($attachment_id, $meta_key, true);
if ($value) {
$attributes[$attr] = $value;
}
}
$custom_class = get_post_meta($attachment_id, '_custom_css_class', true);
if ($custom_class) {
$attributes['class'] = $custom_class;
}
return $attributes;
}
public function update_rest_custom_attributes($value, $object) {
if (!is_array($value)) {
return;
}
$attachment_id = $object->ID;
foreach ($value as $key => $val) {
if ($key === 'class') {
update_post_meta($attachment_id, '_custom_css_class', sanitize_text_field($val));
} elseif (isset($this->supported_attributes[$key])) {
$meta_key = '_custom_' . str_replace('-', '_', $key);
update_post_meta($attachment_id, $meta_key, sanitize_text_field($val));
}
}
}
/**
* 前端获取图片属性的函数
*/
public static function get_image_attributes($attachment_id) {
$instance = self::get_instance();
$default_attrs = array(
'class' => '',
'alt' => get_post_meta($attachment_id, '_wp_attachment_image_alt', true),
'src' => wp_get_attachment_url($attachment_id),
);
$custom_attrs = array();
// 添加自定义类
$custom_class = get_post_meta($attachment_id, '_custom_css_class', true);
if ($custom_class) {
$custom_attrs['class'] = $custom_class;
}
// 添加数据属性
foreach ($instance->supported_attributes as $attr => $label) {
$meta_key = '_custom_' . str_replace('-', '_', $attr);
$value = get_post_meta($attachment_id, $meta_key, true);
if ($value) {
$custom_attrs[$attr] = $value;
}
}
return array_merge($default_attrs, $custom_attrs);
}
/**
* 前端显示图片的快捷函数
*/
public static function the_custom_image($attachment_id, $size = 'full', $attr = array()) {
$custom_attrs = self::get_image_attributes($attachment_id);
$attrs = array_merge($custom_attrs, $attr);
echo wp_get_attachment_image($attachment_id, $size, false, $attrs);
}
}
// 初始化
WP_Image_Attributes_Manager::get_instance();方法5：短代码和模板标签
// 添加图片短代码
function custom_image_shortcode($atts) {
$atts = shortcode_atts(array(
'id' => 0,
'size' => 'full',
'class' => '',
'data_src' => '',
'data_action' => '',
'lazy' => 'auto',
'caption' => '',
'link' => '',
'link_target' => '_self',
), $atts, 'custom_image');
if (!$atts['id']) {
return '';
}
$image_id = intval($atts['id']);
$image_url = wp_get_attachment_image_url($image_id, $atts['size']);
$image_alt = get_post_meta($image_id, '_wp_attachment_image_alt', true);
if (!$image_url) {
return '';
}
// 构建属性
$attributes = array(
'src' => $image_url,
'alt' => $image_alt,
'class' => 'custom-image ' . $atts['class'],
);
// 添加自定义属性
if ($atts['data_src']) {
$attributes['data-src'] = esc_url($atts['data_src']);
}
if ($atts['data_action']) {
$attributes['data-action'] = sanitize_key($atts['data_action']);
}
if ($atts['lazy'] !== 'auto') {
$attributes['loading'] = $atts['lazy'] === 'true' ? 'lazy' : 'eager';
}
// 获取额外的自定义属性
$extra_attrs = apply_filters('custom_image_shortcode_attributes', array(), $image_id, $atts);
if (!empty($extra_attrs)) {
$attributes = array_merge($attributes, $extra_attrs);
}
// 构建HTML
$html = '<img';
foreach ($attributes as $key => $value) {
if (!empty($value)) {
$html .= ' ' . esc_attr($key) . '="' . esc_attr($value) . '"';
}
}
$html .= '>';
// 添加链接
if ($atts['link']) {
$html = sprintf(
'<a href="%s" target="%s">%s</a>',
esc_url($atts['link']),
esc_attr($atts['link_target']),
$html
);
}
// 添加标题
if ($atts['caption']) {
$html = sprintf(
'<figure>%s<figcaption>%s</figcaption></figure>',
$html,
esc_html($atts['caption'])
);
}
return $html;
}
add_shortcode('custom_image', 'custom_image_shortcode');
// 模板函数
function get_custom_image($attachment_id, $args = array()) {
$defaults = array(
'size' => 'full',
'add_class' => '',
'data_attributes' => array(),
'lazy_loading' => true,
'wrap' => false,
'wrap_class' => '',
);
$args = wp_parse_args($args, $defaults);
// 获取图片属性
$img_attrs = array(
'class' => 'custom-image-attachment ' . $args['add_class'],
);
// 延迟加载
if ($args['lazy_loading']) {
$img_attrs['loading'] = 'lazy';
}
// 添加数据属性
if (!empty($args['data_attributes'])) {
foreach ($args['data_attributes'] as $key => $value) {
$img_attrs['data-' . sanitize_key($key)] = esc_attr($value);
}
}
// 获取自定义属性
$custom_attrs = WP_Image_Attributes_Manager::get_image_attributes($attachment_id);
$img_attrs = array_merge($custom_attrs, $img_attrs);
// 生成图片HTML
$image_html = wp_get_attachment_image($attachment_id, $args['size'], false, $img_attrs);
// 添加包装
if ($args['wrap']) {
$wrapper_class = 'custom-image-wrapper ' . $args['wrap_class'];
$image_html = sprintf('<div class="%s">%s</div>', esc_attr($wrapper_class), $image_html);
}
return $image_html;
}
function the_custom_image($attachment_id, $args = array()) {
echo get_custom_image($attachment_id, $args);
}使用方法
1. 基本使用
将方法1的代码添加到主题的functions.php文件中，然后：
- 上传图片时，媒体库中会出现自定义字段
- 前端图片会自动添加设置的属性
2. 在模板中使用
// 获取图片并添加自定义属性
$image_id = get_post_thumbnail_id();
$image_attrs = WP_Image_Attributes_Manager::get_image_attributes($image_id);
// 或者使用快捷函数
the_custom_image($image_id, array(
'size' => 'large',
'add_class' => 'my-custom-class',
'data_attributes' => array(
'modal' => 'gallery',
'index' => '1'
),
'lazy_loading' => true
));
// 使用短代码
[custom_image id="123" size="medium" class="featured-image" data_action="lightbox"]3. 在文章编辑器中
- 上传或选择图片
- 点击编辑图片
- 在”附件详情”中找到自定义字段
- 添加需要的属性
配套CSS样式
/* 自定义图片样式 */
.custom-image {
transition: all 0.3s ease;
max-width: 100%;
height: auto;
}
.custom-image[data-modal] {
cursor: zoom-in;
}
.custom-image[data-action="lightbox"]:hover {
opacity: 0.9;
transform: scale(1.02);
}
/* 延迟加载效果 */
.custom-image[data-src] {
background: #f5f5f5;
min-height: 200px;
}
.custom-image.lazyloaded {
animation: fadeIn 0.5s ease;
}
@keyframes fadeIn {
from { opacity: 0; }
to { opacity: 1; }
}
/* 媒体库样式 */
.attachment-details .setting.custom-attribute {
margin: 10px 0;
padding: 10px;
background: #f9f9f9;
border-left: 3px solid #0073aa;
}
.attachment-details .setting.custom-attribute label {
display: block;
margin-bottom: 5px;
font-weight: 600;
}
.attachment-details .setting.custom-attribute input,
.attachment-details .setting.custom-attribute textarea,
.attachment-details .setting.custom-attribute select {
width: 100%;
padding: 5px;
border: 1px solid #ddd;
border-radius: 3px;
}
/* 媒体列表列样式 */
.column-custom_data .custom-attrs-list {
font-size: 12px;
color: #666;
line-height: 1.4;
}
.column-custom_class code {
background: #f1f1f1;
padding: 2px 5px;
border-radius: 3px;
font-size: 12px;
}这个完整方案提供了从简单到高级的多种实现方式，您可以根据需要选择适合的方法。方案包含了媒体库集成、Gutenberg支持、批量编辑、REST API等完整功能。
湘公网安备43020002000238