Skip to content

Commit b1424e2

Browse files
[go_router] Document regex constraints for path parameters (flutter#12281)
## Description Documents the regular expression constraint syntax supported by `GoRoute.path`. `GoRoute` already supports path parameters in the form `:paramName(regex)`, but this syntax is not currently documented. This change documents the syntax, provides a valid Dart example, and explains how constrained path parameters participate in route matching. Fixes flutter/flutter#177766 ## Testing - No new tests were added because this is a documentation-only change. - Ran `dart run script/tool/bin/flutter_plugin_tools.dart test --packages=go_router`. ## Pre-Review Checklist **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. [^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.
1 parent b9e4c50 commit b1424e2

4 files changed

Lines changed: 69 additions & 0 deletions

File tree

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
// Copyright 2013 The Flutter Authors
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
import 'package:flutter/material.dart';
6+
import 'package:go_router/go_router.dart';
7+
8+
/// Router configuration demonstrating regex-constrained path parameters.
9+
final GoRouter router = GoRouter(
10+
routes: <GoRoute>[
11+
GoRoute(
12+
path: r'/users/:id(\d+)',
13+
builder: (BuildContext context, GoRouterState state) {
14+
return Scaffold(body: Center(child: Text('User ${state.pathParameters['id']}')));
15+
},
16+
),
17+
],
18+
);
19+
20+
/// Runs the path parameter regular expression example.
21+
void main() {
22+
runApp(const PathParameterRegexApp());
23+
}
24+
25+
/// A minimal app demonstrating regex-constrained path parameters.
26+
class PathParameterRegexApp extends StatelessWidget {
27+
/// Creates a [PathParameterRegexApp].
28+
const PathParameterRegexApp({super.key});
29+
30+
@override
31+
Widget build(BuildContext context) {
32+
return MaterialApp.router(routerConfig: router);
33+
}
34+
}
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
// Copyright 2013 The Flutter Authors
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
import 'package:flutter_test/flutter_test.dart';
6+
import 'package:go_router_examples/path_parameter_regex.dart' as example;
7+
8+
void main() {
9+
testWidgets('matches numeric path parameter', (WidgetTester tester) async {
10+
example.router.go('/users/42');
11+
12+
await tester.pumpWidget(const example.PathParameterRegexApp());
13+
await tester.pumpAndSettle();
14+
15+
expect(find.text('User 42'), findsOneWidget);
16+
});
17+
}

‎packages/go_router/lib/src/route.dart‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
// Use of this source code is governed by a BSD-style license that can be
33
// found in the LICENSE file.
44

5+
// ignore_for_file: doc_directive_unknown
6+
57
import 'dart:async';
68

79
import 'package:collection/collection.dart';
@@ -341,6 +343,19 @@ class GoRoute extends RouteBase {
341343
/// `/family/456` and etc. The parameter values are stored in [GoRouterState]
342344
/// that are passed into [pageBuilder] and [builder].
343345
///
346+
/// A path parameter may optionally be constrained to a regular expression
347+
/// by appending the expression in parentheses after the parameter name:
348+
/// `:paramName(regex)`.
349+
///
350+
/// {@example /example/lib/path_parameter_regex.dart}
351+
///
352+
/// The path matches `/users/42` but not `/users/settings`. If a path segment
353+
/// does not satisfy the regular expression, route matching continues with
354+
/// other route candidates.
355+
///
356+
/// The regular expression is interpreted as a Dart [RegExp] pattern and must
357+
/// not contain nested parentheses.
358+
///
344359
/// The query parameter are also capture during the route parsing and stored
345360
/// in [GoRouterState].
346361
///
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
changelog: |
2+
- Documents support for regular expression constraints in GoRoute path parameters.
3+
version: patch

0 commit comments

Comments
 (0)