Xodera Plugins · Bubble Native
Xodera B2 Files Native
将应用附件保存在您自己的 Backblaze B2 存储中。允许有权限的用户上传、浏览和下载文件，并明确选择何时可以公开共享文件。
Public beta guides · Haptics instructions are in its Bubble listing
Public beta offer: free Bubble install · 7-day card trial, then US$1.50/month per plugin/project.
文档审阅日期：2026年11月6日
实用示例
将作业附件存储在开发者自己的私有存储桶中
Bubble 作业需要持久的存储引用，而不能将即将过期的下载 URL 视为文件标识。
`bucket_binding_id = an allowed binding to your own private bucket`；动态的 `local_uri`、`display_name`、`mime_type` 和 `expected_size` 描述所选本地文件。
计划：Check local source → Upload file → 等待 `upload_verified`。随后您的工作流将在所属作业记录中存储 `asset_ref` 及其元数据。
使用 `asset_ref`、`size_bytes`、`mime_type` 和 `upload_status`。稍后，Resolve private read 可提供用于授权使用的临时 URL。
如果在 `upload_verified` 之后数据库保存失败，请使用相同的资产引用而非重新上传来重试数据库更新。使用 Check or recover upload status 和相同的上传 ID 检查 `upload_pending` 的结果。
计划中。您的 B2 账户承担存储和下载费用。
构建拥有的附件图库，使用持久的文件记录
文件图库需要名称、类型和分页，并且需要能够在稍后打开所选资产的方式。
您的应用的文件记录在验证上传后存储已接受的 `asset_ref`、显示名称、MIME 以及所有者/作业关系；请勿使用本地 URI 作为其云端标识。
计划：使用 List my B2 files 构建附件列表。asset_refs 标识文件；相同索引的值提供其名称和类型。选择文件后将其 asset_ref 传递给 Get asset metadata 或 Download accepted version。
`has_more` 和 `next_cursor` 属于当前查询。完成下载后返回 `local_output_uri`；它是设备本地副本，而非永久公共链接。
在绑定/账户/查询更改后重置分页。在 `transfer_error` 时，保留现有的文件对象并显示 `error_code`；不要悄悄用提供商处的另一个文件版本替换它。
计划中。您的 B2 账户承担存储和下载费用。
使发布和精确版本删除成为有意操作
工作人员在替换图片时不应意外暴露私人附件或删除所有版本。
`asset_ref = the selected accepted version`；存储桶绑定和应用的文件权限必须允许请求的操作。
显示当前可见性，要求明确确认，然后执行 Change public sharing。删除时，使用确认调用 Delete accepted version；在确认结果已知之前保留应用元数据。
在 `share_changed` 之后，仅在明确授权公开共享时使用 `visibility` 和 `public_url`。`delete_completed` 之后，更新所属文件记录；`delete_pending` 并非最终删除。
检查不确定操作的结果，而不是假设成功。先前发出的提供商读取 URL 可能在到期前仍然有效；删除数据库行或禁用共享并不会召回已下载的字节。
计划中。您的 B2 账户承担存储和下载费用。
当前可用功能
计划中的插件。尚未安装或可供使用。以下指南展示了预期的文件工作流。
构建工作流
计划中
计划中的工作流。目前的测试版尚不可用。
这些示例使用了诸如 Lesson、Message 和 Order 的应用记录。请将它们替换为您自己的数据类型和元素名称。示例媒体地址必须替换为您自己的文件。
计划：在项目设置中，选择您的 B2 存储和允许的存储桶。设置其隐私、文件夹前缀以及接受的文件类型和大小。
使用 List B2 bindings 显示允许的存储选项。使用 List my B2 files 显示当前用户的文件，Get my B2 file info 显示详细信息。
选择文件。设置 bucket_binding_id、local_uri、display_name、mime_type 和 expected_size，然后运行 Upload file。显示进度，但在 upload_verified 完成之前不要将文件视为已保存。
在您的应用记录中保存 asset_ref。将其用于 Get asset metadata、Resolve private read 或 Download accepted version。Change public sharing 和 Delete accepted version 需要单独确认。
一次性配置
此插件计划启用密钥激活。在 BestPlugins → Dashboard → Plugins 中创建或选择您的 Bubble 应用项目。选择 Xodera B2 Files Native，复制其密钥，然后打开 Bubble → Plugins → Xodera B2 Files Native 并将其粘贴到 project_api_key。保存一次；随后使用以下操作。每个项目中的每个插件都有其自己的密钥。
使用您自己的 Backblaze B2 账户并为此应用选择存储桶。决定谁可以读取和上传文件。将相关用户是/否字段的名称存储在 b2_reader_permission_field 和 b2_writer_permission_field 中；默认值为 b2_files_reader 和 b2_files_writer。仅授权的管理员应更改这些用户权限。
一次性配置
- 在 BestPlugins → Dashboard → Plugins 中创建或选择您的 Bubble 应用项目。
- 选择此插件并复制其项目密钥。
- 计划：打开 Bubble → Plugins → Xodera B2 Files Native；将密钥粘贴到 project_api_key 并保存。
- 添加元素，选择您的应用数据并构建以下工作流。
- 目前仅限私有测试版访问。公开安装和付费激活尚未开放。
安装和订阅
For Audio Player, Video Player, Photo Editor, Audio Recorder, Files Kit and Haptics: free Bubble installation, a 7-day trial with a card, then US$1.50 per month per plugin and app project. Development and production are included, with no operation cap. File-size and feature limits still apply. Review billing and cancellation before confirming. Other plugins remain unavailable for purchase.
将结果保存到您的应用中
示例附件：asset_ref、相关报告/订单、所有者、display_name、mime_type 和 size_bytes。在 upload_verified 之后保存这些。使用 asset_ref 以后重新打开文件；临时读取地址或单个设备上的路径并非永久文件引用。如果保存数据库记录失败，请重试保存该记录，而不是再次上传文件。
失败、取消与恢复
如果上传结果未知，保留 upload_id 并使用 Check or recover upload status。不要自动上传另一个副本。取消操作影响未完成的传输，而不是已保存的文件。如果访问已过期，请重新请求文件，而不是重复使用旧的临时地址。
功能与限制
计划的最大文件大小：256 MiB，或您选择的更低存储桶限制。Backblaze 的存储和下载费用由您的 B2 账户承担。公共存储桶中的文件即使相关应用记录为私有也会公开。没有病毒扫描承诺、分段上传、暂停或应用终止后的恢复功能。
设置、操作和结果
在 Bubble 中使用这些名称。计划中的功能会单独标记。
可用的测试版设置
元素设置
bucket_binding_id · textlocal_uri · textdisplay_name · textmime_type · textexpected_size · numbermetadata_json · textasset_ref · textis_active · yes_nodisabled · yes_nolanguage · textui_text_json · texttitle · textshow_preview · yes_noshow_provider_browse · yes_no状态
status · textis_busy · yes_noupload_id · textupload_status · textasset_ref · textdisplay_name · textmime_type · textsize_bytes · numberbytes_sent · numberprogress · numberprogress_indeterminate · yes_notemporary_read_url · textread_expires_at · textlocal_output_uri · textpublic_url · textvisibility · textnext_cursor · texthas_more · yes_noquery_revision · textfiles_json · textbuckets_json · textremote_files_json · textremote_next_cursor · textremote_has_more · yes_noremote_query_revision · textbucket_binding_id · textcleanup_pending · yes_noerror_code · texterror_message · text事件
file_selectedupload_startedupload_transport_completedupload_verifiedupload_pendingbuckets_loadedbucket_selectedlist_loadedmetadata_loadedread_resolveddownload_completedshare_changeddelete_completeddelete_pendingbrowse_loadedtransfer_cancelledcleanup_pendingtransfer_errorsession_cleared操作及其输入
List allowed bucketsSelect bucket bindingCheck local sourceUpload fileCheck or recover upload statusCancel owned transferClear local sessionList application filesRefresh application filesLoad more application filesSelect asset referenceGet asset metadataResolve private readDownload accepted versionBrowse provider filesChange public sharingDelete accepted version元素设置 · 14
计划中的工作流。目前的测试版尚不可用。
bucket_binding_idtext · 默认: ""- 示例值
<binding returned by List B2 bindings> - 示例 Bubble 表达式
Selected Binding's binding_id - 存储选项由 List B2 bindings 返回。处理此文件时，使用该存储选项的 ID。
local_uritext · 默认: ""- 示例值
file:///app-cache/attachment.jpg - 示例 Bubble 表达式
Offline Files' local_uri - 此设备上的可读文件位置。它不是在线下载链接。
display_nametext · 默认: ""- 示例值
report-photo.jpg - 示例 Bubble 表达式
Selected Attachment's display_name - 使用当前业务记录的值；根据以下限制进行验证。
mime_typetext · 默认: ""- 示例值
image/jpeg - 示例 Bubble 表达式
Photo Editor's output_mime - 使用当前业务记录的值；根据以下限制进行验证。
expected_sizenumber · 默认: 0- 示例值
246975 - 示例 Bubble 表达式
Offline Files' size_bytes - 使用当前业务记录的值；根据以下限制进行验证。
metadata_jsontext · 默认: ""- 示例值
{"label":"field-report"} - 示例 Bubble 表达式
Selected Attachment's safe_metadata_json - 可选 JSON，包含报告标签等应用信息。保持简短，避免个人数据。
asset_reftext · 默认: ""- 示例值
<returned asset_ref> - 示例 Bubble 表达式
Selected B2Asset's asset_ref - 稳定不透明的已接受资产标识来自服务。选择它永不绕过用户授权。
is_activeyes_no · 默认: true- 示例值
yes - 示例 Bubble 表达式
GuideHost's view_is_active (your yes/no custom state) - 在此视图打开时设为是。离开时设为否，以便停止播放或当前工作。
disabledyes_no · 默认: false- 示例值
no - 示例 Bubble 表达式
GuideHost's is_busy (your yes/no custom state) - 当应用忙碌或此操作不可用时禁用该元素。
languagetext · 默认: "auto"- 示例值
uk - 示例 Bubble 表达式
Current User's preferred_language - 将 language=auto 设置为跟随支持的设备或浏览器语言。输入支持的语言代码以明确选择。
ui_text_jsontext · 默认: ""- 示例值
{} - 示例 Bubble 表达式
App Settings' player_labels_json (supported keys only) - 可选的 JSON，包含支持的按钮标签。留空则使用内置文本。
titletext · 默认: ""- 示例值
Lesson 4 — review - 示例 Bubble 表达式
Selected Lesson's name - 可见的应用文本；留空时使用内置的本地化文案（如支持）。请勿填入凭证。
show_previewyes_no · 默认: false- 示例值
yes - 示例 Bubble 表达式
App Settings' b2_preview - 显示或隐藏文件预览。
show_provider_browseyes_no · 默认: false- 示例值
no - 示例 Bubble 表达式
Current User's authorized_browse_UI (presentation only) - 为获准用户显示或隐藏存储浏览控件。
操作及其输入 · 20
计划中的工作流。目前的测试版尚不可用。
List allowed buckets
无操作参数
Select bucket binding
binding_idtext · 默认: —- 示例值
<returned allowed binding ID> - 示例 Bubble 表达式
Selected Binding's binding_id - 使用当前业务记录的值；根据以下限制进行验证。
Check local source
无操作参数
Upload file
acknowledge_public_bytesyes_no · 默认: —- 示例值
no - 示例 Bubble 表达式
Public bucket disclosure Checkbox is checked (private bucket: no) - 使用当前业务记录的值；根据以下限制进行验证。
confirm_retryyes_no · 默认: —- 示例值
no - 示例 Bubble 表达式
Retry Checkbox is checked after confirmed clean pending status - 使用当前业务记录的值；根据以下限制进行验证。
Check or recover upload status
upload_idtext · 默认: —- 示例值
<original returned upload_id> - 示例 Bubble 表达式
Current UploadIntent's upload_id - 使用当前业务记录的值；根据以下限制进行验证。
Cancel owned transfer
无操作参数
Clear local session
无操作参数
List application files
无操作参数
Refresh application files
无操作参数
Load more application files
无操作参数
Select asset reference
asset_reftext · 默认: —- 示例值
<returned asset_ref> - 示例 Bubble 表达式
Selected B2Asset's asset_ref - 稳定不透明的已接受资产标识来自服务。选择它永不绕过用户授权。
Get asset metadata
asset_reftext · 默认: —- 示例值
<returned asset_ref> - 示例 Bubble 表达式
Selected B2Asset's asset_ref - 稳定不透明的已接受资产标识来自服务。选择它永不绕过用户授权。
Resolve private read
asset_reftext · 默认: —- 示例值
<returned asset_ref> - 示例 Bubble 表达式
Selected B2Asset's asset_ref - 稳定不透明的已接受资产标识来自服务。选择它永不绕过用户授权。
Download accepted version
asset_reftext · 默认: —- 示例值
<returned asset_ref> - 示例 Bubble 表达式
Selected B2Asset's asset_ref - 稳定不透明的已接受资产标识来自服务。选择它永不绕过用户授权。
Browse provider files
prefixtext · 默认: —- 示例值
"" - 示例 Bubble 表达式
Authorized Browse Settings' prefix - 使用当前业务记录的值；根据以下限制进行验证。
load_moreyes_no · 默认: —- 示例值
no - 示例 Bubble 表达式
Load More button only, for unchanged query - 使用当前业务记录的值；根据以下限制进行验证。
Change public sharing
asset_reftext · 默认: —- 示例值
<returned asset_ref> - 示例 Bubble 表达式
Selected B2Asset's asset_ref - 稳定不透明的已接受资产标识来自服务。选择它永不绕过用户授权。
enabledyes_no · 默认: —- 示例值
no - 示例 Bubble 表达式
Public Share Checkbox is checked after separate confirmation - 使用当前业务记录的值；根据以下限制进行验证。
confirmyes_no · 默认: —- 示例值
yes — explicit confirmation only - 示例 Bubble 表达式
Confirm Checkbox is checked - 使用当前业务记录的值；根据以下限制进行验证。
Delete accepted version
asset_reftext · 默认: —- 示例值
<returned asset_ref> - 示例 Bubble 表达式
Selected B2Asset's asset_ref - 稳定不透明的已接受资产标识来自服务。选择它永不绕过用户授权。
confirmyes_no · 默认: —- 示例值
yes — explicit confirmation only - 示例 Bubble 表达式
Confirm Checkbox is checked - 使用当前业务记录的值；根据以下限制进行验证。
List B2 bindings
environmenttext · 默认: —- 示例值
development - 示例 Bubble 表达式
App Settings' selected_environment - 使用当前业务记录的值；根据以下限制进行验证。
返回值
ok · yes/nostatus · texterror_code · textbinding_ids · text listlabels · text listprivacy · text listmax_size_bytes · number listList my B2 files
environmenttext · 默认: —- 示例值
development - 示例 Bubble 表达式
App Settings' selected_environment - 使用当前业务记录的值；根据以下限制进行验证。
binding_idtext · 默认: —- 示例值
<returned allowed binding ID> - 示例 Bubble 表达式
Selected Binding's binding_id - 使用当前业务记录的值；根据以下限制进行验证。
limitnumber · 默认: —- 示例值
50 - 示例 Bubble 表达式
Gallery Settings' page_size - 使用当前业务记录的值；根据以下限制进行验证。
cursortext · 默认: —- 示例值
"" - 示例 Bubble 表达式
Previous List my B2 files result's next_cursor; empty on first page - 使用当前业务记录的值；根据以下限制进行验证。
返回值
ok · yes/nostatus · texterror_code · textasset_refs · text listdisplay_names · text listmime_types · text listsize_bytes · number listcreated_ats · text listvisibility · text listpublic_urls · text listprovider_status · text listinspection_status · text listmetadata_labels · text listhas_more · yes/nonext_cursor · textquery_revision · textGet my B2 file info
environmenttext · 默认: —- 示例值
development - 示例 Bubble 表达式
App Settings' selected_environment - 使用当前业务记录的值；根据以下限制进行验证。
binding_idtext · 默认: —- 示例值
<returned allowed binding ID> - 示例 Bubble 表达式
Selected Binding's binding_id - 使用当前业务记录的值；根据以下限制进行验证。
asset_reftext · 默认: —- 示例值
<returned asset_ref> - 示例 Bubble 表达式
Selected B2Asset's asset_ref - 稳定不透明的已接受资产标识来自服务。选择它永不绕过用户授权。
返回值
ok · yes/nostatus · texterror_code · textasset_ref · textdisplay_name · textmime_type · textsize_bytes · numbercreated_at · textvisibility · textpublic_url · textprovider_status · textinspection_status · textmetadata_label · text状态和事件
计划中的工作流。目前的测试版尚不可用。
状态
status · text此操作的当前结果。保存成功前请使用匹配的完成事件。
is_busy · yes_no工作仍在进行中。请在开始其他操作前等待。
upload_id · text此项目或操作的标识符。请与对应的应用记录一起保存。重试不确定结果时使用相同的请求标识符。
upload_status · text此操作的当前结果。保存成功前请使用匹配的完成事件。
asset_ref · text此项目或操作的标识符。请与对应的应用记录一起保存。重试不确定结果时使用相同的请求标识符。
display_name · text所选项目的当前值。请在相关事件后读取。
mime_type · text所选项目的当前值。请在相关事件后读取。
size_bytes · number所选项目的当前值。请在相关事件后读取。
bytes_sent · number所选项目的当前值。请在相关事件后读取。
progress · number所选项目的当前值。请在相关事件后读取。
progress_indeterminate · yes_no所选项目的当前值。请在相关事件后读取。
temporary_read_url · text所选项目的当前值。请在相关事件后读取。
read_expires_at · text所选项目的当前值。请在相关事件后读取。
local_output_uri · text此设备上的文件位置。如果必须保持在线，请单独保存或上传文件。
public_url · text所选项目的当前值。请在相关事件后读取。
visibility · text所选项目的当前值。请在相关事件后读取。
next_cursor · text所选项目的当前值。请在相关事件后读取。
has_more · yes_no所选项目的当前值。请在相关事件后读取。
query_revision · text所选项目的当前值。请在相关事件后读取。
files_json · text所选项目的当前值。请在相关事件后读取。
buckets_json · text所选项目的当前值。请在相关事件后读取。
remote_files_json · text所选项目的当前值。请在相关事件后读取。
remote_next_cursor · text所选项目的当前值。请在相关事件后读取。
remote_has_more · yes_no所选项目的当前值。请在相关事件后读取。
remote_query_revision · text所选项目的当前值。请在相关事件后读取。
bucket_binding_id · text此项目或操作的标识符。请与对应的应用记录一起保存。重试不确定结果时使用相同的请求标识符。
cleanup_pending · yes_no所选项目的当前值。请在相关事件后读取。
error_code · text上一次操作的错误信息。显示有帮助的提示并提供相应的重试。
error_message · text上一次操作的错误信息。显示有帮助的提示并提供相应的重试。
事件
file_selected当此事件发生时，从同一元素读取相关状态。
upload_started当此事件发生时，从同一元素读取相关状态。
upload_transport_completed当此事件发生时，从同一元素读取相关状态。
upload_verified当此事件发生时，从同一元素读取相关状态。
upload_pending当此事件发生时，从同一元素读取相关状态。
buckets_loaded当此事件发生时，从同一元素读取相关状态。
bucket_selected当此事件发生时，从同一元素读取相关状态。
list_loaded当此事件发生时，从同一元素读取相关状态。
metadata_loaded当此事件发生时，从同一元素读取相关状态。
read_resolved当此事件发生时，从同一元素读取相关状态。
download_completed当此事件发生时，从同一元素读取相关状态。
share_changed当此事件发生时，从同一元素读取相关状态。
delete_completed当此事件发生时，从同一元素读取相关状态。
delete_pending当此事件发生时，从同一元素读取相关状态。
browse_loaded当此事件发生时，从同一元素读取相关状态。
transfer_cancelled当此事件发生时，从同一元素读取相关状态。
cleanup_pending当此事件发生时，从同一元素读取相关状态。
transfer_error当此事件发生时，从同一元素读取相关状态。
session_cleared当此事件发生时，从同一元素读取相关状态。
开发者常问问题
我可以将临时读取 URL 保存为我的文件吗？
不可以。持久化 asset_ref 和规范元数据。重新授权读取；设备下载路径不是 Bubble 文件。
订阅是如何运作的？
计划定价：在 Bubble 中安装插件免费。BestPlugins 访问需为每个插件在每个 Bubble 应用项目单独订阅：免费 7 天，然后每月 US$1.50。Development 和 Live 已包含。操作次数没有固定上限；文件大小和功能限制仍然适用。结账尚未开放。激活界面将显示首次计费日期和取消条款。
相关指南
Marketplace 发布待定
论坛指南未发布
如需帮助，请告知我们您使用的插件和设备、尝试的操作以及发生的情况。请使用不含个人数据的示例。切勿分享您的密钥或私有文件。