توابع در [[معرفی پایگاهها|پایگاهها]] برای دستکاری دادهها از [[ویژگیها]] در [[نماها#پالایهها|فیلترها]] و [[فرمولها]] استفاده میشوند. برای اطلاعات بیشتر درباره نحوه استفاده از توابع، مرجع [[سینتکس پایگاهها|سینتکس پایگاهها]] را ببینید.
توابع پایگاهها از رفتار JavaScript پیروی میکنند. برای مستندات مرجع کامل، به [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference) مراجعه کنید.
به جز توابع [[توابع#عمومی|عمومی]]، بیشتر توابع به نوع مقداری که میخواهید تغییر دهید بستگی دارند:
- [[توابع#نوع هر نوع|هر نوع]]
- [[توابع#نوع تاریخ|تاریخ]]
- [[توابع#نوع رشته|رشته]]
- [[توابع#نوع عدد|عدد]]
- [[توابع#نوع فهرست|فهرست]]
- [[توابع#نوع پیوند|پیوند]]
- [[توابع#نوع فایل|فایل]]
- [[توابع#نوع شیء|شیء]]
- [[توابع#نوع عبارت باقاعده|عبارت باقاعده]]
## عمومی
توابع عمومی بدون نوع استفاده میشوند.
### `escapeHTML()`
`escapeHTML(html: string): string`
- نویسههای خاص در یک رشته را اسکیپ میکند تا برای استفاده در HTML ایمن باشد.
### `date()`
`date(date: string): date`
- `date(string): date` رشته ارائهشده را تجزیه کرده و یک شیء تاریخ برمیگرداند.
- رشته `date` باید در قالب `YYYY-MM-DD HH:mm:ss` باشد.
### `duration()`
`duration(value: string): duration`
- یک رشته را به عنوان مدت زمان تجزیه میکند. برای قالب رشته `value` بخش [[سینتکس پایگاهها#محاسبات تاریخ|محاسبات تاریخ]] را ببینید.
- تجزیه صریح برای محاسبات تاریخ لازم نیست (مثلاً `now() + '1d'`)، اما هنگام انجام محاسبات روی مدت زمانها لازم است (مثلاً `now() + (duration('1d') * 2)`).
- هنگام انجام محاسبات مدت زمانها با مقادیر عددی، مدت زمان باید در سمت چپ باشد. مثلاً `duration('5h') * 2`، به جای `2 * duration('5h')`.
### `file()`
`file(path: string | file | url): file`
- یک شیء فایل برای فایل یا مسیر دادهشده برمیگرداند.
- نمونه: `file(link("[[filename]]"))` یا `file("path to file")`.
### `html()`
`html(html: string): html`
- یک رشته را به یک قطعه کد تبدیل میکند که به صورت HTML رندر میشود.
### `if()`
`if(condition: any, trueResult: any, falseResult?: any): any`
- `condition` عبارتی است که ارزیابی میشود.
- `trueResult` خروجی در صورت صحیح بودن `condition` است.
- `falseResult` خروجی اختیاری در صورت نادرست بودن `condition` است. اگر حذف شود، پیشفرض `null` است.
- اگر `condition` صحیح یا حقیقی باشد، `trueResult` را برمیگرداند، در غیر این صورت `falseResult`.
- نمونه: `if(isModified, "Modified", "Unmodified")`
### `image()`
`image(path: string | file | url): image`
- یک شیء تصویر برمیگرداند که تصویر را در نما رندر میکند.
- نمونه: `image(image-property)` یا `image("https://obsidian.md/images/obsidian-logo-gradient.svg")`.
### `icon()`
`icon(name: string): icon`
- مقداری برمیگرداند که در نما به صورت آیکون رندر میشود. نام آیکون باید با یک آیکون Lucide پشتیبانیشده مطابقت داشته باشد.
- نمونه: `icon("arrow-right")`.
### `link()`
`link(path: string | file, display?: value): Link`
- رشته `path` را تجزیه کرده و یک شیء پیوند برمیگرداند که به صورت پیوند به مسیر دادهشده رندر میشود.
- به صورت اختیاری پارامتر `display` را برای تنظیم متن نمایشی پیوند ارائه دهید.
### `list()`
`list(element: any): List`
- اگر عنصر ارائهشده یک فهرست باشد، آن را بدون تغییر برمیگرداند.
- در غیر این صورت، `element` ارائهشده را در یک فهرست قرار داده و فهرستی با یک عنصر ایجاد میکند.
- از این تابع زمانی استفاده کنید که یک ویژگی در سراسر گاوصندوق ترکیبی از رشتهها یا فهرستها را شامل شود.
- نمونه: `list("value")` مقدار `["value"]` را برمیگرداند.
### `max()`
`max(value1: number, value2: number...): number`
- بزرگترین عدد از بین تمام اعداد ارائهشده را برمیگرداند.
### `min()`
`min(value1: number, value2: number...): number`
- کوچکترین عدد از بین تمام اعداد ارائهشده را برمیگرداند.
### `now()`
`now(): date`
- یک شیء تاریخ برای لحظه فعلی برمیگرداند.
### `number()`
`number(input: any): number`
- تلاش میکند مقدار ارائهشده را به عنوان عدد برگرداند.
- اشیاء تاریخ را به صورت میلیثانیه از مبدأ یونیکس برمیگرداند.
- مقادیر بولی را به صورت `1` یا `0` برمیگرداند.
- رشتهها را به عدد تجزیه میکند و در صورتی که رشته یک عدد معتبر نباشد، خطا برمیگرداند.
- نمونه: `number("3.4")` مقدار `3.4` را برمیگرداند.
### `today()`
`today(): date`
- یک شیء تاریخ برای تاریخ فعلی برمیگرداند. بخش زمان روی نیمهشب تنظیم میشود.
### `random()`
`random(): number`
- یک عدد تصادفی بین ۰ و ۱ برمیگرداند.
- تولید عدد هر زمان که یک نما بارگذاری شود بازنشانی میشود. جابهجایی بین نماها عدد تصادفی را تغییر میدهد.
## نوع هر نوع
توابعی که میتوانید با هر مقداری استفاده کنید. این شامل رشتهها (مثلاً `"hello"`)، اعداد (مثلاً `42`)، فهرستها (مثلاً `[1,2,3]`)، اشیاء و موارد دیگر میشود.
### `isTruthy()`
`any.isTruthy(): boolean`
- مقدار را به صورت بولی تبدیلشده برمیگرداند.
- نمونه: `1.isTruthy()` مقدار `true` را برمیگرداند.
### `isType()`
`any.isType(type: string): boolean`
- اگر مقدار از نوع ارائهشده باشد، true برمیگرداند.
- نمونه: `"example".isType("string")` و `true.isType("boolean")` هر دو true برمیگردانند.
### `toString()`
`any.toString(): string`
- نمایش رشتهای هر مقداری را برمیگرداند.
- نمونه: `123.toString()` مقدار `"123"` را برمیگرداند.
## نوع تاریخ
توابعی که میتوانید با تاریخ و زمان مانند `date("2025-05-27")` استفاده کنید. مقایسه تاریخها با استفاده از [[سینتکس پایگاهها#محاسبات تاریخ|محاسبات تاریخ]] انجام میشود.
### فیلدها
فیلدهای زیر برای تاریخها در دسترس هستند:
| فیلد | نوع | توضیح |
| ------------------ | -------- | ------------------------------- |
| `date.year` | `number` | سال تاریخ |
| `date.month` | `number` | ماه تاریخ (۱–۱۲) |
| `date.day` | `number` | روز ماه |
| `date.hour` | `number` | ساعت (۰–۲۳) |
| `date.minute` | `number` | دقیقه (۰–۵۹) |
| `date.second` | `number` | ثانیه (۰–۵۹) |
| `date.millisecond` | `number` | میلیثانیه (۰–۹۹۹) |
### `date()`
`date.date(): date`
- یک شیء تاریخ بدون بخش زمان برمیگرداند.
- نمونه: `now().date().format("YYYY-MM-DD HH:mm:ss")` رشتهای مانند "2025-12-31 00:00:00" برمیگرداند.
### `format()`
`date.format(format: string): string`
- `format` رشته قالب است (مثلاً `"YYYY-MM-DD"`).
- تاریخ را طبق رشته قالب Moment.js قالببندیشده برمیگرداند.
- نمونه: `date.format("YYYY-MM-DD")` مقدار `"2025-05-27"` را برمیگرداند.
### `time()`
`date.time(): string`
- بخش زمان را به صورت رشته برمیگرداند.
- نمونه: `now().time()` رشتهای مانند "23:59:59" برمیگرداند.
### `relative()`
`date.relative(): string`
- مقایسهای خوانا از تاریخ با تاریخ و زمان فعلی برمیگرداند.
- نمونه: `file.mtime.relative()` مقداری مانند `3 days ago` برمیگرداند.
### `isEmpty()`
`date.isEmpty(): boolean`
- مقدار false برمیگرداند.
## نوع رشته
توابعی که میتوانید با دنبالهای از نویسهها مانند `"hello"` استفاده کنید.
### فیلدها
| فیلد | نوع | توضیح |
| --------------- | -------- | ------------------------------ |
| `string.length` | `number` | تعداد نویسههای رشته |
### `contains()`
`string.contains(value: string): boolean`
- `value` زیررشتهای است که باید جستجو شود.
- اگر رشته شامل `value` باشد، true برمیگرداند.
- نمونه: `"hello".contains("ell")` مقدار `true` را برمیگرداند.
### `containsAll()`
`string.containsAll(...values: string): boolean`
- `values` یک یا چند زیررشته برای جستجو هستند.
- اگر رشته شامل همه `values` باشد، true برمیگرداند.
- نمونه: `"hello".containsAll("h", "e")` مقدار `true` را برمیگرداند.
### `containsAny()`
`string.containsAny(...values: string): boolean`
- `values` یک یا چند زیررشته برای جستجو هستند.
- اگر رشته شامل حداقل یکی از `values` باشد، true برمیگرداند.
- نمونه: `"hello".containsAny("x", "y", "e")` مقدار `true` را برمیگرداند.
### `endsWith()`
`string.endsWith(query: string): boolean`
- `query` رشتهای است که باید در انتها بررسی شود.
- اگر این رشته با `query` پایان یابد، true برمیگرداند.
- نمونه: `"hello".endsWith("lo")` مقدار `true` را برمیگرداند.
### `isEmpty()`
`string.isEmpty(): boolean`
- اگر رشته هیچ نویسهای نداشته باشد یا موجود نباشد، true برمیگرداند.
- نمونه: `"Hello world".isEmpty()` مقدار `false` را برمیگرداند.
- نمونه: `"".isEmpty()` مقدار `true` را برمیگرداند.
### `lower()`
`string.lower(): string`
- رشته را به حروف کوچک تبدیلشده برمیگرداند.
### `replace()`
`string.replace(pattern: string | Regexp, replacement: string): string`
- `pattern` مقداری است که باید در رشته هدف جستجو شود.
- `replacement` مقداری است که جایگزین الگوهای یافتشده میشود. هنگامی که `pattern` یک Regexp است، میتوانید با استفاده از `$1`، `$2` و غیره در `replacement` به گروههای ضبط ارجاع دهید.
- اگر `pattern` یک رشته باشد، تمام موارد الگو جایگزین میشوند.
- اگر `pattern` یک Regexp باشد، پرچم `g` تعیین میکند که فقط اولین مورد یا تمام موارد جایگزین شوند.
- نمونه: `"a:b:c:d".replace(/:/, "-")` مقدار `"a-b:c:d"` را برمیگرداند، در حالی که `"a:b:c:d".replace(/:/g, "-")` مقدار `"a-b-c-d"` را برمیگرداند.
- نمونه با گروههای ضبط: `"John Smith".replace(/(\w+) (\w+)/, "$2, $1")` مقدار `"Smith, John"` را برمیگرداند.
### `repeat()`
`string.repeat(count: number): string`
- `count` تعداد دفعات تکرار رشته است.
- نمونه: `"123".repeat(2)` مقدار `"123123"` را برمیگرداند.
### `reverse()`
`string.reverse(): string`
- رشته را معکوس میکند.
- نمونه: `"hello".reverse()` مقدار `"olleh"` را برمیگرداند.
### `slice()`
`string.slice(start: number, end?: number): string`
- `start` اندیس شروع شامل است.
- `end` اندیس پایان اختیاری و غیرشامل است.
- زیررشتهای از `start` (شامل) تا `end` (غیرشامل) برمیگرداند.
- نمونه: `"hello".slice(1, 4)` مقدار `"ell"` را برمیگرداند.
- اگر `end` حذف شود، تا انتهای رشته برش میزند.
### `split()`
`string.split(separator: string | Regexp, n?: number): list`
- `separator` جداکننده برای تقسیم رشته است.
- `n` یک عدد اختیاری است. اگر ارائه شود، نتیجه شامل `n` عنصر اول خواهد بود.
- فهرستی از زیررشتهها برمیگرداند.
- نمونه: `"a,b,c,d".split(",", 3)` یا `"a,b,c,d".split(/,/, 3)` مقدار `["a", "b", "c"]` را برمیگرداند.
### `startsWith()`
`string.startsWith(query: string): boolean`
- `query` رشتهای است که باید در ابتدا بررسی شود.
- اگر این رشته با `query` شروع شود، true برمیگرداند.
- نمونه: `"hello".startsWith("he")` مقدار `true` را برمیگرداند.
### `title()`
`string.title(): string`
- رشته را به حالت عنوان تبدیل میکند (حرف اول هر کلمه بزرگ).
- نمونه: `"hello world".title()` مقدار `"Hello World"` را برمیگرداند.
### `trim()`
`string.trim(): string`
- فضای خالی را از هر دو طرف رشته حذف میکند.
- نمونه: `" hi ".trim()` مقدار `"hi"` را برمیگرداند.
## نوع عدد
توابعی که میتوانید با مقادیر عددی مانند `42`، `3.14` استفاده کنید.
### `abs()`
`number.abs(): number`
- قدر مطلق عدد را برمیگرداند.
- نمونه: `(-5).abs()` مقدار `5` را برمیگرداند.
### `ceil()`
`number.ceil(): number`
- عدد را به بالا به نزدیکترین عدد صحیح گرد میکند.
- نمونه: `(2.1).ceil()` مقدار `3` را برمیگرداند.
### `floor()`
`number.floor(): number`
- عدد را به پایین به نزدیکترین عدد صحیح گرد میکند.
- نمونه: `(2.9).floor()` مقدار `2` را برمیگرداند.
### `isEmpty()`
`number.isEmpty(): boolean`
- اگر عدد موجود نباشد، true برمیگرداند.
- نمونه: `5.isEmpty()` مقدار `false` را برمیگرداند.
### `round()`
`number.round(digits: number): number`
- عدد را به نزدیکترین عدد صحیح گرد میکند.
- به صورت اختیاری، پارامتر `digits` را برای گرد کردن به آن تعداد رقم اعشار ارائه دهید.
- نمونه: `(2.5).round()` مقدار `3` را برمیگرداند، و `(2.3333).round(2)` مقدار `2.33` را برمیگرداند.
### `toFixed()`
`number.toFixed(precision: number): string`
- `precision` تعداد ارقام اعشار است.
- رشتهای با عدد در نماد نقطه ثابت برمیگرداند.
- نمونه: `(3.14159).toFixed(2)` مقدار `"3.14"` را برمیگرداند.
## نوع فهرست
توابعی که میتوانید با فهرست مرتبی از عناصر مانند `[1, 2, 3]` استفاده کنید.
### فیلدها
| فیلد | نوع | توضیح |
| ------------- | -------- | ------------------------------ |
| `list.length` | `number` | تعداد عناصر فهرست |
### `contains()`
`list.contains(value: any): boolean`
- `value` عنصری است که باید جستجو شود.
- اگر فهرست شامل `value` باشد، true برمیگرداند.
- نمونه: `[1,2,3].contains(2)` مقدار `true` را برمیگرداند.
### `containsAll()`
`list.containsAll(...values: any): boolean`
- `values` یک یا چند عنصر برای جستجو هستند.
- اگر فهرست شامل همه `values` باشد، true برمیگرداند.
- نمونه: `[1,2,3].containsAll(2,3)` مقدار `true` را برمیگرداند.
### `containsAny()`
`list.containsAny(...values: any): boolean`
- `values` یک یا چند عنصر برای جستجو هستند.
- اگر فهرست شامل حداقل یکی از `values` باشد، true برمیگرداند.
- نمونه: `[1,2,3].containsAny(3,4)` مقدار `true` را برمیگرداند.
### `filter()`
`list.filter(value: Boolean): list`
- فهرست را پالایش کرده و فقط عناصری را نگه میدارد که عبارت برایشان صحیح باشد.
- `value` مقدار یک آیتم در فهرست است.
- `index` اندیس مقدار فعلی است.
- نمونه: `[1,2,3,4].filter(value > 2)` مقدار `[3,4]` را برمیگرداند.
### `flat()`
`list.flat(): list`
- فهرست تودرتو را به یک فهرست واحد مسطح میکند.
- نمونه: `[1,[2,3]].flat()` مقدار `[1,2,3]` را برمیگرداند.
### `isEmpty()`
`list.isEmpty(): boolean`
- اگر فهرست هیچ عنصری نداشته باشد، true برمیگرداند.
- نمونه: `[1,2,3].isEmpty()` مقدار `false` را برمیگرداند.
### `join()`
`list.join(separator: string): string`
- `separator` رشتهای است که بین عناصر درج میشود.
- همه عناصر فهرست را در یک رشته واحد متصل میکند.
- نمونه: `[1,2,3].join(",")` مقدار `"1,2,3"` را برمیگرداند.
### `map()`
`list.map(value: Any): list`
- هر عنصر فهرست را با استفاده از یک عبارت دگرگون میکند.
- `value` مقدار یک آیتم در فهرست است.
- `index` اندیس مقدار فعلی است.
- نمونه: `[1,2,3,4].map(value + 1)` مقدار `[2,3,4,5]` را برمیگرداند.
### `reduce()`
`list.reduce(expression: Any, acc: Any): Any`
- فهرست را با اجرای یک عبارت برای هر عنصر به یک مقدار واحد کاهش میدهد. عبارت باید مقدار بعدی `acc` را برگرداند. از `value` برای عنصر فعلی، `index` برای موقعیت آن و `acc` برای نتیجه انباشتهشده تا کنون استفاده کنید.
- `expression` برای هر عنصر در فهرست ارزیابی میشود.
- `value` مقدار آیتم فعلی در فهرست است.
- `index` اندیس آیتم فعلی است.
- `acc` مقدار انباشتهشده تا کنون است.
- نمونه (مجموع): `[1,2,3].reduce(acc + value, 0)` مقدار `6` را برمیگرداند.
- نمونه (بیشینه): `values.filter(value.isType("number")).reduce(if(acc == null || value > acc, value, acc), null)` بزرگترین عدد یا `null` در صورت نبود عدد برمیگرداند.
### `reverse()`
`list.reverse(): list`
- فهرست را در جا معکوس میکند.
- نمونه: `[1,2,3].reverse()` مقدار `[3,2,1]` را برمیگرداند.
### `slice()`
`list.slice(start: number, end?: number): list`
- `start` اندیس شروع شامل است.
- `end` اندیس پایان اختیاری و غیرشامل است.
- یک کپی سطحی از بخشی از فهرست از `start` (شامل) تا `end` (غیرشامل) برمیگرداند.
- نمونه: `[1,2,3,4].slice(1,3)` مقدار `[2,3]` را برمیگرداند.
- اگر `end` حذف شود، تا انتهای فهرست برش میزند.
### `sort()`
`list.sort(): list`
- عناصر فهرست را از کوچکترین به بزرگترین مرتب میکند.
- نمونه: `[3, 1, 2].sort()` مقدار `[1, 2, 3]` را برمیگرداند.
- نمونه: `["c", "a", "b"].sort()` مقدار `["a", "b", "c"]` را برمیگرداند.
### `unique()`
`list.unique(): list`
- عناصر تکراری را حذف میکند.
- نمونه: `[1,2,2,3].unique()` مقدار `[1,2,3]` را برمیگرداند.
## نوع پیوند
توابعی که میتوانید روی یک پیوند استفاده کنید. پیوندها میتوانند از یک فایل (`file.asLink()`) یا یک مسیر (`link("path")`) ایجاد شوند.
### `asFile()`
`link.asFile(): file`
- اگر پیوند به یک فایل محلی معتبر اشاره کند، یک شیء فایل برمیگرداند.
- نمونه: `link("[[filename]]").asFile()`.
### `linksTo()`
`link.linksTo(file): boolean`
- اگر فایل نمایشدادهشده توسط `link` پیوندی به `file` داشته باشد، `true` برمیگرداند.
## نوع فایل
توابعی که میتوانید با فایلهای موجود در گاوصندوق استفاده کنید.
### فیلدها
فیلدهای زیر برای فایلها در دسترس هستند:
| فیلد | نوع | توضیح |
| ----------------- | -------- | ------------------------------------------------------ |
| `file.name` | `string` | نام این فایل. |
| `file.basename` | `string` | نام این فایل بدون پسوند. |
| `file.path` | `string` | مسیر کامل این فایل، نسبت به ریشه گاوصندوق. |
| `file.folder` | `string` | مسیر کامل پوشه والد. |
| `file.ext` | `string` | پسوند فایل برای این فایل. |
| `file.size` | `number` | اندازه این فایل، به بایت. |
| `file.properties` | `object` | ویژگیهای یادداشت برای این فایل. |
| `file.tags` | `list` | برچسبهای این فایل. شامل برچسبهای درونخطی نیز هست. |
| `file.links` | `list` | پیوندهای داخلی درون این فایل. |
| `file.ctime` | `date` | مُهر زمانی ایجاد این فایل. |
| `file.mtime` | `date` | مُهر زمانی آخرین تغییر این فایل. |
### `asLink()`
`file.asLink(display?: string): Link`
- `display` متن نمایشی اختیاری برای پیوند است.
- یک شیء پیوند برمیگرداند که به صورت پیوند عملکردی رندر میشود.
- نمونه: `file.asLink()`
### `hasLink()`
`file.hasLink(otherFile: file | string): boolean`
- `otherFile` یک شیء فایل دیگر یا مسیر رشتهای برای بررسی است.
- اگر `file` به `otherFile` پیوند داشته باشد، true برمیگرداند.
- نمونه: `file.hasLink(otherFile)` مقدار `true` را برمیگرداند اگر پیوندی از `file` به `otherFile` وجود داشته باشد.
### `hasProperty()`
`file.hasProperty(name: string): boolean`
- اگر فایل ویژگی دادهشده را داشته باشد، `true` برمیگرداند.
### `hasTag()`
`file.hasTag(...values: string): boolean`
- `values` یک یا چند نام برچسب هستند.
- اگر فایل هر یک از برچسبهای موجود در `values` را داشته باشد، true برمیگرداند.
- نمونه: `file.hasTag("tag1", "tag2")` مقدار `true` را برمیگرداند اگر فایل برچسب `#tag1` یا `#tag2` را داشته باشد. همچنین شامل هر [[برچسبها#برچسبهای تودرتو|برچسب تودرتو]] مانند `#tag1/a` یا `#tag2/b` نیز میشود.
### `inFolder()`
`file.inFolder(folder: string): boolean`
- `folder` نام پوشهای است که باید بررسی شود.
- اگر فایل در پوشه مشخصشده یا یکی از زیرپوشههای آن باشد، true برمیگرداند.
- نمونه: `file.inFolder("notes")` مقدار `true` را برمیگرداند.
## نوع شیء
توابعی که میتوانید با مجموعهای از جفتهای کلید-مقدار مانند `{"a": 1, "b": 2}` استفاده کنید.
### `isEmpty()`
`object.isEmpty(): boolean`
- اگر شیء هیچ ویژگی خاص خودش نداشته باشد، true برمیگرداند.
- نمونه: `{}.isEmpty()` مقدار `true` را برمیگرداند.
### `keys()`
`object.keys(): list`
- فهرستی شامل کلیدهای شیء برمیگرداند.
### `values()`
`object.values(): list`
- فهرستی شامل مقادیر شیء برمیگرداند.
## نوع عبارت باقاعده
توابعی که میتوانید با الگوی عبارت باقاعده استفاده کنید. نمونه: `/abc/`.
### `matches()`
`regexp.matches(value: string): boolean`
- `value` رشتهای است که باید آزمایش شود.
- اگر عبارت باقاعده با `value` مطابقت داشته باشد، true برمیگرداند.
- نمونه: `/abc/.matches("abcde")` مقدار `true` را برمیگرداند.