_Filtering for Presidents_

تتضمن مجموعة البيانات آرون بور، وهو نائب رئيس لم يكن رئيساً قط!

`Array#filter` ينشئ مصفوفة جديدة تحتوي على الصفوف المطلوبة. الرئيس هو من خدم
فترة واحدة على الأقل مع ضبط `type` على `"prez"`. لاختبار ما إذا كان صف معين يحتوي على
فترة `"prez"` واحدة على الأقل، فإن `Array#some` هي دالة JavaScript أصلية أخرى. سيكون
الفلتر الكامل كما يلي:```js
const prez = raw_data.filter(row => row.terms.some(term => term.type === "prez"));

النتيجة هي مصفوفة من كائنات "بسيطة" بدون تداخل:```js
[
  { name: "George Washington", birthday: "1732-02-22" },
  { name: "John Adams", birthday: "1735-10-19" },
  // ... one row per President
]

`XLSX.utils.book_new` ينشئ مصنفًا جديدًا و `XLSX.utils.book_append_sheet`
يُرفق ورقة عمل بالمصنف. ستُسمى ورقة العمل الجديدة "Dates":```js
const workbook = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(workbook, worksheet, "Dates");

_ضبط عرض الأعمدة_

بعض الأسماء أطول من عرض العمود الافتراضي.  تُعيَّن عروض الأعمدة
عبر [تعيين خاصية ورقة العمل `"!cols"`](#row-and-column-properties).

يحدد السطر التالي عرض العمود A إلى حوالي 10 أحرف:```js
worksheet["!cols"] = [ { wch: 10 } ]; // set column A width to 10 characters

ملاحظة: إذا كانت نقطة البداية ملفًا أو جدول HTML، فإن `XLSX.utils.sheet_to_json`
سينشئ مصفوفة من كائنات JS.

**بيانات الحزمة والإصدار**

`XLSX.writeFile` ينشئ ملف جدول بيانات ويحاول كتابته إلى النظام.
في المتصفح، سيحاول مطالبة المستخدم بتنزيل الملف. في NodeJS،
سيكتب إلى الدليل المحلي.```js
XLSX.writeFile(workbook, "Presidents.xlsx");

لاستخدامها في متصفح الويب، بافتراض حفظ المقتطف في `snippet.js`،
يجب استخدام وسوم السكربت لتضمين الإصدارات المستقلة من `axios` و`xlsx`:```html
<script src="https://unpkg.com/xlsx/dist/xlsx.full.min.js"></script>
<script src="https://unpkg.com/axios/dist/axios.min.js"></script>
<script src="snippet.js"></script>

بالنسبة إلى Node ESM، المساعد `readFile` غير مفعّل. بدلاً من ذلك، يجب استخدام `fs.readFileSync` لقراءة بيانات الملف كـ `Buffer` لاستخدامها مع `XLSX.read`:```js
import { readFileSync } from "fs";
import { read } from "xlsx/xlsx.mjs";

const buf = readFileSync("test.xlsx");
/* buf is a Buffer */
const workbook = read(buf);

يجب استدعاء التطبيقات التي تقرأ الملفات باستخدام علامة `--allow-read`. يحتوي
[`deno` demo](https://github.com/weareu/xlsx/blob/HEAD/demos/deno/) على مزيد من الأمثلة

</details>

<details>
  <summary><b>ملف مقدَّم من المستخدم في صفحة ويب ("سحب وإفلات")</b> (انقر للعرض)</summary>

بالنسبة للمواقع الحديثة التي تستهدف Chrome 76+، يُنصح باستخدام `File#arrayBuffer`:```js
// XLSX is a global from the standalone script

async function handleDropAsync(e) {
  e.stopPropagation(); e.preventDefault();
  const f = e.dataTransfer.files[0];
  /* f is a File */
  const data = await f.arrayBuffer();
  /* data is an ArrayBuffer */
  const workbook = XLSX.read(data);

  /* DO SOMETHING WITH workbook HERE */
}
drop_dom_element.addEventListener("drop", handleDropAsync, false);

/* DO SOMETHING WITH workbook HERE */

<https://oss.sheetjs.com/sheetjs/> يعرض تقنية FileReader.

</details>

<details>
  <summary><b>ملف مقدَّم من المستخدم مع عنصر INPUT في HTML</b> (انقر للإظهار)</summary>

بدءًا من عنصر HTML INPUT مع `type="file"`:```html
<input type="file" id="input_dom_element">

لدعم أوسع (بما في ذلك IE10+)، يُنصح باستخدام نهج `FileReader`:```js
function handleFile(e) {
  var file = e.target.files[0];
  var reader = new FileReader();
  reader.onload = function(e) {
    var data = e.target.result;
    /* reader.readAsArrayBuffer(file) -> data will be an ArrayBuffer */
    var workbook = XLSX.read(e.target.result);

    /* DO SOMETHING WITH workbook HERE */
  };
  reader.readAsArrayBuffer(file);
}
input_dom_element.addEventListener("change", handleFile, false);

للحصول على دعم أوسع، يُوصى باستخدام نهج `XMLHttpRequest`:```js
var url = "http://oss.sheetjs.com/test_files/formula_stress_test.xlsx";

/* set up async GET request */
var req = new XMLHttpRequest();
req.open("GET", url, true);
req.responseType = "arraybuffer";

req.onload = function(e) {
  var workbook = XLSX.read(req.response);

  /* DO SOMETHING WITH workbook HERE */
};

req.send();

يتضمن [`extendscript` التجريبي](https://github.com/weareu/xlsx/blob/HEAD/demos/extendscript/) مثالاً أكثر تعقيدًا.

</details>

<details>
  <summary><b>ملف محلي في تطبيق Electron</b> (انقر للعرض)</summary>

يمكن استخدام `readFile` في عملية العارض:```js
/* From the renderer process */
var XLSX = require("xlsx");

var workbook = XLSX.readFile(path);

