タイムゾーン

Reveal SDK はデフォルトで、今日や今月などの相対日付フィルター、日付ピッカー、および currentTimeZone() 関数にブラウザーのタイムゾーンを使用します。別のタイムゾーンでダッシュボードを表示するには (たとえば、ノート PC がロンドンに設定されているニューヨーク勤務のユーザー向け)、RevealSdkSettings.timeZone を設定します。Reveal はそのタイムゾーンを使用し、データソースから読み取るすべての DateTime フィールド (計算フィールドを除く) をそのタイムゾーンに変換します。

Reveal にはタイムゾーンピッカーは含まれていません。言語と同様に、UI はアプリケーションが提供します。

備考

タイムゾーン API は Reveal SDK 2.3.0 以降で使用できます。

タイムゾーンの設定

RevealSdkSettings.timeZone に次のいずれかの値を設定します。

値	相対日付フィルター、日付ピッカー、`currentTimeZone()` が使用するタイムゾーン	DateTime 値
`null` (デフォルト)	ブラウザーのタイムゾーン	変換なし (保存されている値のまま表示)
`RVTimeZone.Browser`	ブラウザーのタイムゾーン	ブラウザーのタイムゾーンに変換
`RVTimeZone` のメンバーまたは IANA 名	指定したタイムゾーン	指定したタイムゾーンに変換

null と RVTimeZone.Browser の違いは変換の有無だけです。2024-01-31 23:30 として保存されている値は、null では 23:30 と表示され、ブラウザーがニューヨークに設定されている場合、RVTimeZone.Browser では 18:30 と表示されます。DateTime 値をユーザー自身のタイムゾーンで表示するには、RVTimeZone.Browser を使用します。

// Use New York time instead of the browser's
RevealSdkSettings.timeZone = RVTimeZone.AmericaNewYork;

// Any IANA time zone name works too
RevealSdkSettings.timeZone = "Europe/Madrid";

// Go back to the default: the browser's time zone, with no conversion
RevealSdkSettings.timeZone = null;

RevealView を作成する前に設定することも、ダッシュボードを開いている間にいつでも設定することもできます (開いているダッシュボードでのタイムゾーンの切り替えを参照してください)。タイムゾーンはグローバルな設定です。ページ上のすべての RevealView が同じタイムゾーンを使用します。使用中のタイムゾーンを取得するには、RevealSdkSettings.getCurrentTimeZone() を呼び出します。

クライアントがすべてのデータリクエストとともにタイムゾーンを送信するため、サーバー SDK (ASP.NET、Java、Node.js) ではタイムゾーン用のコードは必要ありません。独自のタイムゾーンを指定するのはサーバー側のエクスポートのみです。

タイムゾーンリストの作成

RVTimeZone には、よく使用される 139 のタイムゾーン (UTC オフセットと夏時間ルールの組み合わせごとに 1 つ) と Browser が含まれています。すべてのメンバーは、ブラウザーとサーバーの両方で受け入れられる IANA 名です。Etc/GMT のメンバーは、IANA の定義どおり符号が反転した固定オフセットです。たとえば、Etc/GMT+8 は UTC−8 を表します。このトピックの最後にある例では、これらのメンバーをセレクターに追加します。

ブラウザーが認識するすべてのタイムゾーンを選択肢として提供するには、代わりに Intl.supportedValuesOf("timeZone") を使用します。

無効なタイムゾーン名の処理

Reveal が認識できない名前を設定するとエラーがスローされ、以前のタイムゾーンが引き続き使用されます。名前をユーザー入力や保存された設定から取得する場合は、代入を try ブロックで囲みます。

try {
    RevealSdkSettings.timeZone = userInput;
} catch (e) {
    showError(e.message); // "Invalid time zone: ..."
}

例では、保存された名前が無効になっている場合、セレクターの横にエラーが表示されます。

IANA 名のみを使用してください。Pacific Standard Time などの Windows のタイムゾーン名は拒否されます。+05:30 などのオフセット文字列は一部のブラウザーでは受け入れられますが、サーバーでは解決できないため、DateTime フィールドを含むすべての表示形式が「Unknown time zone」エラーで失敗します。固定オフセットを使用する場合は、対応する Etc/GMT のメンバー、またはそのタイムゾーンに属する都市 (UTC+5:30 の場合は Asia/Kolkata など) を使用します。

