التسميات
`labels.list` و`list_all` و`iterate` و`list_colors` و`get` و`create` و`update` و`delete`.
كل الدوالّ
page = client.labels.list(limit: 50)every = client.labels.list_allcolors = client.labels.list_colorsputs page.items.size, every.size, colors.size client.labels.iterate do |row| puts "#{row[:name]} #{row[:threadCount]}"end created = client.labels.create( name: "Invoices", color: {backgroundColor: "gradient:sunset"}) client.labels.update(created[:id], name: "Invoices 2027")client.labels.update(created[:id], color: {backgroundColor: "#3B82F6"}) label = client.labels.get(created[:id])puts label[:name], label.dig(:color, :backgroundColor) client.labels.delete(created[:id])يعيد list صفحة OpenEmail::Page واحدة من التسميات مرتّبة حسب الاسم، ويمر list_all وiterate على كل الصفحات. ويعيد list_all مصفوفة Array واحدة، ويمرّر iterate تسمية واحدة في كل مرة إلى كتلة، أو يعيد Enumerator دونها. وكل تسمية Hash بمفاتيح من نوع Symbol يحمل لونها وthreadCount ووقت إنشائها وآخر تغيير لها. ويعيد list_colors لوحة ألوان التطبيق، أربعة عشر لونًا مصمتًا وسبعة تدرّجات، في صورة Array بسيطة من Hash دون ترقيم صفحات. وtype دائمًا user. والمعرّف مأخوذ من الاسم الذي أُنشئت به التسمية، فـ Invoices هو USER_INVOICES، ولا يتغيّر أبدًا.
حقول create وupdate وسائط مسمّاة أو Hash واحد، وتحتفظ بأسماء API، فاللون هو color: {backgroundColor: "#3B82F6"}.
التسمية تخصّ مساحة العمل، فإعادة تسميتها أو تغيير لونها أو حذفها يغيّرها لكل عضو وكل مفتاح. ويضع threads.update التسميات على محادثة ويزيلها، ويسرد client.threads.list(folder: "USER_INVOICES") كل محادثة تحمل تسمية. وتشرح صفحة المحادثات الأمرين كليهما.
المعاملات: labels.create و labels.update
nameString- الاسم المعروض للتسمية، تُشذَّب فراغاته قبل قياسه، فالحد من 1 إلى 225 حرفًا بعد التشذيب. وهو إلزامي في `create` واختياري في `update`، حيث يُبقي إغفاله الاسم كما هو. والفراغات وحدها تعطي 422. والاسم الذي تحمله تسمية أخرى بالفعل، مع تجاهل حالة الأحرف، يعطي 409 `label_name_taken`، يُرفع في صورة `OpenEmail::ConflictError`. ويرفض `create` بمجرد أن تضم مساحة العمل 50 تسمية، بالخطأ 422 `label_limit_reached`، يُرفع في صورة `OpenEmail::ValidationError`.
colorHash or nil- اختياري في كلا الاستدعاءين. إغفاله في `update` يُبقي اللون المخزَّن، و`color: nil` يمسحه. والمتن صارم، فمفتاح قريب الشبه مثل `colour:` يعطي 422 بدل عملية صامتة بلا أثر.
color.backgroundColorStringمطلوب- لون hex (`#RGB` أو `#RGBA` أو `#RRGGBB` أو `#RRGGBBAA`، ويُخزَّن بأحرف كبيرة) أو رمز تدرّج: `gradient:sunset` أو `gradient:ember` أو `gradient:meadow` أو `gradient:lagoon` أو `gradient:aurora` أو `gradient:berry` أو `gradient:midnight`. والسلسلة الفارغة تعني بلا لون، وأي شيء آخر يعطي 422 `invalid_parameter`.
color.textColorString- يُقبل ويُتجاهل. يُحسب الحبر من `backgroundColor`، بالطريقة نفسها التي يتبعها التطبيق.
الاستجابة: تسمية
التسمية Hash بمفاتيح من نوع Symbol، فيقرأ label[:threadCount] العدد، ويقرأ label.dig(:color, :backgroundColor) اللون ويعطي nil حين لا يكون للتسمية لون.
objectString- دائمًا السلسلة `label`. ويعيد `create` و`update` الـ Hash نفسه، مقروءًا كما هو مخزَّن.
idString- معرّف التسمية، وهو ما يأخذه `get` و`update` و`delete` و`threads.update`. ولا يتغيّر أبدًا، حتى بعد إعادة التسمية.
nameString- ما يراه المستخدم.
typeString- دائمًا `user`. فتسميات النظام لا تُقدَّم هنا أبدًا، ومعرّف نظام في `get` يعطي 404، يُرفع في صورة `OpenEmail::NotFoundError`.
colorHash or nil- يكون nil حين لا يكون للتسمية لون.
color.backgroundColorString- اللون المخزَّن: قيمة ست عشرية أو رمز تدرّج. ويعطي `list_colors` طرفَي التدرّج.
color.textColorString- الحبر الذي يرسمه التطبيق على اللون، `#18181B` أو `#FFFFFF`، ويُحسب على الخادم ولا يُخزَّن.
threadCountInteger- عدد المحادثات التي تحمل التصنيف الآن. وبالنسبة إلى مفتاح مقيّد بعناوين معيّنة لا تُعدّ إلا المحادثات المُسلَّمة إليها.
createdAtString or nil- متى أُنشئت التسمية، بصيغة ISO 8601، أو nil لتسمية أُنشئت قبل أن تُسجَّل هذه الأوقات.
updatedAtString or nil- آخر إعادة تسمية أو تغيير لون، بصيغة ISO 8601، أو nil لتسمية أُنشئت قبل أن تُسجَّل هذه الأوقات.
الاستجابة: عيّنة لون (labels.list_colors)
kindString- ما إذا كانت العيّنة لونًا واحدًا أو تدرّجًا: `solid` أو `gradient`.
nameString- اسم المربّع، مثل `red` أو `sunset`.
valueString- ما يُرسل بوصفه `color.backgroundColor` لاستخدام هذا المربّع.
solidString- قيمة hex واحدة للمواضع التي لا يمكن رسم تدرّج فيها. وهي نفسها `value` في اللون المصمت.
fromString or nil- حيث يبدأ التدرّج، مرسومًا بزاوية 135 درجة. ويكون nil في اللون المصمت.
toString or nil- حيث ينتهي التدرّج. ويكون nil في اللون المصمت.
textColorString- الحبر الذي يرسمه التطبيق على هذا المربّع.