paperclip
Version 6.1.0
تم إهمال مشبك الورق .
بالنسبة للمشاريع الجديدة، نوصي باستخدام ActiveStorage الخاص بشركة Rails.
بالنسبة للمشاريع الحالية، يرجى الرجوع إلى دليل الترحيل والمساهمة فيه، المتوفر باللغة الإنجليزية والإسبانية وكفيديو مسجل في RailsConf 2019. قد تفضل أيضًا برنامجًا تعليميًا بديلاً للترحيل يستخدمه Doorkeeper.
وبدلاً من ذلك، بالنسبة للمشاريع القائمة، تقوم Kreeti بصيانة مشبك الورق kt، وهو شوكة مستمرة لمشبك الورق.
وسوف نترك القضايا مفتوحة كمنتدى للمناقشة فقط . نحن لا نضمن ردا منا في القضايا. يجب أن تذهب جميع تقارير الأخطاء إلى kt-paperclip.
لم نعد نقبل طلبات السحب باستثناء طلبات السحب مقابل دليل الترحيل. سيتم إغلاق جميع طلبات السحب الأخرى دون دمجها.
masterيرجى التحقق من الوثائق الخاصة بإصدار مشبك الورق الذي تستخدمه: https://github.com/thinkbot/paperclip/releases
متطلبات
روبي وريلز
معالج الصور
file
تثبيت
بداية سريعة
نماذج
الهجرات
تحرير وطرق عرض جديدة
تحرير وطرق العرض الجديدة باستخدام نموذج بسيط
المراقب المالي
عرض المساعدين
التحقق من وجود ملف
حذف مرفق
الاستخدام
التحقق من الصحة
التدويل (I18n)
التحقق من صحة الأمن
الافتراضيات
الهجرات
إضافة عمود مرفق إلى جدول
تعريف المخطط
بناء الجملة خمر
تخزين
فهم التخزين
محولات الإدخال والإخراج
معالجة ما بعد
معالجات المرفقات المخصصة
الأحداث
تشويش URI
المجموع الاختباري / بصمة الإصبع
حفظ الملفات للحذف الناعم
التكوين الديناميكي
الأنماط الديناميكية:
المعالجات الديناميكية:
التسجيل
النشر
أنماط المرفقات
اختبار
المساهمة
رخصة
حول ثيكبوت
تم تصميم Paperclip لتكون مكتبة مرفقات ملفات سهلة لـ ActiveRecord. كان الهدف من وراء ذلك هو الحفاظ على عملية الإعداد سهلة قدر الإمكان والتعامل مع الملفات مثل السمات الأخرى قدر الإمكان. هذا يعني أنه لا يتم حفظها في مواقعها النهائية على القرص، ولا يتم حذفها إذا تم ضبطها على الصفر، حتى يتم استدعاء ActiveRecord::Base#save. ويدير عمليات التحقق بناءً على الحجم والتواجد، إذا لزم الأمر. يمكنه تحويل الصورة المخصصة له إلى صور مصغرة إذا لزم الأمر، والمتطلبات الأساسية بسيطة مثل تثبيت ImageMagick (والذي، بالنسبة لمعظم الأنظمة الحديثة المستندة إلى Unix، سهل مثل تثبيت الحزم المناسبة). يتم حفظ الملفات المرفقة في نظام الملفات ويتم الرجوع إليها في المتصفح من خلال مواصفات سهلة الفهم، ولها إعدادات افتراضية معقولة ومفيدة.
راجع وثائق has_attached_file في Paperclip::ClassMethods للحصول على خيارات أكثر تفصيلاً.
ملف RDoc الكامل موجود على الإنترنت.
يتطلب Paperclip الآن إصدار Ruby >= 2.1 وإصدار Rails >= 4.2 (فقط إذا كنت ستستخدم Paperclip مع Ruby on Rails).
يجب تثبيت ImageMagick ويجب أن يكون لدى Paperclip حق الوصول إليه. للتأكد من ذلك، في سطر الأوامر الخاص بك، قم بتشغيل which convert (أحد أدوات ImageMagick المساعدة). سيعطيك هذا المسار حيث تم تثبيت هذه الأداة المساعدة. على سبيل المثال، قد يُرجع /usr/local/bin/convert .
بعد ذلك، في ملف تكوين البيئة لديك، أخبر Paperclip بالبحث هناك عن طريق إضافة هذا الدليل إلى مساره.
في وضع التطوير، يمكنك إضافة هذا السطر إلى config/environments/development.rb) :
Paperclip.options[:command_path] = "/usr/local/bin/"
إذا كنت تستخدم نظام التشغيل Mac OS X، فستحتاج إلى تشغيل ما يلي باستخدام Homebrew:
brew install imagemagick
إذا كنت تتعامل مع تحميلات بتنسيق pdf أو تقوم بتشغيل مجموعة الاختبار، فستحتاج أيضًا إلى تثبيت GhostScript. في نظام التشغيل Mac OS X، يمكنك أيضًا تثبيت ذلك باستخدام Homebrew:
brew install gs
إذا كنت تستخدم Ubuntu (أو أي توزيعة Linux تعتمد على Debian)، فستحتاج إلى تشغيل ما يلي باستخدام apt-get:
sudo apt-get install imagemagick -y
file أمر file Unix مطلوب للتحقق من نوع المحتوى. هذه الأداة غير متوفرة في نظام التشغيل Windows، ولكنها تأتي مرفقة مع Ruby Devkit، لذلك يجب على مستخدمي Windows التأكد من تثبيت devkit وإضافته إلى نظام PATH .
التثبيت اليدوي
إذا كنت تستخدم Windows 7+ كبيئة تطوير، فقد تحتاج إلى تثبيت تطبيق file.exe يدويًا. يعتمد نظام file spoofing في Paperclip 4+ على هذا؛ إذا لم يكن الملف يعمل، فستتلقى Validation failed: Upload file has an extension that does not match its contents. أخطاء.
للتثبيت يدويًا، يجب عليك تنفيذ ما يلي:
قم بتنزيل
fileوتثبيته من عنوان URL هذا
وللاختبار يمكنك استخدام الصورة أدناه:
بعد ذلك، تحتاج إلى التكامل مع بيئتك - ويفضل أن يكون ذلك من خلال متغير PATH ، أو عن طريق تغيير ملف config/environments/development.rb الخاص بك
طريق
1. Click "Start" 2. On "Computer", right-click and select "Properties" 3. In Properties, select "Advanced System Settings" 4. Click the "Environment Variables" button 5. Locate the "PATH" var - at the end, add the path to your newly installed `file.exe` (typically `C:Program Files (x86)GnuWin32bin`) 6. Restart any CMD shells you have open & see if it works
أو
بيئة
1. Open `config/environments/development.rb` 2. Add the following line: `Paperclip.options[:command_path] = 'C:Program Files (x86)GnuWin32bin'` 3. Restart your Rails server
ستمنح أي من هاتين الطريقتين إمكانية وصول إعداد Rails إلى وظيفة file.exe ، وبالتالي توفير القدرة على التحقق من محتويات الملف (إصلاح مشكلة الانتحال)
يتم توزيع مشبك الورق كجوهرة، وهذه هي الطريقة التي ينبغي استخدامه بها في تطبيقك.
قم بتضمين الجوهرة في ملف Gemfile الخاص بك:
جوهرة "مشبك الورق"، "~> 6.0.0"
أو، إذا كنت ترغب في الحصول على الأحدث، يمكنك الحصول على نسخة رئيسية من مستودع مشبك الورق الرئيسي:
جوهرة "مشبك الورق"، بوابة: "git://github.com/thinkbot/paperclip.git"
إذا كنت تحاول استخدام ميزات لا يبدو أنها موجودة في أحدث إصدار جوهري، ولكنها مذكورة في هذا الملف التمهيدي، فمن المحتمل أنك تحتاج إلى تحديد الفرع الرئيسي إذا كنت تريد استخدامها. من المحتمل أن يكون ملف README هذا متقدمًا على أحدث إصدار تم إصداره إذا كنت تقرأه على GitHub.
للاستخدام غير القضبان:
تتضمن الفئة ModuleName < ActiveRecord::Base مشبك ورق::Glue ...نهاية
فئة المستخدم < ActiveRecord::Base has_attached_file: avatar، الأنماط: { متوسط: "300x300>"، الإبهام: "100x100>" }، default_url: "/images/:style/missing.png" validates_attachment_content_type :avatar، content_type: / الصورة/.*z/end بافتراض أن لديك جدول users ، أضف عمود avatar إلى جدول users :
فئة AddAvatarColumnsToUsers < ActiveRecord::Migration def up add_attachment :users, :avatar end def down down Remove_attachment :users, :avatar endend
(أو يمكنك استخدام منشئ ترحيل Rails: rails generate paperclip user avatar )
تأكد من أن لديك الأساليب المقابلة في وحدة التحكم الخاصة بك:
<%=form_for @user, url: users_path, html: { multipart: true } do |form| %> <%=form.file_field :avatar %> <%=form.submit %><% end %><%= simple_form_for @user, url: users_path do |form| %> <%=form.input :avatar، مثل: :file %> <%=form.submit %><% end %>
def create @user = User.create(user_params)endprivate# استخدم strong_parameters للقائمة البيضاء للسمة# تأكد من تحديث أساليب وحدة التحكم create() وupdate().def user_params params.require(:user).permit(:avatar)end
أضف هذه العناصر إلى العرض الذي تريد عرض صورك فيه:
<%= image_tag @user.avatar.url %><%= image_tag @user.avatar.url(:medium) %><%= image_tag @user.avatar.url(:thumb) %>
هناك طريقتان للتحقق من وجود الملف:
file? present? يتحقق من ملء الحقل _file_name
exists? يتحقق من وجود الملف (سيتم إجراء اتصال TCP إذا تم تخزينه في السحابة)
ضع ذلك في الاعتبار إذا كنت تتحقق من وجود الملفات في حلقة ما. الإصدار الأول هو أكثر أداء بشكل ملحوظ، ولكن له دلالات مختلفة.
اضبط السمة على nil ثم احفظها.
@user.avatar = [email protected]
أساسيات Paperclip بسيطة جدًا: أعلن أن النموذج الخاص بك يحتوي على مرفق باستخدام الأسلوب has_attached_file ، وقم بتسميته.
سوف يغلف مشبك الورق ما يصل إلى أربع سمات (جميعها مسبوقة باسم هذا المرفق، بحيث يمكنك الحصول على عدة مرفقات لكل نموذج إذا كنت ترغب في ذلك) ويمنحهم واجهة أمامية ودية. هذه الصفات هي:
افتراضيًا، يلزم وجود
مزيد من المعلومات حول الخيارات التي تم تمريرها إلى has_attached_file متاحة في وثائق Paperclip::ClassMethods .
للتحقق من الصحة، يقدم Paperclip العديد من أدوات التحقق من صحة المرفق الخاص بك:
AttachmentContentTypeValidator
AttachmentPresenceValidator
AttachmentSizeValidator
مثال للاستخدام:
التحقق من صحة: الصورة الرمزية، وجود المرفق: truevalidates_with AttachmentPresenceValidator، السمات:: avatarvalidates_with AttachmentSizeValidator، السمات:: avatar، أقل_من: 1. ميغا بايت
يمكن أيضًا تعريف أدوات التحقق باستخدام نمط المساعد القديم:
validates_attachment_presence
validates_attachment_content_type
validates_attachment_size
مثال للاستخدام:
validates_attachment_presence :avatar
وأخيرًا، يمكنك أيضًا تحديد عمليات التحقق المتعددة على مرفق واحد باستخدام validates_attachment :
validates_attachment: الصورة الرمزية، الحضور: صحيح، نوع_المحتوى: "image/jpeg"، الحجم: { في: 0..10.كيلوبايت }ملاحظة: لن تبدأ مرحلة ما بعد المعالجة حتى إذا كان المرفق غير صالح وفقًا لعمليات التحقق من الصحة. سيتم استدعاء عمليات رد الاتصال والمعالجات الخاصة بك فقط مع المرفقات الصالحة.
رسالة فئة < ActiveRecord::Base has_attached_file :asset,styles: { Thumb: "100x100#" } before_post_process :skip_for_audio def Skip_for_audio
! %w(تطبيق الصوت/ogg/ogg).include?(asset_content_type) النهايةإذا كانت لديك عمليات تحقق أخرى تعتمد على أمر التعيين، فإن الإجراء الموصى به هو منع تعيين المرفق حتى بعد ذلك، ثم التعيين يدويًا:
class Book < ActiveRecord::Base has_attached_file :document, Styles: { الصورة المصغرة: "60x60#" } validates_attachment :document, content_type: "application/pdf" validates_something_else # عمليات التحقق الأخرى التي تتعارض مع Paperclip'sendclass BooksController < ApplicationController def create @book = Book.new(book_params) @book.document = params[:book][:document] @book.save Response_with @book end خاص def book_params params.require(:book).permit(:title, :author) endendملاحظة حول عمليات التحقق من صحة content_type والأمان
يجب عليك التأكد من التحقق من صحة الملفات لتكون فقط أنواع MIME التي تريد دعمها بشكل صريح. إذا لم تقم بذلك، فقد تكون عرضة لهجمات XSS إذا قام المستخدم بتحميل ملف يحتوي على حمولة HTML ضارة.
إذا كنت مهتمًا بالصور فقط، فاقتصر أنواع المحتوى المسموح بها على أنواع الصور:
validates_attachment: الصورة الرمزية، نوع المحتوى: ["image/jpeg"، "image/gif"، "image/png"]
سيحاول Paperclip::ContentTypeDetector مطابقة امتداد الملف مع نوع_المحتوى المستنتج، بغض النظر عن المحتويات الفعلية للملف.
لاستخدام أو إضافة ملفات محلية بلغات مختلفة، تحقق من المشروع https://github.com/thinkbot/paperclip-i18n.
بفضل تقرير من Egor Homakov، اتخذنا خطوات لمنع الأشخاص من انتحال أنواع المحتوى والحصول على بيانات لم تكن تتوقعها على الخادم الخاص بك.
ملاحظة: بدءًا من الإصدار 4.0.0، يُطلب من جميع المرفقات تضمين التحقق من صحة نوع_المحتوى، أو التحقق من صحة اسم_الملف، أو الإشارة بشكل صريح إلى أنها لن تحتوي على أي منهما. سيثير مشبك الورق خطأً إذا لم تقم بذلك.
class ActiveRecord::Base has_attached_file :avatar # التحقق من صحة نوع المحتوى validates_attachment_content_type :avatar, content_type: /Aimage/ # التحقق من صحة اسم الملف validates_attachment_file_name :avatar, matchs: [/pngz/, /jpe?gz/] # صراحة لا تفعل ذلك التحقق من صحة do_not_validate_attachment_file_type :avatarend
يؤدي هذا إلى إبقاء Paperclip آمنًا بشكل افتراضي، وسيمنع الأشخاص من محاولة العبث بنظام الملفات الخاص بك.
ملاحظة: بدءًا من الإصدار 4.0.0 أيضًا، يحتوي Paperclip على عملية تحقق أخرى لا يمكن إيقاف تشغيلها. سيؤدي هذا التحقق من الصحة إلى منع انتحال نوع المحتوى. أي تحميل مستند PHP (على سبيل المثال) كجزء من علامات EXIF لملف JPEG جيد التكوين. يقتصر هذا الفحص على نوع الوسائط (الجزء الأول من نوع MIME، لذا، "نص" في text/plain ). سيؤدي هذا إلى منع تحميل مستندات HTML بتنسيق JPEG، لكنه لن يمنع تحميل ملفات GIF بامتداد .jpg . سيضيف هذا التحقق من الصحة أخطاء التحقق من الصحة إلى النموذج فقط. لن يتسبب في إثارة الأخطاء.
يمكن أن يتسبب هذا في بعض الأحيان في حدوث أخطاء خاطئة في التحقق من الصحة في التطبيقات التي تستخدم امتدادات الملفات المخصصة. في هذه الحالات، قد ترغب في إضافة ملحقك المخصص إلى قائمة تعيينات أنواع المحتوى عن طريق إنشاء config/initializers/paperclip.rb :
# السماح بـ ".foo" كامتداد للملفات ذات نوع MIME "text/plain".Paperclip.options[:content_type_mappings] = { foo: %w(text/plain)} يمكن تحديد الإعدادات الافتراضية العامة لجميع مرفقات Paperclip الخاصة بك عن طريق تغيير تجزئة Paperclip::Attachment.default_options. يمكن أن يكون هذا مفيدًا لتعيين إعدادات التخزين الافتراضية الخاصة بك لكل مثال، لذلك لن تضطر إلى تحديدها في كل تعريف has_attached_file .
إذا كنت تستخدم Rails، فيمكنك تعريف Hash بالخيارات الافتراضية في config/application.rb أو في أي من ملفات config/environments/*.rb على config.paperclip_defaults. سيتم دمجها في Paperclip::Attachment.default_options أثناء تشغيل تطبيق Rails الخاص بك. مثال:
الوحدة النمطية YourApp class Application < Rails::Application # رمز آخر... config.paperclip_defaults = { Storage: :fog, fog_credentials: { Provider: "Local"، local_root: "#{Rails.root}/public"}, fog_directory: ""، fog_host: "localhost"} endend هناك خيار آخر وهو تعديل تجزئة Paperclip::Attachment.default_options مباشرةً - تعمل هذه الطريقة مع التطبيقات غير التابعة لـ Rails أو تكون خيارًا إذا كنت تفضل وضع إعدادات Paperclip الافتراضية في مُهيئ.
سيبدو مثال مُهيئ Rails كما يلي:
مشبك الورق::Attachment.default_options[:storage] = :fogPaperclip::Attachment.default_options[:fog_credentials] = {provider: "Local"، local_root: "#{Rails.root}/public"} مشبك ورق::Attachment.default_options[ :fog_directory] = ""مشبك الورق::Attachment.default_options[:fog_host] = "http://localhost:3000"يحدد Paperclip العديد من طرق الترحيل التي يمكن استخدامها لإنشاء الأعمدة الضرورية في النموذج الخاص بك. هناك نوعان من الأساليب المساعدة للمساعدة في ذلك، كما يلي:
يمكن استخدام مساعد attachment عند إنشاء جدول:
فئة CreateUsersWithAttachments < ActiveRecord::Migration def up create_table :users do |t| t.attachment :avatar end end # هذا على افتراض أنك تستخدم جدول المستخدمين فقط لمرفق مشبك الورق. إسقاط بعناية! قم بإلغاء تحديد drop_table :users endend
يمكنك أيضًا استخدام طريقة change ، بدلاً من التركيبة up / down أعلاه، كما هو موضح أدناه:
فئة CreateUsersWithAttachments < ActiveRecord::Migration def تغيير create_table :users do |t| t.attachment: نهاية نهاية الصورة الرمزية
بدلاً من ذلك، يمكن استخدام الطريقتين add_attachment و remove_attachment لإضافة أعمدة مشبك ورق جديدة إلى جدول موجود:
فئة AddAttachmentColumnsToUsers < ActiveRecord::Migration def up add_attachment :users, :avatar end def down down Remove_attachment :users, :avatar endend
أو يمكنك القيام بذلك باستخدام طريقة change :
فئة AddAttachmentColumnsToUsers < ActiveRecord::Migration def تغيير add_attachment :users, :avatar endend
لا يزال بناء الجملة القديم (مثل t.has_attached_file و drop_attached_file ) مدعومًا في Paperclip 3.x، ولكن ننصحك بتحديث ملفات الترحيل هذه لاستخدام بناء الجملة الجديد هذا.
يأتي مشبك الورق مع 3 محولات تخزين:
تخزين الملفات
تخزين S3 (عبر aws-sdk-s3 )
تخزين الضباب
إذا كنت ترغب في استخدام مشبك الورق مع وحدة تخزين أخرى، فيمكنك تثبيت هذه الجواهر جنبًا إلى جنب مع مشبك الورق:
مشبك الورق اللازوردي
تخزين مشبك الورق اللازوردي
مشبك الورق المنسدل
يتم وضع الملفات التي تم تعيينها كمرفقات، افتراضيًا، في الدليل المحدد بواسطة خيار :path إلى has_attached_file . افتراضيًا، هذا الموقع هو :rails_root/public/system/:class/:attachment/:id_partition/:style/:filename . تم اختيار هذا الموقع لأنه، في عمليات نشر Capistrano القياسية، يمكن ربط الدليل public/system بالدليل المشترك للتطبيق، مما يعني أنه يظل موجودًا بين عمليات النشر. على سبيل المثال، باستخدام هذا :path ، قد يكون لديك ملف في
/data/myapp/releases/20081229172410/public/system/users/avatar/000/000/013/small/my_pic.png
ملاحظة : يعد هذا تغييرًا عن الإصدارات السابقة من Paperclip، ولكنه بشكل عام خيار أكثر أمانًا لمخزن الملفات الافتراضي.
يمكنك أيضًا اختيار تخزين ملفاتك باستخدام خدمة Amazon S3. للقيام بذلك، قم بتضمين الجوهرة aws-sdk-s3 في ملف Gemfile الخاص بك:
جوهرة "aws-sdk-s3"
وبعد ذلك يمكنك تحديد استخدام S3 من has_attached_file . يمكنك العثور على مزيد من المعلومات حول تكوين واستخدام تخزين S3 في وثائق Paperclip::Storage::S3 .
ستكون الملفات الموجودة على نظام الملفات المحلي (وفي الدليل العام لتطبيق Rails) متاحة للإنترنت بشكل عام. إذا كنت بحاجة إلى التحكم في الوصول، فمن الممكن وضع ملفاتك في موقع مختلف. ستحتاج إلى تغيير الخيارين :path و :url للتأكد من أن الملفات غير متاحة للعامة. يسمح كل من :path و :url بنفس مجموعة المتغيرات المحرفة.
عندما يتم تحميل ملف أو إرفاقه، يمكن أن يكون في أحد نماذج الإدخال القليلة المختلفة، بدءًا من كائن UploadedFile في Rails إلى StringIO إلى Tempfile أو حتى سلسلة بسيطة تمثل عنوان URL يشير إلى صورة.
سيقبل مشبك الورق، افتراضيًا، العديد من هذه المصادر. كما أنها قادرة على التعامل مع المزيد مع القليل من التكوين. لا يتم تمكين محولات الإدخال والإخراج التي تتعامل مع الصور من مصادر غير محلية بشكل افتراضي. يمكن تفعيلها عن طريق إضافة سطر مشابه لما يلي في config/initializers/paperclip.rb :
مشبك الورق::DataUriAdapter.register
من الأفضل تمكين محول التحميل عن بعد فقط إذا كنت في حاجة إليه. بخلاف ذلك، هناك احتمال أن يتمكن شخص ما من الحصول على نظرة ثاقبة لبنية شبكتك الداخلية باستخدامها كمتجه.
لا يتم تحميل المحولات التالية بشكل افتراضي:
Paperclip::UriAdapter - الذي يقبل مثيل URI .
Paperclip::HttpUrlProxyAdapter - الذي يقبل سلسلة http .
Paperclip::DataUriAdapter - الذي يقبل data: سلسلة.
يدعم Paperclip مجموعة موسعة من المعالجات اللاحقة. عندما تقوم بتعريف مجموعة من الأنماط لمرفق ما، فمن المتوقع بشكل افتراضي أن تكون تلك "الأنماط" هي في الواقع "صور مصغرة". تتم معالجتها بواسطة Paperclip::Thumbnail . لأسباب تتعلق بالتوافق مع الإصدارات السابقة، يمكنك تمرير إما سلسلة هندسية واحدة، أو مصفوفة تحتوي على شكل هندسي وتنسيق سيتم تحويل الملف إليه، كما يلي:
يحتوي على ملف مرفق: الصورة الرمزية، الأنماط: { Thumb: ["32x32#"، :png] } سيؤدي هذا إلى تحويل النمط "الإبهام" إلى مربع بحجم 32 × 32 بتنسيق PNG، بغض النظر عما تم تحميله. إذا لم يتم تحديد التنسيق، فسيتم الاحتفاظ به كما هو (على سبيل المثال، ستظل ملفات JPG هي ملفات JPG). Paperclip::Thumbnail يستخدم ImageMagick لمعالجة الصور؛ تحتوي وثائق الهندسة الخاصة بـ ImageMagick على مزيد من المعلومات حول تنسيقات الأنماط المقبولة.
لمزيد من التحكم الدقيق في عملية التحويل، يمكن استخدام source_file_options و convert_options لتمرير العلامات والإعدادات مباشرةً إلى أداة التحويل القوية الخاصة بـ ImageMagick، والموثقة هنا. على سبيل المثال:
has_attached_file :صورة، الأنماط: { عادي: ['800x800>'، :png]}،
source_file_options: { عادي: "-الكثافة 96 - العمق 8 - الجودة 85" }, converter_options: { عادي: "-posterize 3"}يدعم ImageMagick عددًا من متغيرات البيئة للتحكم في حدود موارده. على سبيل المثال، يمكنك فرض حدود زمنية للذاكرة أو التنفيذ عن طريق تعيين المتغيرات التالية في بيئة عملية التطبيق الخاص بك:
MAGICK_MEMORY_LIMIT=128MiB
MAGICK_MAP_LIMIT=64MiB
MAGICK_TIME_LIMIT=30
للحصول على قائمة كاملة بالمتغيرات والوصف، راجع وثائق موارد ImageMagick.
يمكنك كتابة معالجات المرفقات المخصصة الخاصة بك لتنفيذ مهام مثل إضافة علامات مائية أو ضغط الصور أو تشفير الملفات. يجب تعريف المعالجات المخصصة ضمن وحدة Paperclip ، وورثها من Paperclip::Processor (انظر lib/paperclip/processor.rb )، وتنفيذ طريقة make التي تُرجع File . سيتم تحميل جميع الملفات الموجودة في مجلدات lib/paperclip و lib/paperclip_processors لتطبيق Rails تلقائيًا بواسطة Paperclip. يتم تحديد المعالجات باستخدام خيار :processors لـ has_attached_file :
has_attached_file :scan، الأنماط: { text: { الجودة: :better } }، المعالجات: [:ocr] سيؤدي هذا إلى تحميل الفئة الافتراضية Paperclip::Ocr ، وتمريرها إلى خيارات التجزئة { quality: :better } ، بالإضافة إلى الملف الذي تم تحميله.
يمكن تحديد معالجات متعددة، وسيتم استدعاؤها بالترتيب المحدد في مصفوفة :processors . يتم إعطاء كل معالج متتالي النتيجة من المعالج السابق. تتلقى جميع المعالجات نفس المعلمات، والتي تم تعريفها في تجزئة :styles . على سبيل المثال، لنفترض أن لدينا هذا التعريف:
has_attached_file :scan، الأنماط: { text: {quality: :better } }، المعالجات: [:rotator, :ocr] سيتلقى كل من المعالج :rotator والمعالج :ocr الخيارات { quality: :better } . إذا تلقى المعالج خيارًا لم يتعرف عليه، فمن المتوقع أن يتجاهله.
ملاحظة: نظرًا لأن المعالجات تعمل عن طريق تحويل المرفق الأصلي إلى أنماط، فلن يتم تشغيل أي معالجات إذا لم تكن هناك أنماط محددة.
إذا كنت مهتمًا بالتخزين المؤقت لعرض الصورة المصغرة وارتفاعها وحجمها في قاعدة البيانات، فقم بإلقاء نظرة على الجوهرة التعريفية لمشبك الورق.
أيضًا، إذا كنت مهتمًا بإنشاء الصورة المصغرة بشكل سريع، فقد ترغب في الاطلاع على الجوهرة المرفقة_on_the_fly.
يتم تطبيق مولد الصور المصغرة الخاص بـ Paperclip (انظر lib/paperclip/thumbnail.rb ) كمعالج، وقد يكون مرجعًا جيدًا لكتابة المعالجات الخاصة بك.
قبل خطوة ما بعد المعالجة وبعدها، يعيد Paperclip الاتصال بالنموذج من خلال عدد قليل من عمليات رد الاتصال، مما يسمح للنموذج بتغيير خطوة المعالجة أو إلغائها. ردود النداء هي before_post_process و after_post_process (والتي يتم استدعاؤها قبل وبعد معالجة كل مرفق)، والرد الخاص بالمرفق before_ و after_ . تهدف عمليات الاسترجاعات إلى أن تكون أقرب ما تكون إلى عمليات الاسترجاعات العادية لـ ActiveRecord قدر الإمكان، لذلك إذا قمت بإرجاع false (على وجه التحديد - إرجاع nil ليس هو نفسه) في before_filter ، فستتوقف خطوة المعالجة اللاحقة. لن يؤدي إرجاع خطأ في after_filter إلى إيقاف أي شيء، ولكن يمكنك الوصول إلى النموذج والمرفق إذا لزم الأمر.
ملاحظة: لن تبدأ عملية النشر حتى إذا كان المرفق غير صالح وفقًا لعمليات التحقق من الصحة. سيتم استدعاء عمليات رد الاتصال والمعالجات الخاصة بك فقط مع المرفقات الصالحة.
رسالة فئة < ActiveRecord::Base has_attached_file :asset,styles: { Thumb: "100x100#" } before_post_process :skip_for_audio def Skip_for_audio
! %w(تطبيق الصوت/ogg/ogg).include?(asset_content_type) النهاية يحتوي Paperclip على استيفاء يسمى :hash لإخفاء أسماء الملفات المتاحة للعامة.
مثال للاستخدام:
has_attached_file :avatar, { url: "/system/:hash.:extension"، hash_secret: "longSecretString"} سيتم استبدال الاستيفاء :hash بتجزئة فريدة تتكون مما هو محدد في :hash_data . القيمة الافتراضية لـ :hash_data هي ":class/:attachment/:id/:style/:updated_at" .
مطلوب :hash_secret - سيتم طرح استثناء إذا تم استخدام :hash بدون وجود :hash_secret .
للمزيد حول هذه الميزة، اقرأ شرح المؤلف الخاص
سيتم وضع المجموع الاختباري للملف الأصلي المعين في النموذج إذا كان يحتوي على سمة تسمى بصمة الإصبع. باتباع مثال ترحيل نموذج المستخدم أعلاه، سيبدو الترحيل كما يلي:
فئة AddAvatarFingerprintColumnToUser < ActiveRecord::Migration def up add_column :users, :avatar_fingerprint, :string end def down down Remove_column :users, :avatar_fingerprint endend
يمكن تحديد الخوارزمية باستخدام خيار التكوين؛ يتم تعيينه افتراضيًا على MD5 للتوافق مع الإصدارات السابقة مع Paperclip 5 والإصدارات الأقدم.
has_attached_file :some_attachment, converter_options: { hash_digest: Digest::SHA256 } تشغيل CLASS=User ATTACHMENT=avatar rake paperclip:refresh:fingerprints بعد تغيير الملخص على المرفقات الموجودة لتحديث بصمات الأصابع في قاعدة البيانات.
يتوفر خيار للاحتفاظ بالمرفقات من أجل اللعب بشكل جيد مع النماذج المحذوفة بشكل بسيط. (الأفعال_كجنون العظمة، جنون العظمة، وما إلى ذلك)
has_attached_file :some_attachment, {server_files: true,} سيؤدي هذا إلى منع مسح some_attachment عند تدمير النموذج، لذلك سيظل موجودًا عند استعادة الكائن لاحقًا.
يمكن استخدام الكائنات القابلة للاستدعاء (lambdas وProcs) في عدد من الأماكن للتكوين الديناميكي عبر Paperclip. توجد هذه الإستراتيجية في عدد من مكونات المكتبة ولكنها الأكثر أهمية في إمكانيات السماح بتطبيق الأنماط والمعالجات المخصصة لمثيلات نموذجية محددة، بدلاً من تطبيق الأنماط والمعالجات المحددة عبر جميع المثيلات.
تخيل نموذج مستخدم له أنماط مختلفة بناءً على دور المستخدم. ربما يكون بعض المستخدمين رؤساء (على سبيل المثال يستجيب مثيل نموذج المستخدم لـ #boss? ) ويستحقون صورة مصغرة أكبر من المستخدمين العاديين. قد يبدو التكوين لتحديد معلمات النمط التي سيتم استخدامها بناءً على دور المستخدم كما يلي، حيث سيتلقى الرئيس صورة مصغرة 300x300 وإلا سيتم إنشاء صورة مصغرة 100x100 .
فئة المستخدم < ActiveRecord::Base has_attached_file :avatar,styles: lambda { |attachment| { الإبهام: (attachment.instance.boss? ? "300x300>" : "100x100>") } }end مثال آخر مفتعل هو نموذج المستخدم الذي يعرف معالجات الملفات التي يجب تطبيقها عليه (خارج معالج thumbnail الضمني الذي يتم استدعاؤه عند تحديد :styles ). ربما يتوفر لدينا معالج للعلامة المائية ويتم استخدامه فقط في الصور الرمزية لنماذج معينة. قد يكون التكوين الخاص بهذا هو المكان الذي يتم فيه الاستعلام عن المعالجات التي يجب تطبيقها عليه. من المفترض أن يقوم بعض المستخدمين بإرجاع [:thumbnail, :watermark] لمعالجاتها، حيث يتم استدعاء معالج watermark المحدد بعد معالج thumbnail المحدد بالفعل بواسطة Paperclip.
فئة المستخدم < ActiveRecord::Base has_attached_file :avatar، المعالجات: lambda { |instance| example.processors } attr_accessor :processorsendبشكل افتراضي، يقوم مشبك الورق بإخراج التسجيل وفقًا لمستوى المسجل الخاص بك. إذا كنت تريد تعطيل التسجيل (على سبيل المثال أثناء الاختبار)، فأضف هذا إلى تكوين بيئتك:
Your::Application.configure do... Paperclip.options[:log] = false...end
مزيد من المعلومات في rdocs
لجعل Capistrano يربط الدليل public/system بحيث تظل المرفقات قادرة على الصمود في عمليات النشر الجديدة، قم بتعيين خيار linked_dirs في ملف config/deploy.rb :
تعيين :linked_dirs، جلب(:linked_dirs، []).push('public/system') يدرك Paperclip أنماط المرفقات الجديدة التي أضفتها في عمليات النشر السابقة. الشيء الوحيد الذي يجب عليك فعله بعد كل عملية نشر هو استدعاء rake paperclip:refresh:missing_styles . سيقوم بتخزين أنماط المرفقات الحالية في RAILS_ROOT/public/system/paperclip_attachments.yml افتراضيًا. يمكنك تغييره عن طريق:
Paperclip.registered_attachments_styles_path = '/tmp/config/paperclip_attachments.yml'
هنا مثال لكابيسترانو:
مساحة الاسم: مشبك ورق قم بوصف مهمة "إنشاء أنماط مشبك الورق المفقودة": قم بتنفيذ أنماط مشبك الورق: build_missing_styles على الأدوار(:app) قم بها داخل Release_path افعلها باستخدام Rails_env: fetch(:rails_env) قم بتنفيذها: rake، "paperclip:refresh:missing_styles" end end end endendafter( "نشر: ترجمة الأصول"، "مشبك الورق: build_missing_styles")
الآن ليس عليك أن تتذكر تحديث الصور المصغرة في الإنتاج في كل مرة تضيف فيها نمطًا جديدًا. ولسوء الحظ، فهو لا يعمل مع الأنماط الديناميكية - بل يتجاهلها فقط.
إذا كان لديك تطبيق يعمل بالفعل ولا ترغب في rake paperclip:refresh:missing_styles لتحديث الصور القديمة، فأنت بحاجة إلى إخبار Paperclip بالأنماط الموجودة. ما عليك سوى إنشاء ملف paperclip_attachments.yml يدويًا. على سبيل المثال:
فئة المستخدم < ActiveRecord::Base has_attached_file: الصورة الرمزية، الأنماط: { الإبهام: 'x100'، قابل للاقتصاص: '600x600>'، كبير: '1000x1000>' }endclass Book < ActiveRecord::Base has_attached_file: الغلاف، الأنماط: { صغير: 'x100'، كبير: '1000x1000>' } has_attached_file :sample,styles: { Thumb: 'x100' }end ثم في RAILS_ROOT/public/system/paperclip_attachments.yml :
---:المستخدم: :avatar: - :إبهام - :قابل للقص - :كبير:كتاب: :الغلاف: - :صغير - :كبير :عينة: - :إبهام
يوفر Paperclip مطابقات متوافقة مع rspec لاختبار المرفقات. راجع الوثائق الموجودة على Paperclip::Shoulda::Matchers لمزيد من المعلومات.
الاختبارات الموازية
نظرًا path الافتراضي لتخزين مشبك الورق، إذا حاولت إجراء اختبارات بالتوازي، فقد تجد أنه تتم الكتابة فوق الملفات لأنه يتم حساب نفس المسار لها في كل عملية اختبار. بينما يعمل هذا الإصلاح مع الاختبارات المتوازية، يجب استخدام مفهوم مماثل لأي آلية أخرى لتشغيل الاختبارات بشكل متزامن.
إذا ENV['PARALLEL_TEST_GROUPS'] مشبك الورق::Attachment.default_options[:path] = ":rails_root/public/system/:rails_env/#{ENV['TEST_ENV_NUMBER'].to_i}/:class/:attachment/:id_partition/ :اسم الملف"آخر مشبك الورق::Attachment.default_options[:path] = ":rails_root/public/system/:rails_env/:class/:attachment/:id_partition/:filename"end الجزء المهم هنا هو تضمين ENV['TEST_ENV_NUMBER'] أو آلية مماثلة لأي مكتبة اختبار موازية تستخدمها.
اختبارات التكامل
قد يؤدي استخدام اختبارات التكامل مع FactoryBot إلى حفظ نسخ متعددة من ملفات الاختبار داخل التطبيق. لتجنب ذلك، حدد مسارًا مخصصًا في الملف config/environments/test.rb كما يلي:
مشبك الورق::Attachment.default_options[:path] = "#{Rails.root}/spec/test_files/:class/:id_partition/:style.:extension" ثم تأكد من حذف هذا الدليل بعد تشغيل مجموعة الاختبار عن طريق إضافة هذا إلى spec_helper.rb .
config.after(:suite) do FileUtils.rm_rf(Dir["#{Rails.root}/spec/test_files/"])endمثال على تكوين الاختبار باستخدام Factory Bot
FactoryBot.define do Factory:user do avatar { File.new("#{Rails.root}/spec/support/fixtures/image.jpg") } endendإذا كنت ترغب في المساهمة بميزة أو إصلاح خطأ: شكرًا! للتأكد من أن الإصلاح/الميزة الخاصة بك لديها فرصة كبيرة لتضمينها، يرجى قراءة الإرشادات التالية:
نشر طلب سحب.
تأكد من وجود اختبارات! لن نقبل أي تصحيح لم يتم اختباره. من النادر أن لا تكون هناك حاجة إلى اختبارات واضحة. إذا كانت لديك أسئلة حول كتابة اختبارات مشبك الورق، فيرجى فتح مشكلة GitHub.
يرجى الاطلاع على CONTRIBUTING.md لمزيد من التفاصيل حول المساهمة وإجراء الاختبار.
شكرا لجميع المساهمين!
حقوق الطبع والنشر لمشبك الورق © 2008-2017 thinkbot, inc. إنه برنامج مجاني، ويمكن إعادة توزيعه بموجب الشروط المحددة في ملف ترخيص MIT.
تتم صيانة مشبك الورق وتمويله بواسطة thinkbot. الأسماء والشعارات الخاصة بـ thinkbot هي علامات تجارية مملوكة لشركة thinkbot, Inc.
نحن نحب البرمجيات مفتوحة المصدر! شاهد مشاريعنا الأخرى أو قم بتعييننا لتصميم منتجك وتطويره وتنميته.
