首頁>編程相關>其他源碼
下載

uuid

用於建立 RFC9562（以前稱為 RFC4122）UUID

  • 完整- 支援所有 RFC9562 UUID 版本
  • 跨平台- 支援...
    • ESM 和通用 JS
    • Chrome、Safari、Firefox、Edge 瀏覽器
    • NodeJS
    • 反應本機/博覽會
  • 安全- 加密強度強的隨機值
  • 緊湊- 無依賴關係，可搖樹
  • CLI - 包括uuid命令列實用程序
  • Typescript - 現在包含類型

筆記

w> uuid@11現已可用：有關詳細信息，請參閱變更日誌。長話短說：

  • 現在包含 TypeScript 支援（從依賴項中刪除@types/uuid ）
  • 對v1() 、 v6()和v7() options arg 的解釋方式進行了微妙的更改。看詳情
  • 二進位 UUID 現在是Uint8Array 。 （可能會影響parse() 、 stringify()的呼叫者或將option#buf參數傳遞給v1() - v7()的呼叫者。）

快速入門

1. 安裝

npm install uuid

2.創建UUID

ESM 語法（必須使用命名導出）： 

 import { v4 as uuidv4 } from 'uuid' ;
uuidv4 ( ) ; // ⇨ '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'

... CommonJS： 

 const { v4 : uuidv4 } = require ( 'uuid' ) ;
uuidv4 ( ) ; // ⇨ '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed'

對於時間戳 UUID、命名空間 UUID 和其他選項，請繼續閱讀...

API摘要

uuid.NIL nil UUID 字串（全為零） [email protected]中的新功能
uuid.MAX最大 UUID 字串（全部為 1） [email protected]中的新功能
uuid.parse()將 UUID 字串轉換為位元組數組[email protected]中的新功能
uuid.stringify()將位元組數組轉換為 UUID 字串[email protected]中的新功能
uuid.v1()建立版本 1（時間戳記）UUID
uuid.v1ToV6()從版本 1 UUID 建立版本 6 UUID uuid@10中的新功能
uuid.v3()建立版本 3（帶 MD5 的命名空間）UUID
uuid.v4()建立版本 4（隨機）UUID
uuid.v5()建立版本 5（帶有 SHA-1 的命名空間）UUID
uuid.v6()建立版本 6（時間戳記、重新排序）UUID uuid@10中的新功能
uuid.v6ToV1()從版本 6 UUID 建立版本 1 UUID uuid@10中的新功能
uuid.v7()建立版本 7（基於 Unix Epoch 時間）的 UUID uuid@10中的新功能
uuid.v8() “故意留空”
uuid.validate()測試字串以查看它是否是有效的 UUID [email protected]中的新功能
uuid.version()檢測 UUID 的 RFC 版本[email protected]中的新功能

應用程式介面

uuid.NIL

nil UUID 字串（全為零）。

例子： 

 import { NIL as NIL_UUID } from 'uuid' ;

NIL_UUID ; // ⇨ '00000000-0000-0000-0000-000000000000'

uuid.MAX

最大 UUID 字串（全為 1）。

例子： 

 import { MAX as MAX_UUID } from 'uuid' ;

MAX_UUID ; // ⇨ 'ffffffff-ffff-ffff-ffff-ffffffffffff'

uuid.parse(str)

將 UUID 字串轉換為位元組數組

str有效的 UUID String
回報Uint8Array[16]
投擲如果str不是有效的 UUID，則TypeError

筆記

parse()和stringify()使用的位元組數組中的值的順序遵循 UUID 字串中十六進位對的左↠右順序。如下例所示。

例子： 

 import { parse as uuidParse } from 'uuid' ;

// Parse a UUID
uuidParse ( '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b' ) ; // ⇨ 
  // Uint8Array(16) [
  //   110, 192, 189, 127,  17,
  //   192,  67, 218, 151,  94,
  //    42, 138, 217, 235, 174,
  //    11
  // ]

uuid.stringify(arr[, 偏移])

將位元組數組轉換為 UUID 字串

arr類似Array的 16 個值的集合（從offset開始），介於 0-255 之間。
[ offset =0] Number數組中的起始索引
回報String
投擲如果無法產生有效的 UUID 字串，則TypeError