開いているダッシュボードでのタイムゾーンの切り替え

ダッシュボードの表示中に RevealSdkSettings.timeZone を設定すると、そのデータがその場で再読み込みされます。ダッシュボードは再構築されないため、ユーザーの次の状態は維持されます。

フィルターの選択
最大化された表示形式
ドリルダウンのレベルとスクロール位置

相対日付フィルターは新しいタイムゾーンに合わせて移動し (今日はそのタイムゾーンでの今日になります)、開いているポップアップは閉じます。すでに使用中の値を設定した場合は、何も再読み込みされません。

次の例では、Asia/Tokyo に切り替える前に Region フィルターを Americas に設定しています。フィルターは維持され、注文時刻のみが変わります。

DateTime 値の変換方法

タイムゾーンが設定されている間、サーバーはデータソースから読み取るすべての DateTime フィールド (計算フィールドを除く) をそのタイムゾーンに変換します。変換はグループ化、フィルタリング、書式設定の前、および計算フィールドの評価前に行われるため、計算フィールドは変換後の値を読み取ります。ダッシュボードやデータソースを変更する必要はありません。

変換は UTC を起点に行われます。Reveal 全体と同様に、タイムゾーンを持たない DateTime 値は UTC として扱われ、SQL Server の datetimeoffset や Oracle の TIMESTAMP WITH TIME ZONE など、独自のオフセットを持つ値は UTC に正規化されます。

変換されるのは DateTime フィールドのみです。 同じ行の DateTime が別の日に移動した場合でも、Date フィールドと Time フィールドがずれることはありません。
グループ化はタイムゾーンに従います。 日、週、月によるグループ化には変換後の値が使用されます。
計算フィールドは変換されません。 計算フィールドが読み取るフィールドはすでに変換済みのため、再度変換されることはありません。applyTimeZone() を呼び出す数式は、値をもう一度変換します (既存のダッシュボードのアップグレードを参照してください)。
カスタム表示形式には変換後の値が渡されます。 カスタム表示形式に渡されるデータは、すでに使用中のタイムゾーンに変換されています。

たとえば、2024-01-31 23:30 として保存されている OrderDate DateTime フィールドと、2024-02-02 として保存されている ShipDate Date フィールドを持つ注文の場合:

`RevealSdkSettings.timeZone`	`OrderDate` (DateTime)	`ShipDate` (Date)
`null`	2024-01-31 23:30	2024-02-02
`RVTimeZone.AmericaNewYork`	2024-01-31 18:30	2024-02-02
`RVTimeZone.AsiaTokyo`	2024-02-01 08:30	2024-02-02

以下のダッシュボードには、1 月 31 日から 2 月 1 日にかけて、UTC の午前 0 時前後に発生した 12 件の注文が含まれています。タイムゾーンを設定しない場合、Sales by Day は注文を 2 日に分けてグループ化します。

RVTimeZone.AsiaTokyo を設定すると、すべての OrderDate が 9 時間進むため、同じ注文が 3 日に分かれます。ShipDate は変わりません。

サポートされるデータソース

タイムゾーンの変換は、データソース別の機能サポートに記載されているデータソースでのみ動作します。タイムゾーンが設定されている間、DateTime フィールドを含む表示形式が、その他のデータソースを使用している場合、その他のデータソースをブレンドしている場合、または入れ替えたデータを使用している場合は、「Converting to the current time zone requires Engine2…」というエラーが表示されます。これらのダッシュボードでは、RevealSdkSettings.timeZone を null のままにしてください。

エクスポート

RevealView から開始したエクスポートには、ユーザーに表示されている値が、使用中のタイムゾーンで含まれます。

サーバー側のエクスポートにはブラウザーがないため、エクスポートオプションの TimeZone プロパティを使用します。このプロパティが設定されている場合、DateTime 値はそのタイムゾーンに変換され、相対日付フィルターと currentTimeZone() もそのタイムゾーンを使用します。設定されていない場合、エクスポートは UTC を使用し、値は変換されません。

