عرض مصدر Rails/active storage

<noinclude>{{DISPLAYTITLE:المكتبة Active Storage في ريلز}}</noinclude>
[[تصنيف:Rails]]
[[تصنيف:Rails Getting Started]]
يجعل Active Storage عملية رفع الملفات وإنشاء مرجع لها في أي خدمة سحابية - مثل [https://aws.amazon.com/s3/ Amazon S3]، أو [https://cloud.google.com/storage/docs/ Google Cloud Storage]، أو [https://azure.microsoft.com/en-us/services/storage/ Microsoft Azure Storage] - وربطها بنماذج [[Rails/active record|Active Record]] عمليةً بسيطةً وسهلةً. يدعم أيضًا امتلاك خدمة تخزين أساسية في خدمة سحابية، وخدمة تخزين انعكاسية (mirror) في خدمات سحابية أخرى وذلك من أجل تحقيق التوافر الدائم. أضف إلى ذلك أنه يوفر خدمة التخزين على قرص صلب (disk service) للفحص أو النشر المحلي ولكن التركيز الأساسي ينصب على التخزين السحابي.

يمكن رفع الملفات من الخادم إلى السحابة أو من العميل إلى السحابة مباشرةً.

إضافة لذلك، يمكن تحويل ملفات الصور من ناحية الجودة أو نسبة العرض إلى الارتفاع، أو الحجم، أو أي عملية تحويل أخرى مدعومة (مثل  [https://github.com/minimagick/minimagick MiniMagick] و [https://www.rubydoc.info/gems/ruby-vips/Vips/Image Vips]).

يمكنك قراءة المزيد حول Active Storage في دليل [[Rails/active storage overview|نظرة عامة على Active Storage]].

== الموازنة مع خيارات تخزين أخرى ==
الاختلاف الجوهري لعمل Active Storage موازنةً مع وسائل التخزين الأخرى المرفقة مع ريلز هو عبر استعمال النموذج [https://github.com/rails/rails/blob/master/activestorage/app/models/active_storage/blob.rb Blob] (كائن بيانات ثنائية) والنموذج [https://github.com/rails/rails/blob/master/activestorage/app/models/active_storage/attachment.rb Attachment] (المرفقات) المدعومين من قبل [[Rails/active record|Active Record]]. هذا يعني عدم الحاجة إلى تعديل نماذج التطبيق الموجودة مسبقًا مع حقول إضافية يراد ربطها مع ملفات. يستعمل Active Storage ارتباطات متعددة الأشكال عبر نموذج الربط Attachment الذي يرتبط بعدها مع النموذج Bolb الفعلي.

نماذج Blob تخزن البيانات الوصفية المرفقة (اسم الملف، ونوع المحتوى ...إلخ)، ومفتاح المعرف الخاص بها في خدمة التخزين. لا تخزن نماذج Blob البيانات الثنائية الفعلية، وتعدُّ غير قابلة للتعديل. ملف واحد يعني نموذج Blob واحد (أي كائن بيانات ثنائي واحد). يمكنك ربط نفس كائن بيانات ثنائي (Blob) مع عدة نماذج للتطبيق أيضًا. وإن أردت إجراء عمليات تحويل لكائن Blob معطى، فالفكرة هي أنك ستنشئ ببساطة كائن آخر جديد بدلًا من محاول تعديل الموجود مسبقًا (رغم أنك تستطيع حذف الإصدار السابق لاحقًا إن لم تعد بحاجة إليه).

== التنزيل ==
نفذ الأمر <code>rails active_storage:install</code> لنسخ التهجيرات <code>active_storage</code>.

'''ملاحظة''': إن لم يُعثَر على المهمة، تأكد من وجود <code>"require "active_storage/engine</code> في الملف config/application.rb.

== أمثلة ==
مرفق واحد:<syntaxhighlight lang="rails">
class User < ApplicationRecord
  # ربط مرفق وكائن بيانات ثنائي. عند حذف المستخدم، سيزالا افتراضيًّا
  # إذ تُدمَّر النماذج وتُحذَف ملفات الموارد
  has_one_attached :avatar
end

# ربط صورة رمزية بالمستخدم
user.avatar.attach(io: File.open("/path/to/face.jpg"), filename: "face.jpg", content_type: "image/jpg")

# هل يملك المستخدم صورة رمزية؟
user.avatar.attached? # => true

# تدمير الصورة الرمزية وملفات الموارد الحقيقية بشكل متزامن
user.avatar.purge

# Active Job تدمير النماذج المرتبطة وملفات الموارد الحقيقية بشكل غير متزامن عبر
user.avatar.purge_later

# هل يملك المستخدم صورة رمزية؟
user.avatar.attached? # => false

# .دائم لكائن البيانات الثنائي الذي يشير إلى التطبيق URL توليد رابط
# .عند الوصول إليه، يعاد التوجيه إلى الخدمة الفعلية النهائية
# العام عن العنوان الفعلي وتسمح مثلًا بعكس  URL هذه المراوغة تفصل عنوان
# المرفقات على خدمةتخزين مختلفة للحرص على توفيرها بشكل دائم.  تملك
# تساوي 5 دقائق HTTP عملية إعادة التوجيه مدة انتهاء لطلبية
url_for(user.avatar)

class AvatarsController < ApplicationController
  def update
    # ActionDispatch::Http::UploadedFile الكائن params[:avatar] يحوي
    Current.user.avatar.attach(params.require(:avatar))
    redirect_to Current.user
  end
end
</syntaxhighlight>عدة مرفقات:<syntaxhighlight lang="rails">
class Message < ApplicationRecord
  has_many_attached :images
end

</syntaxhighlight><syntaxhighlight lang="html">
<%= form_with model: @message, local: true do |form| %>
  <%= form.text_field :title, placeholder: "Title" %><br>
  <%= form.text_area :content %><br><br>

  <%= form.file_field :images, multiple: true %><br>
  <%= form.submit %>
<% end %>
</syntaxhighlight><syntaxhighlight lang="rails">
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.require(:message).permit(:title, :content)
    message.images.attach(params[:message][:images])
    redirect_to message
  end

  def show
    @message = Message.find(params[:id])
  end
end
</syntaxhighlight>تغيير الصورة المرفقة:<syntaxhighlight lang="html">
<%# 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]) %>

</syntaxhighlight>

== التحميل المباشر ==
يدعم Active Storage، مع مكتبة [[JavaScript]] المضمنة فيه، التحميل المباشر من العميل إلى السحابة.

=== تثبيت التحميل التلقائي ===
* ضمِّن activestorage.js في مُحزِّم [[JavaScript]] لتطبيقك.  باستعمال [[Rails/asset pipeline|خط أنابيب الأصول]]:
<syntaxhighlight lang="javascript">
//= require activestorage

</syntaxhighlight>باستعمال npm:<syntaxhighlight lang="rails">
require("@rails/activestorage").start()

</syntaxhighlight>
* علِّق مدخلات الملفات مع عنوان URL للتحميل المباشر:<syntaxhighlight lang="rails">
<%= form.file_field :attachments, multiple: true, direct_upload: true %>

</syntaxhighlight>

* هذا كل ما في الأمر! يجب أن تبدأ عملية التحيمل التحميل بدءًا من إرسال الاستمارة.

=== التحميل التلقائي لأحداث JavaScript ===
{| class="wikitable"
!اسم الحدث
!الوسم المستهدف
!بيانات الحدث

(<code>event.detail</code>)
!الوصف
|-
|<code>direct-uploads:start</code>
|<code><form></code>
|None
|أرسلت استمارة تحوي ملفات للتحميل المباشر للحقولها.
|-
|<code>direct-upload:initialize</code>
|<code><input></code>
|<code>{id, file}</code>
|يرسل مع كل ملف على حدة بعد إرسال الاستمارة.
|-
|<code>direct-upload:start</code>
|<code><input></code>
|<code>{id, file}</code>
|بدء التحميل المباشر.
|-
|<code>direct-upload:before-blob-request</code>
|<code><input></code>
|<code>{id, file, xhr}</code>
|قبل إنشاء طلبية لتطبيقك لتحميل البيانات الوصفية بشكل مباشر.
|-
|<code>direct-upload:before-storage-request</code>
|<code><input></code>
|<code>{id, file, xhr}</code>
|قبل إنشاء طلبية لتخزين ملف.
|-
|<code>direct-upload:progress</code>
|<code><input></code>
|<code>{id, file, progress}</code>
|مثل الطلبيات لتخزين تقدم تخزين الملفات.
|-
|<code>direct-upload:error</code>
|<code><input></code>
|<code>{id, file, error}</code>
|خطأ قد حصل. سيُظهَر تنبيه alert ما لم يُلغَى هذا الحدث.
|-
|<code>direct-upload:end</code>
|<code><input></code>
|<code>{id, file}</code>
|انتهاء عملية التحميل المباشرة.
|-
|<code>direct-uploads:end</code>
|<code><form></code>
|None
|انتهاء جميع عمليات التحميل المباشر.
|}

== مصادر ==
*[https://github.com/rails/rails/tree/master/activestorage صفحة Active Storage من مشروع ريلز على GitHub.]