筆記

parse()和stringify()使用的位元組數組中的值的順序遵循 UUID 字串中十六進位對的左↠右順序。如下例所示。

例子： 

 import { stringify as uuidStringify } from 'uuid' ;

const uuidBytes = Uint8Array . of (
  0x6e ,
  0xc0 ,
  0xbd ,
  0x7f ,
  0x11 ,
  0xc0 ,
  0x43 ,
  0xda ,
  0x97 ,
  0x5e ,
  0x2a ,
  0x8a ,
  0xd9 ,
  0xeb ,
  0xae ,
  0x0b
) ;

uuidStringify ( uuidBytes ) ; // ⇨ '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'

uuid.v1([選項[,緩衝區[,偏移]]])

建立 RFC 版本 1（時間戳記）UUID

[ options ]具有以下一項或多項屬性的Object ：
[ options.node = (random) ] RFC「節點」欄位作為位元組值的Array[6] （依照 4.1.6）
[ options.clockseq = (random) ] RFC「時鐘序列」作為 0 - 0x3fff 之間的Number
[ options.msecs = (current time) ] RFC「時間戳記」欄位（毫秒Number ，unix 紀元）
[ options.nsecs = 0 ] RFC「時間戳記」欄位（加到msecs的奈Number ，應為 0-10,000）
[ options.random = (random) ] 16 個隨機位元組 (0-255) 的Array ，用於產生上面的其他字段
[ options.rng ] options.random的替代方案，一個傳回 16 個隨機位元組 (0-255) 的Array的Function
[ buffer ] Array | Buffer如果指定，uuid 將以位元組形式寫入此處，從offset開始
[ offset =0]開始在buffer中寫入 UUID 位元組Number索引
回報UUID 若沒有指定buffer String ，否則傳回buffer
投擲如果每秒請求超過 10M UUID， Error

筆記

預設節點 ID（UUID 中的最後 12 位數）在進程啟動時隨機產生一次，然後在進程持續時間內保持不變。

筆記

options.random和options.rng僅在第一次呼叫v1()時才有意義，可以傳遞它們來初始化內部node和clockseq欄位。

例子： 

 import { v1 as uuidv1 } from 'uuid' ;

uuidv1 ( ) ; // ⇨ '2c5ea4c0-4067-11e9-9bdd-2b0d7b3dcb6d'

使用options的範例： 

 import { v1 as uuidv1 } from 'uuid' ;

const options = {
  node : Uint8Array . of ( 0x01 , 0x23 , 0x45 , 0x67 , 0x89 , 0xab ) ,
  clockseq : 0x1234 ,
  msecs : new Date ( '2011-11-01' ) . getTime ( ) ,
  nsecs : 5678 ,
} ;
uuidv1 ( options ) ; // ⇨ '710b962e-041c-11e1-9234-0123456789ab'

uuid.v1ToV6(uuid)

將 UUID 從版本 1 轉換為版本 6 

 import { v1ToV6 } from 'uuid' ;

v1ToV6 ( '92f62d9e-22c4-11ef-97e9-325096b39f47' ) ; // ⇨ '1ef22c49-2f62-6d9e-97e9-325096b39f47'

uuid.v3(name, 命名空間[, 緩衝區[, 偏移量]])

建立 RFC 版本 3（帶 MD5 的命名空間）UUID

API 與v5()相同，但使用“v3”代替。

重要的

根據 RFC，“如果向後相容性不是問題，則首選 SHA-1 [版本 5] 。”

uuid.v4([選項[,緩衝區[,偏移]]])

建立 RFC 版本 4（隨機）UUID

[ options ]具有以下一項或多項屬性的Object ：
[ options.random .隨機] 16 個隨機位元Array (0-255)
[ options.rng ] options.random的替代方案，一個傳回 16 個隨機位元組 (0-255) 的Array的Function
[ buffer ] Array | Buffer如果指定，uuid 將以位元組形式寫入此處，從offset開始
[ offset =0]開始在buffer中寫入 UUID 位元組Number索引
回報UUID 若沒有指定buffer String ，否則傳回buffer

