TextSelectionTheme migration
Summary
#The ThemeData
properties that controlled the look of
selected text in Material widgets have been moved into
their own TextSelectionTheme
. These properties include
cursorColor
, textSelectionColor
, and
textSelectionHandleColor
. The defaults for these
properties have also been changed to match the Material
Design specification.
Context
#As part of the larger Material Theme Updates,
we have introduced a new Text Selection Theme
used to specify the properties of selected text in
TextField
and SelectableText
widgets.
These replace several top-level properties of ThemeData
and update their default values to match the Material
Design specification. This document describes how
applications can migrate to this new API.
Migration guide
#If you are currently using the following properties of
ThemeData
, you need to update them to use the new
equivalent properties on ThemeData.textSelectionTheme
:
Before | After |
---|---|
ThemeData.cursorColor |
TextSelectionThemeData.cursorColor |
ThemeData.textSelectionColor |
TextSelectionThemeData.selectionColor |
ThemeData.textSelectionHandleColor |
TextSelectionThemeData.selectionHandleColor |
Code before migration:
ThemeData(
cursorColor: Colors.red,
textSelectionColor: Colors.green,
textSelectionHandleColor: Colors.blue,
)
Code after migration:
ThemeData(
textSelectionTheme: TextSelectionThemeData(
cursorColor: Colors.red,
selectionColor: Colors.green,
selectionHandleColor: Colors.blue,
)
)
Default changes
If you weren't using these properties explicitly,
but depended on the previous default colors used
for text selection you can add a new field to your
ThemeData
for your app to return to the old defaults
as shown:
// Old defaults for a light theme
ThemeData(
textSelectionTheme: TextSelectionThemeData(
cursorColor: const Color.fromRGBO(66, 133, 244, 1.0),
selectionColor: const Color(0xff90caf9),
selectionHandleColor: const Color(0xff64b5f6),
)
)
// Old defaults for a dark theme
ThemeData(
textSelectionTheme: TextSelectionThemeData(
cursorColor: const Color.fromRGBO(66, 133, 244, 1.0),
selectionColor: const Color(0xff64ffda),
selectionHandleColor: const Color(0xff1de9b6),
)
)
If you are fine with the new defaults, but have failing golden file tests, you can update your master golden files using the following command:
flutter test --update-goldens
Timeline
#Landed in version: 1.23.0-4.0.pre
In stable release: 2.0.0
References
#API documentation:
Relevant PRs:
除非另有说明,本文档之所提及适用于 Flutter 的最新稳定版本,本页面最后更新时间: 2024-09-04。 查看文档源码 或者 为本页面内容提出建议。