این سند نحوه تعریف الگوهای قالب تاریخ و عدد جدید را شرح می‌دهد که می‌توانید در درخواست API خود بگنجانید.
قالب‌های تاریخ-زمان و عدد به شما امکان می‌دهد نحوه نمایش داده‌هایتان را در برگ کنترل کنید. «کاربرگ‌نگار Google» چند قالب رایج برای انتخاب ارائه می‌دهد، اما می‌توانید قالب‌های خودتان را هم تعریف کنید.
در میانای کاربر «کاربرگ‌نگار»، قالب‌های عدد و تاریخ را بااستفاده از منو قالب > عدد روی سلول‌ها اعمال می‌کنید. در Google Sheets API، این قالب‌ها را بااستفاده از فراخوانی روش
spreadsheets.batchUpdate
تنظیم می‌کنید تا
UpdateCellsRequest
یا
RepeatCellRequest
ارسال کنید.
در درخواست، شیء
NumberFormat
را با مشخص کردن
NumberFormatType
(مانند NUMBER، CURRENCY، PERCENT، DATE، یا TIME) و رشته اختیاری
pattern پیکربندی می‌کنید. اگر pattern را حذف کنید، «کاربرگ‌نگار» از الگوی قالب پیش‌فرض برای type مشخص‌شده براساس locale صفحه‌گسترده استفاده می‌کند (برای مثال، $1,000.12 برای CURRENCY در en_US).
نمونه تنظیم تاریخ و زمان سفارشی یا قالب اعشاری برای
محدوده نشان می‌دهد که چگونه می‌توان بااستفاده از Sheets API
الگوی قالب را تنظیم کرد. توجه داشته باشید که ارائه واقعی
قالب به locale صفحه‌گسترده بستگی دارد.
این سند فرض می‌کند که locale، en_US است. می‌توانید locale صفحه‌گسترده را با خواندن شیء SpreadsheetProperties بااستفاده از روش spreadsheets.get در منبع spreadsheets تعیین کنید.
برای نمونه‌های بیشتر، قالب‌بندی پایه و قالب‌بندی شرطی را ببینید.
درباره مقادیر تاریخ و زمان
«کاربرگ‌نگار»، مانند اکثر برنامه‌های صفحه‌گسترده دیگر، با مقادیر تاریخ و زمان به‌عنوان مقادیر اعشاری رفتار می‌کند. این کار به شما امکان می‌دهد تا روی آن‌ها در فرمول‌ها محاسبات ریاضی انجام دهید، بنابراین می‌توانید روزها یا هفته‌ها را افزایش دهید، دو تاریخ و زمان را جمع یا تفریق کنید، و عملیات مشابه دیگری را انجام دهید.
«کاربرگ‌نگار» از نوعی تاریخ
مبدأ استفاده می‌کند که معمولاً در
صفحه‌گسترده‌ها استفاده می‌شود. بخش عدد صحیح مقدار (سمت چپ اعشار)
روزهای پس‌از ۳۰ دسامبر ۱۸۹۹ را می‌شمارد. بخش کسری (سمت راست اعشار)
زمان را به‌عنوان کسری از یک روز محاسبه می‌کند. برای مثال، ۱ ژانویه ۱۹۰۰ ظهر
2.5، 2 است چون ۲ روز بعداز ۳۰ دسامبر ۱۸۹۹ است، و 0.5 است چون
ظهر نصف روز است. ۱ فوریه ۱۹۰۰ ساعت ۳ ب.ظ. برابر است با 33.625.
«کاربرگ‌نگار» سال ۱۹۰۰ را به‌درستی به‌عنوان سال عادی درنظر می‌گیرد، نه سال کبیسه. شماره‌های سریال تاریخ و زمان، اختلاف منطقه زمانی را ذخیره نمی‌کنند. درعوض،
آن‌ها براساس
timeZone
صفحه‌گسترده هستند،
که می‌توانید آن را از شیء
SpreadsheetProperties
بااستفاده از روش
spreadsheets.get
بخوانید.
الگوهای قالب تاریخ و زمان
الگوی قالب تاریخ-زمان رشته‌ای از زیررشته‌های نشانهای است که «کاربرگ‌نگار» هنگام تجزیه کردن، آن‌ها را با عناصر تاریخ-زمان مربوطه (مانند ماه یا ساعت) جایگزین می‌کند.
نشانهای قالب تاریخ و زمان
جدول زیر زیررشته‌های نشانهای را که می‌توانید در الگوی قالب تاریخ-زمان استفاده کنید تعریف می‌کند. نویسه + نشان می‌دهد که نویسه قبلی می‌تواند یک یا چند بار ظاهر شود و همچنان با الگو مطابقت داشته باشد. «کاربرگ‌نگار»
نویسه‌هایی را که در این جدول فهرست نشده‌اند به‌عنوان نویسه واقعی درنظر می‌گیرد و آن‌ها را بدون
تغییر برونداد می‌کند.
| کد | شرح |
|---|---|
h |
ساعت روز. بسته به اینکه نشانگر «قبل‌ازظهر» یا «بعدازظهر» در رشته وجود داشته باشد یا نه، بین قالب ۱۲ ساعته و ۲۴ ساعته جابه‌جا می‌شود. |
hh+ |
مشابه مورد قبلی، اما با یک ۰ پیشرو برای ۱ تا ۹. |
m |
اگر کد غیرحرفی قبلی ساعت بود یا کد بعدی ثانیه است، نشان‌دهنده دقیقه در ساعت است (بدون ۰ ابتدایی). درغیراین‌صورت، ماه سال را به‌صورت عدد (بدون صفر اول) نشان می‌دهد. |
M |
ماه سال بدون ۰ پیشرو. از این کد برای بیان صریح ماه، به‌جای دقیقه، در الگوی خود استفاده کنید. |
mm |
مشابه m، اما با یک ۰ در ابتدا برای هر دو مورد. |
MM |
ماه سال با ۰ در ابتدا. از این کد برای بیان صریح ماه، به‌جای دقیقه، در الگوی خود استفاده کنید. |
mmm |
اختصار سه حرفی ماه (برای مثال، «Feb»). |
mmmm |
نام کامل ماه. mmmmmm+ نیز با این مطابقت دارد. |
mmmmm |
حرف اول ماه (برای مثال، «J» برای June). |
s |
ثانیه در دقیقه بدون ۰ پیشرو. |
ss |
ثانیه در دقیقه با ۰ پیشرو. |
[h+] |
تعداد ساعت‌های سپری‌شده در یک مدت زمان. تعداد حروف نشان‌دهنده حداقل تعداد ارقام است (صفرهای ابتدایی را اضافه می‌کند). |
[m+] |
تعداد دقیقه‌های سپری‌شده در یک مدت زمان. تعداد حروف نشان‌دهنده حداقل تعداد ارقام است (صفرهای ابتدایی را اضافه می‌کند). |
[s+] |
تعداد ثانیه‌های سپری‌شده در یک مدت زمان. تعداد حروف نشان‌دهنده حداقل تعداد ارقام است (صفرهای ابتدایی را اضافه می‌کند). |
d |
روز ماه، بدون ۰ پیشرو برای اعداد کمتر از ۱۰. |
dd |
روز ماه، با ۰ پیشرو برای اعداد کمتر از ۱۰. |
ddd |
روز هفته، مخفف سه‌حرفی (برای مثال، «Mon»). |
dddd+ |
روز هفته، نام کامل. |
y |
سال ۲ رقمی. |
yy |
|
yyy |
سال ۴ رقمی. |
yyyy+ |
|
a/p |
«a» را برای قبل‌ازظهر و «p» را برای بعدازظهر نمایش می‌دهد. همچنین ساعت را به قالب ۱۲ ساعته تغییر می‌دهد. اگر حرف کد با حروف بزرگ نوشته شده باشد، برونداد نیز با حروف بزرگ نوشته می‌شود. |
am/pm |
مانند بالا، اما به‌جای آن «AM» یا «PM» را نمایش می‌دهد و همیشه با حروف بزرگ است. |
0 |
دهم ثانیه. می‌توانید دقت را با 00 به دو رقم یا با 000 به سه رقم (میلی‌ثانیه) افزایش دهید. |
\ |
نویسه بعدی را به‌عنوان مقدار دقیق درنظر می‌گیرد و نه هر معنی خاصی که ممکن است داشته باشد. |
"text" |
هر نوشتاری را که داخل علامت نقل‌قول باشد به‌صورت تحت‌اللفظی نمایش می‌دهد. |
نمونه‌های قالب تاریخ و زمان
با فرض تاریخ و زمان Tuesday, April 5, 2016, 4:08:53.528 PM، جدول زیر چند الگوی نمونه و نحوه نمایش تاریخ-زمان مربوط به آن‌ها را نشان می‌دهد. بخش دوم جدول نمونه‌هایی از قالب‌های زمان سپری‌شده را برای زمان سپری‌شده 3 hours, 13 minutes, 41.255 seconds نشان می‌دهد:
| الگوهای تاریخ-زمان | Tuesday, April 5, 2016, 4:08:53.528 PM |
|---|---|
h:mm:ss.00 a/p |
۴:۰۸:۵۳٫۵۳ ب.ظ. |
hh:mm A/P".M." |
۴:۰۸ ب.ظ. |
yyyy-mm-dd |
2016-04-05 |
mmmm d \[dddd\] |
۵ آوریل [سه‌شنبه] |
h PM, ddd mmm dd |
سه‌شنبه، ۵ آوریل، ساعت ۴ ب.ظ. |
dddd, m/d/yy at h:mm |
سه‌شنبه، ۲۰۱۶/۴/۵ ساعت ۱۶:۰۸ |
| الگوهای زمان سپری‌شده | 3 hours, 13 minutes, 41.255 seconds |
[hh] |
۰۳ |
[mmmm] |
0193 |
[ss] |
11621 |
الگوهای قالب عدد
الگوی قالب عدد رشته‌ای از زیررشته‌های کد است که «کاربرگ‌نگار» هنگام تجزیه کردن، آن‌ها را با نمایش‌های عددی مربوطه جایگزین می‌کند. الگوی قالب عدد می‌تواند حداکثر از چهار بخش تشکیل شود که با نقطه‌ویرگول از هم جدا می‌شوند و قالب‌های جداگانه‌ای را که برای اعداد مثبت، اعداد منفی، صفر، و نوشتار (به همین ترتیب) استفاده می‌شود تعریف می‌کنند:
[POSITIVE FORMAT];[NEGATIVE FORMAT];[ZERO FORMAT];[TEXT FORMAT]
لازم نیست هر چهار بخش را در یک قالب بگنجانید. اگر فقط یک بخش اضافه کنید، «کاربرگ‌نگار» از آن قالب برای همه مقادیر استفاده می‌کند. بااستفاده از دو بخش، قالب اول برای صفر و اعداد مثبت و قالب دوم برای اعداد منفی اعمال می‌شود. استفاده از سه بخش، قالب‌های جداگانه‌ای برای اعداد مثبت، منفی، و صفر تعریف می‌کند. برای مثال:
[NUMBER FORMAT] [POSITIVE/ZERO FORMAT];[NEGATIVE FORMAT] [POSITIVE FORMAT];[NEGATIVE FORMAT];[ZERO FORMAT]
بااین‌حال، اگر دو یا چند بخش وجود داشته باشد و بخش نهایی قالب نوشتار باشد، «کاربرگ‌نگار» آن بخش را به‌عنوان قالب نوشتار درنظر می‌گیرد و بخش‌های دیگر طوری رفتار می‌کنند که گویی یک بخش کمتر وجود دارد. بنابراین، با گنجاندن قالب نوشتار نهایی، می‌توان قالب‌هایی مانند موارد زیر را تعریف کرد:
[POSITIVE/ZERO FORMAT];[NEGATIVE FORMAT];[TEXT FORMAT] [NUMBER FORMAT];[TEXT FORMAT]
تجزیه قالب به بخش‌ها قبل‌از تجزیه‌های دیگر انجام می‌شود، بنابراین امکان دارد قالب تاریخ یا زمان به‌عنوان یکی از بخش‌ها گنجانده شود (هرچند این کار کاربرد محدودی دارد).
نشانه‌های قالب عدد
جدول زیر زیررشته‌های نشانهای را که می‌توانید در بخش قالب استفاده کنید تعریف می‌کند تا نحوه نمایش مقادیر آن بخش را تعریف کند.
| کد | شرح |
|---|---|
0 |
نشان‌دهنده رقمی در عدد است. اگر رقم ۰ بی‌اهمیت باشد،
به‌صورت ۰ ارائه می‌شود. برای مثال، قالب عدد
00.0 عدد ۳ را به‌صورت «03.0» ارائه می‌کند. |
# |
نشان‌دهنده رقمی در عدد است. اگر رقم 0 بی‌اهمیت باشد،
نمایش داده نمی‌شود. برای مثال، قالب عدد ##0
عدد ۱۲ را به‌صورت «12» ارائه می‌کند. |
? |
نشان‌دهنده رقمی در عدد است. اگر رقم 0 بی‌اهمیت باشد،
به‌صورت فاصله ارائه می‌شود. این کار اغلب برای تراز کردن ممیز اعشاری در
یک ستون هنگام استفاده از قلم‌های با عرض ثابت استفاده می‌شود. برای مثال، قالب عدد
???.??? عدد ۱۲٫۴ را به‌صورت زیر ارائه می‌کند:
« 12.4 ». |
. |
نقطه اول نشان‌دهنده ممیز اعشاری در عدد است. نقطه‌های بعدی به‌صورت نویسه تحت‌اللفظی ارائه می‌شوند. اگر ممیز اعشاری را در قالب اضافه کنید، همیشه نمایش داده می‌شود، حتی برای اعداد صحیح. برای مثال،
#0.# عدد ۳ را به‌صورت «3.» ارائه می‌کند. |
% |
به‌صورت تحت‌اللفظی نشان داده می‌شود اما باعث می‌شود اعداد موجود قبل‌از ارائه در ۱۰۰ ضرب شوند تا درصدها خواناتر شوند. برای مثال، قالب عدد #%
عدد ۰٫۲۵ را به‌صورت «25%» ارائه می‌کند. |
, |
اگر بین نویسه‌های دورقمی (0،
#، یا ?) ظاهر شود، کل عدد را
با جداکننده‌های گروه‌بندی (گروه‌بندی براساس هزارگان) ارائه می‌کند. اگر بعداز نویسه‌های رقمی بیاید، ارقام را به‌ازای هر ویرگول هزار برابر می‌کند (برای مثال، قالب #0.0,, عدد ۱۲٬۲۰۰٬۰۰۰ را به‌صورت 12.2 نشان می‌دهد). |
E- |
عدد را در قالب علمی ارائه می‌کند، به‌طوری‌که
قالب‌بندی سمت چپ E برای بخش غیرنمایی
و قالب‌بندی سمت راست E برای بخش نمایی
استفاده می‌شود. E+ علامت + را برای توان‌های مثبت نشان می‌دهد. E- فقط برای توان‌های منفی علامت نشان می‌دهد. اگر
از حروف کوچک استفاده شود، برونداد e نیز با حروف کوچک خواهد بود.
برای مثال، قالب عدد ##0.00#E+##
عدد ۰٫۰۰۰۰۰۰۱ را به‌صورت «100.00E-9» ارائه می‌کند. |
E+ |
|
e- |
|
e+ |
|
/ |
اگر بین نویسه‌های دو رقمی (0،
#، یا ?) ظاهر شود، آن گروه‌های رقمی را به‌عنوان
قالب کسری درنظر می‌گیرد. برای مثال، قالب عدد 0 #/#
عدد ۲۳٫۲۵ را به‌صورت 23 1/4 ارائه می‌کند. مخرج
می‌تواند عدد صحیح واقعی هم باشد، که در این صورت آن عدد صحیح را به‌عنوان
مخرج اعمال می‌کند. قالب عدد 0 #/8
عدد ۲۳٫۲۵ را به‌صورت 23 2/8 نمایش می‌دهد. اگر صورت کسر ۰ شود، بخش کسری پرداز نمی‌شود. عدد
۲۳٫۱ با قالب عدد 0 #/3 به‌صورت
23 ارائه می‌شود (چون ۰٫۱ به ۰/۳ گرد می‌شود). / با قالب علمی یا قالبی که ممیز اعشاری داشته باشد سازگار نیست. |
* |
برای سازگاری با قالب‌های عدد Microsoft Excel اضافه شده است. «کاربرگ‌نگار» این کد را نادیده می‌گیرد. |
_ |
نویسه بعدی را رد می‌کند و فاصله می‌گذارد. از این کد برای تراز کردن قالب‌های عدد در جایی که پرانتزها مقدار منفی را احاطه کرده‌اند استفاده کنید. |
\ |
با نویسه بعدی به‌عنوان مقدار تحت‌اللفظی رفتار می‌کند و نه هر معنی خاصی که ممکن است داشته باشد. برای مثال، قالب عدد \#0
عدد ۱۰ را به‌صورت «#10» ارائه می‌کند. |
"text" |
هر نوشتاری را که داخل علامت نقل‌قول باشد به‌صورت تحت‌اللفظی نمایش می‌دهد. |
@ |
اگر سلول ورودی نوشتاری داشته باشد، نوشتار خام را برای سلول درج می‌کند. با هیچ‌یک از نویسه‌های خاص دیگر سازگار نیست و برای مقادیر عددی (که به‌صورت قالب عمومی نمایش داده می‌شوند) نمایش داده نمی‌شود. |
$ - + ( ) : space |
«کاربرگ‌نگار» این نویسه‌ها و نمادهای رایج ارز (مانند $، €، £، و ¥) را به‌عنوان نویسه ثابت درنظر می‌گیرد و آن‌ها را بدون تغییر نمایش می‌دهد. |
دستورالعمل‌های متا
علاوه‌براین، هریک از بخش‌های قالب می‌تواند دستورالعمل‌های فراداده اختیاری داشته باشد که در نویسه‌های [] محصور شده‌اند و قبل‌از قالب قرار می‌گیرند و دستورالعمل‌های اضافی ارائه می‌دهند:
| آموزش | شرح |
|---|---|
[condition] |
مقایسه پیش‌فرض مثبت، منفی، یا صفر بخش را با عبارت شرطی دیگری جایگزین می‌کند. برای مثال،
[<100]"Low";[>1000]"High";000 کلمه
«پایین» را برای مقادیر زیر ۱۰۰، «بالا» را برای مقادیر بالای ۱۰۰۰، و عدد سه رقمی (با صفر در ابتدا) را برای هر چیزی بین این دو مقدار ارائه می‌دهد. فقط می‌توانید
شرایط را برای دو زیرقالب اول اعمال کنید، و اگر عددی با بیش‌از
یک مورد مطابقت داشته باشد، «کاربرگ‌نگار» از اولین مطابقت استفاده می‌کند. اگر قالب سومی وجود داشته باشد، «کاربرگ‌نگار» از آن برای «هر چیز دیگری» استفاده می‌کند؛ درغیراین‌صورت، اگر عددی با هیچ‌کدام از قالب‌ها مطابقت نداشته باشد، «کاربرگ‌نگار» همه نویسه‌های «#» را در سراسر عرض سلول نمایش می‌دهد. اگر وجود داشته باشد،
قالب چهارم همیشه برای نوشتار استفاده می‌شود. |
[Color] or [Color#] |
باعث می‌شود هر مقداری که این زیرقالب پرداز می‌کند با رنگ نوشتار داده‌شده نشان داده شود. مقادیر معتبر برای Color عبارت‌اند از: سیاه،
آبی، فیروزه‌ای، سبز، سرخابی، قرمز، سفید، یا زرد.
مقادیر معتبر برای «#» در Color# از ۱ تا ۵۶ است. رنگ‌های قالب عدد بر هر رنگی که کاربر در سلول وارد کرده باشد اولویت دارد، اما بر رنگ‌های تنظیم‌شده با قالب‌بندی مشروط اولویت ندارد. این
پالت رنگ
فهرستی از رنگ‌ها را نشان می‌دهد که با هر عدد مطابقت دارد. این موارد براساس ویژگی
ColorIndex
در Microsoft Excel است. |
[$currency] |
نماد یا کد واحد پول مشخص‌شده را به‌صورت دقیق (مثلاً [$€]#,##0.00 یا [$CAD]#,##0.00) نمایش می‌دهد. اگر کد منطقه زبانی اختیاری را بعداز خط تیره (مثلاً [$CAD-1009]) اضافه کنید، «کاربرگ‌نگار» کد منطقه زبانی را نادیده می‌گیرد. |
نمونه‌های قالب عدد
جدول زیر چند نمونه الگو و قالب‌بندی شماره مربوط به آن‌ها را نشان می‌دهد:
| عدد | الگو | مقدار قالب‌بندی‌شده |
|---|---|---|
| 12345.125 | ####.# |
12345.1 |
| ۱۲٫۳۴ | 000.0000 |
۰۱۲٫۳۴۰۰ |
| 12 | #.0# |
۱۲٫۰ |
| ۵٫۱۲۵ | # ???/??? |
۵ ۱/۸ |
| 12000 | #,### |
۱۲٬۰۰۰ |
| ۱۲۳۴٫۵۶ -۱۲۳۴٫۵۶ |
$#,##0.00;($#,##0.00) |
۱٬۲۳۴٫۵۶ دلار (۱٬۲۳۴٫۵۶ دلار) |
| 1230000 | 0.0,,"M" |
۱٫۲ میلیون |
| 1234500000 | 0.00e+00 |
۱٫۲۳e+09 |
| 123114.15115 MyText |
###0.000;"TEXT: "_(@_) |
123114.151 TEXT: MyText |
| 1234 -1234 0 MyText |
[Blue]#,##0;[Red]#,##0;[Green]0.0;[Magenta]_(@_) |
۱٬۲۳۴ ۱٬۲۳۴ ۰٫۰ MyText |
| 1005 32 527 |
[>1000]"HIGH";[Color43][<=200]"LOW";0000 |
HIGH LOW 0527 |