Active Storage

Active Storage 讓上傳檔案並參考檔案變得簡單，這些檔案所在的位置包括雲端服務，例如 Amazon S3、Google Cloud Storage 或 Microsoft Azure Storage，並將這些檔案附加至 Active Records。支援擁有一個主要服務，並在其他服務中備份，以取得備援。它也提供一個可供測試或用於本機部署的磁碟服務，但重點在於雲端儲存空間。

可以從伺服器上傳檔案至雲端，也可以由客戶端直接上傳檔案至雲端。

圖像檔案可以使用依據品質、長寬比、大小或任何其他 MiniMagick 或 Vips 支援的轉換，進行按需變形的轉換。

您可以在 Active Storage 概觀指南中閱讀更多關於 Active Storage 的資訊。

與其他儲存解決方案的比較

與 Rails 中其他附加元件解決方案相比，Active Storage 的工作方式有一個主要的差異，在於使用內建的 Blob 和 Attachment 模型（由 Active Record 做為後端）。這表示不需要修改現有的應用程式模型，並新增額外的欄位來與檔案關聯。Active Storage 使用多型關聯，透過 Attachment 加入模型，然後再連接至實際的 Blob。

Blob 模型儲存附加元件的資訊（檔名、內容類型等），以及儲存服務中的識別器金鑰。Blob 模型不會儲存實際的二進位資料。其目的在於具備不可修改的精神。一個檔案，一個 blob。您也能夠將同一個 blob 與多個應用程式模型關聯起來。而且如果您想對一個 blob 進行轉換，其概念在於您會簡單地建立一個新的 blob，而不是嘗試變更現有的 blob（當然，如果您不需要現有的 blob，您可以在稍後刪除它）。

安裝

執行 bin/rails active_storage:install 以複製 Active Storage 的遷移。

注意：如果找不到這個工作，請驗證 config/application.rb 中是否已經有 require "active_storage/engine"。

範例

一個附加檔案

class User < ApplicationRecord
  # Associates an attachment and a blob. When the user is destroyed they are
  # purged by default (models destroyed, and resource files deleted).
  has_one_attached :avatar
end

# Attach an avatar to the user.
user.avatar.attach(io: File.open("/path/to/face.jpg"), filename: "face.jpg", content_type: "image/jpeg")

# Does the user have an avatar?
user.avatar.attached? # => true

# Synchronously destroy the avatar and actual resource files.
user.avatar.purge

# Destroy the associated models and actual resource files async, via Active Job.
user.avatar.purge_later

# Does the user have an avatar?
user.avatar.attached? # => false

# Generate a permanent URL for the blob that points to the application.
# Upon access, a redirect to the actual service endpoint is returned.
# This indirection decouples the public URL from the actual one, and
# allows for example mirroring attachments in different services for
# high-availability. The redirection has an HTTP expiration of 5 min.
url_for(user.avatar)

class AvatarsController < ApplicationController
  def update
    # params[:avatar] contains an ActionDispatch::Http::UploadedFile object
    Current.user.avatar.attach(params.require(:avatar))
    redirect_to Current.user
  end
end

多個附加檔案

class Message < ApplicationRecord
  has_many_attached :images
end

<%= form_with model: @message, local: true do |form| %>
  <%= form.text_field :title, placeholder: "Title" %><br>
  <%= form.textarea :content %><br><br>

  <%= form.file_field :images, multiple: true %><br>
  <%= form.submit %>
<% end %>

class MessagesController < ApplicationController
  def index
    # Use the built-in with_attached_images scope to avoid N+1
    @messages = Message.all.with_attached_images
  end

  def create
    message = Message.create! params.expect(message: [ :title, :content, images: [] ])
    redirect_to message
  end

  def show
    @message = Message.find(params[:id])
  end
end

圖片附加檔案的變化

