跳至内容 跳至搜索

Active Storage 附加模型

提供用于声明 Active Record 模型附件的类级别 DSL。

方法
#
H
V
W

实例公共方法

*_attachment

返回 has_one_attached 的附件。

User.last.avatar_attachment

来源： 在 GitHub 上 

# File activestorage/lib/active_storage/attached/model.rb, line 13

*_attachments

返回 has_many_attached 的附件。

Gallery.last.photos_attachments

来源： 在 GitHub 上 

# File activestorage/lib/active_storage/attached/model.rb, line 20

*_blob

返回 has_one_attached 附件的二进制大对象。

User.last.avatar_blob

来源： 在 GitHub 上 

# File activestorage/lib/active_storage/attached/model.rb, line 27

*_blobs

返回 has_many_attached 附件的二进制大对象。

Gallery.last.photos_blobs

来源： 在 GitHub 上 

# File activestorage/lib/active_storage/attached/model.rb, line 34

has_many_attached(name, dependent: :purge_later, service: nil, strict_loading: false)

指定多个附件与模型之间的关系。

class Gallery < ApplicationRecord
  has_many_attached :photos
end

模型端没有定义列，Active Storage 会处理记录与附件之间的映射。

为避免 N+1 查询，可以像这样将附加的 blob 包含在查询中

Gallery.where(user: Current.user).with_attached_photos

在底层，此关系实现为与 ActiveStorage::Attachment 记录的 has_many 关联以及与 ActiveStorage::Blob 记录的 has_many-through 关联。这些关联可用作 photos_attachments 和 photos_blobs。但在大多数情况下，不需要直接使用这些关联。

系统设计为让你通过 ActiveStorage::Attached::Many 代理进行，该代理为关联和工厂方法（如 #attach）提供动态代理。

如果未设置 :dependent 选项，则无论何时销毁记录，所有附件都将被清除（即销毁）。

如果需要附件使用与全局配置不同的服务，请传递 :service 选项。例如

class Gallery < ActiveRecord::Base
  has_many_attached :photos, service: :s3
end

如果需要启用 strict_loading 以防止附件延迟加载，请传递 :strict_loading 选项。你可以执行

class Gallery < ApplicationRecord
  has_many_attached :photos, strict_loading: true
end

来源：显示 | 在 GitHub 上 

