Features ar

English · 简体中文 · 繁體中文 · Español · العربية · Français · Português (Brasil) · Deutsch · हिन्दी · 日本語 · 한국어 · Русский · Bahasa Indonesia · Türkçe · Italiano · Tiếng Việt

ميزات docxi: الفقرات والنصوص والجداول والصور ورؤوس الصفحات وتذييلاتها

تسرد هذه الصفحة كل عنصر يمكن لمكتبة docxi إضافته إلى مستند Word، والخيارات التي يقبلها كل عنصر. تعتمد الأمثلة على الإعداد التالي:

require "docxi"

word = Docxi::Document.new
document = word.document

يمكنك حذف الخيارات التي لا تحتاج إليها. الألوان قيم ست عشرية دون #، مثل "8B0000". للاطلاع على الوحدات وإعداد الصفحة، راجع الإعدادات.

الفقرات

يضيف document.p(options) { |p| ... } فقرة.

الخيار	القيم	التأثير
align	"left" و"center" و"right" و"both"	المحاذاة. القيمة "both" تضبط النص من الجانبين
fill	لون ست عشري	تظليل خلف الفقرة ونصها
left وright	جزء من عشرين من النقطة	المسافة البادئة. اضبط الاثنين معًا، لأن ضبط أحدهما وحده يُتجاهل
ul	true	يجعل الفقرة عنصرًا في قائمة نقطية
bottom	true	يرسم حدًا أسفل الفقرة

يمكن أيضًا تمرير خيارات النص مثل size: أو bold: أو color: إلى p، فتصبح القيم الافتراضية لكل مقطع نصي في الفقرة.

داخل الكتلة يمكنك استدعاء text وbr وtab وimage وhyperlink وframe. والدالة document.text(string, options) اختصار لفقرة تحتوي على مقطع واحد.

document.p(align: "both", left: 720, right: 720) do |p|
  p.text "An indented, justified paragraph."
end

document.p(ul: true) { |p| p.text "A bullet item" }
document.text "A one-line paragraph", size: 14, bold: true

النص

يضيف p.text(string, options) مقطعًا نصيًا (run).

الخيار	القيم	التأثير
bold	true	غامق
italic	true	مائل
underline	true	تسطير مفرد
color	لون ست عشري	لون النص
size	نقاط	حجم الخط
font	اسم الخط	الخط، مثل "Georgia"
fill	لون ست عشري	تظليل خلف النص
space	true	يحافظ على المسافات في بداية النص ونهايته
br	true	يضيف فاصل أسطر بعد النص

تُتجاهل السلسلة النصية nil.

document.p do |p|
  p.text "Total: ", bold: true, space: true
  p.text "$1,200", color: "007A33", font: "Georgia", size: 14
end

فواصل الأسطر وفواصل الصفحات وعلامات الجدولة

• يضيف p.br أو p.br(times: 3) فواصل أسطر داخل الفقرة.
• يبدأ document.br(page: true) صفحة جديدة.
• يضيف p.tab أو p.tab(times: 2) علامات جدولة داخل الفقرة.
• يضيف document.tab(page: true) فقرة تحتوي على علامة جدولة واحدة.

لا تستدعِ document.br أو document.tab دون page: true، فهما تضعان مقطعًا نصيًا مباشرة في متن المستند، وهذا ليس WordprocessingML صالحًا.

document.p do |p|
  p.text "Name:", br: true
  p.tab
  p.text "Signature line"
  p.br(times: 2)
end

document.br(page: true)

الجداول

تقبل document.table(options) كتلة، وداخلها تضيف table.tr(options) الصفوف وتضيف tr.tc(options) الخلايا.

خيارات الجدول

