概要
<b-calendar>はWAI-ARIAアクセシビリティに準拠しており、キーボード操作（矢印キー、Page Up/Downキー、Homeキー、Endキー）に最適化されています。国際化もサポートされており、ロケールが指定されていない場合は、ブラウザまたはページのロケールがデフォルトで使用されます。
カスタムフォームコントロール入力として日付ピッカーが必要な場合は、代わりに<b-form-datepicker>コンポーネントを使用してください。
<template>
<b-row>
<b-col md="auto">
<b-calendar v-model="value" @context="onContext" locale="en-US"></b-calendar>
</b-col>
<b-col>
<p>Value: <b>'{{ value }}'</b></p>
<p class="mb-0">Context:</p>
<pre class="small">{{ context }}</pre>
</b-col>
</b-row>
</template>
<script>
export default {
data() {
return {
value: '',
context: null
}
},
methods: {
onContext(ctx) {
this.context = ctx
}
}
}
</script>
v-modelの戻り値
デフォルトでは、<b-calendar>は日付をYYYY-MM-DD形式の文字列として返します。これは、ネイティブブラウザの<input type="date">コントロールによって返される形式と同じです。value-as-dateプロパティを設定することで、<b-calendar>にDateオブジェクト（時間部分は含まない）をv-model値として返すようにすることができます。
日付が選択されていない場合、<b-calendar>は空文字列''を返し、value-as-dateプロパティが設定されている場合はnullを返します。
value-as-dateプロパティが設定されている場合、返されるDateオブジェクトはブラウザのデフォルトのタイムゾーンになります。
無効と読み取り専用の状態
disabledプロパティを設定すると、<b-calendar>コンポーネントのすべてのインタラクティブ性が削除されます。
readonlyプロパティを設定すると、日付の選択は無効になりますが、コンポーネントはインタラクティブなままで、日付のナビゲーションが可能になります。v-modelは読み取り専用の状態では更新されません。
特定の日付を無効にする場合、または最小日付と最大日付の制限を設定する場合は、「日付の制約」セクションを参照してください。
<template>
<div>
<b-form-group label="Select calendar interactive state" v-slot="{ ariaDescribedby }">
<b-form-radio-group
v-model="state"
:aria-describedby="ariaDescribedby"
aria-controls="ex-disabled-readonly"
>
<b-form-radio value="disabled">Disabled</b-form-radio>
<b-form-radio value="readonly">Readonly</b-form-radio>
<b-form-radio value="normal">Normal</b-form-radio>
</b-form-radio-group>
</b-form-group>
<b-calendar
id="ex-disabled-readonly"
:disabled="disabled"
:readonly="readonly"
></b-calendar>
</div>
</template>
<script>
export default {
data() {
return {
state: 'disabled'
}
},
computed: {
disabled() {
return this.state === 'disabled'
},
readonly() {
return this.state === 'readonly'
}
}
}
</script>
日付の制約
最小日付と最大日付
minプロパティとmaxプロパティを使用して、カレンダーの範囲を制限します。これらのプロパティは、YYYY-MM-DD形式の日付文字列、またはDateオブジェクトを受け入れます。
<template>
<div>
<b-calendar v-model="value" :min="min" :max="max" locale="en"></b-calendar>
</div>
</template>
<script>
export default {
data() {
const now = new Date()
const today = new Date(now.getFullYear(), now.getMonth(), now.getDate())
const minDate = new Date(today)
minDate.setMonth(minDate.getMonth() - 2)
minDate.setDate(15)
const maxDate = new Date(today)
maxDate.setMonth(maxDate.getMonth() + 2)
maxDate.setDate(15)
return {
value: '',
min: minDate,
max: maxDate
}
}
}
</script>
日付の無効化
カレンダー内の特定の日付を無効にする必要がある場合は、date-disabled-fnプロパティに関数の参照を指定します。この関数には2つの引数が渡されます。
ymd YYYY-MM-DD形式の日付文字列date Dateオブジェクトとしての日付
この関数は、日付を選択できない（無効）場合はtrueを返し、日付を選択できる（有効）場合はfalseを返す必要があります。この関数は非同期にすることができず、できるだけ迅速に値を返す必要があります。
<template>
<div>
<b-calendar v-model="value" :date-disabled-fn="dateDisabled" locale="en"></b-calendar>
</div>
</template>
<script>
export default {
data() {
return {
value: ''
}
},
methods: {
dateDisabled(ymd, date) {
const weekday = date.getDay()
const day = date.getDate()
return weekday === 0 || weekday === 6 || day === 13
}
}
}
</script>
minとmaxの日付制約は、date-disabled-fnの前に最初に評価されます。
スタイル
バリアント
選択された日付のボタン（背景色）は、デフォルトで'primary'テーマバリアントになります。これをBootstrap v4のテーマバリアントカラー（'secondary'、'success'、'danger'、'warning'、'info'など）のいずれかに変更するには、selected-variantプロパティを使用します。
今日の日付も、デフォルトでは選択された日付と同じバリアントを使用して強調表示されます（テキストの色）。今日の日付に使用するテーマカラーを指定するには、today-variantプロパティを使用します。
今日の日の強調表示を完全に無効にするには、no-highlight-todayプロパティを設定します。
ナビゲーションボタンは、デフォルトで'secondary'テーマバリアントになります。これはnav-button-variantプロパティで変更できます。
<template>
<b-calendar
selected-variant="success"
today-variant="info"
nav-button-variant="primary"
></b-calendar>
</template>
幅
<b-calendar>は、デフォルト幅270pxのインラインブロック要素としてレンダリングされます（追加される可能性のあるパディングやボーダーは除く）。この幅は、小型モバイルデバイスの幅に合わせて最適化されています。
幅を変更するには、widthプロパティに有効なCSS幅（単位を含む）を設定します。
オプションとして、blockプロパティを設定することで、カレンダーを全幅にすることができます。これにより、親要素の幅に合わせて拡大されます。blockが設定されている場合、widthプロパティは無効になります。
<template>
<b-calendar block locale="en-US"></b-calendar>
</template>
260px以下の幅を設定することは推奨されません。それ以外の場合は、コンポーネントで切り捨てやレイアウトの問題が発生する可能性があります。
初期表示カレンダーの日付
デフォルトでは、日付が選択されていない場合、カレンダービューは現在の月に設定されます（今日の日付がminまたはmaxの範囲外にある場合は、minまたはmaxの日付）。initial-dateプロパティを使用して日付を指定することで、この動作を変更できます。初期日付プロパティは、ユーザーに最初に表示するカレンダー月を決定するために使用されます。コンポーネントの値を設定するものではありません。
v2.6.0以降
コンポーネント内の表示日付テキスト（例：ヘッダー内）の書式オプションを変更するには（例：ヘッダー内）、date-format-optionsプロパティを、要求された書式プロパティを含むオブジェクトに設定します。Intl.DateTimeFormatオブジェクト（国際化も参照）。
<template>
<div>
<p>Custom date format:</p>
<b-calendar
:date-format-options="{ year: 'numeric', month: 'short', day: '2-digit', weekday: 'short' }"
locale="en"
></b-calendar>
<p class="mt-3">Short date format:</p>
<b-calendar
:date-format-options="{ year: 'numeric', month: 'numeric', day: 'numeric' }"
locale="en"
></b-calendar>
</div>
</template>
次の表は、各書式プロパティの有効なオプションをまとめたものです。
| プロパティ | 可能な値 |
年 | 'numeric'または'2-digit' |
月 | 'numeric'、'2-digit'、'long'、'short'、または'narrow' |
日 | 'numeric'または'2-digit' |
曜日 | 'long'、'short'、または'narrow' |
備考
- 特定のオプションを省略すると、書式付きテキスト文字列に影響を与える可能性があります（例：
weekday）。 - 書式設定された値は、解決されたロケールによって異なります。一部のロケールでは
'narrow'形式がサポートされていない場合があり、'short'または'long'にフォールバックします（'short'が使用できない場合）。 year、month、dayは常に表示されます。値を省略する必要がある場合は、プロパティをundefinedに設定しますが、アクセシビリティの理由から、これは強くお勧めしません。
2.12.0+
カレンダーの曜日名ヘッダー形式は、デフォルトで'short'になっており、通常は曜日の3文字の略語ですが、一部のロケールではこれがオーバーライドされる場合があります。この形式は、weekday-header-formatプロパティで制御でき、3つの値のいずれかを受け入れます。
'long' 曜日の完全な名前（例：Tuesday）。全幅カレンダーを使用する場合に便利です。デフォルトのカレンダー幅では使用しないでください。'short' は、通常、選択されたロケールに応じて、曜日の名前を 2 文字または 3 文字で略したものです（例：「Tue」）。'narrow' は、通常、1 文字の略語です（例：T）。一部のロケールでは、2 つの曜日が同じ狭いスタイルを持つ場合があります（例：火曜日と木曜日の狭いスタイルはどちらも T）。これは、'short' 形式をサポートしていないロケール（例：'ar' と 'fa'）で便利です。
デフォルトでは、現在選択されている日付が、ロケールの言語でフォーマットされ、カレンダーコンポーネントの上部に表示されます。
hide-header プロパティを使用して、このヘッダーを非表示にすることができます。これは選択済み日付を視覚的に非表示にするだけであり、スクリーンリーダーユーザーには aria-live リージョンとして利用可能です。
使用例については、以下の国際化セクションを参照してください。
show-decade-nav プロパティを設定して、カレンダーの日付ナビゲーションツールバーに前の10年と次の10年のボタンを有効にします。
label-prev-decade プロパティと label-next-decade プロパティを使用して、10年単位のボタンのカスタムラベルテキストを指定できます。
使用例については、以下の国際化セクションを参照してください。
ボーダーとパディング
ボーダーとパディングのあるカレンダーが必要ですか？Bootstrapのボーダーとパディングのユーティリティクラスを使用して、ボーダーとパディングを追加します。
<template>
<b-calendar class="border rounded p-2" locale="en"></b-calendar>
</template>
デフォルトスロット
デフォルトスロットを使用して、カレンダーインターフェースの下部にオプションのコンテンツを追加します。このスロットを使用して、今日を選択やリセットなどのボタンを追加できます。
<template>
<b-calendar v-model="value" value-as-date locale="en">
<div class="d-flex" dir="ltr">
<b-button
size="sm"
variant="outline-danger"
v-if="value"
@click="clearDate"
>
Clear date
</b-button>
<b-button
size="sm"
variant="outline-primary"
class="ml-auto"
@click="setToday"
>
Set Today
</b-button>
</div>
</b-calendar>
</template>
<script>
export default {
data() {
return {
value: null
}
},
methods: {
setToday() {
const now = new Date()
this.value = new Date(now.getFullYear(), now.getMonth(), now.getDate())
},
clearDate() {
this.value = ''
}
}
}
</script>
2.12.0+
カレンダーの日付ナビゲーションボタンのコンテンツを変更するには、BootstrapVueは各ボタンにスコープ付きスロットを提供します。
'nav-prev-decade''nav-prev-year''nav-prev-month''nav-this-month'（選択済み/今日へのボタン）'nav-next-month''nav-next-year''nav-next-decade'
7つのスロットすべてで、同じスコーププロパティを使用できます。
| プロパティ | 型 | 説明 |
isRTL | ブール値 | 日付ナビゲーションバーが右から左にレンダリングされるときにtrueになります。 |
isRTL スコーププロパティを使用して、前後のボタンのコンテンツを「反転」し、左から右への向きと右から左への向きの変更に対応できます。つまり、isRTL が true の場合、前年のボタンは左ではなく右側に表示されます。
特定の日付へのCSSクラスの追加
特定の日付を強調表示する必要がある場合は、date-info-fn プロパティを、日付のセルに適用するCSSクラス文字列（または文字列の配列）を返す関数の参照に設定します。この関数には2つの引数が渡されます。
ymd YYYY-MM-DD形式の日付文字列date Dateオブジェクトとしての日付
関数は、文字列または文字列の配列を返すことができます。クラスを設定しない場合は、空文字列('')、空の配列([])、またはnullを返すことができます。
この例では、table-{variant} カラークラスを使用して、日付セルの背景色を設定しています。table-{variant} カラークラスは、テーマカラーのミュートバージョンであるため効果的です。
<template>
<div>
<b-calendar v-model="value" :date-info-fn="dateClass" locale="en"></b-calendar>
</div>
</template>
<script>
export default {
data() {
return {
value: ''
}
},
methods: {
dateClass(ymd, date) {
const day = date.getDate()
return day >= 10 && day <= 20 ? 'table-info' : ''
}
}
}
</script>
無効な日付には、関数は呼び出されません。
アクセシビリティに関する注記
クラスを使用して日付に特定の意味を伝える場合は、カレンダーの外側（またはデフォルトスロットを介して）、強調表示されている日付に関する追加のコンテキスト（aria-live リージョンなど）を、特にスクリーンリーダーユーザーのために含める必要があります。
BootstrapVueでは、将来的に、この関数を使用して、強調表示された日付にスクリーンリーダーフレンドリーなテキストメモを追加する機能が追加される可能性があります。
イベント
v-model を更新するときに 'input' イベントが送信されます。このイベントには、選択された日付である単一の引数が含まれています。デフォルトでは、値は YYYY-MM-DD 形式の文字列です（日付が選択されていない場合は空文字列）。value-as-date プロパティが設定されている場合、最初の引数は Date オブジェクトになります（日付が選択されていない場合は null）。
disabled プロパティまたは readonly プロパティが設定されている場合、'input' イベントは**送信されません**。
selected イベント
ユーザーが無効ではない日付をクリックすると、'selected' イベントが送信されます。このイベントは2つの引数を渡します。
ymd YYYY-MM-DD 形式の文字列として選択された日付date Date オブジェクトとして選択された日付
ユーザーが既に選択されている日付をクリックした場合でも、selected イベントは送信されます。これは、既に選択されている日付を再送信しない 'input' イベントとは異なります。
disabled プロパティまたは readonly プロパティが設定されている場合、'selected' イベントは**送信されません**。
context イベント
'context' イベントは、ユーザーが日付を選択した場合、またはユーザーがカレンダーをナビゲートした場合（カーソルキー、Page Up/Downキー、HomeキーまたはEndキーを使用するか、カレンダーナビゲーションボタンを使用）に送信されます。コンポーネントが作成されたとき（DOMへの挿入直前）または解決されたロケールが変更されたときにも送信されます。
readonly プロパティが設定されている場合でも、ユーザーがカレンダーをナビゲートするときにイベントは送信されます。disabled プロパティが設定されている場合（カレンダーが作成されたときの最初の送信を除く）、イベントは送信されません。
'context' イベントには、次のプロパティを持つコンテキストオブジェクトが唯一の引数として渡されます。
| プロパティ | 説明 |
selectedYMD | 選択された日付の値（YYYY-MM-DD 形式）。日付が選択されていない場合は空文字列。 |
selectedDate | Date オブジェクトとしての選択された日付の値。日付が選択されていない場合はnull。 |
selectedFormatted | 現在のロケールでフォーマットされた選択された日付。日付が選択されていない場合は、label-no-date-selected プロパティの値になります。 |
activeYMD | フォーカスを受け取ることができるカレンダーの日付ボタンの現在の日付（YYYY-MM-DD 形式の文字列）。 |
activeDate | フォーカスを受け取ることができるカレンダーの日付ボタンの現在の日付（Date オブジェクト）。 |
activeFormatted | 現在のロケールでフォーマットされたアクティブな日付。 |
disabled | アクティブな日付が無効な場合はtrue、そうでない場合はfalse。 |
locale | 解決されたロケール（要求されたロケールと異なる場合があります）。 |
calendarLocale | カレンダーで使用される解決されたロケール。必要に応じて、カレンダーの種類（つまり「gregory」）が含まれます。通常、これはlocaleと同じですが、ペルシャロケール（'fa'）を選択したときにfa-u-ca-gregoryなど、使用されるカレンダーの種類が含まれる場合があります。 |
isRTL | カレンダーがRTL（右から左）の向きになっている場合はtrue、LTR（左から右）の場合はfalseになります。 |
Intl.DateTimeFormatを使用して日付を手動でフォーマットする場合は、<b-calendar>と同じカレンダー規則を使用するように、localeプロパティ値ではなくcalendarLocaleプロパティ値を使用してください。これは、Intl.DateTimeFormatのすべての機能を完全に実装していないIE 11ブラウザの場合に特に当てはまります。詳細については、以下の国際化セクションを参照してください。
国際化
カレンダーの国際化は、カレンダーコントロールの要素に適用されるラベル（aria-ラベル、選択状態、ヘルプテキスト）を除き、Intl.DateTimeFormatを介して提供されます。これらのラベルには、独自の翻訳を提供する必要があります。使用可能なロケールはブラウザによって異なります（すべてのブラウザがすべてのロケールをサポートしているわけではありません）。
デフォルトでは、<b-calendar>はブラウザのデフォルトロケールを使用しますが、localeプロパティを使用して、使用するロケール（またはロケール）を指定できます。このプロパティは、単一のロケール文字列またはロケール文字列の配列（優先ロケールの順序でリストされています）のいずれかを قبولします。
カレンダーは日曜日から週が始まります。これは、start-weekday プロパティを 0 から 6 の範囲の数値に設定することで変更できます。0 は日曜日、1 は月曜日、6 は土曜日を表します。
発信されるcontextイベントには、カレンダーが解決したロケールが含まれます（Intlのサポートされているロケールによっては、要求されたロケールと異なる場合があります）。
<template>
<b-row>
<b-col cols="12" class="mb-3">
<label for="example-locales">Locale:</label>
<b-form-select id="example-locales" v-model="locale" :options="locales"></b-form-select>
<label for="example-weekdays" class="mt-2">Start weekday:</label>
<b-form-select id="example-weekdays" v-model="weekday" :options="weekdays"></b-form-select>
<b-form-checkbox v-model="showDecadeNav" switch inline class="my-2">
Show decade navigation buttons
</b-form-checkbox>
<b-form-checkbox v-model="hideHeader" switch inline class="my-2">
Hide the date header
</b-form-checkbox>
</b-col>
<b-col md="auto">
<b-calendar
v-model="value"
v-bind="labels[locale] || {}"
:locale="locale"
:start-weekday="weekday"
:hide-header="hideHeader"
:show-decade-nav="showDecadeNav"
@context="onContext"
></b-calendar>
</b-col>
<b-col>
<p>Value: <b>'{{ value }}'</b></p>
<p class="mb-0">Context:</p>
<pre class="small">{{ context }}</pre>
</b-col>
</b-row>
</template>
<script>
export default {
data() {
return {
value: '',
context: null,
showDecadeNav: false,
hideHeader: false,
locale: 'en-US',
locales: [
{ value: 'en-US', text: 'English US (en-US)' },
{ value: 'de', text: 'German (de)' },
{ value: 'ar-EG', text: 'Arabic Egyptian (ar-EG)' },
{ value: 'zh', text: 'Chinese (zh)' }
],
weekday: 0,
weekdays: [
{ value: 0, text: 'Sunday' },
{ value: 1, text: 'Monday' },
{ value: 6, text: 'Saturday' }
],
labels: {
de: {
labelPrevDecade: 'Vorheriges Jahrzehnt',
labelPrevYear: 'Vorheriges Jahr',
labelPrevMonth: 'Vorheriger Monat',
labelCurrentMonth: 'Aktueller Monat',
labelNextMonth: 'Nächster Monat',
labelNextYear: 'Nächstes Jahr',
labelNextDecade: 'Nächstes Jahrzehnt',
labelToday: 'Heute',
labelSelected: 'Ausgewähltes Datum',
labelNoDateSelected: 'Kein Datum gewählt',
labelCalendar: 'Kalender',
labelNav: 'Kalendernavigation',
labelHelp: 'Mit den Pfeiltasten durch den Kalender navigieren'
},
'ar-EG': {
weekdayHeaderFormat: 'narrow',
labelPrevDecade: 'العقد السابق',
labelPrevYear: 'العام السابق',
labelPrevMonth: 'الشهر السابق',
labelCurrentMonth: 'الشهر الحالي',
labelNextMonth: 'الشهر المقبل',
labelNextYear: 'العام المقبل',
labelNextDecade: 'العقد القادم',
labelToday: 'اليوم',
labelSelected: 'التاريخ المحدد',
labelNoDateSelected: 'لم يتم اختيار تاريخ',
labelCalendar: 'التقويم',
labelNav: 'الملاحة التقويم',
labelHelp: 'استخدم مفاتيح المؤشر للتنقل في التواريخ'
},
zh: {
weekdayHeaderFormat: 'narrow',
labelPrevDecade: '过去十年',
labelPrevYear: '上一年',
labelPrevMonth: '上个月',
labelCurrentMonth: '当前月份',
labelNextMonth: '下个月',
labelNextYear: '明年',
labelNextDecade: '下一个十年',
labelToday: '今天',
labelSelected: '选定日期',
labelNoDateSelected: '未选择日期',
labelCalendar: '日历',
labelNav: '日历导航',
labelHelp: '使用光标键浏览日期'
}
}
}
},
methods: {
onContext(ctx) {
this.context = ctx
}
}
}
</script>
現在、<b-calendar>はグレゴリオ暦（'gregory'）のみをサポートしています。
デフォルトでは、<b-calendar>は解決されたロケールを使用してRTLとLTRを自動的に検出します。directionプロパティを文字列rtlに設定してカレンダーを右から左へのレンダリングを強制的に行うか、directionプロパティを'ltr'に設定して常に左から右へのレンダリングを行うことができます。
contextイベントをリッスンして、カレンダーが解決したロケールと方向性を判断できます。
Node.jsを使用するサーバーサイドレンダリング（SSR）の場合、使用しているNode.jsランタイムがIntlと使用するロケールをサポートしていることを確認してください。詳細は、Node Intlサポートドキュメントを参照してください。
アクセシビリティ
<b-calendar>は、aria-live領域、ロール、ariaラベリング、ショートカットキー、およびフルキーボードナビゲーションなど、多くのアクセシビリティ機能を提供して、ほとんどのスクリーンリーダーで動作します。
キーボードナビゲーション
- ArrowLeft 前の日へ移動します（RTLモードでは次の日）。
- ArrowRight 次の日へ移動します（RTLモードでは前日）。
- ArrowUp 前の週の同じ日へ移動します。
- ArrowDown 次の週の同じ日へ移動します。
- PageUp 前の月の同じ日へ移動します。
- PageDown 次の月の同じ日へ移動します。
- Alt+PageUp 前年の同じ日と月へ移動します。
- Alt+PageDown 次年の同じ日と月へ移動します。
- Ctrl+Alt+PageUp 前の10年の同じ日と月へ移動します。
- Ctrl+Alt+PageDown 次の10年の同じ日と月へ移動します。
- Home 今日の日付へ移動します。
- End 現在選択されている日付へ移動します。日付が選択されていない場合は今日の日付へ移動します。
- EnterまたはSpace 現在強調表示されている（フォーカスされている）日を選択します。
いくつかのlabel-*プロパティは画面に表示されませんが、スクリーンリーダーユーザーのためにカレンダー内のさまざまな要素にラベルを付けるために使用されます。例：label-todayプロパティは、今日の日の日付を含むセルに追加されます。'January 28, 2020 (Today)'、一方label-selectedプロパティは、選択された日付を含むセル'January 28, 2020 (Selected date)'に追加され、選択された日付の見出しにもsr-onlyテキストとして追加されます。
日付ピッカーを国際化する場合、国際的なスクリーンリーダーユーザーが正しいプロンプトと説明を聞くことができるように、適切な翻訳済み文字列を使用してlabel-*プロパティも更新することが重要です。
<b-calendar>の機能とスタイルは、意図的に最小限に抑えられており、すべてのユーザーに可能な限り最高のアクセシビリティを提供しています。
実装に関する注記
<b-calendar>は、Bootstrapのボーダーとフレックスのユーティリティクラス、ボタン（btn-*）クラス、およびform-controlクラスを使用しています。適切なスタイル設定には、BootstrapVueのカスタムSCSS/CSSも必要です。
アクセシビリティの観点から、冗長性を最小限に抑え、さまざまなスクリーンリーダー（NVDAは、gridロールに遭遇すると、フォーカスされているセルを「選択済み」として読み取ることがあり、ユーザーにとって誤解を招く可能性があります）間の一貫性を確保するために、カレンダーにARIAロールgridを使用しないことを選択しました。
参照