Skip to main content

CupertinoTabBar 需要 Localizations 父元件

為了提供符合語言地區的語意，CupertinoTabBar 需要有 Localizations 父元件。

摘要

#

CupertinoTabBar 的實例必須有 Localizations 父元件，才能提供在地化的 Semantics 提示。若嘗試在沒有 localizations 的情況下建立 CupertinoTabBar，將會出現如下的 assertion： 

CupertinoTabBar requires a Localizations parent in order to provide an appropriate Semantics hint
for tab indexing. A CupertinoApp provides the DefaultCupertinoLocalizations, or you can
instantiate your own Localizations.
'package:flutter/src/cupertino/bottom_tab_bar.dart':
Failed assertion: line 213 pos 7: 'localizations != null'

背景

#

為了支援在地語系化的語意資訊，CupertinoTabBar 需要本地化（localizations）。

在此變更之前，提供給 CupertinoTabBar 的 Semantics 提示（hint）是一個硬編碼的字串：'tab, $index of $total'。語意提示的內容也從原本的這個字串，更新為英文的 'Tab $index of $total'。

如果你的 CupertinoTabBar 位於 CupertinoApp 的範圍內，DefaultCupertinoLocalizations 已經被實例化，通常可以直接滿足你的需求，無需對現有程式碼做任何修改。

如果你的 CupertinoTabBar 不在 CupertinoApp 之內，你可以使用 Localizations 元件 (Widget) 提供你所需的本地化內容。

遷移指南

#

如果你遇到 'localizations != null' 斷言錯誤，請確認你的 CupertinoTabBar 已正確提供 locale（語系）資訊。

遷移前的程式碼：

dart 
import 'package:flutter/cupertino.dart';
​
void main() => runApp(Foo());
​
class Foo extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MediaQuery(
      data: const MediaQueryData(),
      child: CupertinoTabBar(
        items: const <BottomNavigationBarItem>[
          BottomNavigationBarItem(
            icon: Icon(CupertinoIcons.add_circled),
            label: 'Tab 1',
          ),
          BottomNavigationBarItem(
            icon: Icon(CupertinoIcons.add_circled_solid),
            label: 'Tab 2',
          ),
        ],
        currentIndex: 1,
      ),
    );
  }
}

遷移後的程式碼（透過 CupertinoApp 提供在地化）：

dart 
import 'package:flutter/cupertino.dart';
​
void main() => runApp(Foo());
​
class Foo extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return CupertinoApp(
      home: CupertinoTabBar(
        items: const <BottomNavigationBarItem>[
          BottomNavigationBarItem(
            icon: Icon(CupertinoIcons.add_circled),
            label: 'Tab 1',
          ),
          BottomNavigationBarItem(
            icon: Icon(CupertinoIcons.add_circled_solid),
            label: 'Tab 2',
          ),
        ],
        currentIndex: 1,
      ),
    );
  }
}

遷移後的程式碼（使用 Localizations 元件 (Widget) 提供在地化）：

dart 
import 'package:flutter/cupertino.dart';
​
void main() => runApp(Foo());
​
class Foo extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Localizations(
      locale: const Locale('en', 'US'),
      delegates: <LocalizationsDelegate<dynamic>>[
        DefaultWidgetsLocalizations.delegate,
        DefaultCupertinoLocalizations.delegate,
      ],
      child: MediaQuery(
        data: const MediaQueryData(),
        child: CupertinoTabBar(
          items: const <BottomNavigationBarItem>[
            BottomNavigationBarItem(
              icon: Icon(CupertinoIcons.add_circled),
              label: 'Tab 1',
            ),
            BottomNavigationBarItem(
              icon: Icon(CupertinoIcons.add_circled_solid),
              label: 'Tab 2',
            ),
          ],
          currentIndex: 1,
        ),
      ),
    );
  }
}

時間軸

#

合併於版本：1.18.0-9.0.pre
進入穩定版：1.20.0

參考資料

#

API 文件：

相關 PR：

Unless stated otherwise, the documentation on this site reflects Flutter 3.44.0. Page last updated on 2026-06-14. View source or report an issue.