الخيار	القيم	التأثير
columns_width	مصفوفة أرقام	عرض الأعمدة، مضروبًا في 14.92 لتحويله إلى أجزاء من عشرين من النقطة. وهو أيضًا العرض الافتراضي للخلايا
height	جزء من عشرين من النقطة	الحد الأدنى لارتفاع كل صف
iwidth	جزء من عشرين من النقطة	إزاحة الجدول عن الهامش الأيسر
style	معرّف النمط	نمط الجدول. تعرّف docxi النمطين TableNormal وTableCustom
width	رقم	العرض المفضّل للجدول، ويُكتب بالنوع auto. ومن دون columns_width تحصل كل خلية أيضًا على هذا العرض مضروبًا في 14.92
align	"left" و"center" و"right"	محاذاة الجدول. ويُحاذى النص المضاف باستخدام tc.text بالطريقة نفسها
padding	true	يضيف حشوة ثابتة داخل الخلايا
borders	قاموس (Hash)	مشكلة معروفة: يُطبَّق على كل خلية بدلًا من الحواف الخارجية للجدول

خيارات الصف: يضبط height: الحد الأدنى لارتفاع الصف. وأي خيار خلية يُمرَّر إلى tr ينطبق على كل خلايا الصف. وتُمرَّر خيارات الجدول بالطريقة نفسها إلى كل صف وكل خلية.

خيارات الخلية

الخيار	القيم	التأثير
borders	{ top:, right:, bottom:, left: }	عرض الحد بوحدة ثُمن النقطة. القيمة nil تعني عدم وجود حد في ذلك الجانب
fill	لون ست عشري	تظليل الخلية. الخلايا التي لا تعبئة لها بيضاء ("FFFFFF")
valign	"top" و"center" و"bottom"	المحاذاة العمودية
colspan	عدد صحيح	عدد الأعمدة التي تمتد عليها الخلية
rowspan	true	يبدأ دمجًا عموديًا
merged	true	يكمل الدمج العمودي من الخلية التي فوقها، ويُتجاهل محتواها
width	رقم	عرض الخلية، مضروبًا في 14.92

محتوى الخلية

• الدالة tc.text(string, options): تنطبق خيارات الخلية والصف، مثل bold: أو align:، على النص أيضًا.
• الدالة tc.p(options) { |p| ... }: فقرة بخياراتها الخاصة فقط.
• الدالة tc.image(media, width:, height:): صورة. راجع مشكلة الحجم في قسم الصور.
• الدالة tc.page_numbers: حقل رقم الصفحة. مشكلة معروفة: يسبقه النص «GlobalOptions».

document.table(columns_width: [150, 150]) do |table|
  table.tr do |tr|
    tr.tc(rowspan: true, valign: "center", borders: { top: 4, right: 4, bottom: 4, left: 4 }) do |tc|
      tc.text "Spans two rows"
    end
    tr.tc { |tc| tc.text "Row 1" }
  end
  table.tr do |tr|
    tr.tc(merged: true)
    tr.tc { |tc| tc.text "Row 2" }
  end
end

الصور

تسجّل media = document.add_media(source) صورة. يمكن أن يكون source:

• كائن IO، مثل File أو StringIO
• مسار ملف
• عنوان URL من نوع http أو https أو ftp

تُقرأ الصورة عند استدعاء render، وتُخزَّن دائمًا كجزء PNG، لذا فملفات PNG هي الخيار الآمن.

الصور المضمّنة: تضع p.image(media, options) الصورة في سطر النص.

الخيار	القيم	التأثير
style	قاموس بخصائص CSS	الحجم، مثل { width: "120pt", height: "60pt" }
title	سلسلة نصية	عنوان الصورة
fill_color	لون VML مثل "#00FF00"	تعبئة خلف الصورة
opacity	سلسلة نصية مثل "50%"	عتامة التعبئة
wrap	true	يوقف التفاف النص حول الصورة

logo = document.add_media(File.open("logo.png", "rb"))
document.p(align: "center") { |p| p.image logo, style: { width: "120pt", height: "60pt" } }

الصور المحددة الموضع: تثبّت p.image(media, pH:, pV:, wrap: true, width:, height:) الصورة على إزاحة من العمود (pH) ومن الفقرة (pV)، بوحدة EMU. يجب تمرير pH وpV وwrap جميعًا، وإلا وُضعت الصورة مضمّنة في السطر.

صور رأس الصفحة: h.image(media, align:, width:, height:, pH:, pV:, behind:, wrap:). القيمة wrap: "none" توقف الالتفاف، وأي قيمة أخرى تجعل النص يلتف حول الصورة بشكل مربع.

