Xcode「ambiguous use of ‘opacity’」の解決方法【SwiftUI overlay・Xcode 27】

Xcode 27でSwiftUIプロジェクトをビルドしたとき、これまで通っていたoverlayやbackgroundのコードに「ambiguous use of ‘opacity’」が表示されることがあります。これは不透明度の値が不正なのではなく、Xcode 27世代のSwiftUIでresult builderが@ContentBuilderへ統合されたことに伴うソース互換性の問題です。Appleが案内している推奨対応は、直接引数を渡す形式からclosure形式へ書き換えることです。

表示されるエラー

error: ambiguous use of 'opacity'

error: ambiguous use of 'blendMode'

再現しやすいコード

たとえば、ShapeStyleとしてもViewとしても解釈できる式を、非closure形式のoverlayへ直接渡すと発生します。

import SwiftUI

struct ContentView: View {
    var body: some View {
        Text("Hello")
            .overlay(
                Color.blue.opacity(0.70).blendMode(.overlay)
            )
    }
}

原因

Xcode 27のSwiftUIでは、複数のresult builderが@ContentBuilderの仕組みに統合されました。従来はbuilder側のView制約によって候補が早い段階で絞られていましたが、新しい型推論では同じ絞り込みが行われません。

overlayとbackgroundには、Viewを受け取るoverloadとShapeStyleを扱うoverloadがあります。Color.blue.opacity(...).blendMode(...)のような式を直接引数として渡すと、opacityやblendModeをどちらの文脈で解決するか決められず、曖昧な呼び出しとしてコンパイルに失敗します。

発生条件と対象バージョン

• Xcode 27でSwiftUIコードをコンパイルしている
• overlay(...)またはbackground(...)へ内容を直接渡している
• ColorなどのShapeStyle式にopacity、blendModeなどを連結している
• 以前のXcodeでは同じコードがコンパイルできていた

AppleのTN3211は2026年6月8日に公開され、この変更をXcode 27へのソース移行事項として説明しています。Appleは「修正版を待つ一時的不具合」とはしていないため、コードを新しい推奨形式へ移行するのが基本対応です。

推奨する解決手順

1. overlayをclosure形式へ変更する

Text("Hello")
    .overlay {
        Color.blue
            .opacity(0.70)
            .blendMode(.overlay)
    }

trailing closureを使うことでbuilderを使うoverloadが明確になり、型推論の曖昧さが解消されます。

2. backgroundも同様に書き換える

Text("Hello")
    .padding()
    .background {
        Color.blue.opacity(0.30)
    }

3. alignmentがある場合はラベル付き引数を残す

Text("Status")
    .overlay(alignment: .topTrailing) {
        Circle()
            .fill(Color.red.opacity(0.8))
            .frame(width: 10, height: 10)
    }

見た目や配置を変えず、コンテンツだけをclosureへ移します。

代替策

• 複雑な装飾を独立したViewまたはViewModifierへ抽出し、closure内で呼び出す
• 依存ライブラリ内で発生する場合は、Xcode 27対応版へ更新する
• 更新版がない場合は、ライセンスを確認した上でforkし、同じclosure形式の修正を最小限適用する
• 別モジュールにもColorなど同名型がある場合は、必要に応じてSwiftUI.Colorのようにモジュール名を明示する

修正後の確認方法

1. エラー箇所のoverlayまたはbackgroundをclosure形式へ変更する
2. Product > Clean Build Folderを実行して再ビルドする
3. DebugとReleaseの両構成でコンパイルする
4. Preview、Simulator、実機で不透明度、blend mode、alignmentが修正前と同じか確認する
5. プロジェクトと依存コードを検索し、同じ非closure形式が残っていないか確認する

注意点

• ambiguous use of 'blendMode'も同じ移行方法で対処できます。
• closureへ移す際にalignmentや条件分岐を落とさないでください。
• サードパーティ製ライブラリを直接編集すると更新時に消えるため、まず正式な対応版を確認してください。
• 古いXcodeへ戻す方法は一時回避にはなりますが、Xcode 27対応としてはソース修正が推奨されます。

まとめ

Xcode 27の「ambiguous use of ‘opacity’」は、SwiftUIのContentBuilder変更によってoverlay／backgroundのoverload解決が曖昧になることが原因です。直接引数を渡す形式をoverlay { ... }またはbackground { ... }へ変更してください。値や描画効果を削除せず、Appleが示すclosure形式へ移行するのが最も安全です。

公式情報

• Apple TN3211: Resolving SwiftUI source incompatibilities for State and ContentBuilder
• SwiftUI View.overlay(alignment:content:)
• SwiftUI View.background(alignment:content:)