「这是我参与2022首次更文挑战的第18天，活动详情查看：2022首次更文挑战」。

本文翻译自pub: uuid | Dart Package (flutter-io.cn)

译时版本： uuid 3.0.5

感觉该库的 pub 文档不太好理解。

自己的水平还是太烂。

3.0.x 版本有破坏性的改动，请查阅改动履历和文档。UuidValue 仍然是试验性的，它的API也还未定，请注意改动履历和版本。

uuid

用于简单快速生成 RFC4122 UUID 。

特性:

生成 RFC4122 版本 1 、版本 4 、或版本 5 的 UUID
可在 Web、服务器、和 Flutter 中运行。
在所有平台生成强加密随机数
- 默认的生成器不加密，查看用于 cryptoRNG 的 UuidUtil
文档

开始

使用说明

打开命令行进入到工程的根目录
在 pubspec 中添加 dart-uuid 依赖 (下面的示例)
运行 pub install
如果想运行测试，进入到 packages/dart-uuid/ 并运行 'dart test/uuid_test.dart'

Pubspec

这里有两个选项，直接依赖 git 或者依赖 pub.flutter-io.cn 。

pub.flutter-io.cn：（如果总是想使用最新版本，可以使用 'any' 代替具体版本）

dependencies:
  uuid: 3.0.5

import 'package:uuid/uuid.dart';

var uuid = Uuid();

然后创建一些 ID ...

// 生成 v1 (基于时间) id
uuid.v1(); // -> '6c84fb90-12c4-11e1-840d-7b25c5ee775a'

// 生成 v4 (随机数) id
uuid.v4(); // -> '110ec58a-a0f2-4ac4-8393-c866d813b8d1'

// 生成 v5 (基于命名空间 SHA1 ) id
uuid.v5(Uuid.NAMESPACE_URL, 'www.google.com'); // -> 'c74a196f-f19d-5ea9-bffd-a2742432fc9c'

API

Uuid({Map<String, dynamic> options: null}) -> Uuid (Constructor)

构造方法支持一些全局的 RNG 设定，这样你无需为每个函数的 v4 或 v5 调用时指定。

options - (Map<String, dynamic>) 可选的 UUID 状态。属性可能包括：
- grng - (函数) 随机 # 作为全局 RNG 函数的生成器。是一个返回字节值的列表[长度16]的自定义函数，或者提供的两者之一（or 1 of 2 provided 最后这句不知道怎么翻译）。
- gNamedArgs - (Map<Symbol, dynamic>) 传递给全局 RNG 函数的参数和值。
- gPositionalArgs - (列表) 全局 RNG 函数的占位参数（如果有的话）。
- v1rng - (函数) 随机 # 用于 V1 种子的 RNG 函数的生成器。是一个返回字节值的列表[长度16]的自定义函数，或者提供的两者之一（or 1 of 2 provided 最后这句不知道怎么翻译）。
- v1rngNamedArgs - (Map<Symbol, dynamic>) 传递给 v1 RNG 函数的参数和值。
- v1rngPositionalArgs - (列表) ，是 v1 RNG 函数的占位参数（如果有的话）。

默认是 Uuid.mathRNG

示例: 使用全局 CryptoRNG

var uuid = Uuid(options: {
  'grng': UuidUtil.cryptoRNG
})

// 使用 cryptRNG 作为 rng 生成 v4（随机） ID 
uuid.v4();