مشكلة معروفة في الإصدار 0.1.0: تحسب الصور المحددة الموضع وصور رؤوس الصفحات وصور خلايا الجداول عرضها وارتفاعها كليهما على أنه width * height * 14.92 EMU، لذلك تظهر دائمًا مربعة وصغيرة جدًا في الغالب. أما الصور المضمّنة التي يُضبط حجمها عبر style: فلا تتأثر. راجع أفضل الممارسات للاطلاع على حل بديل.

رؤوس الصفحات وتذييلاتها

header = Docxi::Word::Headers::Header.new do |h|
  h.text "Quarterly report", size: 9, align: "right"
end

footer = Docxi::Word::Footers::Footer.new do |f|
  f.page_numbers name: "Page", align: "center"
end

document.add_header(header)
document.add_footer(footer)
document.add_first_header(Docxi::Word::Headers::Header.new { |h| h.text "Cover page" })

• يمكن أن يحتوي رأس الصفحة على text وbr وtable وimage وpage_numbers، ويمكن أن يحتوي التذييل على text وbr وtable وpage_numbers.
• الخيارات المُمرَّرة إلى Header.new أو Footer.new تنطبق على نصوصها.
• يغطي add_header وadd_footer الصفحات من 2 فصاعدًا، أما الصفحة 1 فتستخدم دائمًا add_first_header وadd_first_footer. راجع الإعدادات.

أرقام الصفحات

تكتب page_numbers(name: "Page", align: "center") نص name يليه حقل PAGE. يظهر الرقم بخط Arial بحجم 10 نقاط وبلون رمادي داكن. القيمة الافتراضية لـ align هي "right".

مشكلة معروفة: يُكتب رمز الحقل دون الشرطة المائلة العكسية في \* MERGEFORMAT.

جدول المحتويات

document.table_of_content do |toc|
  toc.add_row "Introduction", 1
  toc.add_row "Appendix", 7, leader: "hyphen", pos: 8000
  toc.add_row "Notes"
end

• التوقيع: add_row(text, page = nil, leader: "dot", pos: 9360).
• عند تمرير رقم صفحة، يحصل السطر على علامة جدولة بمحاذاة إلى اليمين عند pos (بوحدة جزء من عشرين من النقطة، و9360 تساوي 6.5 بوصة) تُملأ بحرف leader. قيم حرف التعبئة مأخوذة من WordprocessingML، مثل "dot" و"hyphen" و"underscore" و"middleDot" و"none".
• من دون رقم صفحة، يكون السطر هو النص بعد علامة جدولة.
• أرقام الصفحات هي الأرقام التي تمررها. لا تنشئ docxi حقل TOC في Word ولا تحسب الصفحات.

الارتباطات التشعبية

url = "https://github.com/hammad417/docxi"
link = document.add_hyperlink(url)
document.p { |p| p.hyperlink "docxi on GitHub", url, link }

تعيد add_hyperlink(url) معرّف علاقة، وتضع hyperlink(text, url, id) الارتباط. يأتي الهدف من العلاقة، لذا مرّر المعرّف المُعاد لعنوان URL الذي تريده. الارتباطات الخارجية فقط مدعومة.

الإطارات (مربعات النص)

document.p do |p|
  p.frame(style: "width:200pt;height:40pt") do |f|
    f.text "Text inside a box"
  end
end

document.frame "A box with one line", style: "width:200pt;height:30pt"

• الإطارات مربعات نص VML بتعبئة رمادية فاتحة شبه شفافة ثابتة وحدّ خارجي أسود. يلتف النص فوقها وتحتها.
• داخل الإطار يمكنك استدعاء text وbr وtab وimage وframe.
• يضيف spacing: true مسافة قبل النص.

المخرجات

تعيد word.render كائن StringIO يحتوي على حزمة .docx كاملة. يُكتب الأرشيف دون سجلات Zip64، لذا يمكن لـ Google Docs وإصدارات LibreOffice القديمة فتحه. تسرد صفحة البنية كل أجزاء الحزمة.

صفحات ذات صلة

• أمثلة الاستخدام
• مرجع API
• خارطة الطريق للاطلاع على المشكلات المعروفة المخطط إصلاحها في الإصدار 0.2.0

---

→ الصفحة الرئيسية للويكي · README