# File activestorage/lib/active_storage/attached/model.rb, line 182
      def has_many_attached(name, dependent: :purge_later, service: nil, strict_loading: false)
        validate_service_configuration(name, service)

        generated_association_methods.class_eval <<-CODE, __FILE__, __LINE__ + 1
          # frozen_string_literal: true
          def #{name}
            @active_storage_attached ||= {}
            @active_storage_attached[:#{name}] ||= ActiveStorage::Attached::Many.new("#{name}", self)
          end

          def #{name}=(attachables)
            attachables = Array(attachables).compact_blank
            pending_uploads = attachment_changes["#{name}"].try(:pending_uploads)

            attachment_changes["#{name}"] = if attachables.none?
              ActiveStorage::Attached::Changes::DeleteMany.new("#{name}", self)
            else
              ActiveStorage::Attached::Changes::CreateMany.new("#{name}", self, attachables, pending_uploads: pending_uploads)
            end
          end
        CODE

        has_many :"#{name}_attachments", -> { where(name: name) }, as: :record, class_name: "ActiveStorage::Attachment", inverse_of: :record, dependent: :destroy, strict_loading: strict_loading
        has_many :"#{name}_blobs", through: :"#{name}_attachments", class_name: "ActiveStorage::Blob", source: :blob, strict_loading: strict_loading

        scope :"with_attached_#{name}", -> {
          if ActiveStorage.track_variants
            includes("#{name}_attachments": { blob: {
              variant_records: { image_attachment: :blob },
              preview_image_attachment: { blob: { variant_records: { image_attachment: :blob } } }
            } })
          else
            includes("#{name}_attachments": :blob)
          end
        }

        after_save { attachment_changes[name.to_s]&.save }

        after_commit(on: %i[ create update ]) { attachment_changes.delete(name.to_s).try(:upload) }

        reflection = ActiveRecord::Reflection.create(
          :has_many_attached,
          name,
          nil,
          { dependent: dependent, service_name: service },
          self
        )
        yield reflection if block_given?
        ActiveRecord::Reflection.add_attachment_reflection(self, name, reflection)
      end

has_one_attached(name, dependent: :purge_later, service: nil, strict_loading: false)

指定单个附件与模型之间的关系。

class User < ApplicationRecord
  has_one_attached :avatar
end

模型端没有定义列，Active Storage 会处理记录与附件之间的映射。

为避免 N+1 查询，可以像这样将附加的 blob 包含在查询中

User.with_attached_avatar

在底层，此关系实现为与 ActiveStorage::Attachment 记录的 has_one 关联以及与 ActiveStorage::Blob 记录的 has_one-through 关联。这些关联可用作 avatar_attachment 和 avatar_blob。但在大多数情况下，不需要直接使用这些关联。

该系统经过设计，让您通过 ActiveStorage::Attached::One 代理进行操作，该代理为关联和工厂方法（如 attach）提供动态代理。

如果未设置 :dependent 选项，则每当记录被销毁时，附件都将被清除（即销毁）。

如果需要附件使用与全局配置不同的服务，请传递 :service 选项。例如

class User < ActiveRecord::Base
  has_one_attached :avatar, service: :s3
end

如果您需要启用 strict_loading 以防止附件的延迟加载，请传递 :strict_loading 选项。您可以执行

class User < ApplicationRecord
  has_one_attached :avatar, strict_loading: true
end

源代码：显示 | 在 GitHub 上 

# File activestorage/lib/active_storage/attached/model.rb, line 94
      def has_one_attached(name, dependent: :purge_later, service: nil, strict_loading: false)
        validate_service_configuration(name, service)

        generated_association_methods.class_eval <<-CODE, __FILE__, __LINE__ + 1
          # frozen_string_literal: true
          def #{name}
            @active_storage_attached ||= {}
            @active_storage_attached[:#{name}] ||= ActiveStorage::Attached::One.new("#{name}", self)
          end

          def #{name}=(attachable)
            attachment_changes["#{name}"] =
              if attachable.nil? || attachable == ""
                ActiveStorage::Attached::Changes::DeleteOne.new("#{name}", self)
              else
                ActiveStorage::Attached::Changes::CreateOne.new("#{name}", self, attachable)
              end
          end
        CODE

        has_one :"#{name}_attachment", -> { where(name: name) }, class_name: "ActiveStorage::Attachment", as: :record, inverse_of: :record, dependent: :destroy, strict_loading: strict_loading
        has_one :"#{name}_blob", through: :"#{name}_attachment", class_name: "ActiveStorage::Blob", source: :blob, strict_loading: strict_loading

        scope :"with_attached_#{name}", -> {
          if ActiveStorage.track_variants
            includes("#{name}_attachment": { blob: {
              variant_records: { image_attachment: :blob },
              preview_image_attachment: { blob: { variant_records: { image_attachment: :blob } } }
            } })
          else
            includes("#{name}_attachment": :blob)
          end
        }

        after_save { attachment_changes[name.to_s]&.save }

        after_commit(on: %i[ create update ]) { attachment_changes.delete(name.to_s).try(:upload) }

        reflection = ActiveRecord::Reflection.create(
          :has_one_attached,
          name,
          nil,
          { dependent: dependent, service_name: service },
          self
        )
        yield reflection if block_given?
        ActiveRecord::Reflection.add_attachment_reflection(self, name, reflection)
      end

validate_global_service_configuration()

源代码：显示 | 在 GitHub 上 

# File activestorage/lib/active_storage/attached/model.rb, line 244
def validate_global_service_configuration
  if connected? && ActiveStorage::Blob.table_exists? && Rails.configuration.active_storage.service.nil?
    raise RuntimeError, "Missing Active Storage service name. Specify Active Storage service name for config.active_storage.service in config/environments/#{Rails.env}.rb"
  end
end

validate_service_configuration(association_name, service)

源代码：显示 | 在 GitHub 上 

# File activestorage/lib/active_storage/attached/model.rb, line 234
def validate_service_configuration(association_name, service)
  if service.present?
    ActiveStorage::Blob.services.fetch(service) do
      raise ArgumentError, "Cannot configure service :#{service} for #{name}##{association_name}"
    end
  else
    validate_global_service_configuration
  end
end

with_attached_*

在您的查询中包含附加的二进制大对象，以避免 N+1 查询。

如果启用了 ActiveStorage.track_variants，它还将包含变体记录及其附加的二进制大对象。

User.with_attached_avatar

对 has_many_attached 使用复数形式

Gallery.with_attached_photos

源代码：显示 | 在 GitHub 上 

# File activestorage/lib/active_storage/attached/model.rb, line 54
    class_methods do
      # Specifies the relation between a single attachment and the model.
      #
      #   class User < ApplicationRecord
      #     has_one_attached :avatar
      #   end
      #
      # There is no column defined on the model side, Active Storage takes
      # care of the mapping between your records and the attachment.
      #
      # To avoid N+1 queries, you can include the attached blobs in your query like so:
      #
      #   User.with_attached_avatar
      #
      # Under the covers, this relationship is implemented as a +has_one+ association to a
      # ActiveStorage::Attachment record and a +has_one-through+ association to a
      # ActiveStorage::Blob record. These associations are available as +avatar_attachment+
      # and +avatar_blob+. But you shouldn't need to work with these associations directly in
      # most circumstances.
      #
      # The system has been designed to having you go through the ActiveStorage::Attached::One
      # proxy that provides the dynamic proxy to the associations and factory methods, like +attach+.
      #
      # If the +:dependent+ option isn't set, the attachment will be purged
      # (i.e. destroyed) whenever the record is destroyed.
      #
      # If you need the attachment to use a service which differs from the globally configured one,
      # pass the +:service+ option. For instance:
      #
      #   class User < ActiveRecord::Base
      #     has_one_attached :avatar, service: :s3
      #   end
      #
      # If you need to enable +strict_loading+ to prevent lazy loading of attachment,
      # pass the +:strict_loading+ option. You can do:
      #
      #   class User < ApplicationRecord
      #     has_one_attached :avatar, strict_loading: true
      #   end
      #
      def has_one_attached(name, dependent: :purge_later, service: nil, strict_loading: false)
        validate_service_configuration(name, service)

        generated_association_methods.class_eval <<-CODE, __FILE__, __LINE__ + 1
          # frozen_string_literal: true
          def #{name}
            @active_storage_attached ||= {}
            @active_storage_attached[:#{name}] ||= ActiveStorage::Attached::One.new("#{name}", self)
          end

          def #{name}=(attachable)
            attachment_changes["#{name}"] =
              if attachable.nil? || attachable == ""
                ActiveStorage::Attached::Changes::DeleteOne.new("#{name}", self)
              else
                ActiveStorage::Attached::Changes::CreateOne.new("#{name}", self, attachable)
              end
          end
        CODE

        has_one :"#{name}_attachment", -> { where(name: name) }, class_name: "ActiveStorage::Attachment", as: :record, inverse_of: :record, dependent: :destroy, strict_loading: strict_loading
        has_one :"#{name}_blob", through: :"#{name}_attachment", class_name: "ActiveStorage::Blob", source: :blob, strict_loading: strict_loading

        scope :"with_attached_#{name}", -> {
          if ActiveStorage.track_variants
            includes("#{name}_attachment": { blob: {
              variant_records: { image_attachment: :blob },
              preview_image_attachment: { blob: { variant_records: { image_attachment: :blob } } }
            } })
          else
            includes("#{name}_attachment": :blob)
          end
        }

        after_save { attachment_changes[name.to_s]&.save }

        after_commit(on: %i[ create update ]) { attachment_changes.delete(name.to_s).try(:upload) }

        reflection = ActiveRecord::Reflection.create(
          :has_one_attached,
          name,
          nil,
          { dependent: dependent, service_name: service },
          self
        )
        yield reflection if block_given?
        ActiveRecord::Reflection.add_attachment_reflection(self, name, reflection)
      end

      # Specifies the relation between multiple attachments and the model.
      #
      #   class Gallery < ApplicationRecord
      #     has_many_attached :photos
      #   end
      #
      # There are no columns defined on the model side, Active Storage takes
      # care of the mapping between your records and the attachments.
      #
      # To avoid N+1 queries, you can include the attached blobs in your query like so:
      #
      #   Gallery.where(user: Current.user).with_attached_photos
      #
      # Under the covers, this relationship is implemented as a +has_many+ association to a
      # ActiveStorage::Attachment record and a +has_many-through+ association to a
      # ActiveStorage::Blob record. These associations are available as +photos_attachments+
      # and +photos_blobs+. But you shouldn't need to work with these associations directly in
      # most circumstances.
      #
      # The system has been designed to having you go through the ActiveStorage::Attached::Many
      # proxy that provides the dynamic proxy to the associations and factory methods, like +#attach+.
      #
      # If the +:dependent+ option isn't set, all the attachments will be purged
      # (i.e. destroyed) whenever the record is destroyed.
      #
      # If you need the attachment to use a service which differs from the globally configured one,
      # pass the +:service+ option. For instance:
      #
      #   class Gallery < ActiveRecord::Base
      #     has_many_attached :photos, service: :s3
      #   end
      #
      # If you need to enable +strict_loading+ to prevent lazy loading of attachments,
      # pass the +:strict_loading+ option. You can do:
      #
      #   class Gallery < ApplicationRecord
      #     has_many_attached :photos, strict_loading: true
      #   end
      #
      def has_many_attached(name, dependent: :purge_later, service: nil, strict_loading: false)
        validate_service_configuration(name, service)

        generated_association_methods.class_eval <<-CODE, __FILE__, __LINE__ + 1
          # frozen_string_literal: true
          def #{name}
            @active_storage_attached ||= {}
            @active_storage_attached[:#{name}] ||= ActiveStorage::Attached::Many.new("#{name}", self)
          end

          def #{name}=(attachables)
            attachables = Array(attachables).compact_blank
            pending_uploads = attachment_changes["#{name}"].try(:pending_uploads)

            attachment_changes["#{name}"] = if attachables.none?
              ActiveStorage::Attached::Changes::DeleteMany.new("#{name}", self)
            else
              ActiveStorage::Attached::Changes::CreateMany.new("#{name}", self, attachables, pending_uploads: pending_uploads)
            end
          end
        CODE

        has_many :"#{name}_attachments", -> { where(name: name) }, as: :record, class_name: "ActiveStorage::Attachment", inverse_of: :record, dependent: :destroy, strict_loading: strict_loading
        has_many :"#{name}_blobs", through: :"#{name}_attachments", class_name: "ActiveStorage::Blob", source: :blob, strict_loading: strict_loading

        scope :"with_attached_#{name}", -> {
          if ActiveStorage.track_variants
            includes("#{name}_attachments": { blob: {
              variant_records: { image_attachment: :blob },
              preview_image_attachment: { blob: { variant_records: { image_attachment: :blob } } }
            } })
          else
            includes("#{name}_attachments": :blob)
          end
        }

        after_save { attachment_changes[name.to_s]&.save }

        after_commit(on: %i[ create update ]) { attachment_changes.delete(name.to_s).try(:upload) }

        reflection = ActiveRecord::Reflection.create(
          :has_many_attached,
          name,
          nil,
          { dependent: dependent, service_name: service },
          self
        )
        yield reflection if block_given?
        ActiveRecord::Reflection.add_attachment_reflection(self, name, reflection)
      end

      private
        def validate_service_configuration(association_name, service)
          if service.present?
            ActiveStorage::Blob.services.fetch(service) do
              raise ArgumentError, "Cannot configure service :#{service} for #{name}##{association_name}"
            end
          else
            validate_global_service_configuration
          end
        end

        def validate_global_service_configuration
          if connected? && ActiveStorage::Blob.table_exists? && Rails.configuration.active_storage.service.nil?
            raise RuntimeError, "Missing Active Storage service name. Specify Active Storage service name for config.active_storage.service in config/environments/#{Rails.env}.rb"
          end
        end
    end