kaminari
v1.2.2
مجموعة من النطاق والمحرك ، نظيفة ، قوية ، قابلة للتخصيص ومتطورة لأطر تطبيق الويب الحديثة و ORMS
لا يتم تلوث عالميًا أو Array Hash Object أو AR::Base .
فقط قم بتجميع الأحجار الكريمة ، ثم تكون الطرز جاهزة للتراجع. لا يوجد تكوين مطلوب. لا تضطر إلى تحديد أي شيء في النماذج أو المساعدين.
كل شيء قابل للسلسلة مع أقل "التهاب الحشائش". أنت تعرف ، هذه هي طريقة القضبان الحديثة. لا توجد فئة تجميع خاصة أو أي شيء للقيم المربوطة ، بدلاً من ذلك باستخدام مثيل AR::Relation العام. لذلك ، بالطبع يمكنك سلسلة أي شروط أخرى قبل أو بعد نطاق Paginator.
نظرًا لأن مساعد ترقيم الصفحات بأكمله هو في الأساس مجرد مجموعة من الروابط وغير الروابط ، فإن Kaminari يجعل كل منهم من خلال قالبه الجزئي داخل المحرك. لذلك ، يمكنك بسهولة تعديل سلوكهم أو أسلوبهم أو أي شيء عن طريق تجاوز القوالب الجزئية.
يدعم Kaminari العديد من ORMS (ActivereCord ، Datamapper ، Mongoid ، Mongomapper) ، أطر عمل متعددة (القضبان ، سيناترا ، العنب) ، ومحركات القوالب المتعددة (ERB ، Haml ، Slim).
يخرج مساعد ترقيم الصفحات علامة HTML5 <nav> بشكل افتراضي. بالإضافة إلى ذلك ، يدعم المساعد قضبان أياكس غير مزعجة.
Ruby 2.1 ، 2.2 ، 2.3 ، 2.4 ، 2.5 ، 2.6 ، 2.7 ، 3.0 ، 3.1 ، 3.2 ، 3.3
القضبان 4.1 ، 4.2 ، 5.0 ، 5.1 ، 5.2 ، 6.0 ، 6.1 ، 7.0 ، 7.1 ، 7.2 ، 8.0
سيناترا 1.4 ، 2.0
هامل 3+
mongoid 3+
mongomapper 0.9+
Datamapper 1.1.0+
لتثبيت kaminari على مكدس القضبان الافتراضي ، فقط ضع هذا الخط في Gemfile:
gem 'kaminari'ثم باقة:
% bundleإذا كنت تقوم ببناء تطبيق غير قضبان أو تطبيق غير ActivereCord وتريد ميزة ترقيم الصفحات عليه ، فيرجى إلقاء نظرة على قسم دعم الإطار/المكتبة الآخر.
page لجلب الصفحة السابعة من المستخدمين (الافتراضي per_page هو 25)
User . page ( 7 )ملاحظة: يبدأ ترقيم الصفحات في الصفحة 1 ، وليس في الصفحة 0 (الصفحة (0) ستعيد نفس النتائج مثل الصفحة (1)).
Kaminari لا يضيف order للاستعلام. لتجنب المفاجآت ، يجب أن تتضمن عمومًا طلبًا في الاستعلامات المربوطة. على سبيل المثال:
User . order ( :name ) . page ( 7 )يمكنك الحصول على أرقام الصفحات أو شروط الصفحة باستخدام الأساليب أدناه.
User . count #=> 1000
User . page ( 1 ) . limit_value #=> 20
User . page ( 1 ) . total_pages #=> 50
User . page ( 1 ) . current_page #=> 1
User . page ( 1 ) . next_page #=> 2
User . page ( 2 ) . prev_page #=> 1
User . page ( 1 ) . first_page? #=> true
User . page ( 50 ) . last_page? #=> true
User . page ( 100 ) . out_of_range? #=> trueper نطاق لإظهار الكثير من المستخدمين في كل صفحة (قم بتغيير per قيمة)
User . order ( :name ) . page ( 7 ) . per ( 50 ) لاحظ أنه لا يتم تعريف النطاق per مباشرة على النماذج ولكنه مجرد طريقة محددة في نطاق الصفحة. هذا أمر معقول تمامًا لأنك لن per فعليًا دون تحديد رقم page .
ضع في اعتبارك أنه يستخدم per limit ، وبالتالي سيتخطى أي limit تم تعيينه مسبقًا. وإذا كنت ترغب في الحصول على الحجم لجميع سجلات الطلب ، يمكنك استخدام طريقة total_count :
User . count #=> 1000
a = User . limit ( 5 ) ; a . count #=> 5
a . page ( 1 ) . per ( 20 ) . size #=> 20
a . page ( 1 ) . per ( 20 ) . total_count #=> 1000paddingفي بعض الأحيان ، تحتاج إلى وضع عدد من السجلات التي ليست مضاعفة لحجم الصفحة.
User . order ( :name ) . page ( 7 ) . per ( 50 ) . padding ( 3 ) لاحظ أن نطاق padding غير محدد أيضًا مباشرة على النماذج.
إذا كنت بحاجة لسبب ما إلى page غير per ، يمكنك الاتصال except(:limit, :offset)
users = User . order ( :name ) . page ( 7 ) . per ( 50 )
unpaged_users = users . except ( :limit , :offset ) # unpaged_users will not use the kaminari scopes يمكنك تكوين القيم الافتراضية التالية عن طريق تجاوز هذه القيم باستخدام طريقة Kaminari.configure .
default_per_page # 25 by default
max_per_page # nil by default
max_pages # nil by default
window # 4 by default
outer_window # 0 by default
left # 0 by default
right # 0 by default
page_method_name # :page by default
param_name # :page by default
params_on_first_page # false by default
هناك مولد مفيد يقوم بإنشاء ملف التكوين الافتراضي في دليل التكوين/المبدعين. قم بتشغيل أمر المولد التالي ، ثم قم بتحرير الملف الذي تم إنشاؤه.
% rails g kaminari:configpage_method_name يمكنك تغيير page اسم الطريقة إلى bonzo أو plant أو ما تريد ، من أجل اللعب بشكل جيد مع طريقة page أو الارتباط أو النطاق الحالي أو أي مكون إضافي يحدد طريقة page على الطرز الخاصة بك.
paginates_per يمكنك تحديد قيمة per_page الافتراضية لكل نموذج باستخدام DSL التعريفي التالي.
class User < ActiveRecord :: Base
paginates_per 50
endmax_paginates_per يمكنك تحديد قيمة max per_page لكل نموذج باستخدام DSL التعريفي التالي. إذا كان المتغير الذي تم تحديده per النطاق أكثر من هذا المتغير ، يتم استخدام max_paginates_per بدلاً من ذلك. القيمة الافتراضية هي NIL ، مما يعني أنك لا تفرض أي قيمة MAX per_page .
class User < ActiveRecord :: Base
max_paginates_per 100
endmax_pages يمكنك تحديد قيمة max_pages لكل نموذج باستخدام DSL التعريفي التالي. هذه القيمة تقيد إجمالي عدد الصفحات التي يمكن إرجاعها. مفيد لوضع حدود على مجموعات كبيرة.
class User < ActiveRecord :: Base
max_pages 100
end إذا كنت تستخدم جوهرة ransack_memory وتجربة مشاكل في العودة إلى الصفحة السابقة أو الأولى ، فقم بتعيين إعداد params_on_first_page إلى true .
params[:page]عادة ، سيبدو رمز وحدة التحكم الخاص بك هكذا:
@users = User . order ( :name ) . page params [ :page ] ما عليك سوى الاتصال بمساعد paginate :
<%= paginate @users %> سيؤدي هذا إلى جعل العديد من روابط ترقيم ?page=N محاطًا بعلامة HTML5 <nav> .
paginate <%= paginate @users %> هذا من شأنه أن يخرج العديد من روابط ترقيم الصفحات مثل « First ‹ Prev ... 2 3 4 5 6 7 8 9 10 ... Next › Last » .
<%= paginate @users, window: 2 %> هذا من شأنه أن يخرج شيئًا مثل ... 5 6 7 8 9 ... عندما يكون 7 هو الصفحة الحالية.
<%= paginate @users, outer_window: 3 %> هذا من شأنه أن يخرج شيئًا مثل 1 2 3 ...(snip)... 18 19 20 بينما كان هناك 20 صفحة في المجموع.
<%= paginate @users, left: 1, right: 3 %> هذا من شأنه أن يخرج شيئًا مثل 1 ...(snip)... 18 19 20 بينما كان هناك 20 صفحة في المجموع.
:param_name ) للروابط <%= paginate @users, param_name: :pagina %> هذا من شأنه تعديل اسم معلمة الاستعلام على كل روابط.
:params ) للروابط <%= paginate @users, params: {controller: 'foo', action: 'bar', format: :turbo_stream} %> هذا من شأنه تعديل url_option لكل رابط. :controller و :action قد يكون المفاتيح المشتركة.
<%= paginate @users, remote: true %> هذا من شأنه أن يضيف data-remote="true" إلى جميع الروابط في الداخل.
<%= paginate @users, views_prefix: 'templates' %> هذا من شأنه أن يبحث عن الجزأين في app/views/templates/kaminari . هذا الخيار يجعل من السهل القيام بأشياء مثل قوالب/موضوعات لترقيم ترقيم ترقيم ترقيم الأطراف A/B ، باستخدام قوالب جديدة/قديمة في نفس الوقت بالإضافة إلى تكامل أفضل مع الأحجار الكريمة الأخرى مثل الخلايا.
link_to_next_page و link_to_previous_page (المستعار إلى link_to_prev_page ) أساليب المساعد <%= link_to_next_page @items, 'Next Page' %> هذا ببساطة يجعل رابطًا إلى الصفحة التالية. سيكون هذا مفيدًا لإنشاء ميزة ترقيم ترقيم تويتر.
تدعم طرق المساعد خيار params لتحديد الرابط. إذا كان الحاجة إلى تعيين format ، قم بتضمينه في تجزئة params .
<%= link_to_next_page @items, 'Next Page', params: {controller: 'foo', action: 'bar', format: :turbo_stream} %> page_entries_info المساعد <%= page_entries_info @posts %>هذا يجعل رسالة مفيدة مع أعداد من الإدخالات المعروضة مقابل إجمالي.
بشكل افتراضي ، ستستخدم الرسالة اسم الفئة البشرية للكائنات في المجموعة: على سبيل المثال ، "أنواع المشروع" لنماذج ProjectType. سيتم قطع مساحة الاسم وسيتم استخدام الاسم الأخير فقط. تجاوز هذا باستخدام المعلمة :entry_name :
<%= page_entries_info @posts, entry_name: 'item' %>
#= > Displaying items 6 - 10 of 26 in totalrel_next_prev_link_tags <%= rel_next_prev_link_tags @users %>هذا يجعل علامات REL التالية والرابط السابق للرأس.
path_to_next_page <%= path_to_next_page @users %>هذا يعيد المسار النسبي الخادم إلى الصفحة التالية.
path_to_prev_page <%= path_to_prev_page @users %>هذا يعيد المسار النسبي الخادم إلى الصفحة السابقة.
يتم تخزين الملصقات الافتراضية لـ "First" و "Last" و "Prevent" و "..." و "Next" في I18N Yaml داخل المحرك ، ويتم تقديمها من خلال I18N API. يمكنك تبديل قيمة التسمية لكل i18n.locale لتطبيقك الدولي. المفاتيح والقيم الافتراضية هي ما يلي. يمكنك تجاوزها عن طريق إضافة ملف yaml في دليل Rails.root/config/locales .
en :
views :
pagination :
first : " « First "
last : " Last » "
previous : " ‹ Prev "
next : " Next › "
truncate : " … "
helpers :
page_entries_info :
one_page :
display_entries :
zero : " No %{entry_name} found "
one : " Displaying <b>1</b> %{entry_name} "
other : " Displaying <b>all %{count}</b> %{entry_name} "
more_pages :
display_entries : " Displaying %{entry_name} <b>%{first}–%{last}</b> of <b>%{total}</b> in total " إذا كنت تستخدم التعريب غير الإنجليزي ، راجع قواعد I18N لتغيير one_page:display_entries Block.
يشمل Kaminari مولد قالب مفيد.
قم بتشغيل المولد أولاً ،
% rails g kaminari:views default ثم قم بتحرير الجزأات في app/views/kaminari/ الدليل.
يمكنك استخدام GEM HTML2HAML أو HTML2Slim GEM لتحويل قوالب ERB. ستقوم GEM Kaminari تلقائيًا بالتقاط قوالب Haml/Slim إذا وضعتها في app/views/kaminari/ .
في حال كنت بحاجة إلى قوالب مختلفة لـ Paginator الخاص بك (على سبيل المثال العام والمشرف) ، يمكنك تمرير- --views-prefix directory مثل هذا:
% rails g kaminari:views default --views-prefix admin من شأنه أن يولد جزئيا في app/views/admin/kaminari/ الدليل.
يتمتع المولد بالقدرة على جلب العديد من سمات قالب عينة من المستودع الخارجي (https://github.com/amatsuda/kaminari_themes) بالإضافة إلى "الافتراضي" المجمعة ، مما سيساعدك على إنشاء عامل استثمار جميل المظهر.
% rails g kaminari:views THEME لمشاهدة القائمة الكاملة للمواضيع المتاحة ، ألقِ نظرة على مستودع المواضيع ، أو فقط ضرب المولد دون تحديد وسيطة THEME .
% rails g kaminari:viewsللاستفادة من سمات متعددة من داخل تطبيق واحد ، قم بإنشاء دليل داخل التطبيق/المشاهدات/kaminari/ونقل ملفات القالب المخصصة إلى هذا الدليل.
% rails g kaminari:views default (skip if you have existing kaminari views)
% cd app/views/kaminari
% mkdir my_custom_theme
% cp _ * .html. * my_custom_theme/ بعد ذلك ، الرجوع إلى هذا الدليل عند استدعاء طريقة paginate :
<%= paginate @users, theme: 'my_custom_theme' %> تخصيص بعيدا!
ملاحظة: إذا لم يكن السمة موجودًا أو لم يتم تحديد أي شيء ، فسيقوم Kaminari بالعودة إلى المشاهدات المدرجة في الأحجار الكريمة.
بشكل عام ، يحتاج Paginator إلى معرفة إجمالي عدد السجلات لعرض الروابط ، ولكن في بعض الأحيان لا نحتاج إلى إجمالي عدد السجلات ونحتاج فقط إلى روابط "الصفحة السابقة" و "الصفحة التالية". لمثل هذه الحالة الاستخدام ، يوفر Kaminari without_count وضع _count الذي ينشئ مجموعة قابلة للاتصال دون حساب عدد جميع السجلات. قد يكون هذا مفيدًا عندما تتعامل مع مجموعة بيانات كبيرة جدًا لأن الاعتماد على جدول كبير يميل إلى أن يصبح بطيئًا في RDBMS.
فقط أضف .without_count إلى كائنك المصقول:
User . page ( 3 ) . without_count في ملف العرض الخاص بك ، يمكنك فقط استخدام مساعدين بسيطين مثل ما يلي بدلاً من المساعد paginate الكامل:
<%= link_to_prev_page @users, 'Previous Page' %>
<%= link_to_next_page @users, 'Next Page' %> يوفر Kaminari فئة غلاف المصفوفة التي تتكيف مع كائن صفيف عام إلى المساعد في طريقة paginate . ومع ذلك ، لا يتعامل المساعد paginate تلقائيًا إلى كائن الصفيف الخاص بك (هذا مقصود وتصميم). Kaminari::paginate_array طريقة تحويل كائن الصفيف الخاص بك إلى صفيف قابل للاتصالات يقبل طريقة page .
@paginatable_array = Kaminari . paginate_array ( my_array_object ) . page ( params [ :page ] ) . per ( 10 ) يمكنك تحديد قيمة total_count من خلال تجزئة الخيارات. سيكون هذا مفيدًا عند التعامل مع كائن صفيف له قيمة count مختلفة من count الفعلي مثل نتيجة البحث RSOLR أو عندما تحتاج إلى إنشاء ترقيم تراجع مخصص. على سبيل المثال:
@paginatable_array = Kaminari . paginate_array ( [ ] , total_count : 145 ) . page ( params [ :page ] ) . per ( 10 )أو ، في حالة استخدام واجهة برمجة تطبيقات خارجي لمصدر صفحة البيانات:
page_size = 10
one_page = get_page_of_data params [ :page ] , page_size
@paginatable_array = Kaminari . paginate_array ( one_page . data , total_count : one_page . total_count ) . page ( params [ :page ] ) . per ( page_size ) بسبب معلمة page وتوجيه القضبان ، يمكنك بسهولة إنشاء عناوين URL سهلة الاستخدام. لأي مورد ترغب في تراجعه ، ما عليك سوى إضافة ما يلي إلى routes.rb :
resources :my_resources do
get 'page/:page' , action : :index , on : :collection
end إذا كنت تستخدم Rails 4 أو لاحقًا ، فيمكنك تبسيط تعريفات الطريق باستخدام concern :
concern :paginatable do
get '(page/:page)' , action : :index , on : :collection , as : ''
end
resources :my_resources , concerns : :paginatable سيؤدي ذلك إلى إنشاء عناوين URL مثل /my_resources/page/33 بدلاً من /my_resources?page=33 . هذا الآن عنوان URL ودود ، ولكن لديه أيضًا فوائد إضافية أخرى ...
لأن معلمة page أصبحت الآن شريحة عناوين URL ، يمكننا الاستفادة من التخزين المؤقت لصفحة القضبان!
ملاحظة: في هذا المثال ، أشرت إلى الطريق إلى :index الإجراء. ربما تكون قد حددت إجراء ترقيم تراجع مخصص في وحدة التحكم الخاصة بك - يجب عليك action: :your_custom_action بدلاً من ذلك.
من الناحية الفنية ، تتكون جوهرة kaminari من 3 مكونات فردية:
kaminari-core: the core pagination logic
kaminari-activerecord: Active Record adapter
kaminari-actionview: Action View adapter
لذلك ، فإن تجميع gem 'kaminari' تعادل الخطين التاليين (تتم الإشارة إلى Kaminari-Core من المحولات):
gem 'kaminari-activerecord'
gem 'kaminari-actionview'إذا كنت ترغب في استخدام ORMs المدعومة الأخرى بدلاً من ActivereCord ، على سبيل المثال ، قم بتجميع محولها بدلاً من kaminari-activereCord.
gem 'kaminari-mongoid'
gem 'kaminari-actionview'يوفر Kaminari حاليًا محولات لأرمز التالية:
إذا كنت ترغب في استخدام أطر الويب الأخرى بدلاً من عرض Rails + Action ، على سبيل المثال Sinatra ، قم بتجميع محولها بدلاً من Caminari-mateview.
gem 'kaminari-activerecord'
gem 'kaminari-sinatra'يوفر Kaminari حاليًا محولات لأطر الويب التالية:
تحقق من وصفات Kaminari على Github Wiki للحصول على المزيد من النصائح والتقنيات المتقدمة. https://github.com/kaminari/Kaminari/Wiki/Kaminari-Recipes
لا تتردد في مراسلتي على Github (Amatsuda) أو Twitter (A_Matsuda) ☇☇☇ :)
شوكة ، إصلاح ، ثم أرسل طلب سحب.
لتشغيل جناح الاختبار محليًا مقابل جميع الأطر المدعومة:
% bundle install
% rake test:allلاستهداف جناح الاختبار مقابل إطار عمل واحد:
% rake test:active_record_50 يمكنك العثور على قائمة بمهام الاختبار المدعومة عن طريق تشغيل rake -T . قد تجد أيضًا أنه من المفيد إجراء اختبار محدد لإطار عمل محدد. للقيام بذلك ، سيتعين عليك أولاً التأكد من أنك قد جمعت كل شيء لهذا التكوين ، ثم يمكنك إجراء اختبار محدد:
% BUNDLE_GEMFILE= ' gemfiles/active_record_50.gemfile ' bundle install
% BUNDLE_GEMFILE= ' gemfiles/active_record_50.gemfile ' TEST=kaminari-core/test/requests/navigation_test.rb bundle exec rake test حقوق الطبع والنشر (ج) 2011- أكيرا ماتسودا. انظر معهد ماساتشوستس للتكنولوجيا الترخيص لمزيد من التفاصيل.