- [`react-native-fs`](https://npm.im/react-native-fs)

ترميز `ascii` يُرجع سلاسل ثنائية متوافقة مع نوع `binary`:```js
import XLSX from "xlsx";
import { readFile } from "react-native-fs";

const bstr = await readFile(path, "ascii");
/* bstr is a binary string */
const workbook = XLSX.read(bstr, {type: "binary"});

/* DO SOMETHING WITH workbook HERE */

يحتوي العرض التجريبي [`server`](https://github.com/weareu/xlsx/blob/HEAD/demos/server) على أمثلة أكثر تقدمًا.

</details>

<details>
  <summary><b>تنزيل الملفات في عملية NodeJS</b> (انقر للإظهار)</summary>

يوفر Node 17.5 و18.0 دعمًا أصليًا لـ fetch:```js
const XLSX = require("xlsx");

const data = await (await fetch(url)).arrayBuffer();
/* data is an ArrayBuffer */
const workbook = XLSX.read(data);

[`axios`](https://npm.im/axios) يعمل بنفس الطريقة في المتصفح وفي NodeJS:```js
const XLSX = require("xlsx");
const axios = require("axios");

(async() => {
  const res = await axios.get(url, {responseType: "arraybuffer"});
  /* res.data is a Buffer */
  const workbook = XLSX.read(res.data);

  /* DO SOMETHING WITH workbook HERE */
})();

const XLSX = require("xlsx");
const { net } = require("electron");

const req = net.request(url);
req.on("response", (res) => {
  const bufs = []; // this array will collect all of the buffers
  res.on("data", (chunk) => { bufs.push(chunk); });
  res.on("end", () => {
    const workbook = XLSX.read(Buffer.concat(bufs));

    /* DO SOMETHING WITH workbook HERE */
  });
});
req.end();
```
</details>

<details>
  <summary><b>التدفقات القابلة للقراءة في NodeJS</b> (انقر للعرض)</summary>

عند التعامل مع التدفقات القابلة للقراءة، فإن أبسط نهج هو تخزين التدفق مؤقتًا
ومعالجة المحتوى بالكامل في النهاية:```js
var fs = require("fs");
var XLSX = require("xlsx");

function process_RS(stream, cb) {
  var buffers = [];
  stream.on("data", function(data) { buffers.push(data); });
  stream.on("end", function() {
    var buffer = Buffer.concat(buffers);
    var workbook = XLSX.read(buffer, {type:"buffer"});

    /* DO SOMETHING WITH workbook IN THE CALLBACK */
    cb(workbook);
  });
}
```
</details>

<details>
  <summary><b>ReadableStream في المتصفح</b> (انقر للعرض)</summary>

عند التعامل مع `ReadableStream`، فإن الطريقة الأسهل هي تخزين الدفق في مخزن مؤقت
ومعالجة المحتوى كاملاً في النهاية:```js
// XLSX is a global from the standalone script

async function process_RS(stream) {
  /* collect data */
  const buffers = [];
  const reader = stream.getReader();
  for(;;) {
    const res = await reader.read();
    if(res.value) buffers.push(res.value);
    if(res.done) break;
  }

  /* concat */
  const out = new Uint8Array(buffers.reduce((acc, v) => acc + v.length, 0));

  let off = 0;
  for(const u8 of arr) {
    out.set(u8, off);
    off += u8.length;
  }

  return out;
}

const data = await process_RS(stream);
/* data is Uint8Array */
const workbook = XLSX.read(data);
```
</details>

تتم تغطية أمثلة أكثر تفصيلاً في [العروض التوضيحية المضمنة](https://github.com/weareu/xlsx/blob/HEAD/demos/)

### معالجة بيانات JSON وJS

تميل بيانات JSON وJS إلى تمثيل أوراق عمل مفردة. سيستخدم هذا القسم بعض الدوال المساعدة لإنشاء مصنفات.

_إنشاء مصنف جديد_```js
var workbook = XLSX.utils.book_new();
```
دالة الأداة المساعدة `book_new` تنشئ مصنفًا فارغًا بدون أي أوراق عمل.

تتطلب برامج جداول البيانات عمومًا ورقة عمل واحدة على الأقل وتفرض
المتطلب في واجهة المستخدم.  تفرض هذه المكتبة المتطلب في وقت الكتابة،
وتطرح أخطاءً إذا تم تمرير مصنف فارغ إلى دوال الكتابة.

**API**

_إنشاء ورقة عمل من مصفوفة من مصفوفات قيم JS_```js
var worksheet = XLSX.utils.aoa_to_sheet(aoa, opts);
```
تتجول دالة الأداة المساعدة `aoa_to_sheet` عبر "مصفوفة من المصفوفات" بترتيب الصفوف الرئيسي،
مُنشئةً كائن ورقة عمل.  يُنشئ المقتطف التالي ورقة
تحتوي على الخلية `A1` مضبوطة على السلسلة `A1`، والخلية `B1` مضبوطة على `B1`، وهكذا:```js
var worksheet = XLSX.utils.aoa_to_sheet([
  ["A1", "B1", "C1"],
  ["A2", "B2", "C2"],
  ["A3", "B3", "C3"]
]);
```
["مدخل مصفوفة من المصفوفات"](#array-of-arrays-input) يصف الدالة والوسيطة
الاختيارية `opts` بمزيد من التفصيل.


_إنشاء ورقة عمل من مصفوفة كائنات JS_```js
var worksheet = XLSX.utils.json_to_sheet(jsa, opts);
```
تقوم الدالة المساعدة `json_to_sheet` بالمرور على مصفوفة من كائنات JS بالترتيب،
مولّدةً كائن ورقة عمل. افتراضيًا، ستنشئ صفًا للترويسة
وصفًا واحدًا لكل كائن في المصفوفة. تحتوي الوسيطة الاختيارية `opts` على إعدادات
للتحكم في ترتيب الأعمدة ومخرجات الترويسة.

["مدخل مصفوفة الكائنات"](#array-of-arrays-input) يصف الدالة و
الوسيطة الاختيارية `opts` بمزيد من التفصيل.

**أمثلة**

["فلسفة SheetJS"](#the-zen-of-sheetjs) يحتوي مثالًا تفصيليًا "الحصول على البيانات
من نقطة نهاية JSON وإنشاء مصنف"

[`x-spreadsheet`](https://github.com/myliang/x-spreadsheet) هي شبكة بيانات تفاعلية
لمعاينة وتعديل البيانات المنظمة في متصفح الويب. يتضمن
[`xspreadsheet` عرض تجريبي](https://github.com/weareu/xlsx/blob/HEAD/demos/xspreadsheet) نصًا برمجيًا نموذجيًا مع
دالة `xtos` للتحويل من كائن بيانات x-spreadsheet إلى مصنف.
<https://oss.sheetjs.com/sheetjs/x-spreadsheet> هو عرض تجريبي مباشر.

<details>
  <summary><b>سجلات من استعلام قاعدة بيانات (SQL أو no-SQL)</b> (انقر للإظهار)</summary>

يتضمن [`database` عرض تجريبي](https://github.com/weareu/xlsx/blob/HEAD/demos/database/) أمثلة على التعامل مع
قواعد البيانات ونتائج الاستعلام.

</details>


<details>
  <summary><b>الحسابات العددية باستخدام TensorFlow.js</b> (انقر للإظهار)</summary>

تتوقع [`@tensorflow/tfjs`](https://github.com/weareu/xlsx/blob/HEAD/@tensorflow/tfjs) والمكتبات الأخرى البيانات في صورة مصفوفات
بسيطة، وهي مناسبة تمامًا لأوراق العمل حيث يمثل كل عمود متجه بيانات. وهذا هو
تبديل طريقة استخدام معظم الناس لجداول البيانات، حيث يمثل كل صف متجهًا.

عند استعادة البيانات من `tfjs`، تُخزَّن نقاط البيانات المُرجَعة في مصفوفة
مُنمّطة. ويمكن إنشاء مصفوفة من المصفوفات باستخدام الحلقات. يمكن لـ `Array#unshift` إضافة
صف عنوان قبل التحويل:```js
const XLSX = require("xlsx");
const tf = require('@tensorflow/tfjs');

/* suppose xs and ys are vectors (1D tensors) -> tfarr will be a typed array */
const tfdata = tf.stack([xs, ys]).transpose();
const shape = tfdata.shape;
const tfarr = tfdata.dataSync();

/* construct the array of arrays */
const aoa = [];
for(let j = 0; j < shape[0]; ++j) {
  aoa[j] = [];
  for(let i = 0; i < shape[1]; ++i) aoa[j][i] = tfarr[j * shape[1] + i];
}
/* add headers to the top */
aoa.unshift(["x", "y"]);

/* generate worksheet */
const worksheet = XLSX.utils.aoa_to_sheet(aoa);
```
The [`array` demo](https://github.com/weareu/xlsx/blob/HEAD/demos/array/) يوضح مثالًا كاملًا.

</details>


### معالجة جداول HTML

**API**

_إنشاء ورقة عمل عن طريق استخراج جدول HTML من الصفحة_```js
var worksheet = XLSX.utils.table_to_sheet(dom_element, opts);
```
تأخذ الدالة المساعدة `table_to_sheet` عنصر DOM TABLE وتكرر عبر الصفوف لإنشاء ورقة عمل. وسيطة `opts` اختيارية.
[إدخال جدول HTML](#html-table-input) يصف الدالة بمزيد من التفصيل.



_أنشئ مصنفًا عن طريق استخراج جدول HTML من الصفحة_```js
var workbook = XLSX.utils.table_to_book(dom_element, opts);
```
دالة `table_to_book` تتبع نفس منطق `table_to_sheet`.
بعد إنشاء ورقة عمل، تنشئ مصنفًا فارغًا وتُضيف
جدول البيانات.

تدعم وسيطة الخيارات نفس الخيارات المدعومة في `table_to_sheet`، مع
إضافة خاصية `sheet` للتحكم في اسم ورقة العمل. إذا كانت الخاصية
مفقودة أو لم يتم تحديد أي خيارات، يُستخدم الاسم الافتراضي `Sheet1`.

**أمثلة**

فيما يلي بعض السيناريوهات الشائعة (انقر على كل عنوان فرعي لرؤية الكود):

<details>
  <summary><b>عنصر HTML TABLE في صفحة ويب</b> (انقر للعرض)</summary>```html
<!-- include the standalone script and shim.  this uses the UNPKG CDN -->
<script src="https://unpkg.com/xlsx/dist/shim.min.js"></script>
<script src="https://unpkg.com/xlsx/dist/xlsx.full.min.js"></script>

<!-- example table with id attribute -->
<table id="tableau">
  <tr><td>Sheet</td><td>JS</td></tr>
  <tr><td>12345</td><td>67</td></tr>
</table>

<!-- this block should appear after the table HTML and the standalone script -->
<script type="text/javascript">
  var workbook = XLSX.utils.table_to_book(document.getElementById("tableau"));

  /* DO SOMETHING WITH workbook HERE */
</script>
```
يمكن تحويل الجداول المتعددة في صفحة ويب إلى أوراق عمل فردية:```js
/* create new workbook */
var workbook = XLSX.utils.book_new();

/* convert table "table1" to worksheet named "Sheet1" */
var sheet1 = XLSX.utils.table_to_sheet(document.getElementById("table1"));
XLSX.utils.book_append_sheet(workbook, sheet1, "Sheet1");

/* convert table "table2" to worksheet named "Sheet2" */
var sheet2 = XLSX.utils.table_to_sheet(document.getElementById("table2"));
XLSX.utils.book_append_sheet(workbook, sheet2, "Sheet2");

/* workbook now has 2 worksheets */
```
بدلاً من ذلك، يمكن استخراج كود HTML وتحليله:```js
var htmlstr = document.getElementById("tableau").outerHTML;
var workbook = XLSX.read(htmlstr, {type:"string"});
```
</details>

<details>
  <summary><b>امتداد Chrome/Chromium</b> (اضغط للعرض)</summary>

يُظهر [`chrome` demo](https://github.com/weareu/xlsx/blob/HEAD/demos/chrome/) مثالًا كاملًا ويوضّح الأذونات المطلوبة
والإعدادات الأخرى.

في الامتداد، يُنصح بإنشاء المصنف (workbook) في سكربت المحتوى (content script)
ثم تمرير الكائن مرة أخرى إلى الامتداد:```js
/* in the worker script */
chrome.runtime.onMessage.addListener(function(msg, sender, cb) {
  /* pass a message like { sheetjs: true } from the extension to scrape */
  if(!msg || !msg.sheetjs) return;
  /* create a new workbook */
  var workbook = XLSX.utils.book_new();
  /* loop through each table element */
  var tables = document.getElementsByTagName("table")
  for(var i = 0; i < tables.length; ++i) {
    var worksheet = XLSX.utils.table_to_sheet(tables[i]);
    XLSX.utils.book_append_sheet(workbook, worksheet, "Table" + i);
  }
  /* pass back to the extension */
  return cb(workbook);
});
```
</details>

<details>
  <summary><b>جداول HTML من جانب الخادم باستخدام Headless Chrome</b> (انقر للعرض)</summary>

يتضمن [العرض التجريبي `headless`](https://github.com/weareu/xlsx/blob/HEAD/demos/headless/) عرضًا توضيحيًا كاملًا لتحويل
ملفات HTML إلى مصنفات XLSB.  الفكرة الأساسية هي إضافة السكربت إلى الصفحة، وتحليل
الجدول في سياق الصفحة، وإنشاء مصنف `base64` وإرساله مرة أخرى
لمزيد من المعالجة:```js
const XLSX = require("xlsx");
const { readFileSync } = require("fs"), puppeteer = require("puppeteer");

const url = `https://sheetjs.com/demos/table`;

/* get the standalone build source (node_modules/xlsx/dist/xlsx.full.min.js) */
const lib = readFileSync(require.resolve("xlsx/dist/xlsx.full.min.js"), "utf8");

(async() => {
  /* start browser and go to web page */
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto(url, {waitUntil: "networkidle2"});

  /* inject library */
  await page.addScriptTag({content: lib});

  /* this function `s5s` will be called by the script below, receiving the Base64-encoded file */
  await page.exposeFunction("s5s", async(b64) => {
    const workbook = XLSX.read(b64, {type: "base64" });

    /* DO SOMETHING WITH workbook HERE */
  });

  /* generate XLSB file in webpage context and send back result */
  await page.addScriptTag({content: `
    /* call table_to_book on first table */
    var workbook = XLSX.utils.table_to_book(document.querySelector("TABLE"));

    /* generate XLSX file */
    var b64 = XLSX.write(workbook, {type: "base64", bookType: "xlsb"});

    /* call "s5s" hook exposed from the node process */
    window.s5s(b64);
  `});

  /* cleanup */
  await browser.close();
})();
```
</details>

<details>
  <summary><b>جداول HTML من جهة الخادم مع WebKit بدون واجهة رسومية</b> (انقر للعرض)</summary>

يتضمن [`headless` عرض تجريبي](https://github.com/weareu/xlsx/blob/HEAD/demos/headless/) عرضًا تجريبيًا كاملًا لتحويل ملفات
HTML إلى كتب عمل XLSB باستخدام [PhantomJS](https://phantomjs.org/). الفكرة الأساسية
هي إضافة السكربت إلى الصفحة، وتحليل الجدول في سياق الصفحة، وإنشاء
كتاب عمل `binary` وإرساله مرة أخرى لمزيد من المعالجة:```js
var XLSX = require('xlsx');
var page = require('webpage').create();

/* this code will be run in the page */
var code = [ "function(){",
  /* call table_to_book on first table */
  "var wb = XLSX.utils.table_to_book(document.body.getElementsByTagName('table')[0]);",

  /* generate XLSB file and return binary string */
  "return XLSX.write(wb, {type: 'binary', bookType: 'xlsb'});",
"}" ].join("");

page.open('https://sheetjs.com/demos/table', function() {
  /* Load the browser script from the UNPKG CDN */
  page.includeJs("https://unpkg.com/xlsx/dist/xlsx.full.min.js", function() {
    /* The code will return an XLSB file encoded as binary string */
    var bin = page.evaluateJavaScript(code);

    var workbook = XLSX.read(bin, {type: "binary"});
    /* DO SOMETHING WITH workbook HERE */

    phantom.exit();
  });
});
```
</details>

<details>
  <summary><b>جداول HTML في NodeJS دون متصفح</b> (اضغط للعرض)</summary>

لا تتضمن NodeJS تطبيقًا لـ DOM، ويتطلب Puppeteer بناء Chromium ضخمًا.  [`jsdom`](https://npm.im/jsdom) بديل خفيف:```js
const XLSX = require("xlsx");
const { readFileSync } = require("fs");
const { JSDOM } = require("jsdom");

/* obtain HTML string.  This example reads from test.html */
const html_str = fs.readFileSync("test.html", "utf8");
/* get first TABLE element */
const doc = new JSDOM(html_str).window.document.querySelector("table");
/* generate workbook */
const workbook = XLSX.utils.table_to_book(doc);
```
</details>

## معالجة البيانات

["تنسيق جدول البيانات الشائع"](#common-spreadsheet-format) هو تمثيل كائن بسيط
للمفاهيم الأساسية للمصنف. تعمل الدوال المساعدة
مع تمثيل الكائن وهي مصممة للتعامل مع حالات الاستخدام الشائعة.

### تعديل بنية المصنف

**API**

_إلحاق ورقة عمل بمصنف_```js
XLSX.utils.book_append_sheet(workbook, worksheet, sheet_name);
```
تُلحق الدالة المساعدة `book_append_sheet` ورقة عمل بالمصنف.
تحدد الوسيطة الثالثة اسم ورقة العمل المطلوب. يمكن إضافة عدة أوراق عمل إلى مصنف عبر استدعاء الدالة عدة مرات. إذا كان اسم ورقة العمل مستخدمًا بالفعل في المصنف، فستطرح الدالة خطأً.

_إلحاق ورقة عمل بمصنف وإيجاد اسم فريد_```js
var new_name = XLSX.utils.book_append_sheet(workbook, worksheet, name, true);
```
إذا كانت الوسيطة الرابعة `true`، ستبدأ الدالة باسم ورقة العمل المحدد. إذا كان اسم الورقة موجودًا في المصنف، فسيتم اختيار اسم ورقة عمل جديد من خلال العثور على جذع الاسم وزيادة العداد:```js
XLSX.utils.book_append_sheet(workbook, sheetA, "Sheet2", true); // Sheet2
XLSX.utils.book_append_sheet(workbook, sheetB, "Sheet2", true); // Sheet3
XLSX.utils.book_append_sheet(workbook, sheetC, "Sheet2", true); // Sheet4
XLSX.utils.book_append_sheet(workbook, sheetD, "Sheet2", true); // Sheet5
```
_اذكر أسماء أوراق العمل بترتيب التبويبات_```js
var wsnames = workbook.SheetNames;
```
خاصية `SheetNames` لكائن المصنف هي قائمة بأسماء أوراق العمل
بترتيب "التبويب".  ستنظر دوال API إلى هذه المصفوفة.

_استبدال ورقة عمل في موضعها_```js
workbook.Sheets[sheet_name] = new_worksheet;
```
خاصية `Sheets` لكائن المصنف (workbook) هي كائن مفاتيحه أسماء
وقيمه كائنات أوراق عمل. عن طريق إعادة التعيين إلى خاصية من خصائص
كائن `Sheets`، يمكن تغيير كائن ورقة العمل دون الإخلال ببقية بنية ورقة العمل.

**أمثلة**

<details>
  <summary><b>إضافة ورقة عمل جديدة إلى مصنف</b> (انقر للعرض)</summary>

يستخدم هذا المثال [`XLSX.utils.aoa_to_sheet`](#array-of-arrays-input).```js
var ws_name = "SheetJS";

/* Create worksheet */
var ws_data = [
  [ "S", "h", "e", "e", "t", "J", "S" ],
  [  1 ,  2 ,  3 ,  4 ,  5 ]
];
var ws = XLSX.utils.aoa_to_sheet(ws_data);

/* Add the worksheet to the workbook */
XLSX.utils.book_append_sheet(wb, ws, ws_name);
```
</details>

### تعديل قيم الخلايا

**API**

_تعديل قيمة خلية واحدة في ورقة عمل_```js
XLSX.utils.sheet_add_aoa(worksheet, [[new_value]], { origin: address });
```
_تعديل قيم خلايا متعددة في ورقة عمل_```js
XLSX.utils.sheet_add_aoa(worksheet, aoa, opts);
```
الدالة المساعدة `sheet_add_aoa` تُعدِّل قيم الخلايا في ورقة العمل. الوسيط الأول هو كائن ورقة العمل. الوسيط الثاني هو مصفوفة من مصفوفات القيم. مفتاح `origin` في الوسيط الثالث يتحكم في المكان الذي ستُكتب فيه الخلايا. المقتطف التالي يضبط `B3=1` و `E5="abc"`:```js
XLSX.utils.sheet_add_aoa(worksheet, [
  [1],                             // <-- Write 1 to cell B3
  ,                                // <-- Do nothing in row 4
  [/*B5*/, /*C5*/, /*D5*/, "abc"]  // <-- Write "abc" to cell E5
], { origin: "B3" });
```
["Array of Arrays Input"](#array-of-arrays-input) يصف الدالة ووسيط `opts` الاختياري بمزيد من التفصيل.

**أمثلة**

<details>
  <summary><b>إلحاق صفوف بورقة عمل</b> (انقر للعرض)</summary>

تشير القيمة الخاصة `-1` إلى أن `sheet_add_aoa` يبدأ في العمود A من
الصف التالي بعد آخر صف في النطاق، مع إلحاق البيانات:```js
XLSX.utils.sheet_add_aoa(worksheet, [
  ["first row after data", 1],
  ["second row after data", 2]
], { origin: -1 });
```
</details>


### تعديل خصائص ورقة العمل / المصنف / الخلية الأخرى

يصف قسم ["تنسيق جدول البيانات الشائع"](#common-spreadsheet-format) بنى الكائنات بمزيد من التفصيل.

## تغليف البيانات وإصدارها

### كتابة المصنفات

**واجهة برمجة التطبيقات**

_توليد بايتات جدول البيانات (ملف) من البيانات_```js
var data = XLSX.write(workbook, opts);
```
تحاول طريقة `write` حزم البيانات من المصنف في ملف في الذاكرة. بشكل افتراضي، يتم إنشاء ملفات XLSX، ولكن يمكن التحكم في ذلك عبر خاصية `bookType` من وسيط `opts`. بناءً على خيار `type`، يمكن تخزين البيانات كـ "سلسلة ثنائية"، سلسلة نصية JS، `Uint8Array` أو Buffer.

وسيط `opts` الثاني مطلوب. يغطي ["خيارات الكتابة"](#writing-options) الخصائص والسلوكيات المدعومة.

_توليد ومحاولة حفظ الملف_```js
XLSX.writeFile(workbook, filename, opts);
```
طريقة `writeFile` تغلّف البيانات وتحاول حفظ الملف الجديد. يتم تحديد تنسيق ملف التصدير من خلال امتداد `filename` (`SheetJS.xlsx` يشير إلى تصدير XLSX، `SheetJS.xlsb` يشير إلى تصدير XLSB، وهكذا).

تستخدم طريقة `writeFile` واجهات برمجية خاصة بالمنصة لبدء حفظ الملف. في NodeJS، يمكن لـ `fs.readFileSync` إنشاء ملف. في متصفح الويب، تتم محاولة التنزيل باستخدام خاصية `download` في HTML5، مع بدائل لـ IE.

_إنشاء ملف XLSX ومحاولة حفظه_```js
XLSX.writeFileXLSX(workbook, filename, opts);
```
The `writeFile` method embeds a number of different export functions. This is
great for developer experience but not amenable to tree shaking using the
current developer tools. When only XLSX exports are needed, this method avoids
referencing the other export functions.

The second `opts` argument is optional. ["خيارات الكتابة"](#writing-options)
covers the supported properties and behaviors.

**أمثلة**

<details>
  <summary><b>ملف محلي في خادم NodeJS</b> (اضغط للعرض)</summary>

`writeFile` uses `fs.writeFileSync` in server environments:```js
var XLSX = require("xlsx");

/* output format determined by filename */
XLSX.writeFile(workbook, "out.xlsb");
```
بالنسبة إلى Node ESM، فإن الأداة المساعدة `writeFile` غير مفعّلة. بدلاً من ذلك، `fs.writeFileSync`
يجب استخدامها لكتابة بيانات الملف إلى `Buffer` لاستخدامها مع `XLSX.write`:```js
import { writeFileSync } from "fs";
import { write } from "xlsx/xlsx.mjs";

const buf = write(workbook, {type: "buffer", bookType: "xlsb"});
/* buf is a Buffer */
const workbook = writeFileSync("out.xlsb", buf);
```
</details>

<details>
  <summary><b>ملف محلي في تطبيق Deno</b> (انقر للإظهار)</summary>

يستخدم `writeFile` الدالة `Deno.writeFileSync` في الخلفية:```js
// @deno-types="https://deno.land/x/sheetjs/types/index.d.ts"
import * as XLSX from 'https://deno.land/x/sheetjs/xlsx.mjs'

XLSX.writeFile(workbook, "test.xlsx");
```
يجب استدعاء التطبيقات التي تكتب الملفات باستخدام العلم `--allow-write`.  يحتوي
[`deno` demo](https://github.com/weareu/xlsx/blob/HEAD/demos/deno/) على مزيد من الأمثلة

</details>

<details>
  <summary><b>ملف محلي في ملحق PhotoShop أو InDesign</b> (انقر للعرض)</summary>

`writeFile` يغلّف منطق `File` في Photoshop وأهداف ExtendScript الأخرى.
يجب أن يكون المسار المحدد مسارًا مطلقًا:```js
#include "xlsx.extendscript.js"

/* output format determined by filename */
XLSX.writeFile(workbook, "out.xlsx");
/* at this point, out.xlsx is a file that you can distribute */
```
يتضمن العرض التجريبي [`extendscript`](https://github.com/weareu/xlsx/blob/HEAD/demos/extendscript/) مثالًا أكثر تعقيدًا.

</details>

<details>
  <summary><b>تنزيل ملف في المتصفح إلى جهاز المستخدم</b> (انقر للعرض)</summary>

`XLSX.writeFile` يغلّف عدة تقنيات لبدء حفظ ملف:

- واجهة برمجة تطبيقات المتصفح `URL` تنشئ عنوان URL لكائن الملف، والذي تستخدمه المكتبة
  بإنشاء رابط وفرض النقر عليه. وهو مدعوم في المتصفحات الحديثة.
- تمثل `msSaveBlob` واجهة برمجة تطبيقات IE10+ لبدء حفظ ملف.
- يستخدم `IE_FileSave` VBScript وActiveX لكتابة ملف في IE6+ لنظامي Windows XP وWindows 7.  يجب تضمين الكود المساند (shim) في صفحة HTML الحاوية.

لا توجد طريقة معيارية لتحديد ما إذا تم تنزيل الملف الفعلي.```js
/* output format determined by filename */
XLSX.writeFile(workbook, "out.xlsb");
/* at this point, out.xlsb will have been downloaded */
```
</details>

<details>
  <summary><b>تنزيل ملف في المتصفحات القديمة</b> (انقر للعرض)</summary>

تعمل تقنيات `XLSX.writeFile` مع معظم المتصفحات الحديثة وكذلك IE الأقدم.
بالنسبة للمتصفحات الأقدم بكثير، توجد حلول بديلة تنفذها مكتبات غلاف.

تنفّذ [`FileSaver.js`](https://github.com/eligrey/FileSaver.js/) دالة `saveAs`.
ملاحظة: سيستدعي `XLSX.writeFile` تلقائيًا `saveAs` إذا كان متاحًا.```js
/* bookType can be any supported output type */
var wopts = { bookType:"xlsx", bookSST:false, type:"array" };

var wbout = XLSX.write(workbook,wopts);

/* the saveAs call downloads a file on the local machine */
saveAs(new Blob([wbout],{type:"application/octet-stream"}), "test.xlsx");
```
[`Downloadify`](https://github.com/dcneiner/downloadify) يستخدم زر Flash SWF
لإنشاء ملفات محلية، وهو مناسب للبيئات التي لا يتوفر فيها ActiveX:```js
Downloadify.create(id,{
  /* other options are required! read the downloadify docs for more info */
  filename: "test.xlsx",
  data: function() { return XLSX.write(wb, {bookType:"xlsx", type:"base64"}); },
  append: false,
  dataType: "base64"
});
```
يُظهر [`oldie` ديمو](https://github.com/weareu/xlsx/blob/HEAD/demos/oldie/) سيناريو احتياطيًا متوافقًا مع IE.

</details>

<details>
  <summary><b>رفع ملف من المتصفح (ajax)</b> (انقر للإظهار)</summary>

مثال كامل باستخدام XHR هو [مضمّن في العرض التوضيحي XHR](https://github.com/weareu/xlsx/blob/HEAD/demos/xhr/)، إلى جانب
أمثلة لمكتبات fetch والتغليف. يفترض هذا المثال أن الخادم
يمكنه التعامل مع الملفات المشفرة بـ Base64 (انظر إلى العرض التوضيحي للحصول على خادم nodejs أساسي):```js
/* in this example, send a base64 string to the server */
var wopts = { bookType:"xlsx", bookSST:false, type:"base64" };

var wbout = XLSX.write(workbook,wopts);

var req = new XMLHttpRequest();
req.open("POST", "/upload", true);
var formdata = new FormData();
formdata.append("file", "test.xlsx"); // <-- server expects `file` to hold name
formdata.append("data", wbout); // <-- `data` holds the base64-encoded data
req.send(formdata);
```
</details>

<details>
  <summary><b>توليد الملفات عبر PhantomJS (Headless Webkit)</b> (انقر للعرض)</summary>

يضمّ [`headless` demo](https://github.com/weareu/xlsx/blob/HEAD/demos/headless/) عرضًا توضيحيًا كاملًا لتحويل ملفات HTML
إلى مصنّفات XLSB باستخدام [PhantomJS](https://phantomjs.org/). يدعم
`fs.write` في PhantomJS كتابة الملفات من العملية الرئيسية، لكن واجهته مختلفة
عن وحدة `fs` في NodeJS:```js
var XLSX = require('xlsx');
var fs = require('fs');

/* generate a binary string */
var bin = XLSX.write(workbook, { type:"binary", bookType: "xlsx" });
/* write to file */
fs.write("test.xlsx", bin, "wb");
```
ملاحظة: يُظهر قسم [“معالجة جداول HTML”](#processing-html-tables) كيفية
إنشاء مصنف من جداول HTML في صفحة ضمن "Headless WebKit".

</details>



تُغطي [العروض التوضيحية المرفقة](https://github.com/weareu/xlsx/blob/HEAD/demos/) تطبيقات الجوال وغيرها من عمليات النشر الخاصة.

### أمثلة على الكتابة

- <http://sheetjs.com/demos/table.html> تصدير جدول HTML
- <http://sheetjs.com/demos/writexlsx.html> ينشئ ملفًا بسيطًا

### الكتابة المتدفقة

تتوفر دوال الكتابة المتدفقة في كائن `XLSX.stream`. وهي
تأخذ نفس الوسائط التي تأخذها دوال الكتابة العادية لكنها تُرجع دفق قراءة NodeJS (Readable Stream).

- `XLSX.stream.to_csv` هو النسخة المتدفقة من `XLSX.utils.sheet_to_csv`.
- `XLSX.stream.to_html` هو النسخة المتدفقة من `XLSX.utils.sheet_to_html`.
- `XLSX.stream.to_json` هو النسخة المتدفقة من `XLSX.utils.sheet_to_json`.

<details>
  <summary><b>تحويل nodejs إلى CSV وكتابة الملف</b> (انقر للعرض)</summary>```js
var output_file_name = "out.csv";
var stream = XLSX.stream.to_csv(worksheet);
stream.pipe(fs.createWriteStream(output_file_name));
```
</details>

<details>
  <summary><b>nodejs كتابة تدفق JSON إلى الشاشة</b> (انقر للعرض)</summary>```js
/* to_json returns an object-mode stream */
var stream = XLSX.stream.to_json(worksheet, {raw:true});

/* the following stream converts JS objects to text via JSON.stringify */
var conv = new Transform({writableObjectMode:true});
conv._transform = function(obj, e, cb){ cb(null, JSON.stringify(obj) + "\n"); };

stream.pipe(conv); conv.pipe(process.stdout);
```
</details>

<details>
  <summary><b>تصدير ملفات NUMBERS</b> (اضغط للعرض)</summary>

يتطلب كاتب ملفات NUMBERS قاعدة كبيرة إلى حد ما. توفر البرامج النصية الإضافية `xlsx.zahl` الدعم. تم تصميم `xlsx.zahl.js` للاستخدام المستقل ومع NodeJS، بينما `xlsx.zahl.mjs` مناسب لـ ESM.

_المتصفح_```html
<meta charset="utf8">
<script src="xlsx.full.min.js"></script>
<script src="xlsx.zahl.js"></script>
<script>
var wb = XLSX.utils.book_new(); var ws = XLSX.utils.aoa_to_sheet([
  ["SheetJS", "<3","விரிதாள்"],
  [72,,"Arbeitsblätter"],
  [,62,"数据"],
  [true,false,],
]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
XLSX.writeFile(wb, "textport.numbers", {numbers: XLSX_ZAHL, compression: true});
</script>
```
_Node_```js
var XLSX = require("./xlsx.flow");
var XLSX_ZAHL = require("./dist/xlsx.zahl");
var wb = XLSX.utils.book_new(); var ws = XLSX.utils.aoa_to_sheet([
  ["SheetJS", "<3","விரிதாள்"],
  [72,,"Arbeitsblätter"],
  [,62,"数据"],
  [true,false,],
]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
XLSX.writeFile(wb, "textport.numbers", {numbers: XLSX_ZAHL, compression: true});
```
_Deno_```ts
import * as XLSX from './xlsx.mjs';
import XLSX_ZAHL from './dist/xlsx.zahl.mjs';

var wb = XLSX.utils.book_new(); var ws = XLSX.utils.aoa_to_sheet([
  ["SheetJS", "<3","விரிதாள்"],
  [72,,"Arbeitsblätter"],
  [,62,"数据"],
  [true,false,],
]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
XLSX.writeFile(wb, "textports.numbers", {numbers: XLSX_ZAHL, compression: true});
```
</details>

<https://github.com/sheetjs/sheetaki> يربط تدفقات الكتابة باستجابة nodejs.

### توليد بيانات JSON وJS

تميل بيانات JSON وJS إلى تمثيل أوراق عمل فردية. تعمل الدوال المساعدة في
هذا القسم مع أوراق العمل الفردية.

يصف قسم ["تنسيق جدول البيانات الشائع"](#common-spreadsheet-format)
بنية الكائن بمزيد من التفصيل.  `workbook.SheetNames` هو قائمة مرتبة
بأسماء أوراق العمل.  `workbook.Sheets` هو كائن مفاتيحه هي أسماء الأوراق
وقيمه هي كائنات أوراق العمل.

يتم تخزين "ورقة العمل الأولى" في `workbook.Sheets[workbook.SheetNames[0]]`.

**API**

_أنشئ مصفوفة من كائنات JS من ورقة عمل_```js
var jsa = XLSX.utils.sheet_to_json(worksheet, opts);
```
_إنشاء مصفوفة من المصفوفات لقيم JS من ورقة عمل_```js
var aoa = XLSX.utils.sheet_to_json(worksheet, {...opts, header: 1});
```
دالة الأداة المساعدة `sheet_to_json` تتنقل عبر مصنف بترتيب الصفوف، مولّدةً مصفوفة من الكائنات. تتحكم الوسيطة الثانية `opts` في عدد من قرارات التصدير بما في ذلك نوع القيم (قيم JS أو نص منسّق). يصف قسم ["JSON"](#json) الوسيطة بمزيد من التفصيل.

افتراضيًا، يفحص `sheet_to_json` الصف الأول ويستخدم القيم كعناوين. مع الخيار `header: 1`، تقوم الدالة بتصدير مصفوفة من مصفوفات القيم.

**أمثلة**

[`x-spreadsheet`](https://github.com/myliang/x-spreadsheet) هي شبكة بيانات تفاعلية لمعاينة وتعديل البيانات المنظمة في متصفح الويب. يتضمن [عرض `xspreadsheet`](https://github.com/weareu/xlsx/blob/HEAD/demos/xspreadsheet) نصًا برمجيًا نموذجيًا مع دالة `stox` للتحويل من مصنف إلى كائن بيانات x-spreadsheet. <https://oss.sheetjs.com/sheetjs/x-spreadsheet> هو عرض توضيحي مباشر.

<details>
  <summary><b>معاينة البيانات في شبكة بيانات React</b> (انقر للعرض)</summary>

[`react-data-grid`](https://npm.im/react-data-grid) هي شبكة بيانات مصمّمة خصيصًا لـ React. تتوقع خاصيتين: `rows` من كائنات البيانات و`columns` التي تصف الأعمدة. لأغراض تهيئة البيانات لتلائم واجهة برمجة تطبيقات react-data-grid، يكون من الأسهل البدء من مصفوفة من المصفوفات.

يبدأ هذا العرض التوضيحي بجلب ملف عن بُعد واستخدام `XLSX.read` لاستخراج:```js
import { useEffect, useState } from "react";
import DataGrid from "react-data-grid";
import { read, utils } from "xlsx";

const url = "https://oss.sheetjs.com/test_files/RkNumber.xls";

export default function App() {
  const [columns, setColumns] = useState([]);
  const [rows, setRows] = useState([]);
  useEffect(() => {(async () => {
    const wb = read(await (await fetch(url)).arrayBuffer(), { WTF: 1 });

    /* use sheet_to_json with header: 1 to generate an array of arrays */
    const data = utils.sheet_to_json(wb.Sheets[wb.SheetNames[0]], { header: 1 });

    /* see react-data-grid docs to understand the shape of the expected data */
    setColumns(data[0].map((r) => ({ key: r, name: r })));
    setRows(data.slice(1).map((r) => r.reduce((acc, x, i) => {
      acc[data[0][i]] = x;
      return acc;
    }, {})));
  })(); });

  return <DataGrid columns={columns} rows={rows} />;
}
```
</details>

<details>
  <summary><b>معاينة البيانات في شبكة بيانات VueJS</b> (انقر للعرض)</summary>

[`vue3-table-lite`](https://github.com/linmasahiro/vue3-table-lite) هو جدول بيانات
بسيط خاص بـ VueJS 3. وهو معروض [في عرض VueJS التجريبي](https://github.com/weareu/xlsx/blob/HEAD/demos/vue/modify/).

</details>

<details>
  <summary><b>تعبئة قاعدة بيانات (SQL أو no-SQL)</b> (انقر للعرض)</summary>

يتضمن [العرض التجريبي `database`](https://github.com/weareu/xlsx/blob/HEAD/demos/database/) أمثلة على العمل مع
قواعد البيانات ونتائج الاستعلام.

</details>

<details>
  <summary><b>الحسابات العددية باستخدام TensorFlow.js</b> (انقر للعرض)</summary>

[`@tensorflow/tfjs`](https://github.com/weareu/xlsx/blob/HEAD/@tensorflow/tfjs) والمكتبات الأخرى تتوقع بيانات في مصفوفات
بسيطة، وهي مناسبة تمامًا لأوراق العمل حيث يمثل كل عمود متجه بيانات. وهذا هو
منقلب طريقة استخدام معظم الأشخاص للجداول الممتدة، حيث يمثل كل صف متجهًا.

يمكن لاستدعاء واحد `Array#map` سحب صفوف مسماة فردية من تصدير `sheet_to_json`:

</details>```js
const XLSX = require("xlsx");
const tf = require('@tensorflow/tfjs');

const key = "age"; // this is the field we want to pull
const ages = XLSX.utils.sheet_to_json(worksheet).map(r => r[key]);
const tf_data = tf.tensor1d(ages);
```
يمكن معالجة جميع الحقول دفعة واحدة باستخدام تبديل (transpose) للموتر (tensor) ثنائي الأبعاد الناتج
من تصدير `sheet_to_json` مع `header: 1`. يجب إزالة الصف الأول، إذا كان يحتوي
على تسميات الترويسة، باستخدام شريحة (slice):```js
const XLSX = require("xlsx");
const tf = require('@tensorflow/tfjs');

/* array of arrays of the data starting on the second row */
const aoa = XLSX.utils.sheet_to_json(worksheet, {header: 1}).slice(1);
/* dataset in the "correct orientation" */
const tf_dataset = tf.tensor2d(aoa).transpose();
/* pull out each dataset with a slice */
const tf_field0 = tf_dataset.slice([0,0], [1,tensor.shape[1]]).flatten();
const tf_field1 = tf_dataset.slice([1,0], [1,tensor.shape[1]]).flatten();
```
The [`array` demo](https://github.com/weareu/xlsx/blob/HEAD/demos/array/) shows a complete example.

</details>


### إنشاء جداول HTML

**API**

_إنشاء جدول HTML من ورقة العمل_```js
var html = XLSX.utils.sheet_to_html(worksheet);
```
تُنشئ دالة الأداة المساعدة `sheet_to_html` كود HTML استنادًا إلى بيانات ورقة
العمل. يتم تعيين كل خلية في ورقة العمل إلى عنصر `<TD>`. يتم تسلسل الخلايا
المدمجة في ورقة العمل عن طريق تعيين سمتَي `colspan` و`rowspan`.

**أمثلة**

تُنشئ دالة الأداة المساعدة `sheet_to_html` كود HTML يمكن إضافته إلى
أي عنصر DOM عن طريق تعيين `innerHTML`:```js
var container = document.getElementById("tavolo");
container.innerHTML = XLSX.utils.sheet_to_html(worksheet);
```
عند الدمج مع `fetch`، يصبح إنشاء موقع من مصنف أمرًا مباشرًا:

<details>
  <summary><b>Vanilla JS + HTML لجلب مصنف وإنشاء معاينات جدول</b> (انقر للعرض)</summary>```html
<body>
  <style>TABLE { border-collapse: collapse; } TD { border: 1px solid; }</style>
  <div id="tavolo"></div>
  <script src="https://unpkg.com/xlsx/dist/xlsx.full.min.js"></script>
  <script type="text/javascript">
(async() => {
  /* fetch and parse workbook -- see the fetch example for details */
  const workbook = XLSX.read(await (await fetch("sheetjs.xlsx")).arrayBuffer());

  let output = [];
  /* loop through the worksheet names in order */
  workbook.SheetNames.forEach(name => {

    /* generate HTML from the corresponding worksheets */
    const worksheet = workbook.Sheets[name];
    const html = XLSX.utils.sheet_to_html(worksheet);

    /* add a header with the title name followed by the table */
    output.push(`<H3>${name}</H3>${html}`);
  });
  /* write to the DOM at the end */
  tavolo.innerHTML = output.join("\n");
})();
  </script>
</body>
```
</details>

<details>
  <summary><b>جلب المصنف في React وإنشاء معاينات جدول HTML</b> (انقر للإظهار)</summary>

يُنصح عمومًا باستخدام سير عمل متوافق مع React، ولكن من الممكن توليد HTML واستخدامه في React عبر `dangerouslySetInnerHTML`:
</details>```jsx
function Tabeller(props) {
  /* the workbook object is the state */
  const [workbook, setWorkbook] = React.useState(XLSX.utils.book_new());

  /* fetch and update the workbook with an effect */
  React.useEffect(() => { (async() => {
    /* fetch and parse workbook -- see the fetch example for details */
    const wb = XLSX.read(await (await fetch("sheetjs.xlsx")).arrayBuffer());
    setWorkbook(wb);
  })(); });

  return workbook.SheetNames.map(name => (<>
    <h3>name</h3>
    <div dangerouslySetInnerHTML={{
      /* this __html mantra is needed to set the inner HTML */
      __html: XLSX.utils.sheet_to_html(workbook.Sheets[name])
    }} />
  </>));
}
```
يحتوي [العرض التوضيحي `react`](https://github.com/weareu/xlsx/blob/HEAD/demos/react) على المزيد من أمثلة React.

</details>

<details>
  <summary><b>جلب المصنف باستخدام VueJS وإنشاء معاينات جدول HTML</b> (انقر للعرض)</summary>

يُفضَّل عمومًا استخدام سير عمل متوافق مع VueJS، لكن من الممكن
إنشاء HTML واستخدامه في VueJS مع توجيه `v-html`:```jsx
import { read, utils } from 'xlsx';
import { reactive } from 'vue';

const S5SComponent = {
  mounted() { (async() => {
    /* fetch and parse workbook -- see the fetch example for details */
    const workbook = read(await (await fetch("sheetjs.xlsx")).arrayBuffer());
    /* loop through the worksheet names in order */
    workbook.SheetNames.forEach(name => {
      /* generate HTML from the corresponding worksheets */
      const html = utils.sheet_to_html(workbook.Sheets[name]);
      /* add to state */
      this.wb.wb.push({ name, html });
    });
  })(); },
  /* this state mantra is required for array updates to work */
  setup() { return { wb: reactive({ wb: [] }) }; },
  template: `
  <div v-for="ws in wb.wb" :key="ws.name">
    <h3>{{ ws.name }}</h3>
    <div v-html="ws.html"></div>
  </div>`
};
```
يتضمّن [`vuejs` demo](https://github.com/weareu/xlsx/blob/HEAD/demos/vue) المزيد من أمثلة React.

</details>

### إنشاء لقطات لورقة عمل واحدة

تقبل دوال `sheet_to_*` كائن ورقة عمل.

**API**

_إنشاء ملف CSV من ورقة عمل واحدة_```js
var csv = XLSX.utils.sheet_to_csv(worksheet, opts);
```
هذه اللقطة مصممة لتكرار نوع الإخراج "CSV UTF8 (`.csv`)".
يصف [المخرجات المفصولة بفواصل](#delimiter-separated-output) الوظيفة والوسيطة الاختيارية `opts` بمزيد من التفصيل.

_إنشاء "Text" من ورقة عمل واحدة_```js
var txt = XLSX.utils.sheet_to_txt(worksheet, opts);
```
تم تصميم هذه اللقطة لمحاكاة نوع الإخراج "UTF16 Text (`.txt`)".
[الإخراج المفصول بمحددات](#delimiter-separated-output) يصف الوظيفة ووسيطة `opts` الاختيارية بمزيد من التفاصيل.

_إنشاء قائمة بالصيغ من ورقة عمل واحدة_```js
var fmla = XLSX.utils.sheet_to_formulae(worksheet);
```
تُنشئ هذه اللقطة مصفوفةً من الإدخالات التي تمثل الصيغ المضمّنة.
تُعرض صيغ المصفوفات بالشكل `range=formula` بينما تُعرض الخلايا العادية
بالشكل `cell=formula or value`. تُسبَق حرفيات النص بفاصلة علوية `'`، بما يتوافق مع عرض شريط الصيغة في Excel.

يصف [«مخرجات الصيغ»](#formulae-output) الوظيفة بمزيد من التفصيل.

## الواجهة

`XLSX` هو المتغير المُعرَّض في المتصفح والمتغير المُصدَّر في Node

`XLSX.version` هو إصدار المكتبة (يُضاف عبر سكربت البناء).

`XLSX.SSF` هو إصدار مضمّن من [مكتبة التنسيق](https://git.io/ssf).

### دوال التحليل

يحاول `XLSX.read(data, read_opts)` تحليل `data`.

يحاول `XLSX.readFile(filename, read_opts)` قراءة `filename` وتحليلها.

خيارات التحليل موصوفة في قسم [خيارات التحليل](#parsing-options).

### دوال الكتابة

يحاول `XLSX.write(wb, write_opts)` كتابة مصنف العمل `wb`

يحاول `XLSX.writeFile(wb, filename, write_opts)` كتابة `wb` إلى `filename`.
في البيئات القائمة على المتصفح، سيحاول فرض تنزيل من جهة العميل.

يحاول `XLSX.writeFileAsync(wb, filename, o, cb)` كتابة `wb` إلى `filename`.
إذا تم حذف `o`، سيستخدم الكاتب الوسيطة الثالثة كدالة استدعاء.

يحتوي `XLSX.stream` على مجموعة من دوال الكتابة المتدفقة.

خيارات الكتابة موصوفة في قسم [خيارات الكتابة](#writing-options).

### الأدوات المساعدة

الأدوات المساعدة متاحة في كائن `XLSX.utils` وهي موصوفة في
قسم [الدوال المساعدة](#utility-functions):

**الإنشاء:**

- `book_new` ينشئ مصنف عمل فارغًا
- `book_append_sheet` يضيف ورقة عمل إلى مصنف عمل

**الاستيراد:**

- `aoa_to_sheet` يحول مصفوفة من مصفوفات بيانات JS إلى ورقة عمل.
- `json_to_sheet` يحول مصفوفة من كائنات JS إلى ورقة عمل.
- `table_to_sheet` يحول عنصر DOM TABLE إلى ورقة عمل.
- `sheet_add_aoa` يضيف مصفوفة من مصفوفات بيانات JS إلى ورقة عمل موجودة.
- `sheet_add_json` يضيف مصفوفة من كائنات JS إلى ورقة عمل موجودة.


**التصدير:**

- `sheet_to_json` يحول كائن ورقة عمل إلى مصفوفة من كائنات JSON.
- `sheet_to_csv` يولّد مخرجات قيم مفصولة بمحددات.
- `sheet_to_txt` يولّد نصًا منسقًا UTF16.
- `sheet_to_html` يولّد مخرجات HTML.
- `sheet_to_formulae` يولّد قائمة بالصيغ (مع قيم احتياطية).


**التعامل مع الخلايا وعناوين الخلايا:**

- `format_cell` يولّد القيمة النصية لخلية (باستخدام تنسيقات الأرقام).
- `encode_row / decode_row` يحول بين الصفوف ذات الفهرس 0 والصفوف ذات الفهرس 1.
- `encode_col / decode_col` يحول بين الأعمدة ذات الفهرس 0 وأسماء الأعمدة.
- `encode_cell / decode_cell` يحول عناوين الخلايا.
- `encode_range / decode_range` يحول نطاقات الخلايا.

## تنسيق جدول البيانات الشائع

يتوافق SheetJS مع تنسيق جدول البيانات الشائع (CSF):

### البنى العامة

تُخزَّن كائنات عناوين الخلايا بالشكل `{c:C, r:R}` حيث يكون `C` و `R` هما فهرسي العمود والصف على الترتيب بفهرسة تبدأ من 0
أرقام العمود والصف على التوالي. على سبيل المثال، يتم تمثيل عنوان الخلية `B5`
بالكائن `{c:1, r:4}`.

تُخزَّن كائنات نطاق الخلايا بالشكل `{s:S, e:E}` حيث `S` هي الخلية الأولى و
`E` هي الخلية الأخيرة في النطاق. النطاقات شاملة للطرفين. على سبيل المثال،
يتم تمثيل النطاق `A3:B7` بالكائن `{s:{c:0, r:2}, e:{c:1, r:6}}`.
تنفذ الدوال المساعدة اجتيازًا لنطاق ورقة العمل بترتيب الصفوف الأساسي:```js
for(var R = range.s.r; R <= range.e.r; ++R) {
  for(var C = range.s.c; C <= range.e.c; ++C) {
    var cell_address = {c:C, r:R};
    /* if an A1-style address is needed, encode the address */
    var cell_ref = XLSX.utils.encode_cell(cell_address);
  }
}
```
### كائن الخلية

كائنات الخلايا هي كائنات JS عادية بمفاتيح وقيم تتبع الاصطلاح التالي:

| المفتاح | الوصف |
| --- | --- |
| `v` | القيمة الخام (راجع قسم أنواع البيانات لمزيد من المعلومات) |
| `w` | النص المنسق (إن وُجد) |
| `t` | النوع: `b` منطقي، `e` خطأ، `n` رقم، `d` تاريخ، `s` نص، `z` عنصر نائب |
| `f` | صيغة الخلية مشفرة كسلسلة بنمط A1 (إن وُجدت) |
| `F` | نطاق المصفوفة المحيطة إذا كانت الصيغة صيغة مصفوفة (إن وُجد) |
| `D` | إذا كان صحيحًا، فإن صيغة المصفوفة ديناميكية (إن وُجد) |
| `r` | ترميز النص المنسق (إن وُجد) |
| `h` | عرض HTML للنص المنسق (إن وُجد) |
| `c` | التعليقات المرتبطة بالخلية |
| `z` | سلسلة تنسيق الأرقام المرتبطة بالخلية (إن طُلبت) |
| `l` | كائن الارتباط التشعبي للخلية (`.Target` يحمل الرابط، `.Tooltip` هو التلميح) |
| `s` | نمط/ثيم الخلية (إن وُجد) |

ستستخدم أدوات التصدير المدمجة (مثل مُصدِّر CSV) نص `w` إذا كان
متاحًا. لتغيير قيمة، تأكد من حذف `cell.w` (أو تعيينه إلى
`undefined`) قبل محاولة التصدير. ستعيد الأدوات توليد نص `w`
من تنسيق الأرقام (`cell.z`) والقيمة الخام إذا أمكن.

تُخزَّن صيغة المصفوفة الفعلية في حقل `f` للخلية الأولى في
نطاق المصفوفة. أما الخلايا الأخرى في النطاق فستحذف حقل `f`.

#### أنواع البيانات

تُخزَّن القيمة الخام في خاصية القيمة `v`، وتُفسَّر بناءً على خاصية النوع `t`.
يتيح هذا الفصل تمثيل الأرقام وكذلك النص الرقمي. هناك 6 أنواع صالحة للخلايا:

| النوع | الوصف |
| :--: | :-------------------------------------------------------------------- |
| `b` | منطقي: القيمة تُفسَّر كـ `boolean` في JS |
| `e` | خطأ: القيمة رمز رقمي وخاصية `w` تخزن الاسم الشائع ** |
| `n` | رقم: القيمة `number` في JS ** |
| `d` | تاريخ: القيمة كائن `Date` في JS أو سلسلة تُحلَّل كتاريخ ** |
| `s` | نص: القيمة تُفسَّر كـ `string` في JS وتُكتب كنص ** |
| `z` | عنصر نائب: خلية نائبة فارغة يتم تجاهلها بواسطة أدوات معالجة البيانات ** |

<details>
  <summary><b>قيم الأخطاء وتفسيرها</b> (انقر للإظهار)</summary>

| القيمة | معنى الخطأ |
| -----: | :-------------- |
| `0x00` | `#NULL!`        |
| `0x07` | `#DIV/0!`       |
| `0x0F` | `#VALUE!`       |
| `0x17` | `#REF!`         |
| `0x1D` | `#NAME?`        |
| `0x24` | `#NUM!`         |
| `0x2A` | `#N/A`          |
| `0x2B` | `#GETTING_DATA` |

</details>

النوع `n` هو نوع الرقم. يتضمن جميع أشكال البيانات التي يخزنها Excel كأرقام،
مثل التواريخ/الأوقات والحقول المنطقية. يستخدم Excel حصريًا بيانات يمكن
احتواءها في رقم فاصلة عائمة IEEE754، تمامًا مثل رقم JS، لذا يحمل حقل `v`
الرقم الخام. يحمل حقل `w` النص المنسق. تُخزَّن التواريخ كأرقام افتراضيًا
وتُحوَّل باستخدام `XLSX.SSF.parse_date_code`.

النوع `d` هو نوع التاريخ، ويُولَّد فقط عند تمرير الخيار `cellDates`.
نظرًا لأن JSON لا يحتوي على نوع تاريخ طبيعي، فمن المتوقع عمومًا أن تخزن
المحلِّلات سلاسل تاريخ ISO 8601 مثل تلك التي ستحصل عليها من
`date.toISOString()`. من ناحية أخرى، يجب أن يكون الكتّاب والمُصدِّرون قادرين
على التعامل مع سلاسل التواريخ وكائنات JS Date. لاحظ أن Excel يتجاهل معدِّلات
المنطقة الزمنية ويعامل جميع التواريخ في المنطقة الزمنية المحلية. لا تصحح
المكتبة هذا الخطأ.

النوع `s` هو نوع السلسلة النصية. تُخزَّن القيم صراحةً كنص. سيفسر Excel
هذه الخلايا على أنها "رقم مخزَّن كنص". تمنع ملفات Excel المولَّدة تلقائيًا
هذا النوع من الأخطاء، لكن التنسيقات الأخرى قد تستدعي أخطاء.

النوع `z` يمثل الخلايا النائبة الفارغة. تُولَّد في الحالات التي لا تحتوي فيها
الخلايا على قيمة مخصصة ولكنها تحمل تعليقات أو بيانات وصفية أخرى. يتم تجاهلها
بواسطة دوال معالجة البيانات في المكتبة الأساسية. افتراضيًا لا تُولَّد هذه
الخلايا؛ يجب تعيين خيار المحلِّل `sheetStubs` إلى `true`.

#### التواريخ

<details>
  <summary><b>تفاصيل رمز تاريخ Excel</b> (انقر للإظهار)</summary>

افتراضيًا، يخزن Excel التواريخ كأرقام مع رمز تنسيق يحدد معالجة التاريخ.
على سبيل المثال، يُخزَّن التاريخ `19-Feb-17` كرقم `42785` بتنسيق أرقام
`d-mmm-yy`. تفهم وحدة `SSF` تنسيقات الأرقام وتجري التحويل المناسب.

يدعم XLSX أيضًا نوع تاريخ خاص `d` حيث تكون البيانات سلسلة تاريخ ISO 8601.
يحول المُنسِّق التاريخ مرة أخرى إلى رقم.

السلوك الافتراضي لجميع المحلِّلات هو توليد خلايا رقمية. تعيين `cellDates`
إلى `true` سيجبر المولِّدات على تخزين التواريخ.

</details>

<details>
  <summary><b>المناطق الزمنية والتواريخ</b> (انقر للإظهار)</summary>

لا يمتلك Excel مفهومًا أصليًا للوقت العالمي. تُحدَّد جميع الأوقات في المنطقة
الزمنية المحلية. تمنع قيود Excel تحديد تواريخ مطلقة حقيقية.

اتباعًا لـ Excel، تتعامل هذه المكتبة مع جميع التواريخ على أنها نسبية للمنطقة
الزمنية المحلية.

</details>

<details>
  <summary><b>الحِقب: 1900 و1904</b> (انقر للإظهار)</summary>

يدعم Excel حقبتين (1 يناير 1900 و1 يناير 1904).
يمكن تحديد حقبة المصنف بفحص خاصية `wb.Workbook.WBProps.date1904` للمصنف:```js
!!(((wb.Workbook||{}).WBProps||{}).date1904)
```
</details>

### كائنات الورقة

كل مفتاح لا يبدأ بـ `!` يرتبط بخلية (باستخدام ترميز `A-1`)

`sheet[address]` يُرجع كائن الخلية للعنوان المحدد.

**مفاتيح الورقة الخاصة (يمكن الوصول إليها عبر `sheet[key]`، وكل منها يبدأ بـ `!`):**

- `sheet['!ref']`: نطاق قائم على A-1 يمثل نطاق الورقة. يجب أن تستخدم الدوال
  التي تتعامل مع الأوراق هذه المعلمة لتحديد النطاق. الخلايا المعيّنة خارج
  النطاق لا تتم معالجتها. على وجه الخصوص، عند كتابة ورقة يدويًا، لا يتم تضمين
  الخلايا خارج النطاق

  يجب على الدوال التي تتعامل مع الأوراق التحقق من وجود حقل `!ref`. إذا تم حذف
  `!ref` أو لم يكن نطاقًا صالحًا، فالدوال حرة في معاملة الورقة على أنها فارغة
  أو محاولة تخمين النطاق. الأدوات المساعدة القياسية المرفقة مع هذه المكتبة
  تتعامل مع الأوراق على أنها فارغة (على سبيل المثال، يكون ناتج CSV سلسلة
  فارغة).

  عند قراءة ورقة عمل مع تعيين خاصية `sheetRows`، ستستخدم معلمة ref النطاق
  المقيّد. النطاق الأصلي يُضبط في `ws['!fullref']`

- `sheet['!margins']`: كائن يمثل هوامش الصفحة. تتبع القيم الافتراضية الإعداد
  المسبق "العادي" في Excel. لدى Excel أيضًا إعدادان مسبقان "واسع" و"ضيّق" لكنهما
  يُخزنان كقياسات خام. الخصائص الرئيسية مذكورة أدناه:

<details>
  <summary><b>تفاصيل هوامش الصفحة</b> (انقر للعرض)</summary>

| المفتاح | الوصف                    | "عادي" | "واسع" | "ضيّق" |
|----------|------------------------|:---------|:-------|:-------- |
| `left`   | الهامش الأيسر (بالبوصة) | `0.7`    | `1.0`  | `0.25`   |
| `right`  | الهامش الأيمن (بالبوصة) | `0.7`    | `1.0`  | `0.25`   |
| `top`    | الهامش العلوي (بالبوصة) | `0.75`   | `1.0`  | `0.75`   |
| `bottom` | الهامش السفلي (بالبوصة) | `0.75`   | `1.0`  | `0.75`   |
| `header` | هامش الترويسة (بالبوصة) | `0.3`    | `0.5`  | `0.3`    |
| `footer` | هامش التذييل (بالبوصة)  | `0.3`    | `0.5`  | `0.3`    |```js
/* Set worksheet sheet to "normal" */
ws["!margins"]={left:0.7, right:0.7, top:0.75,bottom:0.75,header:0.3,footer:0.3}
/* Set worksheet sheet to "wide" */
ws["!margins"]={left:1.0, right:1.0, top:1.0, bottom:1.0, header:0.5,footer:0.5}
/* Set worksheet sheet to "narrow" */
ws["!margins"]={left:0.25,right:0.25,top:0.75,bottom:0.75,header:0.3,footer:0.3}
```
</details>

#### كائن ورقة العمل

بالإضافة إلى مفاتيح الورقة الأساسية، تضيف أوراق العمل أيضًا:

- `ws['!cols']`: مصفوفة من كائنات خصائص الأعمدة. يتم تخزين عروض الأعمدة
  فعليًا في الملفات بطريقة موحّدة، وتُقاس من حيث «الحد الأقصى لعرض الأرقام»
  (أكبر عرض للأرقام المعروضة 0-9، بالبكسل). عند التحليل، تخزّن كائنات
  الأعمدة عرض البكسل في الحقل `wpx`، وعرض الأحرف في الحقل `wch`، والحد
  الأقصى لعرض الأرقام في الحقل `MDW`.

- `ws['!rows']`: مصفوفة من كائنات خصائص الصفوف كما هو موضح لاحقًا في
  الوثائق. يرمّز كل كائن صف خصائص تشمل ارتفاع الصف ومدى ظهوره.

- `ws['!merges']`: مصفوفة من كائنات النطاقات المقابلة للخلايا المدمجة في ورقة
  العمل. لا تدعم تنسيقات النص العادي دمج الخلايا. سيكتب تصدير CSV جميع
  الخلايا في نطاق الدمج إذا كانت موجودة، لذا تأكد من تعيين الخلية الأولى فقط
  (العلوية اليسرى) في النطاق.

- `ws['!outline']`: تكوين سلوك المخططات التفصيلية. تأخذ الخيارات قيمها
  الافتراضية من الإعدادات الافتراضية في Excel 2019:

| المفتاح | ميزة Excel | الافتراضي |
|:----------|:----------------------------------------------|:--------|
| `above` | إلغاء تحديد «صفوف الملخص أسفل التفاصيل» | `false` |
| `left` | إلغاء تحديد «صفوف الملخص على يمين التفاصيل» | `false` |

- `ws['!protect']`: كائن لخصائص حماية ورقة العمل عند الكتابة. يحدد مفتاح
  `password` كلمة المرور للتنسيقات التي تدعم الأوراق المحمية بكلمة مرور
  (XLSX/XLSB/XLS). يستخدم الكاتب طريقة التعتيم XOR. تتحكم المفاتيح التالية
  في حماية الورقة -- اضبطها على `false` لتمكين ميزة عندما تكون الورقة
  مقفلة، أو اضبطها على `true` لتعطيل ميزة:

<details>
  <summary><b>تفاصيل حماية ورقة العمل</b> (انقر للعرض)</summary>

| المفتاح | الميزة (true=معطّلة / false=مفعّلة) | الافتراضي |
|:----------------------|:----------------------------------------|:-----------|
| `selectLockedCells` | تحديد الخلايا المقفلة | مفعّل |
| `selectUnlockedCells` | تحديد الخلايا غير المقفلة | مفعّل |
| `formatCells` | تنسيق الخلايا | معطّل |
| `formatColumns` | تنسيق الأعمدة | معطّل |
| `formatRows` | تنسيق الصفوف | معطّل |
| `insertColumns` | إدراج أعمدة | معطّل |
| `insertRows` | إدراج صفوف | معطّل |
| `insertHyperlinks` | إدراج ارتباطات تشعبية | معطّل |
| `deleteColumns` | حذف أعمدة | معطّل |
| `deleteRows` | حذف صفوف | معطّل |
| `sort` | فرز | معطّل |
| `autoFilter` | تصفية | معطّل |
| `pivotTables` | استخدام تقارير PivotTable | معطّل |
| `objects` | تحرير الكائنات | مفعّل |
| `scenarios` | تحرير السيناريوهات | مفعّل |
</details>

- `ws['!autofilter']`: كائن AutoFilter وفقًا للمخطط التالي:```typescript
type AutoFilter = {
  ref:string; // A-1 based range representing the AutoFilter table range
}
```
#### كائن Chartsheet

يتم تمثيل مخططات الأوراق (Chartsheets) كأوراق قياسية. يتم تمييزها بخاصية
`!type` المضبوطة على `"chart"`.

تشير البيانات الأساسية و`!ref` إلى البيانات المخزنة مؤقتًا في ورقة المخطط.
الصف الأول من ورقة المخطط هو الترويسة الأساسية.

#### كائن Macrosheet

يتم تمثيل أوراق الماكرو (Macrosheets) كأوراق قياسية. يتم تمييزها بخاصية
`!type` المضبوطة على `"macro"`.

#### كائن Dialogsheet

يتم تمثيل أوراق الحوار (Dialogsheets) كأوراق قياسية. يتم تمييزها بخاصية
`!type` المضبوطة على `"dialog"`.

### كائن المصنف (Workbook Object)

`workbook.SheetNames` هي قائمة مرتبة بالأوراق الموجودة في المصنف

`wb.Sheets[sheetname]` يُرجع كائنًا يمثل ورقة العمل.

`wb.Props` هو كائن يخزن الخصائص القياسية. `wb.Custprops` يخزن
الخصائص المخصصة. نظرًا لأن خصائص XLS القياسية تنحرف عن معيار XLSX،
فإن تحليل XLS يخزن الخصائص الأساسية في كلا المكانين.

`wb.Workbook` يخزن [سمات على مستوى المصنف](#workbook-level-attributes).

#### خصائص ملف المصنف

تستخدم تنسيقات الملفات المختلفة أسماء داخلية مختلفة لخصائص الملف. يعمل
كائن `Props` الخاص بالمصنف على توحيد الأسماء:

<details>
  <summary><b>خصائص الملف</b> (انقر للإظهار)</summary>

| اسم JS             | وصف Excel                      |
|:-------------------|:-------------------------------|
| `Title`            | تبويب "الملخص" "العنوان"       |
| `Subject`          | تبويب "الملخص" "الموضوع"       |
| `Author`           | تبويب "الملخص" "المؤلف"        |
| `Manager`          | تبويب "الملخص" "المدير"        |
| `Company`          | تبويب "الملخص" "الشركة"        |
| `Category`         | تبويب "الملخص" "الفئة"         |
| `Keywords`         | تبويب "الملخص" "الكلمات المفتاحية" |
| `Comments`         | تبويب "الملخص" "التعليقات"     |
| `LastAuthor`       | تبويب "الإحصائيات" "آخر حفظ بواسطة" |
| `CreatedDate`      | تبويب "الإحصائيات" "تاريخ الإنشاء" |

</details>

على سبيل المثال، لتعيين خاصية عنوان المصنف:```js
if(!wb.Props) wb.Props = {};
wb.Props.Title = "Insert Title Here";
```
تُضاف الخصائص المخصصة في كائن `Custprops` الخاص بالمصنف:```js
if(!wb.Custprops) wb.Custprops = {};
wb.Custprops["Custom Property"] = "Custom Value";
```
سيعالج الكتّاب مفتاح `Props` الخاص بكائن الخيارات:```js
/* force the Author to be "SheetJS" */
XLSX.write(wb, {Props:{Author:"SheetJS"}});
```
### سمات مستوى المصنف

يخزّن `wb.Workbook` سمات مستوى المصنف.

#### الأسماء المعرّفة

`wb.Workbook.Names` عبارة عن مصفوفة من كائنات الأسماء المعرّفة التي تحتوي على المفاتيح التالية:

<details>
  <summary><b>خصائص الاسم المعرّف</b> (انقر للإظهار)</summary>

| المفتاح    | الوصف                                                            |
|:----------|:-----------------------------------------------------------------|
| `Sheet`   | نطاق الاسم. فهرس الورقة (0 = الورقة الأولى) أو `null` (المصنف)   |
| `Name`    | اسم حساس لحالة الأحرف. تنطبق القواعد القياسية **                 |
| `Ref`     | مرجع بنمط A1 (`"Sheet1!$A$1:$D$20"`)                             |
| `Comment` | تعليق (يُطبَّق فقط على XLS/XLSX/XLSB)                            |

</details>

يتيح Excel لاسمين معرّفين على مستوى ورقة العمل مشاركة الاسم نفسه. ومع ذلك، لا يمكن لاسم على مستوى ورقة العمل أن يتعارض مع اسم على مستوى المصنف. قد لا تفرض أدوات كتابة المصنفات هذا القيد.

#### طرق عرض المصنف

`wb.Workbook.Views` عبارة عن مصفوفة من كائنات طرق عرض المصنف التي تحتوي على المفاتيح التالية:

| المفتاح        | الوصف                                         |
|:----------------|:----------------------------------------------------|
| `RTL`           | إذا كانت القيمة true، اعرض من اليمين إلى اليسار      |

#### خصائص المصنف المتنوعة

يحتفظ `wb.Workbook.WBProps` بخصائص مصنف أخرى:

| المفتاح         | الوصف                                         |
|:----------------|:----------------------------------------------------|
| `CodeName`      | [اسم رمز مصنف مشروع VBA](#vba-and-macros)    |
| `date1904`      | الحقبة: 0/false لنظام 1900، 1/true لنظام 1904|
| `filterPrivacy` | تحذير أو إزالة المعلومات الشخصية عند الحفظ    |

### ميزات المستند

حتى بالنسبة للميزات الأساسية مثل تخزين التاريخ، تخزّن تنسيقات Excel الرسمية المحتوى نفسه بطرق مختلفة. يُتوقع من المحللات (parsers) التحويل من تمثيل تنسيق الملف الأساسي إلى تنسيق الجداول الممتدة الشائع (Common Spreadsheet Format). ويُتوقع من الكتّاب (writers) التحويل من CSF مرة أخرى إلى تنسيق الملف الأساسي.

#### الصيغ

يتم تخزين سلسلة الصيغة بنمط A1 في الحقل `f`. وعلى الرغم من أن تنسيقات الملفات المختلفة تخزّن الصيغ بطرق مختلفة، فإن التنسيقات يتم تحويلها. وعلى الرغم من أن بعض التنسيقات تخزّن الصيغ بعلامة يساوي في البداية، فإن صيغ CSF لا تبدأ بـ `=`.

<details>
  <summary><b>دعم تنسيق ملفات الصيغ</b> (انقر للإظهار)</summary>

| تمثيل التخزين            | التنسيقات                  | قراءة | كتابة |
|:-----------------------|:-------------------------|:-----:|:-----:|
| سلاسل بنمط A1          | XLSX                     |   ✔   |   ✔   |
| سلاسل بنمط RC          | XLML والنص العادي        |   ✔   |   ✔   |
| صيغ BIFF المحللة       | XLSB وجميع تنسيقات XLS   |   ✔   |       |
| صيغ OpenFormula        | ODS/FODS/UOS             |   ✔   |   ✔   |
| صيغ Lotus المحللة      | جميع تنسيقات Lotus WK_   |   ✔   |       |

نظرًا لأن Excel يمنع الخلايا المسماة من التعارض مع أسماء مراجع الخلايا بنمط A1 أو RC، فإن تحويلًا بالتعبيرات النمطية (regex) (ليس بسيطًا تمامًا) ممكن. يجب فك صيغ BIFF المحللة وصيغ Lotus المحللة بشكل صريح. ويمكن تحويل صيغ OpenFormula باستخدام التعبيرات النمطية.

يتم فك ضغط الصيغ المشتركة، وتحتوي كل خلية على الصيغة المقابلة لخليةها. لا تحاول أدوات الكتابة عمومًا إنشاء صيغ مشتركة.
</details>

**الصيغ أحادية الخلية**

بالنسبة للصيغ البسيطة، يمكن ضبط المفتاح `f` للخلية المطلوبة على نص الصيغة الفعلي. تمثل ورقة العمل هذه `A1=1` و`A2=2` و`A3=A1+A2`:```js
var worksheet = {
  "!ref": "A1:A3",
  A1: { t:'n', v:1 },
  A2: { t:'n', v:2 },
  A3: { t:'n', v:3, f:'A1+A2' }
};
```
الأدوات المساعدة مثل `aoa_to_sheet` ستقبل كائنات الخلايا بدلاً من القيم:```js
var worksheet = XLSX.utils.aoa_to_sheet([
  [ 1 ], // A1
  [ 2 ], // A2
  [ {t: "n", v: 3, f: "A1+A2"} ] // A3
]);
```
الخلايا التي تحتوي على إدخالات معادلات ولكن بدون قيمة سيتم تسلسلها بطريقة يتعرف عليها Excel
وأدوات جداول البيانات الأخرى.  لن تقوم هذه المكتبة تلقائيًا
بحساب نتائج المعادلات!  على سبيل المثال، ستتضمن ورقة العمل التالية
دالة `BESSELJ` ولكن النتيجة لن تكون متاحة في JavaScript:```js
var worksheet = XLSX.utils.aoa_to_sheet([
  [ 3.14159, 2 ], // Row "1"
  [ { t:'n', f:'BESSELJ(A1,B1)' } ] // Row "2" will be calculated on file open
}
```
إذا كانت النتائج الفعلية مطلوبة في JS، فإن [SheetJS Pro](https://sheetjs.com/pro)
يوفّر مكوّن حاسبة صيغ لتقييم التعبيرات، وتحديث القيم والخلايا التابعة، وتحديث مصنّفات كاملة.


**صيغ المصفوفات**

_تعيين صيغة مصفوفة_```js
XLSX.utils.sheet_set_array_formula(worksheet, range, formula);
```
تُخزَّن الصيغ المصفوفية في الخلية العلوية اليسرى من كتلة المصفوفة.  تحتوي جميع خلايا الصيغة المصفوفية على حقل `F` يطابق النطاق.  يمكن تمييز صيغة الخلية الواحدة عن الصيغة العادية بوجود حقل `F`.

على سبيل المثال، تعيين الخلية `C1` إلى الصيغة المصفوفية `{=SUM(A1:A3*B1:B3)}`:```js
// API function
XLSX.utils.sheet_set_array_formula(worksheet, "C1", "SUM(A1:A3*B1:B3)");

// ... OR raw operations
worksheet['C1'] = { t:'n', f: "SUM(A1:A3*B1:B3)", F:"C1:C1" };
```
بالنسبة لصيغة مصفوفة متعددة الخلايا، تحتوي كل خلية على نفس نطاق المصفوفة ولكن فقط
الخلية الأولى تحدد الصيغة.  ضع في اعتبارك `D1:D3=A1:A3*B1:B3`:```js
// API function
XLSX.utils.sheet_set_array_formula(worksheet, "D1:D3", "A1:A3*B1:B3");

// ... OR raw operations
worksheet['D1'] = { t:'n', F:"D1:D3", f:"A1:A3*B1:B3" };
worksheet['D2'] = { t:'n', F:"D1:D3" };
worksheet['D3'] = { t:'n', F:"D1:D3" };
```
من المتوقع أن تتحقق الأدوات والكتّاب من وجود حقل `F` وتتجاهل أي عنصر صيغة محتمل `f` في الخلايا غير الخلية البادئة. وليس من المتوقع أن يقوموا بالتحقق من صحة الصيغ!


**صيغ المصفوفات الديناميكية**

_تعيين صيغة مصفوفة ديناميكية_```js
XLSX.utils.sheet_set_array_formula(worksheet, range, formula, true);
```
تم إطلاقها في عام 2020، وتُدعم صيغ المصفوفات الديناميكية في صيغ ملفات XLSX/XLSM وXLSB.
وهي ممثلة مثل صيغ المصفوفات العادية ولكنها تحتوي على بيانات تعريف خاصة للخلية
تشير إلى أن الصيغة يجب أن يُسمح لها بضبط النطاق.

يمكن تمييز صيغة المصفوفة بأنها ديناميكية عن طريق تعيين خاصية `D` الخاصة بالخلية إلى
true. النطاق `F` متوقع لكن يمكن تعيينه إلى الخلية الحالية:```js
// API function
XLSX.utils.sheet_set_array_formula(worksheet, "C1", "_xlfn.UNIQUE(A1:A3)", 1);

// ... OR raw operations
worksheet['C1'] = { t: "s", f: "_xlfn.UNIQUE(A1:A3)", F:"C1", D: 1 }; // dynamic
```
**التوطين مع أسماء الدوال**

تعمل SheetJS على مستوى الملف.  يخزّن Excel تعبيرات الصيغ باستخدام
أسماء الدوال الإنجليزية (الولايات المتحدة).  بالنسبة للمستخدمين غير الناطقين بالإنجليزية، يستخدم Excel
مجموعة مترجمة من أسماء الدوال.

على سبيل المثال، عندما يتم ضبط لغة الكمبيوتر والمنطقة على الفرنسية (فرنسا)،
يفسّر Excel `=SOMME(A1:C3)` كما لو أن `SOMME` هي دالة `SUM`.  ومع ذلك،
في الملف الفعلي، يخزّن Excel `SUM(A1:C3)`.

**الدوال "المستقبلية" المسبوقة ببادئة**

الدوال التي تم تقديمها في إصدارات أحدث من Excel تكون مسبوقة بـ `_xlfn.` عند
تخزينها في الملفات.  عند كتابة تعبيرات الصيغ باستخدام هذه الدوال،
تكون البادئة مطلوبة لتحقيق أقصى توافق:```js
// Broadest compatibility
XLSX.utils.sheet_set_array_formula(worksheet, "C1", "_xlfn.UNIQUE(A1:A3)", 1);

// Can cause errors in spreadsheet software
XLSX.utils.sheet_set_array_formula(worksheet, "C1", "UNIQUE(A1:A3)", 1);
```
عند قراءة ملف، يحافظ خيار `xlfn` على البادئات.

<details>
  <summary><b> الدوال التي تتطلب بادئة `_xlfn.`</b> (انقر للعرض)</summary>

هذه القائمة في تزايد مع كل إصدار من Excel.```
ACOT
ACOTH
AGGREGATE
ARABIC
BASE
BETA.DIST
BETA.INV
BINOM.DIST
BINOM.DIST.RANGE
BINOM.INV
BITAND
BITLSHIFT
BITOR
BITRSHIFT
BITXOR
BYCOL
BYROW
CEILING.MATH
CEILING.PRECISE
CHISQ.DIST
CHISQ.DIST.RT
CHISQ.INV
CHISQ.INV.RT
CHISQ.TEST
COMBINA
CONFIDENCE.NORM
CONFIDENCE.T
COT
COTH
COVARIANCE.P
COVARIANCE.S
CSC
CSCH
DAYS
DECIMAL
ERF.PRECISE
ERFC.PRECISE
EXPON.DIST
F.DIST
F.DIST.RT
F.INV
F.INV.RT
F.TEST
FIELDVALUE
FILTERXML
FLOOR.MATH
FLOOR.PRECISE
FORMULATEXT
GAMMA
GAMMA.DIST
GAMMA.INV
GAMMALN.PRECISE
GAUSS
HYPGEOM.DIST
IFNA
IMCOSH
IMCOT
IMCSC
IMCSCH
IMSEC
IMSECH
IMSINH
IMTAN
ISFORMULA
ISOMITTED
ISOWEEKNUM
LAMBDA
LET
LOGNORM.DIST
LOGNORM.INV
MAKEARRAY
MAP
MODE.MULT
MODE.SNGL
MUNIT
NEGBINOM.DIST
NORM.DIST
NORM.INV
NORM.S.DIST
NORM.S.INV
NUMBERVALUE
PDURATION
PERCENTILE.EXC
PERCENTILE.INC
PERCENTRANK.EXC
PERCENTRANK.INC
PERMUTATIONA
PHI
POISSON.DIST
QUARTILE.EXC
QUARTILE.INC
QUERYSTRING
RANDARRAY
RANK.AVG
RANK.EQ
REDUCE
RRI
SCAN
SEC
SECH
SEQUENCE
SHEET
SHEETS
SKEW.P
SORTBY
STDEV.P
STDEV.S
T.DIST
T.DIST.2T
T.DIST.RT
T.INV
T.INV.2T
T.TEST
UNICHAR
UNICODE
UNIQUE
VAR.P
VAR.S
WEBSERVICE
WEIBULL.DIST
XLOOKUP
XOR
Z.TEST
```
</details>

#### خصائص الصفوف والأعمدة

<details>
  <summary><b>دعم التنسيقات</b> (انقر للعرض)</summary>

**خصائص الصفوف**: XLSX/M, XLSB, BIFF8 XLS, XLML, SYLK, DOM, ODS

**خصائص الأعمدة**: XLSX/M, XLSB, BIFF8 XLS, XLML, SYLK, DOM

</details>


لا يتم استخراج خصائص الصفوف والأعمدة افتراضيًا عند القراءة من ملف
ولا يتم حفظها افتراضيًا عند الكتابة إلى ملف. يجب تمرير الخيار
`cellStyles: true` إلى دالة القراءة أو الكتابة ذات الصلة.

_خصائص الأعمدة_

مصفوفة `!cols` في كل ورقة عمل، إذا كانت موجودة، هي مجموعة من كائنات `ColInfo`
التي تمتلك الخصائص التالية:```typescript
type ColInfo = {
  /* visibility */
  hidden?: boolean; // if true, the column is hidden

  /* column width is specified in one of the following ways: */
  wpx?:    number;  // width in screen pixels
  width?:  number;  // width in Excel's "Max Digit Width", width*256 is integral
  wch?:    number;  // width in characters

  /* other fields for preserving features from files */
  level?:  number;  // 0-indexed outline / group level
  MDW?:    number;  // Excel's "Max Digit Width" unit, always integral
};
```
_Row Properties_

مصفوفة `!rows` في كل ورقة عمل، إذا كانت موجودة، هي مجموعة من كائنات `RowInfo`
التي تحتوي على الخصائص التالية:```typescript
type RowInfo = {
  /* visibility */
  hidden?: boolean; // if true, the row is hidden

  /* row height is specified in one of the following ways: */
  hpx?:    number;  // height in screen pixels
  hpt?:    number;  // height in points

  level?:  number;  // 0-indexed outline / group level
};
```
_اصطلاح مستويات المخطط التفصيلي / المجموعات_

تعرض واجهة Excel مستوى المخطط التفصيلي الأساسي كـ `1` والحد الأقصى كـ `8`.
باتباع اصطلاحات JS، يستخدم SheetJS مستويات مخطط تفصيلي مفهرسة من الصفر، حيث يكون
مستوى المخطط الأساسي هو `0` والحد الأقصى هو `7`.

<details>
  <summary><b>لماذا توجد ثلاثة أنواع للعرض؟</b> (اضغط للإظهار)</summary>

هناك ثلاثة أنواع مختلفة للعرض تُقابل الطرق الثلاث المختلفة
التي تخزّن بها جداول البيانات أعمدة العروض:

تستخدم SYLK وغيرها من صيغ النص العادي عدد الأحرف الخام. كانت الأدوات المعاصرة
مثل Visicalc وMultiplan قائمة على الأحرف. وبما أن الأحرف كانت بنفس العرض،
كان يكفي تخزين عدد. استمر هذا التقليد في
صيغ BIFF.

حاولت SpreadsheetML (2003) التوافق مع HTML من خلال التوحيد على عدد بكسلات الشاشة
في الملف بأكمله. تستخدم أعمدة العروض وارتفاعات الصفوف والقياسات الأخرى
البكسلات. عندما لا تتطابق أعداد البكسل والأحرف، يقوم Excel بتقريب القيم.

يخزّن XLSX داخليًا أعمدة العروض في صيغة "أقصى عرض للرقم" (Max Digit Width) الغامضة.
أقصى عرض للرقم هو عرض أكبر رقم عند عرضه (عمومًا يكون الحرف
"0" هو الأوسع). يجب أن يكون العرض الداخلي مضاعفًا صحيحًا
للعرض مقسومًا على 256. يصف ECMA-376 صيغة للتحويل
بين البكسلات والعرض الداخلي. وهذا يمثل نهجًا هجينًا.

تحاول دوال القراءة تعبئة الخصائص الثلاث جميعها. ستحاول دوال الكتابة
تدوير القيم المحددة إلى النوع المطلوب. لتجنب التعارضات المحتملة،
يجب حذف الخصائص الأخرى أولاً عند المعالجة. على سبيل المثال،
عند تغيير عرض البكسل، احذف خصائص `wch` و `width`.

</details>

<details>
  <summary><b>تفاصيل التنفيذ</b> (اضغط للإظهار)</summary>

_ارتفاعات الصفوف_

يخزّن Excel داخليًا ارتفاعات الصفوف بالنقاط. الدقة الافتراضية هي 72 DPI
أو 96 PPI، لذا يجب أن يتطابق حجم البكسل مع حجم النقطة. بالنسبة للدقات المختلفة
قد لا يتطابقان، لذلك تفصل المكتبة بين المفهومين.

على الرغم من توفّر جميع المعلومات، يُتوقّع من دوال الكتابة
اتباع ترتيب الأولوية التالي:

1) استخدام ارتفاع البكسل `hpx` إذا كان متاحًا
2) استخدام ارتفاع النقطة `hpt` إذا كان متاحًا

_عروض الأعمدة_

في ظل هذه القيود، من الممكن تحديد MDW دون
فحص الخط فعليًا! تخمّن أدوات التحليل عرض البكسل بالتحويل من العرض
إلى بكسلات والعودة مرة أخرى، مع التكرار لكل قيم MDW الممكنة واختيار MDW الذي
يقلل الخطأ. يخزّن XLML في الواقع عرض البكسل، لذا يعمل التخمين
في الاتجاه المعاكس.

على الرغم من توفّر جميع المعلومات، يُتوقّع من دوال الكتابة
اتباع ترتيب الأولوية التالي:

1) استخدام الحقل `width` إذا كان متاحًا
2) استخدام عرض البكسل `wpx` إذا كان متاحًا
3) استخدام عدد الأحرف `wch` إذا كان متاحًا

</details>

#### تنسيقات الأرقام

يتم إنتاج النص المنسّق `cell.w` لكل خلية من تنسيق `cell.v` و`cell.z`.
إذا لم يتم تحديد التنسيق، يُستخدم تنسيق Excel العام `General`.
يمكن تحديد التنسيق إما كسلسلة نصية أو كمؤشر إلى جدول
التنسيقات. يُتوقّع من أدوات التحليل تعبئة `workbook.SSF` بجدول تنسيقات
الأرقام. ويُتوقّع من أدوات الكتابة تسلسل الجدول.

يجب على الأدوات المخصصة التأكد من أن الجدول المحلي يحتوي على كل سلسلة تنسيق
مستخدمة في مكان ما داخل الجدول. تفرض اصطلاحات Excel أن تبدأ التنسيقات المخصصة
من الفهرس 164. المثال التالي ينشئ تنسيقًا مخصصًا من الصفر:

<details>
  <summary><b>ورقة عمل جديدة بتنسيق مخصص</b> (اضغط للإظهار)</summary>```js
var wb = {
  SheetNames: ["Sheet1"],
  Sheets: {
    Sheet1: {
      "!ref":"A1:C1",
      A1: { t:"n", v:10000 },                    // <-- General format
      B1: { t:"n", v:10000, z: "0%" },           // <-- Builtin format
      C1: { t:"n", v:10000, z: "\"T\"\ #0.00" }  // <-- Custom format
    }
  }
}
```
</details>

تختلف القواعد قليلاً عن كيفية عرض Excel لتنسيقات الأرقام المخصصة.
على وجه الخصوص، يجب وضع الأحرف الحرفية بين علامتي اقتباس مزدوجتين أو أن يسبقها شرطة مائلة للخلف. لمزيد من المعلومات، راجع مقالة توثيق Excel `Create or delete a custom number format` أو ECMA-376 18.8.31 (Number Formats)


<details>
  <summary><b>تنسيقات الأرقام الافتراضية</b> (انقر للإظهار)</summary>

التنسيقات الافتراضية مدرجة في ECMA-376 18.8.30:

| المعرّف | التنسيق                     |
|---:|:---------------------------|
|  0 | `General`                  |
|  1 | `0`                        |
|  2 | `0.00`                     |
|  3 | `#,##0`                    |
|  4 | `#,##0.00`                 |
|  9 | `0%`                       |
| 10 | `0.00%`                    |
| 11 | `0.00E+00`                 |
| 12 | `# ?/?`                    |
| 13 | `# ??/??`                  |
| 14 | `m/d/yy` (انظر أدناه)       |
| 15 | `d-mmm-yy`                 |
| 16 | `d-mmm`                    |
| 17 | `mmm-yy`                   |
| 18 | `h:mm AM/PM`               |
| 19 | `h:mm:ss AM/PM`            |
| 20 | `h:mm`                     |
| 21 | `h:mm:ss`                  |
| 22 | `m/d/yy h:mm`              |
| 37 | `#,##0 ;(#,##0)`           |
| 38 | `#,##0 ;[Red](#,##0)`      |
| 39 | `#,##0.00;(#,##0.00)`      |
| 40 | `#,##0.00;[Red](#,##0.00)` |
| 45 | `mm:ss`                    |
| 46 | `[h]:mm:ss`                |
| 47 | `mmss.0`                   |
| 48 | `##0.0E+0`                 |
| 49 | `@`                        |

</details>

التنسيق 14 (`m/d/yy`) يتم توطينه بواسطة Excel: حتى إذا كان الملف يحدد هذا التنسيق الرقمي، فسيتم عرضه بشكل مختلف اعتمادًا على إعدادات النظام. يكون ذلك منطقيًا عندما يكون منتج الملف ومستهلكه في نفس الإعدادات المحلية، لكن هذا ليس الحال دائمًا عبر الإنترنت. للتغلب على هذا الغموض، تقبل دوال التحليل الخيار `dateNF` لتجاوز تفسير سلسلة التنسيق المحددة هذه.

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

<details>
  <summary><b>دعم التنسيقات</b> (انقر للإظهار)</summary>

**روابط الخلايا التشعبية**: XLSX/M, XLSB, BIFF8 XLS, XLML, ODS

**تلميحات الأدوات**: XLSX/M, XLSB, BIFF8 XLS, XLML

</details>

تُخزَّن الروابط التشعبية في المفتاح `l` لكائنات الخلايا. حقل `Target` في كائن الرابط التشعبي هو هدف الرابط، بما في ذلك جزء URI. تُخزَّن تلميحات الأدوات في حقل `Tooltip` وتظهر عند تحريك مؤشر الماوس فوق النص.

على سبيل المثال، المقتطف التالي ينشئ رابطًا من الخلية `A3` إلى <https://sheetjs.com> مع التلميح `"Find us @ SheetJS.com!"`:```js
ws['A1'].l = { Target:"https://sheetjs.com", Tooltip:"Find us @ SheetJS.com!" };
```
لاحظ أن Excel لا ينسّق الروابط التشعبية تلقائيًا -- سيتم عرضها عمومًا
كنص عادي.

_الروابط البعيدة_

يمكن استخدام روابط HTTP / HTTPS مباشرة:```js
ws['A2'].l = { Target:"https://docs.sheetjs.com/#hyperlinks" };
ws['A3'].l = { Target:"http://localhost:7262/yes_localhost_works" };
```
يدعم Excel أيضًا روابط البريد الإلكتروني `mailto` مع سطر الموضوع:```js
ws['A4'].l = { Target:"mailto:[email protected]" };
ws['A5'].l = { Target:"mailto:[email protected]?subject=Test Subject" };
```
_الروابط المحلية_

يجب أن تستخدم الروابط إلى المسارات المطلقة مخطط `file://` URI:```js
ws['B1'].l = { Target:"file:///SheetJS/t.xlsx" }; /* Link to /SheetJS/t.xlsx */
ws['B2'].l = { Target:"file:///c:/SheetJS.xlsx" }; /* Link to c:\SheetJS.xlsx */
```
يمكن تحديد الروابط إلى المسارات النسبية بدون مخطط:```js
ws['B3'].l = { Target:"SheetJS.xlsb" }; /* Link to SheetJS.xlsb */
ws['B4'].l = { Target:"../SheetJS.xlsm" }; /* Link to ../SheetJS.xlsm */
```
المسارات النسبية لها سلوك غير محدد في تنسيق SpreadsheetML 2003.  Excel
2019 سيتعامل مع علامة الأصل `..\` كمستويين لأعلى.

_الروابط الداخلية_

الروابط التي يكون هدفها خلية أو نطاقًا أو اسمًا معرفًا في نفس المصنف
("الروابط الداخلية") يتم تمييزها بحرف هاش في البداية:```js
ws['C1'].l = { Target:"#E2" }; /* Link to cell E2 */
ws['C2'].l = { Target:"#Sheet2!E2" }; /* Link to cell E2 in sheet Sheet2 */
ws['C3'].l = { Target:"#SomeDefinedName" }; /* Link to Defined Name */
```
#### تعليقات الخلايا

تعليقات الخلايا هي كائنات مخزنة في مصفوفة `c` داخل كائنات الخلايا. وتنقسم المحتويات الفعلية للتعليق إلى كتل بناءً على مؤلف التعليق. حقل `a` في كل كائن تعليق هو مؤلف التعليق وحقل `t` هو تمثيل النص العادي.

على سبيل المثال، المقتطف التالي يضيف تعليق خلية إلى الخلية `A1`:```js
if(!ws.A1.c) ws.A1.c = [];
ws.A1.c.push({a:"SheetJS", t:"I'm a little comment, short and stout!"});
```
ملاحظة: يفرض تنسيق XLSB حدًا أقصى يبلغ 54 حرفًا لاسم المؤلف. قد تسبب الأسماء الأطول من 54 حرفًا مشكلات مع التنسيقات الأخرى.

لتعليم تعليق كأنه مخفي بشكل طبيعي، اضبط خاصية `hidden`:```js
if(!ws.A1.c) ws.A1.c = [];
ws.A1.c.push({a:"SheetJS", t:"This comment is visible"});

if(!ws.A2.c) ws.A2.c = [];
ws.A2.c.hidden = true;
ws.A2.c.push({a:"SheetJS", t:"This comment will be hidden"});
```
_التعليقات المترابطة_

تم تقديمها في Excel 365، وهي عبارة عن مقتطفات تعليقات نصية عادية تحتوي على بيانات تعريف للمؤلف ومراجع للعنصر الأصلي. وهي مدعومة في XLSX وXLSB.

لتمييز تعليق كمترابط، يجب أن يحتوي كل جزء من أجزاء التعليق على خاصية `T` بقيمة true:```js
if(!ws.A1.c) ws.A1.c = [];
ws.A1.c.push({a:"SheetJS", t:"This is not threaded"});

if(!ws.A2.c) ws.A2.c = [];
ws.A2.c.hidden = true;
ws.A2.c.push({a:"SheetJS", t:"This is threaded", T: true});
ws.A2.c.push({a:"JSSheet", t:"This is also threaded", T: true});
```
لا توجد بيانات وصفية لـ Active Directory أو Office 365 مرتبطة بالمؤلفين في سلسلة رسائل.

#### رؤية الورقة

يتيح Excel إخفاء الأوراق في شريط علامات التبويب السفلي.  يتم تخزين بيانات الورقة في
الملف ولكن الواجهة لا توفرها بسهولة.  تظهر الأوراق المخفية القياسية
عبر قائمة "Unhide".  يحتوي Excel أيضًا على أوراق "مخفية جدًا" والتي
لا يمكن إظهارها من القائمة.  وهي متاحة فقط عبر محرر VB!

يتم تخزين إعداد الرؤية في الخاصية `Hidden` لمصفوفة خصائص الأوراق.

<details>
  <summary><b>مزيد من التفاصيل</b> (انقر للإظهار)</summary>

| القيمة | التعريف  |
|:-----:|:------------|
|   0   | مرئية     |
|   1   | مخفية      |
|   2   | مخفية جدًا |

باستخدام <https://rawgit.com/SheetJS/test_files/HEAD/sheet_visibility.xlsx>:```js
> wb.Workbook.Sheets.map(function(x) { return [x.name, x.Hidden] })
[ [ 'Visible', 0 ], [ 'Hidden', 1 ], [ 'VeryHidden', 2 ] ]
```
لا تدعم التنسيقات غير الخاصة بـ Excel حالة الإخفاء الشديد.  أفضل طريقة لاختبار ما إذا كانت الورقة مرئية هي التحقق من أن الخاصية `Hidden` تمثل قيمة منطقية صحيحة:```js
> wb.Workbook.Sheets.map(function(x) { return [x.name, !x.Hidden] })
[ [ 'Visible', true ], [ 'Hidden', false ], [ 'VeryHidden', false ] ]
```
</details>

#### VBA والماكرو

يتم تخزين ماكرو VBA في كتلة بيانات خاصة يتم عرضها في خاصية `vbaraw` لكائن المصنف عندما يكون خيار `bookVBA` هو `true`. وهي مدعومة في صيغ `XLSM` و `XLSB` و `BIFF8 XLS`. تقوم أدوات الكتابة المدعومة للصيغ بإدراج كتل البيانات تلقائيًا إذا كانت موجودة في المصنف وتربطها بأسماء أوراق العمل.

<details>
	<summary><b>أسماء الأكواد المخصصة</b> (انقر للعرض)</summary>

يتم تخزين اسم كود المصنف في `wb.Workbook.WBProps.CodeName`. افتراضيًا، يكتب Excel `ThisWorkbook` أو عبارة مترجمة مثل `DieseArbeitsmappe`. يتم تخزين أسماء أكواد أوراق العمل وأوراق المخططات في كائن خصائص ورقة العمل عند `wb.Workbook.Sheets[i].CodeName`. يتم تجاهل أوراق الماكرو وأوراق الحوار.

تحافظ أدوات القراءة والكتابة على أسماء الأكواد، ولكن يجب ضبطها يدويًا عند إضافة كتلة VBA إلى مصنف مختلف.

</details>

<details>
	<summary><b>أوراق الماكرو</b> (انقر للعرض)</summary>

دعمت الإصدارات الأقدم من Excel أيضًا نوع ورقة "ماكرو" غير VBA يقوم بتخزين أوامر الأتمتة. يتم عرض هذه الأوراق في كائنات ذات خاصية `!type` مضبوطة على `"macro"`.

</details>

<details>
	<summary><b>اكتشاف الماكرو في المصنفات</b> (انقر للعرض)</summary>

سيتم ضبط حقل `vbaraw` فقط إذا كانت الماكرو موجودة، لذا يكون الاختبار بسيطًا:
</details>```js
function wb_has_macro(wb/*:workbook*/)/*:boolean*/ {
	if(!!wb.vbaraw) return true;
	const sheets = wb.SheetNames.map((n) => wb.Sheets[n]);
	return sheets.some((ws) => !!ws && ws['!type']=='macro');
}
```
</details>

## خيارات التحليل

دوال التصدير `read` و `readFile` تقبل وسيط خيارات:

| Option Name | Default | Description                                          |
| :---------- | ------: | :--------------------------------------------------- |
|`type`       |         | تشفير بيانات الإدخال (انظر نوع الإدخال أدناه)          |
|`raw`        | false   | إذا كان صحيحًا، فلن يحلل تحليل النص العادي القيم ** |
|`codepage`   |         | إذا تم تحديده، استخدم صفحة الرموز عند الاقتضاء **      |