iOS UIButton titleLabel 不顯示的正確設置方法

問題現象

代碼創建 UIButton 並嘗試直接設置 titleLabel.text、titleLabel.font，按鈕背景圖片正常顯示，但標題文字不顯示。

原始代碼

UIButton *button = [[UIButton alloc] initWithFrame:CGRectMake(0, 0, 50, 50)];
[button setBackgroundImage:[UIImage imageNamed:@"button.png"] forState:UIControlStateNormal];
button.titleLabel.text = @"Title";           // 錯誤方式
button.titleLabel.font = [UIFont fontWithName:@"System-Bold" size:25.0f]; // 錯誤方式
[self.view addSubview:button];

根因分析

• UIButton 的 titleLabel 是只讀屬性，其 text、font、textColor 等屬性不應直接修改。
• UIButton 內部根據狀態（Normal、Highlighted、Selected、Disabled）管理標題顯示，直接修改 label 會被按鈕內部機制覆蓋或忽略。
• 正確方式是使用 setTitle:forState:、setTitleColor:forState:、titleLabel.font（僅設置 font 可直接訪問 label，但推薦統一用狀態方法）。

正確解決方案

標準設置代碼

UIButton *button = [[UIButton alloc] initWithFrame:CGRectMake(0, 0, 100, 50)]; // 寬度需足夠容納文字
[button setBackgroundImage:[UIImage imageNamed:@"button.png"] forState:UIControlStateNormal];

// 關鍵：使用 setTitle:forState: 設置標題
[button setTitle:@"Title" forState:UIControlStateNormal];

// 設置字體（可直接訪問 titleLabel.font，但建議統一風格）
button.titleLabel.font = [UIFont boldSystemFontOfSize:18]; // 推薦用 boldSystemFontOfSize

// 關鍵：設置文字顏色（默認白色，深色背景需顯式設置）
[button setTitleColor:[UIColor whiteColor] forState:UIControlStateNormal];
[button setTitleColor:[UIColor lightGrayColor] forState:UIControlStateHighlighted]; // 按下狀態顏色

[self.view addSubview:button];

進階：不同狀態設置不同標題/顏色

[button setTitle:@"Normal" forState:UIControlStateNormal];
[button setTitle:@"Pressed" forState:UIControlStateHighlighted];
[button setTitle:@"Selected" forState:UIControlStateSelected];
[button setTitle:@"Disabled" forState:UIControlStateDisabled];

[button setTitleColor:[UIColor blackColor] forState:UIControlStateNormal];
[button setTitleColor:[UIColor redColor] forState:UIControlStateHighlighted];
[button setTitleColor:[UIColor grayColor] forState:UIControlStateDisabled];

關鍵屬性對照表

常見坑點與調試技巧

• 按鈕寬度不足：initWithFrame 寬度過小（如 50）導致文字被截斷或不顯示，設置合適寬度或使用 sizeToFit / Auto Layout 約束。
• 文字顏色與背景衝突：默認標題顏色為白色，若背景圖亦為白/淺色，文字不可見。必須顯式設置 setTitleColor:。
• 字體名稱錯誤：@"System-Bold" 非標準字體名，應用 [UIFont boldSystemFontOfSize:] 或 [UIFont systemFontOfSize:weight:]。
• 狀態組合：UIControlStateHighlighted | UIControlStateSelected 等組合狀態需單獨設置，否則繼承 Normal 狀態。
• 調試技巧：在 View Debugger 中檢查按鈕層級，確認 titleLabel 存在、frame 正確、文字屬性生效。

最佳實踐建議

• 統一使用 setTitle:forState:、setTitleColor:forState:、setImage:forState:、setBackgroundImage:forState: 系列方法配置按鈕。
• 按鈕創建後立即調用 sizeToFit 或設置 Auto Layout 約束，確保框架足夠容納內容。
• 封裝 ButtonFactory 或分類方法，統一項目按鈕風格（字體、顏色、圓角、內邊距）。
• iOS 15+ 可使用 UIButton.Configuration 現代 API 簡化配置：

var config = UIButton.Configuration.filled()
config.title = "Title"
config.baseForegroundColor = .white
config.titleTextAttributesTransformer = UIConfigurationTextAttributesTransformer { incoming in
    var outgoing = incoming
    outgoing.font = .boldSystemFont(ofSize: 18)
    return outgoing
}
button.configuration = config

總結：UIButton 標題不顯示 99% 因直接修改 titleLabel 屬性而非使用狀態配置方法，或未設置文字顏色導致與背景融合。遵循「狀態驅動配置」原則，顯式設置標題、顏色、字體，即可解決。