<%# Hitting the variant URL will lazy transform the original blob and then redirect to its new service location %>
<%= image_tag user.avatar.variant(resize_to_limit: [100, 100]) %>

`File` 提供方式

Active Storage 支援兩種提供檔案的方式：重新導向和代理。

重新導向

Active Storage 會針對檔案產生穩定的應用程式 URL，當存取這些檔案時會重新導向到有簽章、短暫存在於服務中的 URL。這讓應用程式伺服器免除提供檔案資料的負擔。這是預設的檔案提供方式。

當應用程式已設定為預設代理檔案時，請使用 rails_storage_redirect_path 和 _url 路由輔助函式來重新導向

<%= image_tag rails_storage_redirect_path(@user.avatar) %>

代理

選擇性地，檔案也能夠改用代理的方式提供。這表示您的應用程式伺服器會在收到要求時從儲存服務下載檔案資料。這對於從 CDN 提供檔案會很有用。

您可以設定 Active Storage 以預設使用代理

# config/initializers/active_storage.rb
Rails.application.config.active_storage.resolve_model_to_route = :rails_storage_proxy

或者，如果你想明確代理特定附件，你可以使用 rails_storage_proxy_path 和 rails_storage_proxy_url 這些 URL 輔助程式。

<%= image_tag rails_storage_proxy_path(@user.avatar) %>

直接上傳

Active Storage 透過其所包含的 JavaScript 函式庫，支援將檔案從客戶端直接上傳到雲端。

直接上傳安裝

將 Active Storage JavaScript 納入應用程式的 JavaScript 程式集，或直接參照。

在應用程式 HTML 中透過自動啟動機制，直接要求而不需要透過套件管理程式進行組合
```
<%= javascript_include_tag "activestorage" %>
```
在應用程式 HTML 中透過 importmap-rails 要求而不需要透過套件管理程式進行組合，並使用 ESM
```
# config/importmap.rb
pin "@rails/activestorage", to: "activestorage.esm.js"
```
```
<script type="module-shim">
  import * as ActiveStorage from "@rails/activestorage"
  ActiveStorage.start()
</script>
```
使用套件管理程式
```
//= require activestorage
```
使用 npm 套件
```
import * as ActiveStorage from "@rails/activestorage"
ActiveStorage.start()
```

使用直接上傳 URL 標示檔案輸入。

<%= form.file_field :attachments, multiple: true, direct_upload: true %>

完成了！檔案會在提交表單後開始上傳。

直接上傳 JavaScript 事件

事件名稱	事件目標	事件資料（「event.detail」）	說明
‘direct-uploads:start`	‘<form>`	無	提交了含有檔案以供直接上傳欄位資料的表單。
‘direct-upload:initialize`	‘<input>`	‘{id, file}`	於提交表單後，由每個檔案分派。
‘direct-upload:start`	‘<input>`	‘{id, file}`	開始直接上傳。
‘direct-upload:before-blob-request`	‘<input>`	‘{id, file, xhr}`	於發出要求給你的應用程式以取得直接上傳的元資料之前。
‘direct-upload:before-storage-request`	‘<input>`	‘{id, file, xhr}`	於發出儲存檔案的請求之前。
‘direct-upload:progress`	‘<input>`	‘{id, file, progress}`	隨著檔案儲存要求的進展。
‘direct-upload:error`	‘<input>`	‘{id, file, error}`	發生錯誤。除非取消這個事件，否則會顯示「alert」。
‘direct-upload:end`	‘<input>`	‘{id, file}`	直接上傳已結束。
‘direct-uploads:end`	‘<form>`	無	所有直接上傳都已結束。

授權

Active Storage 已於 MIT 授權下發布。

支援

API 文件位於

api.rubyonrails.org

可以在此提交 Ruby on Rails 專案的錯誤報告

github.com/rails/rails/issues

應該在此處的 rails-core 郵件列表討論功能要求

discuss.rubyonrails.org/c/rubyonrails-core

README.md