uri 套件為 Dart 應用程式中的 URI 建構、解析與操作提供實用工具。它支援符合 RFC 6570 標準的 URI 模板解析,可實現帶變數的動態 URL 產生。此套件專為所有主要平台設計,能無縫整合至 HTTP 客戶端與網路服務整合中。該套件由 Google 維護,為 Flutter 與 Dart 專案中的複雜 URI 操作提供輕量且可靠的解決方案。
適用情境
建構動態 API URL
從 URI 解析查詢參數
擴展帶有變數的 URI 模板
處理相對和絕對 URI
與 HTTP 客戶端整合
驗證 URI 結構
主要特色
RFC 6570 URI 模板支援
強大的解析和構建
跨平台相容性
輕便高效
支援查詢字串操作
可擴展以支援自訂 URI 邏輯
適合對象
API 客戶端
Web服務整合
URL路由系統
資料獲取管道
後端通訊層
測試 HTTP 互動
使用建議
需要手動處理特殊字元的編碼
不適用於超出語法的完整URL驗證
僅限URI級別操作,不支援完整的HTTP請求
無內建快取或重試機制
取決於範本語法的正確使用
可能需要與 http 包搭配以完成完整的 HTTP 工作流程
原始 README
以下為關聯原始碼儲存庫的 README 原文快照,最新內容請造訪原始碼儲存庫。
Utilities for working with URIs in Dart, mostly parsing and generating URIs.
UriPattern
UriPattern is an interface for classes that match and parse URIs, much like the Pattern is for Strings. It defines the methods bool matches(Uri uri) and UriMatch match(Uri uri).
UriMatch
UriMatch is the result of UriPattern.match(). It contains the parameters parsed out of a URI and the "rest" of the URI left over after parsing, which is useful for parsing a single URI with multiple relative URI patterns that form a hierarchy.
UriTemplate
UriTemplate is an implementation of RFC 6570 URI Templates. URI Templates are useful for generating URIs from data. UriTemplates are created from a template string, and then expanded with data to generate a URI:
URI templates are strings made up of fixed and variable parts. The variable parts are described with expressions, which are places within single curly-braces: { and }.
Expressions consist of an optional operator and a comma-separated list of variable specifications_. Variable specifications consist of a variable name and an optional modifier. The operator applies to the whole expression and controls how reserved characters are expanded, the prefix and separator, if any, applied to the expansion, and whether to expand the variable as a key/value pair. Modifiers apply to each variable in the expression and allow truncating the value, or "exploding" list and maps into multiple key/value pairs.
Examples
http://example.com/~{username}/
http://example.com/dictionary/{term:1}/{term}
http://example.com/search{?q,lang}
Operators
URI template expansions does more than simple variable replacement, it has facilities for generating paths, fragments, query strings and more. To control the expansion, expressions can use one of the supported operators:
Operator
Description
none
Simple string expansion
+
Reserved string expansion
#
Fragment expansion
.
Label expansion, dot-prefixed
/
Path segments, slash-prefixed
;
Path-style parameters, semicolon-prefixed
?
Form-style query, ampersand-separated
&
Form-style query continuation
Modifiers
Modifiers control
Modifier
Description
none
Default expansion
:n
Prefix: use only the first n characters of the value
*
"Explode" the lists and maps into key/value pairs
UriParser
UriParser parses URIs according to a UriTemplate, extracting parameters based on the variables defined in the template.
Since URI Templates are not designed to be parsable, only a restricted subset of templates can be used for parsing.
Parsable templates have the following restrictions over expandable templates:
URI components must come in order: scheme, host, path, query, fragment.
There can only be one of each component.
Path expressions can only contain one variable.
Multiple expressions must be separated by a literal.
Only the following operators are supported: none, +, #, ?, &
Default and + operators are not allowed in query or fragment components.
Queries can only use the ? or & operator.
The ? operator can only be used once.
Fragments can only use the # operator
UriBuilder
UriBuilder is mutable container of URI components for incrementally building Uris.