uuid.v1({Map<String, dynamic> options: null) -> String

uuid.v1obj({Map<String, dynamic> options: null) -> UuidValue

uuid.v1buffer(List

生成和返回 RFC4122 v1 (基于时间戳) UUID.

options - (Map<String, dynamic>) 可选的 UUID 状态。属性可能包括：
- node - 列表
- clockseq - （0 到 0x3fff 之间的数值）RFC 时钟序列。默认：使用内部维护的时钟序列。
- msecs - （Number） UNIUX 时间戳的毫秒。默认：当前时间。
- nsecs - (0 到 9999 之间的数值) 附加时间，百纳秒单位。如果 msecs 未指定会忽略（该属性）。默认：内部的 UUID 计数器，例如每4.2.1.2？（此处不会翻译）
buffer - 列表
offset - (Int) buffer的开始下标，从该下标开始写（buffer）。

v1() 返回 UUID 的字符串表现。

v1buffer() 返回一个列表。

v1obj() 返回一个 UuidValue （UUID 值），它包装了字符串，并带有一个有效性检验和一些内置函数。

示例：指定所有选项，生成 UUID 字符串。

uuid.v1(options: {
    'node': [0x01, 0x23, 0x45, 0x67, 0x89, 0xab],
    'clockSeq': 0x1234,
    'mSecs': new DateTime.utc(2011,11,01).millisecondsSinceEpoch,
    'nSecs': 5678
})   // -> "710b962e-041c-11e1-9234-0123456789ab"

示例：使用两个二进制 ID 就地生成

// 在数组中生成两个 ID
var myBuffer = new List(32); // -> []
uuid.v1buffer(myBuffer);
// -> [115, 189, 5, 128, 201, 91, 17, 225, 146, 52, 109, 0, 9, 0, 52, 128, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null]
uuid.v1buffer(myBuffer, offset: 16);  
// -> [115, 189, 5, 128, 201, 91, 17, 225, 146, 52, 109, 0, 9, 0, 52, 128, 115, 189, 5, 129, 201, 91, 17, 225, 146, 52, 109, 0, 9, 0, 52, 128]

// 指定选项，使用 uuid.unparse() 来获取 ID 的字符串
uuid.unparse(myBuffer);    // -> '73bd0580-c95b-11e1-9234-6d0009003480'
uuid.unparse(myBuffer, offset: 16) // -> '73bd0581-c95b-11e1-9234-6d0009003480'

示例: UuidValue 用法

uuidValue = uuid.v1Obj(options: {
    'node': [0x01, 0x23, 0x45, 0x67, 0x89, 0xab],
    'clockSeq': 0x1234,
    'mSecs': new DateTime.utc(2011,11,01).millisecondsSinceEpoch,
    'nSecs': 5678
}) // -> UuidValue{uuid: '710b962e-041c-11e1-9234-0123456789ab'}

print(uuidValue) -> // -> '710b962e-041c-11e1-9234-0123456789ab'
uuidValue.toBytes() -> // -> [...]

uuid.v4({Map<String, dynamic> options: null}) -> String

uuid.v4obj({Map<String, dynamic> options: null}) -> UuidValue

uuid.v4buffer(List

生成和返回一个 RFC4122 v4 UUID 。

options - (Map<String, dynamic>) 可选的 UUID 状态。属性可能包括：
- random - (Number[16]) 长度为16的列表 (0-255) ，用于代替随机生成的值。
- rng - (函数) 随机 # 使用的生成器。返回字节值的列表[长度16]的自定义函数，（or 1 of 2 provided 最后这句不知道怎么翻译）。
- namedArgs - (Map<Symbol, dynamic>) 传递给函数函数的参数和值。
- positionalArgs - (列表)函数的占位参数（如果有）。
buffer - (列表
offset - (Number) buffer的开始下标，从该下标开始写（buffer）。

v4() 返回 UUID 的字符串表现。

v4buffer() 返回一个列表。

v4obj() 返回一个 UuidValue （UUID 值），它包装了字符串，并带有一个有效性检验和一些内置函数。

示例: 使用不同的 RNG 方法生成 UUID 字符串。

import 'package:uuid/uuid_util.dart';
uuid.v4(options: {
  'rng': UuidUtil.cryptoRNG
});
// -> "109156be-c4fb-41ea-b1b4-efe1671c5836"

示例：使用不同的 RNG 方法和命名的参数生成 UUID 字符串。

import 'package:uuid/uuid_util.dart';
uuid.v4(options: {
  'rng': UuidUtil.mathRNG,
  'namedArgs': new Map.fromIterables([const Symbol('seed')],[1])
});
// -> "09a91894-e93f-4141-a3ec-82eb32f2a3ef"

示例：使用不同的 RNG 方法和占位参数生成 UUID 字符串。

import 'package:uuid/uuid_util.dart';
uuid.v4(options: {
  'rng': UuidUtil.cryptoRNG,
  'positionalArgs': [1]
});
// -> "09a91894-e93f-4141-a3ec-82eb32f2a3ef"

示例: 指定所有选项，生成 UUID 字符串。

uuid.v4(options: {
  'random': [
    0x10, 0x91, 0x56, 0xbe, 0xc4, 0xfb, 0xc1, 0xea,
    0x71, 0xb4, 0xef, 0xe1, 0x67, 0x1c, 0x58, 0x36
  ]
});
// -> "109156be-c4fb-41ea-b1b4-efe1671c5836"

示例: 在单个 Buffer（缓冲）中生成两个 ID 。

var myBuffer = new List(32);
uuid.v4buffer(myBuffer);
uuid.v4buffer(myBuffer, offset: 16);

示例: UuidValue 用法

uuidValue = uuid.v4obj(options: {
  'random': [
    0x10, 0x91, 0x56, 0xbe, 0xc4, 0xfb, 0xc1, 0xea,
    0x71, 0xb4, 0xef, 0xe1, 0x67, 0x1c, 0x58, 0x36
  ]
}) // -> UuidValue{uuid: '109156be-c4fb-41ea-b1b4-efe1671c5836'}

print(uuidValue) -> // -> '109156be-c4fb-41ea-b1b4-efe1671c5836'
uuidValue.toBytes() -> // -> [...]

uuid.v5(String namespace, String name, {Map<String, dynamic> options: null}) -> String

uuid.v5obj(String namespace, String name, {Map<String, dynamic> options: null}) -> UuidValue

uuid.v5buffer(String namespace, String name, List

生成和返回 RFC4122 v5 UUID 。

options - (Map<String, dynamic>)可选的 UUID 状态。属性可能包括：
- randomNamespace - (Boolean) 默认为 true 。如果想要一个生成的命名空间会返回 true，使用NAMESPACE_NIL 的话会返回 false 。
buffer - (列表
offset - (Number) buffer的开始下标，从该下标开始写（buffer）。

v4() 返回 UUID 的字符串表现。

v4buffer() 返回一个列表。

v5() 返回 UUID 的字符串表现。

v5buffer() 返回一个列表。

v5obj() 返回一个 UuidValue （UUID 值），它包装了字符串，并带有一个有效性检验和一些内置函数。

示例: 指定所有选项，生成 UUID 字符串。

uuid.v5(Uuid.NAMESPACE_URL, 'www.google.com');
// -> "c74a196f-f19d-5ea9-bffd-a2742432fc9c"

示例: 在单个 Buffer（缓冲）中生成两个 ID 。

var myBuffer = new List(32);
uuid.v5buffer(Uuid.NAMESPACE_URL, 'www.google.com', myBuffer);
uuid.v5buffer(Uuid.NAMESPACE_URL, 'www.google.com', myBuffer, offset: 16);

示例: UuidValue 用法。

uuidValue = uuid.v5obj(Uuid.NAMESPACE_URL, 'www.google.com'); 
// -> UuidValue(uuid: "c74a196f-f19d-5ea9-bffd-a2742432fc9c")

print(uuidValue) -> // -> 'c74a196f-f19d-5ea9-bffd-a2742432fc9c'
uuidValue.toBytes() -> // -> [...]

uuid.parse(String uuid, {List

uuid.parseAsByteList(String uuid, {List

uuid.unparse(List

解析和反解析 UUID 。

id - (String) UUID(-之类) 字符串
buffer - (List) 用于写 UUID 字节的数组或 Buffer（缓冲）。默认：一个新数组或 Buffer。
offset - (Int | Number) buffer的开始下标，从该下标开始写（buffer）。默认：0 。
validate - (bool, 默认：true) 允许禁用 UUID 检验，主要用于 Microsoft GUID 的一些奇怪现象。

Throws:

parse() -> FormatException - 如果不是一个有效的 UUID

unparse() -> Exception - 如果列表内容长度不是 16 。

解析和反解析 UUID 字符串的示例：

var bytes = uuid.parse('797ff043-11eb-11e1-80d6-510998755d10'); // -> [121, 127, 240, 67, 17, 235, 17, 225, 128, 214, 81, 9, 152, 117, 93, 16]
var string = uuid.unparse(bytes); // -> '797ff043-11eb-11e1-80d6-510998755d10'

更多示例或用户，参考 test（测试）实现。

测试

在 dartvm 中：

dart test\uuid_test.dart

在浏览器/Flutter 中：

没有在浏览器中的测试，但是我知道一些使用该库的 Web 和 Flutter 工程

Dart2js 输出大小 (最小、使用 -O2 的最优optimized with -O2)

仅v1：59kb
仅v4：54kb
仅v4加密：61kb
仅v5：69kb
v1 + v4：66kb (包含加密)
v4 + v5：76kb (包含加密)
所有: 76kb
v1 + v5：77kb

发布事项

参考CHANGELOG。

[译]Dart UUID库uuid