使用 List API 的项目需要使用 Cloud Storage for Firebase 规则版本 2。如果您已有一个 Firebase 项目,请按照安全规则指南中的步骤操作。
list() 使用 Google Cloud Storage List API。在 Cloud Storage for Firebase 中,我们使用 / 作为分隔符来模拟文件系统语义。为了高效遍历大型分层 Cloud Storage 存储桶,List API 会分开返回前缀和项。例如,如果您上传一个文件 /images/uid/file1,则:
valstorage=Firebase.storagevallistRef=storage.reference.child("files/uid")// You'll need to import com.google.firebase.storage.component1 and// com.google.firebase.storage.component2listRef.listAll().addOnSuccessListener{(items,prefixes)->
for(prefixinprefixes){// All the prefixes under listRef.// You may call listAll() recursively on them.}for(iteminitems){// All the items under listRef.}}.addOnFailureListener{// Uh-oh, an error occurred!}
StorageReferencelistRef=storage.getReference().child("files/uid");listRef.listAll().addOnSuccessListener(newOnSuccessListener<ListResult>(){@OverridepublicvoidonSuccess(ListResultlistResult){for(StorageReferenceprefix:listResult.getPrefixes()){// All the prefixes under listRef.// You may call listAll() recursively on them.}for(StorageReferenceitem:listResult.getItems()){// All the items under listRef.}}}).addOnFailureListener(newOnFailureListener(){@OverridepublicvoidonFailure(@NonNullExceptione){// Uh-oh, an error occurred!}});
funlistAllPaginated(pageToken:String?){valstorage=Firebase.storagevallistRef=storage.reference.child("files/uid")// Fetch the next page of results, using the pageToken if we have one.vallistPageTask=if(pageToken!=null){listRef.list(100,pageToken)}else{listRef.list(100)}// You'll need to import com.google.firebase.storage.component1 and// com.google.firebase.storage.component2listPageTask.addOnSuccessListener{(items,prefixes,pageToken)->
// Process page of resultsprocessResults(items,prefixes)// Recurse onto next pagepageToken?.let{listAllPaginated(it)}}.addOnFailureListener{// Uh-oh, an error occurred.}}
publicvoidlistAllPaginated(@NullableStringpageToken){FirebaseStoragestorage=FirebaseStorage.getInstance();StorageReferencelistRef=storage.getReference().child("files/uid");// Fetch the next page of results, using the pageToken if we have one.Task<ListResult>listPageTask=pageToken!=null?listRef.list(100,pageToken):listRef.list(100);listPageTask.addOnSuccessListener(newOnSuccessListener<ListResult>(){@OverridepublicvoidonSuccess(ListResultlistResult){List<StorageReference>prefixes=listResult.getPrefixes();List<StorageReference>items=listResult.getItems();// Process page of results// ...// Recurse onto next pageif(listResult.getPageToken()!=null){listAllPaginated(listResult.getPageToken());}}}).addOnFailureListener(newOnFailureListener(){@OverridepublicvoidonFailure(@NonNullExceptione){// Uh-oh, an error occurred.}});}
[null,null,["最后更新时间 (UTC):2025-08-21。"],[],[],null,["\u003cbr /\u003e\n\nCloud Storage for Firebase allows you to list the contents of your\nCloud Storage bucket. The SDKs return both the items and the prefixes of\nobjects under the current Cloud Storage reference.\n\nProjects that use the List API require Cloud Storage for Firebase\nRules version 2. If you have an existing Firebase project, follow the steps in\nthe [Security Rules Guide](/docs/storage/security/core-syntax).\n| **Note:** The List API is only allowed for Rules version 2. In Rules version 2, `allow read` is the shorthand for `allow get, list`.\n\n`list()` uses the\n[Google Cloud Storage List API](//cloud.google.com/storage/docs/json_api/v1/objects/list).\nIn Cloud Storage for Firebase, we use `/` as a delimiter, which allows us to\nemulate file system semantics. To allow for efficient traversal of large,\nhierarchical Cloud Storage buckets, the List API returns prefixes and\nitems separately. For example, if you upload one file `/images/uid/file1`,\n\n- `root.child('images').listAll()` will return `/images/uid` as a prefix.\n- `root.child('images/uid').listAll()` will return the file as an item.\n\nThe Cloud Storage for Firebase SDK does not return object paths that contain two\nconsecutive `/`s or end with a `/`. For example, consider a bucket that has the\nfollowing objects:\n\n- `correctPrefix/happyItem`\n- `wrongPrefix//sadItem`\n- `lonelyItem/`\n\nThe list operations on items in this bucket will give the following results:\n\n- The list operation at the root returns the references to `correctPrefix`, `wrongPrefix` and `lonelyItem` as `prefixes`.\n- The list operation at the `correctPrefix/` returns the references to `correctPrefix/happyItem` as `items`.\n- The list operation at the `wrongPrefix/` doesn't return any references because `wrongPrefix//sadItem` contains two consecutive `/`s.\n- The list operation at the `lonelyItem/` doesn't return any references because the object `lonelyItem/` ends with `/`.\n\nList all files\n\nYou can use `listAll` to fetch all results for a directory.\nThis is best used for small directories as all results are buffered in memory.\nThe operation also may not return a consistent snapshot if objects are added or\nremoved during the process.\n\nFor a large list, use the paginated `list()` method as `listAll()` buffers all\nresults in memory.\n\nThe following example demonstrates `listAll`. \n\nKotlin \n\n```kotlin\nval storage = Firebase.storage\nval listRef = storage.reference.child(\"files/uid\")\n\n// You'll need to import com.google.firebase.storage.component1 and\n// com.google.firebase.storage.component2\nlistRef.listAll()\n .addOnSuccessListener { (items, prefixes) -\u003e\n for (prefix in prefixes) {\n // All the prefixes under listRef.\n // You may call listAll() recursively on them.\n }\n\n for (item in items) {\n // All the items under listRef.\n }\n }\n .addOnFailureListener {\n // Uh-oh, an error occurred!\n }https://github.com/firebase/snippets-android/blob/391c1646eacf44d2aab3f76bcfa60dfc6c14acf1/storage/app/src/main/java/com/google/firebase/referencecode/storage/kotlin/StorageActivity.kt#L437-L455\n```\n\nJava \n\n```java\nStorageReference listRef = storage.getReference().child(\"files/uid\");\n\nlistRef.listAll()\n .addOnSuccessListener(new OnSuccessListener\u003cListResult\u003e() {\n @Override\n public void onSuccess(ListResult listResult) {\n for (StorageReference prefix : listResult.getPrefixes()) {\n // All the prefixes under listRef.\n // You may call listAll() recursively on them.\n }\n\n for (StorageReference item : listResult.getItems()) {\n // All the items under listRef.\n }\n }\n })\n .addOnFailureListener(new OnFailureListener() {\n @Override\n public void onFailure(@NonNull Exception e) {\n // Uh-oh, an error occurred!\n }\n });https://github.com/firebase/snippets-android/blob/391c1646eacf44d2aab3f76bcfa60dfc6c14acf1/storage/app/src/main/java/com/google/firebase/referencecode/storage/StorageActivity.java#L558-L579\n```\n\nPaginate list results\n\nThe `list()` API places a limit on the number of results it returns. `list()`\nprovides a consistent pageview and exposes a pageToken that allows control over\nwhen to fetch additional results.\n\nThe pageToken encodes the path and version of the last item returned in the\nprevious result. In a subsequent request using the pageToken, items that come\nafter the pageToken are shown.\n\nThe following example demonstrates paginating a result: \n\nKotlin \n\n```kotlin\nfun listAllPaginated(pageToken: String?) {\n val storage = Firebase.storage\n val listRef = storage.reference.child(\"files/uid\")\n\n // Fetch the next page of results, using the pageToken if we have one.\n val listPageTask = if (pageToken != null) {\n listRef.list(100, pageToken)\n } else {\n listRef.list(100)\n }\n\n // You'll need to import com.google.firebase.storage.component1 and\n // com.google.firebase.storage.component2\n listPageTask\n .addOnSuccessListener { (items, prefixes, pageToken) -\u003e\n // Process page of results\n processResults(items, prefixes)\n\n // Recurse onto next page\n pageToken?.let {\n listAllPaginated(it)\n }\n }.addOnFailureListener {\n // Uh-oh, an error occurred.\n }\n}https://github.com/firebase/snippets-android/blob/391c1646eacf44d2aab3f76bcfa60dfc6c14acf1/storage/app/src/main/java/com/google/firebase/referencecode/storage/kotlin/StorageActivity.kt#L463-L488\n```\n\nJava \n\n```java\npublic void listAllPaginated(@Nullable String pageToken) {\n FirebaseStorage storage = FirebaseStorage.getInstance();\n StorageReference listRef = storage.getReference().child(\"files/uid\");\n\n // Fetch the next page of results, using the pageToken if we have one.\n Task\u003cListResult\u003e listPageTask = pageToken != null\n ? listRef.list(100, pageToken)\n : listRef.list(100);\n\n listPageTask\n .addOnSuccessListener(new OnSuccessListener\u003cListResult\u003e() {\n @Override\n public void onSuccess(ListResult listResult) {\n List\u003cStorageReference\u003e prefixes = listResult.getPrefixes();\n List\u003cStorageReference\u003e items = listResult.getItems();\n\n // Process page of results\n // ...\n\n // Recurse onto next page\n if (listResult.getPageToken() != null) {\n listAllPaginated(listResult.getPageToken());\n }\n }\n }).addOnFailureListener(new OnFailureListener() {\n @Override\n public void onFailure(@NonNull Exception e) {\n // Uh-oh, an error occurred.\n }\n });\n}https://github.com/firebase/snippets-android/blob/391c1646eacf44d2aab3f76bcfa60dfc6c14acf1/storage/app/src/main/java/com/google/firebase/referencecode/storage/StorageActivity.java#L584-L614\n```\n\nHandle errors\n\n`list()` and `listAll()` fail if you haven't upgraded\nthe Security Rules to version 2. Upgrade your Security Rules if you see this\nerror: \n\n Listing objects in a bucket is disallowed for rules_version = \"1\".\n Please update storage security rules to rules_version = \"2\" to use list.\n\nOther possible errors may indicate the user does not have the right permission.\nMore information on errors can be found in the\n[Handle Errors](/docs/storage/android/handle-errors)."]]