例子： 

 import { v4 as uuidv4 } from 'uuid' ;

uuidv4 ( ) ; // ⇨ '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'

使用預定義random值的範例： 

 import { v4 as uuidv4 } from 'uuid' ;

const v4options = {
  random : Uint8Array . of (
    0x10 ,
    0x91 ,
    0x56 ,
    0xbe ,
    0xc4 ,
    0xfb ,
    0xc1 ,
    0xea ,
    0x71 ,
    0xb4 ,
    0xef ,
    0xe1 ,
    0x67 ,
    0x1c ,
    0x58 ,
    0x36
  ) ,
} ;
uuidv4 ( v4options ) ; // ⇨ '109156be-c4fb-41ea-b1b4-efe1671c5836'

uuid.v5(name, 命名空間[, 緩衝區[, 偏移量]])

建立 RFC 版本 5（具有 SHA-1 的命名空間）UUID

name String | Array
namespace String | Array[16]命名空間UUID
[ buffer ] Array | Buffer如果指定，uuid 將以位元組形式寫入此處，從offset開始
[ offset =0]開始在buffer中寫入 UUID 位元組Number索引
回報UUID 若沒有指定buffer String ，否則傳回buffer

筆記

RFC DNS和URL命名空間可用作v5.DNS和v5.URL 。

自訂命名空間的範例： 

 import { v5 as uuidv5 } from 'uuid' ;

// Define a custom namespace.  Readers, create your own using something like
// https://www.uuidgenerator.net/
const MY_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341' ;

uuidv5 ( 'Hello, World!' , MY_NAMESPACE ) ; // ⇨ '630eb68f-e0fa-5ecc-887a-7c7a62614681'

RFC URL命名空間範例： 

 import { v5 as uuidv5 } from 'uuid' ;

uuidv5 ( 'https://www.w3.org/' , uuidv5 . URL ) ; // ⇨ 'c106a26a-21bb-5538-8bf2-57095d1976c1'

uuid.v6([選項[,緩衝區[,偏移]]])

建立 RFC 版本 6（時間戳記、重新排序）UUID

此方法採用與 uuid.v1() 相同的參數。 

 import { v6 as uuidv6 } from 'uuid' ;

uuidv6 ( ) ; // ⇨ '1e940672-c5ea-64c0-9b5d-ab8dfbbd4bed'

使用options的範例： 

 import { v6 as uuidv6 } from 'uuid' ;

const options = {
  node : [ 0x01 , 0x23 , 0x45 , 0x67 , 0x89 , 0xab ] ,
  clockseq : 0x1234 ,
  msecs : new Date ( '2011-11-01' ) . getTime ( ) ,
  nsecs : 5678 ,
} ;
uuidv6 ( options ) ; // ⇨ '1e1041c7-10b9-662e-9234-0123456789ab'

uuid.v6ToV1(uuid)

將 UUID 從版本 6 轉換為版本 1 

 import { v6ToV1 } from 'uuid' ;

v6ToV1 ( '1ef22c49-2f62-6d9e-97e9-325096b39f47' ) ; // ⇨ '92f62d9e-22c4-11ef-97e9-325096b39f47'

uuid.v7([選項[,緩衝區[,偏移]]])

建立 RFC 版本 7（隨機）UUID

[ options ]具有以下一項或多項屬性的Object ：
[ options.msecs = (current time) ] RFC「時間戳記」欄位（毫秒Number ，unix 紀元）
[ options.random = (random) ] 16 個隨機位元組 (0-255) 的Array ，用於產生上面的其他字段
[ options.rng ] options.random的替代方案，一個傳回 16 個隨機位元組 (0-255) 的Array的Function
[ options.seq = (random) ] 32 位元序列 0 - 0xffffffff 之間的Number 。這可以被提供以幫助確保在同一毫秒時間間隔內產生的UUID的唯一性。預設值 = 隨機值。
[ buffer ] Array | Buffer如果指定，uuid 將以位元組形式寫入此處，從offset開始
[ offset =0]開始在buffer中寫入 UUID 位元組Number索引
回報UUID 若沒有指定buffer String ，否則傳回buffer