ASP.NET
Java
Node.js

var pdfOptions = new PdfExportOptions()
{
    TimeZone = "America/New_York"
};

var stream = await dashboardExporter.ExportToPdf(dashboardName, options: pdfOptions);

PdfExportOptions options = new PdfExportOptions();
options.setTimeZone("America/New_York");

// revealServer is the IRevealServer your application built with RevealServerBuilder
IDashboardExporter exporter = revealServer.getDashboardExporter();
InputStream stream = exporter.exportToPdf(dashboardName, userContext, options).get();

import { PdfExportOptions } from "reveal-sdk-node";

const options = new PdfExportOptions();
options.timeZone = "America/New_York";

const stream = await revealServer.exporter.exportPdf(dashboardName, null, options, null);

同じプロパティは、Excel、PowerPoint、画像、CSV のすべてのエクスポートオプションクラスで使用できます。ユーザーがアプリケーションで選択したタイムゾーンでエクスポートするには、エクスポートリクエストとともにその選択をサーバーに送信します。

既存のダッシュボードのアップグレード

applyTimeZone([OrderDate], currentTimeZone()) や applyTimeZone([OrderDate], "Europe/Madrid") など、手動で変換を行っていた applyTimeZone() 数式を削除し、[OrderDate] を直接使用してください。タイムゾーンが設定されている間は OrderDate がすでに変換されているため、これらの数式によって値が 2 回変換されます。RevealSdkSettings.timeZone が null の間は、ダッシュボードは従来どおり動作します。

例: ユーザーによるタイムゾーンの選択

この例では、ダッシュボードの横にタイムゾーンセレクターを追加し、使用中のタイムゾーンを表示して、ユーザーの選択を記憶し、フィルターを失うことなく開いているダッシュボードのタイムゾーンを切り替えます。

手順 1 - セレクター、使用中のタイムゾーンを表示するラベル、およびエラーを表示する場所を追加します。

<select id="timeZone">
    <option value="">Browser time zone (no conversion)</option>
    <option value="Browser">Browser time zone (convert dates)</option>
</select>
<span id="currentTimeZone"></span>
<span id="timeZoneError" style="color: red"></span>
<div id="revealView" style="height: 800px; width: 100%;"></div>

手順 2 - セレクターに項目を追加し、ダッシュボードを読み込む前に保存された選択を適用して、変更時にタイムゾーンを切り替えます。

const select = document.getElementById("timeZone");
const current = document.getElementById("currentTimeZone");
const error = document.getElementById("timeZoneError");

for (const zone of Object.values(RVTimeZone)) {
    if (zone !== RVTimeZone.Browser) {
        select.add(new Option(zone.replace(/_/g, " "), zone));
    }
}

// Sets the time zone; returns false and keeps the previous one when the name is invalid
function setTimeZone(zone) {
    let applied = true;
    try {
        RevealSdkSettings.timeZone = zone || null;
        error.textContent = "";
        select.value = zone || "";
    } catch (e) {
        error.textContent = e.message;
        applied = false;
    }
    current.textContent = `Times shown in ${RevealSdkSettings.getCurrentTimeZone()}`;
    return applied;
}

select.addEventListener("change", () => {
    // An open dashboard reloads by itself, keeping its filters
    if (setTimeZone(select.value)) {
        localStorage.setItem("timeZone", select.value);
    }
});

// Apply the saved choice before creating the RevealView
setTimeZone(localStorage.getItem("timeZone") ?? "");

RevealSdkSettings.setBaseUrl("https://localhost:5111/");
RVDashboard.loadDashboard("Sales").then(dashboard => {
    const revealView = new RevealView("#revealView");
    revealView.dashboard = dashboard;
});

デバイス間で選択を引き継ぐには、localStorage の代わりにアプリケーションのユーザープロファイルに保存し、RevealView を作成する前にそこから読み取ります。

タイムゾーンの設定​

タイムゾーン リストの作成​

無効なタイムゾーン名の処理​

開いているダッシュボードでのタイムゾーンの切り替え​

DateTime 値の変換方法​

サポートされるデータ ソース​

エクスポート​

既存のダッシュボードのアップグレード​

例: ユーザーによるタイムゾーンの選択​