গুগল ডক্স এপিআই কার্যকরভাবে ব্যবহার করার জন্য, আপনাকে একটি গুগল ডক্স ডকুমেন্টের গঠন এবং ডকুমেন্টটি যে উপাদানগুলো দিয়ে তৈরি, সেইসাথে তাদের মধ্যকার সম্পর্ক বুঝতে হবে। এই পৃষ্ঠাটিতে এই বিষয়গুলোর একটি বিশদ বিবরণ দেওয়া হয়েছে:
- নথির উপাদানগুলির একটি ধারণাগত মডেল
- ডকস এপিআই কীভাবে এই উপাদানগুলিকে উপস্থাপন করে
- উপাদানগুলির স্টাইলিং বৈশিষ্ট্য
শীর্ষ-স্তরের উপাদান
গুগল ডক্স-এর সবচেয়ে বাইরের কন্টেইনার এলিমেন্ট হলো একটি ডকুমেন্ট । এটিই সেই ইউনিট যা গুগল ড্রাইভে সেভ করা, অন্যান্য ব্যবহারকারীদের সাথে শেয়ার করা এবং টেক্সট ও ছবি দিয়ে আপডেট করা যায়।
একটি documents রিসোর্সের শীর্ষ-স্তরের উপাদানগুলোর মধ্যে রয়েছে এর Tab , SuggestionsViewMode এবং অন্যান্য অ্যাট্রিবিউটসমূহ:
document: {
title: ... ,
revisionId: ... ,
documentId: ... ,
suggestionsViewMode: ... ,
tabs: ...
}
ট্যাব
একটি একক ডকুমেন্টে একাধিক ট্যাব থাকতে পারে, যেগুলোর টেক্সট-স্তরের বিষয়বস্তু ভিন্ন ভিন্ন হয়। ডকুমেন্টের ` tabs প্রপার্টি হলো Tab অবজেক্টের একটি অনুক্রম। একটি Tab নিম্নলিখিত ফিল্ডগুলো দ্বারা গঠিত:
-
TabProperties: এতে একটি ট্যাবের অ্যাট্রিবিউটসমূহ, যেমন ID, title, এবং index, থাকে। -
childTabs: একটি ট্যাবের চাইল্ড ট্যাবগুলো (অর্থাৎ, এর ঠিক নিচে থাকা ট্যাবগুলো) প্রদর্শন করে। -
DocumentTab: একটি ট্যাবের পাঠ্য বিষয়বস্তুকে বোঝায়।
পরবর্তী বিভাগগুলিতে ডকুমেন্ট ট্যাবের স্তরবিন্যাস সম্পর্কে একটি সংক্ষিপ্ত বিবরণ দেওয়া হয়েছে; ট্যাব JSON উপস্থাপনাটিতে আরও বিস্তারিত তথ্যও রয়েছে। ট্যাব বৈশিষ্ট্য সম্পর্কে আরও তথ্যের জন্য ‘ট্যাব নিয়ে কাজ করুন’ দেখুন।
ডকুমেন্টের মূল অংশের ( Body content) বাইরে গ্লোবাল ডকুমেন্ট ট্যাবের বৈশিষ্ট্যগুলো ব্যবহার করার জন্য, এক বা একাধিক ডকুমেন্ট টেমপ্লেট ব্যবহার করাই প্রায় সবসময় শ্রেয়, যেগুলোকে ভিত্তি করে আপনি প্রোগ্রাম্যাটিকভাবে নতুন ডকুমেন্ট তৈরি করতে পারেন। আরও তথ্যের জন্য, ‘Merge text into a document’ দেখুন।
শরীরের উপাদান
Body সাধারণত একটি ডকুমেন্টের ট্যাবগুলোর সম্পূর্ণ বিষয়বস্তু থাকে। যেসব আইটেম আপনি প্রোগ্রামগতভাবে ব্যবহার করতে পারেন বা করতে চাইতে পারেন, তার বেশিরভাগই Body কন্টেন্টের অন্তর্ভুক্ত এলিমেন্ট:
কাঠামোগত উপাদান
একটি StructuralElement এমন বিষয়বস্তু বর্ণনা করে যা ডকুমেন্টকে একটি কাঠামো প্রদান করে। Body বিষয়বস্তুটি হলো StructuralElement অবজেক্টের একটি অনুক্রম। একটি content element প্রতিটি StructuralElement অবজেক্টকে নিজস্ব রূপ দেয়, যেমনটি নিম্নলিখিত ডায়াগ্রামে দেখানো হয়েছে:
কাঠামোগত উপাদান এবং তাদের কন্টেন্ট অবজেক্টগুলোর মধ্যে ডকুমেন্টের সমস্ত ভিজ্যুয়াল উপাদান থাকে। এর মধ্যে রয়েছে টেক্সট, ইনলাইন ইমেজ এবং ফরম্যাটিং।
অনুচ্ছেদ কাঠামো
Paragraph হলো একটি StructuralElement যা একটি অনুচ্ছেদকে উপস্থাপন করে। এর একটি নির্দিষ্ট পরিসরের বিষয়বস্তু থাকে যা একটি নিউলাইন ক্যারেক্টার দ্বারা সমাপ্ত হয়। এটি নিম্নলিখিত অবজেক্টগুলো দ্বারা গঠিত:
-
ParagraphElement: একটি অনুচ্ছেদের বিষয়বস্তু বর্ণনা করে। -
ParagraphStyle: একটি ঐচ্ছিক উপাদান যা অনুচ্ছেদের জন্য স্টাইল বৈশিষ্ট্যগুলো সুস্পষ্টভাবে নির্ধারণ করে। -
Bullet: অনুচ্ছেদটি যদি কোনো তালিকার অংশ হয়, তবে এটি একটি ঐচ্ছিক উপাদান যা বুলেটের বৈশিষ্ট্য নির্ধারণ করে।
ParagraphElement অনেকটা StructuralElement মতোই কাজ করে। কিছু নির্দিষ্ট কন্টেন্ট এলিমেন্ট টাইপ (যেমন ColumnBreak এবং Equation ) তাদের নিজস্ব ParagraphElement কাস্টমাইজ করে, যা নিচের ডায়াগ্রামে দেখানো হয়েছে:
একটি সম্পূর্ণ ডকুমেন্ট কাঠামোর উদাহরণের জন্য, JSON ফরম্যাটে ডকুমেন্ট উদাহরণটি দেখুন। আউটপুটে আপনি অনেকগুলো মূল কাঠামোগত ও বিষয়বস্তুগত উপাদান দেখতে পাবেন, সেইসাথে পরবর্তী একটি বিভাগে বর্ণিত স্টার্ট ও এন্ড ইনডেক্সের ব্যবহারও দেখতে পাবেন।
টেক্সট চলে
TextRun হলো একটি ParagraphElement যা একই টেক্সট স্টাইলযুক্ত একটি অবিচ্ছিন্ন টেক্সট স্ট্রিংকে উপস্থাপন করে। একটি প্যারাগ্রাফে একাধিক টেক্সট রান থাকতে পারে, কিন্তু টেক্সট রানগুলো কখনোই প্যারাগ্রাফের সীমানা অতিক্রম করে না। আলাদা টেক্সট রান তৈরি করার জন্য একটি নিউলাইন ক্যারেক্টারের পরে বিষয়বস্তু বিভক্ত হয়ে যায়। উদাহরণস্বরূপ, নিম্নলিখিতের মতো একটি ছোট ডকুমেন্ট বিবেচনা করুন:
নিম্নলিখিত ডায়াগ্রামটি দেখায় যে আপনি পূর্ববর্তী ডকুমেন্টের অনুচ্ছেদগুলির ক্রমকে কীভাবে কল্পনা করতে পারেন, যেখানে প্রতিটির নিজস্ব TextRun এবং ঐচ্ছিক Bullet সেটিংস রয়েছে।
অটোটেক্সট
AutoText হলো একটি ParagraphElement যা টেক্সটের এমন একটি স্থানকে বোঝায়, যেখানে সময়ের সাথে সাথে পরিবর্তনশীল কন্টেন্ট দিয়ে গতিশীলভাবে প্রতিস্থাপন করা হয়। Docs-এ এটি পৃষ্ঠা নম্বরের জন্য ব্যবহৃত হয়।
শুরু এবং শেষ সূচক
যখন আপনি কোনো ডকুমেন্টের ট্যাবের বিষয়বস্তুতে কোনো পরিবর্তন আনেন, তখন প্রতিটি পরিবর্তন ডকুমেন্টের অভ্যন্তরে কোনো একটি নির্দিষ্ট স্থানে বা একটি পরিসর জুড়ে কার্যকর হয়। এই স্থান ও পরিসরগুলো ইনডেক্স ব্যবহার করে নির্দিষ্ট করা হয়, যা ধারণকারী ডকুমেন্ট সেগমেন্টের মধ্যে একটি অফসেটকে নির্দেশ করে। একটি সেগমেন্ট হলো মূল অংশ, হেডার, ফুটার বা ফুটনোট, যেখানে কাঠামোগত বা বিষয়বস্তুগত উপাদানগুলো থাকে। একটি সেগমেন্টের ভেতরের উপাদানগুলোর ইনডেক্স সেই সেগমেন্টের শুরুর সাপেক্ষে নির্ধারিত হয়।
বডি কন্টেন্টের অন্তর্গত বেশিরভাগ এলিমেন্টেরই শূন্য-ভিত্তিক startIndex এবং endIndex প্রপার্টি থাকে। এগুলো কোনো এলিমেন্টের শুরু এবং শেষের অফসেট নির্দেশ করে, যা তার পরিবেষ্টনকারী সেগমেন্টের শুরুর সাপেক্ষে নির্ধারিত হয়। আপনার ব্যাচ ডক্স এপিআই কলগুলো কীভাবে সাজাতে হয় সে সম্পর্কে আরও তথ্যের জন্য, ব্যাচ আপডেট দেখুন।
ইনডেক্স UTF-16 কোড ইউনিটে পরিমাপ করা হয়। এর মানে হলো, সারোগেট পেয়ার দুটি ইনডেক্স ব্যবহার করে। উদাহরণস্বরূপ, "GRINNING FACE" ইমোজি, 😄, কে \uD83D\uDE00 হিসেবে প্রকাশ করা হয় এবং এটি দুটি ইনডেক্স ব্যবহার করে।
ডকুমেন্টের মূল অংশের অন্তর্গত এলিমেন্টগুলোর ক্ষেত্রে, ইনডেক্সগুলো মূল কন্টেন্টের শুরু থেকে অফসেট বা দূরত্ব নির্দেশ করে, যেখানে মূল কন্টেন্ট হলো "রুট" এলিমেন্ট।
স্ট্রাকচারাল এলিমেন্টগুলোর— SectionBreak , TableOfContents , Table , এবং Paragraph "পার্সোনালিজিং" টাইপগুলোতে এই ইনডেক্সগুলো থাকে না, কারণ এদের আবদ্ধকারী StructuralElement মধ্যেই এই ফিল্ডগুলো থাকে। ParagraphElement এর অন্তর্ভুক্ত পার্সোনালাইজিং টাইপগুলোর ক্ষেত্রেও একই কথা প্রযোজ্য, যেমন TextRun , AutoText , এবং PageBreak ।
অ্যাক্সেস উপাদান
documents.batchUpdate মেথড ব্যবহার করে অনেক এলিমেন্ট পরিবর্তন করা যায়। উদাহরণস্বরূপ, InsertTextRequest ব্যবহার করে আপনি টেক্সটযুক্ত যেকোনো এলিমেন্টের বিষয়বস্তু পরিবর্তন করতে পারেন। একইভাবে, UpdateTextStyleRequest ব্যবহার করে আপনি এক বা একাধিক এলিমেন্টের অন্তর্ভুক্ত টেক্সটের একটি পরিসরে ফরম্যাটিং প্রয়োগ করতে পারেন।
ডকুমেন্টের উপাদানগুলো পড়ার জন্য, সম্পূর্ণ ডকুমেন্টটির একটি JSON ডাম্প পেতে documents.get মেথডটি ব্যবহার করুন। এরপর আপনি প্রাপ্ত JSON-টি পার্স করে প্রতিটি উপাদানের মান খুঁজে বের করতে পারেন। আরও তথ্যের জন্য, “ আউটপুট ডকুমেন্ট কন্টেন্টস অ্যাজ JSON” দেখুন।
বিষয়বস্তু বিশ্লেষণ করা বিভিন্ন ক্ষেত্রে উপকারী হতে পারে। উদাহরণস্বরূপ, একটি ডকুমেন্ট ক্যাটালগিং অ্যাপ্লিকেশনের কথা ভাবুন যা খুঁজে পাওয়া ডকুমেন্টগুলোর তালিকা তৈরি করে। এই অ্যাপটি একটি ডকুমেন্টের ট্যাবগুলোর শিরোনাম, রিভিশন আইডি এবং শুরুর পৃষ্ঠা নম্বর বের করতে পারে, যেমনটি নিচের ডায়াগ্রামে দেখানো হয়েছে:
যেহেতু এই সেটিংসগুলো সরাসরি পড়ার কোনো পদ্ধতি নেই, তাই আপনার অ্যাপকে পুরো ডকুমেন্টটি সংগ্রহ করতে হবে এবং তারপর এই মানগুলো বের করার জন্য JSON পার্স করতে হবে।
সম্পত্তির উত্তরাধিকার
একটি StructuralElement তার প্যারেন্ট অবজেক্টগুলো থেকে প্রোপার্টি উত্তরাধিকার সূত্রে পেতে পারে। একটি অবজেক্টের প্রোপার্টিগুলো, যার মধ্যে তার নিজের সংজ্ঞায়িত এবং উত্তরাধিকার সূত্রে প্রাপ্ত প্রোপার্টিগুলো অন্তর্ভুক্ত, তার চূড়ান্ত দৃশ্যমান রূপ নির্ধারণ করে।
টেক্সট ক্যারেক্টার ফরম্যাটিং নির্ধারণ করে যে একটি ডকুমেন্টে টেক্সট কীভাবে প্রদর্শিত হবে, যেমন বোল্ড, ইটালিক এবং আন্ডারলাইন। আপনি যে ফরম্যাটিং প্রয়োগ করেন, তা মূল প্যারাগ্রাফের TextStyle থেকে প্রাপ্ত ডিফল্ট ফরম্যাটিংকে ওভাররাইড করে। বিপরীতভাবে, যে সমস্ত ক্যারেক্টারের ফরম্যাটিং আপনি সেট করেন না, সেগুলি প্যারাগ্রাফের স্টাইল থেকেই তাদের ফরম্যাটিং পেতে থাকে।
প্যারাগ্রাফ ফরম্যাটিং নির্ধারণ করে যে একটি ডকুমেন্টে টেক্সটের ব্লকগুলো কীভাবে প্রদর্শিত হবে, যেমন অ্যালাইনমেন্ট, বর্ডার এবং ইনডেন্টেশন। আপনি যে ফরম্যাটিং প্রয়োগ করেন, তা অন্তর্নিহিত ParagraphStyle থেকে প্রাপ্ত ডিফল্ট ফরম্যাটিংকে ওভাররাইড করে। বিপরীতভাবে, যে ফরম্যাটিং বৈশিষ্ট্যগুলো আপনি সেট করেন না, সেগুলো প্যারাগ্রাফ স্টাইল থেকেই উত্তরাধিকারসূত্রে প্রাপ্ত হতে থাকে।