@0xcda7a/path-to-regexp-es6 中文文档教程

Question

Path-to-RegExp

将 Express 样式的路径字符串（例如 /user/:name）转换为正则表达式。

Installation

npm install path-to-regexp --save

Usage

var pathToRegexp = require('path-to-regexp')

// pathToRegexp(path, keys, options)
// pathToRegexp.parse(path)
// pathToRegexp.compile(path)

• path An Express-style string, an array of strings, or a regular expression.
• keys An array to be populated with the keys found in the path.
• options
• sensitive When true the route will be case sensitive. (default: false)
• strict When false the trailing slash is optional. (default: false)
• end When false the path will match at the beginning. (default: true)
• delimiter Set the default delimiter for repeat parameters. (default: '/')

var keys = []
var re = pathToRegexp('/foo/:bar', keys)
// re = /^\/foo\/([^\/]+?)\/?$/i
// keys = [{ name: 'bar', prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '[^\\/]+?' }]

请注意： path-to-regexp 返回的 RegExp 用于带有路径名或主机名。 它不能处理查询字符串或 URL 片段。

Parameters

路径字符串可用于定义参数和填充键。

Named Parameters

命名参数是通过在参数名称前加一个冒号 (:foo) 来定义的。 默认情况下，该参数将匹配到以下路径段。

var re = pathToRegexp('/:foo/:bar', keys)
// keys = [{ name: 'foo', prefix: '/', ... }, { name: 'bar', prefix: '/', ... }]

re.exec('/test/route')
//=> ['/test/route', 'test', 'route']

请注意：命名参数必须由“单词字符”组成（[A-Za-z0-9_]）。

var re = pathToRegexp('/(apple-)?icon-:res(\\d+).png', keys)
// keys = [{ name: 0, prefix: '/', ... }, { name: 'res', prefix: '', ... }]

re.exec('/icon-76.png')
//=> ['/icon-76.png', undefined, '76']

Modified Parameters

Optional

可以在参数后加上问号 (?) 使参数可选。 这也将使前缀成为可选的。

var re = pathToRegexp('/:foo/:bar?', keys)
// keys = [{ name: 'foo', ... }, { name: 'bar', delimiter: '/', optional: true, repeat: false }]

re.exec('/test')
//=> ['/test', 'test', undefined]

re.exec('/test/route')
//=> ['/test', 'test', 'route']

Zero or more

参数可以以星号 (*) 为后缀，以表示零个或多个参数匹配。 每个匹配项都会考虑前缀。

var re = pathToRegexp('/:foo*', keys)
// keys = [{ name: 'foo', delimiter: '/', optional: true, repeat: true }]

re.exec('/')
//=> ['/', undefined]

re.exec('/bar/baz')
//=> ['/bar/baz', 'bar/baz']

One or more

参数可以以加号 (+) 为后缀，以表示一个或多个参数匹配。 每个匹配项都会考虑前缀。

var re = pathToRegexp('/:foo+', keys)
// keys = [{ name: 'foo', delimiter: '/', optional: false, repeat: true }]

re.exec('/')
//=> null

re.exec('/bar/baz')
//=> ['/bar/baz', 'bar/baz']

Custom Match Parameters

可以为所有参数提供一个自定义正则表达式，它会覆盖默认值 ([^\/]+)。

var re = pathToRegexp('/:foo(\\d+)', keys)
// keys = [{ name: 'foo', ... }]

re.exec('/123')
//=> ['/123', '123']

re.exec('/abc')
//=> null

请注意：反斜杠需要用字符串中的另一个反斜杠进行转义。

Unnamed Parameters

可以编写仅由匹配组组成的未命名参数。 它与命名参数的工作方式相同，只是它将被数字索引。

var re = pathToRegexp('/:foo/(.*)', keys)
// keys = [{ name: 'foo', ... }, { name: 0, ... }]

re.exec('/test/route')
//=> ['/test/route', 'test', 'route']

Asterisk

星号可用于匹配所有内容。 相当于(.*)的未命名匹配组。

var re = pathToRegexp('/foo/*', keys)
// keys = [{ name: '0', ... }]

re.exec('/foo/bar/baz')
//=> ['/foo/bar/baz', 'bar/baz']

Parse

解析函数通过 pathToRegexp.parse 公开。 这将返回一个字符串和键数组。

var tokens = pathToRegexp.parse('/route/:foo/(.*)')

console.log(tokens[0])
//=> "/route"

console.log(tokens[1])
//=> { name: 'foo', prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '[^\\/]+?' }

console.log(tokens[2])
//=> { name: 0, prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '.*' }

注意：此方法仅适用于 Express 风格的字符串。

Compile ("Reverse" Path-To-RegExp)

Path-To-RegExp 公开了一个编译函数，用于将 Express 样式的路径转换为有效路径。

var toPath = pathToRegexp.compile('/user/:id')

toPath({ id: 123 }) //=> "/user/123"
toPath({ id: 'café' }) //=> "/user/caf%C3%A9"
toPath({ id: '/' }) //=> "/user/%2F"

toPath({ id: ':' }) //=> "/user/%3A"
toPath({ id: ':' }, { pretty: true }) //=> "/user/:"

var toPathRepeated = pathToRegexp.compile('/:segment+')

toPathRepeated({ segment: 'foo' }) //=> "/foo"
toPathRepeated({ segment: ['a', 'b', 'c'] }) //=> "/a/b/c"

var toPathRegexp = pathToRegexp.compile('/user/:id(\\d+)')

toPathRegexp({ id: 123 }) //=> "/user/123"
toPathRegexp({ id: '123' }) //=> "/user/123"
toPathRegexp({ id: 'abc' }) //=> Throws `TypeError`.

注意：生成的函数将抛出无效输入。 它将进行所有必要的检查以确保生成的路径有效。 此方法仅适用于字符串。

Working with Tokens

Path-To-RegExp 公开了内部使用的两个接受令牌数组的函数。

• pathToRegexp.tokensToRegExp(tokens, options) Transform an array of tokens into a matching regular expression.
• pathToRegexp.tokensToFunction(tokens) Transform an array of tokens into a path generator function.

Token Information

• name The name of the token (string for named or number for index)
• prefix The prefix character for the segment (/ or .)
• delimiter The delimiter for the segment (same as prefix or /)
• optional Indicates the token is optional (boolean)
• repeat Indicates the token is repeated (boolean)
• partial Indicates this token is a partial path segment (boolean)
• pattern The RegExp used to match this token (string)
• asterisk Indicates the token is an * match (boolean)

Compatibility with Express <= 4.x

Path-To-RegExp 打破了与 Express <= 4.x

• No longer a direct conversion to a RegExp with sugar on top - it's a path matcher with named and unnamed matching groups
• It's unlikely you previously abused this feature, it's rare and you could always use a RegExp instead
• All matching RegExp special characters can be used in a matching group. E.g. /:user(.*)
• Other RegExp features are not support - no nested matching groups, non-capturing groups or look aheads
• Parameters have suffixes that augment meaning - *, + and ?. E.g. /:user*

TypeScript

的兼容性：包括 .d.ts TypeScript 用户的文件。

Live Demo

您可以在 express-route-tester 查看该库的现场演示。

License

麻省理工学院