例子： 

 import { v7 as uuidv7 } from 'uuid' ;

uuidv7 ( ) ; // ⇨ '01695553-c90c-705a-b56d-778dfbbd4bed'

uuid.v8()

“故意留空”

筆記

版本 8（實驗性）UUID「用於實驗性或特定於供應商的用例」。 RFC 沒有為它們定義建立演算法，這就是為什麼這個套件不提供v8()方法。然而， validate()和version()方法確實適用於此類 UUID。

uuid.validate(str)

測試字串以查看它是否是有效的 UUID

str要驗證的String
回報如果字串是有效的 UUID，則為true ，否則為false

例子： 

 import { validate as uuidValidate } from 'uuid' ;

uuidValidate ( 'not a UUID' ) ; // ⇨ false
uuidValidate ( '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b' ) ; // ⇨ true

一起使用validate和version可以進行每個版本的驗證，例如僅驗證 v4 UUId。 

 import { version as uuidVersion } from 'uuid' ;
import { validate as uuidValidate } from 'uuid' ;

function uuidValidateV4 ( uuid ) {
  return uuidValidate ( uuid ) && uuidVersion ( uuid ) === 4 ;
}

const v1Uuid = 'd9428888-122b-11e1-b85c-61cd3cbb3210' ;
const v4Uuid = '109156be-c4fb-41ea-b1b4-efe1671c5836' ;

uuidValidateV4 ( v4Uuid ) ; // ⇨ true
uuidValidateV4 ( v1Uuid ) ; // ⇨ false

uuid.版本(str)

檢測 UUID 的 RFC 版本

str有效的 UUID String
回報Number UUID 的 RFC 版本
投擲如果str不是有效的 UUID，則TypeError

例子： 

 import { version as uuidVersion } from 'uuid' ;

uuidVersion ( '45637ec4-c85f-11ea-87d0-0242ac130003' ) ; // ⇨ 1
uuidVersion ( '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b' ) ; // ⇨ 4

筆記

對於NIL UUID，此方法傳回0 ；對於MAX UUID，此方法傳回15 。

命令列

可以使用uuid從命令列產生 UUID。 

$ npx uuid
ddeb27fb-d9a0-4624-be4d-4615062daed4

預設產生版本 4 UUIDS，但也支援其他版本。輸入uuid --help以了解詳細資訊： 

$ npx uuid --help

Usage:
  uuid
  uuid v1
  uuid v3 < name > < namespace uuid >
  uuid v4
  uuid v5 < name > < namespace uuid >
  uuid v7
  uuid --help

Note: < namespace uuid > may be " URL " or " DNS " to use the corresponding UUIDs
defined by RFC9562

時間戳 UUID 的options處理

在uuid@11之前， options狀態可能會幹擾用於確保基於時間戳記的 UUID 唯一性的內部狀態（ v1() 、 v6()和v7()方法）。從uuid@11開始，這個問題已透過使用options參數的存在作為標誌來在兩種可能的行為之間進行選擇來解決：

  • 不含options ：利用內部狀態來提高 UUID 的唯一性。
  • 使用options ：不使用內部狀態，而是根據需要套用適當的預設值。

支援

瀏覽器： uuid版本針對最新版本的桌面 Chrome、Safari、Firefox 和 Edge 進行了測試。這些瀏覽器的行動版本預計可以運行，但目前尚未經過測試。

Node ： uuid建置針對 Node（LTS 版本）以及先前的版本進行測試。例如， node@18處於維護模式， node@22是目前的 LTS 版本。所以uuid支援node@16 - node@22 。

Typescript ：支援過去兩年內發布的 TS 版本。來源

已知問題

反應本機/博覽會

  1. 安裝react-native-get-random-values
  2. 在uuid之前導入它。由於uuid也可能顯示為某些其他導入的傳遞依賴項，因此最安全的做法是導入react-native-get-random-values作為入口點的第一件事： 
 import 'react-native-get-random-values' ;
import { v4 as uuidv4 } from 'uuid' ;

從 README_js.md 產生的 Markdown

展開
附加信息
相關應用
爲您推薦
相關資訊 全部