iOS中UIButton setBackgroundImage方法失效问题求助

现象详情 #

(A) 以下代码可正常修改UIImageView的图片：

[(UIImageView *)[cell viewWithTag:400] setImage:[UIImage imageNamed:@"sellsign"]];

(B) 以下代码仅能修改UIButton的标题，setBackgroundImage:方法无效（已测试System和Custom两种按钮类型）：

[(UIButton *)[cell viewWithTag:500] setBackgroundImage:[UIImage imageNamed:@"sellsign"] forState:UIControlStateNormal];
[(UIButton *)[cell viewWithTag:500] setTitle:@"1" forState:UIControlStateNormal];

(C) 按钮配置图：

已确认信息 #

• 按钮引用正确（标题修改生效）；
• 按钮处于正常状态（显示标题“1”）；
• 图片名称正确（已在UIImageView中正常显示）。

疑问 #

UIButton背景图设置无效，怀疑遗漏iOS新版本相关设置，寻求适配iOS新特性的有效方案，而非临时修改按钮样式的办法。

在iOS 15及以后的版本中，UIButton默认使用UIButtonConfiguration管理按钮样式与内容，旧的setBackgroundImage:等方法会被Configuration的设置覆盖，这是导致调用无效的核心原因。以下两种适配方案供参考：

方式一：基于UIButtonConfiguration设置（苹果推荐） #

这种方式符合iOS新设计规范，代码示例：

UIButton *button = (UIButton *)[cell viewWithTag:500];
// 获取当前配置，若无则创建默认配置
UIButtonConfiguration *config = button.configuration ?: [UIButtonConfiguration plainButtonConfiguration];

// 设置常态背景图
UIImage *bgImage = [UIImage imageNamed:@"sellsign"];
config.backgroundImage = bgImage;

// 若需针对不同状态设置，可通过配置更新回调处理
button.configurationUpdateHandler = ^(UIButton *btn, UIButtonConfiguration *updatedConfig) {
    if (btn.state == UIControlStateHighlighted) {
        // 可单独设置高亮状态的背景图
        updatedConfig.backgroundImage = [UIImage imageNamed:@"sellsign_highlight"];
    }
};

// 应用配置并设置标题
button.configuration = config;
[button setTitle:@"1" forState:UIControlStateNormal];

方式二：禁用Configuration，沿用旧版API #

如果希望继续使用setBackgroundImage:等旧方法，可直接清空按钮的Configuration：

UIButton *button = (UIButton *)[cell viewWithTag:500];
button.configuration = nil;

// 此时旧API可正常生效
[button setBackgroundImage:[UIImage imageNamed:@"sellsign"] forState:UIControlStateNormal];
[button setTitle:@"1" forState:UIControlStateNormal];

补充说明 #

• 若通过Storyboard/Xib创建按钮，iOS 15+环境下默认启用Configuration，可在属性面板中找到「Configuration」选项，手动设置背景图或选择「None」禁用Configuration；
• 优先推荐方式一，苹果后续会持续优化Configuration的能力，更适配新系统的设计逻辑。

内容的提问来源于stack exchange，提问作者Parth