生理との付き合い方

期間値は、3h、2d、1w3d4h などの時間を表します。ワークフローでは、通常、予測や経過時間などのフィールドを読み取ったり更新したり、作業項目を追加したり、期間から日付を計算したりする際に、期間値を使用します。

period 型を格納するフィールドは、期間オブジェクトを返します。ワークフローコードで期間オブジェクトを作成するには、date-time モジュールを使用します。期間値を比較するには、まず共通の単位に変換してください。

ピリオド文字列構文

date-time モジュールは、数値と単位略語が続く期間文字列を受け付けます。単位はスペースを入れずに降順で指定してください。

単位	説明	サンプル
`w`	週	`2w`
`d`	日	`4d`
`h`	時間	`6h`
`m`	分	`30m`

例: 2w4d3h15m は、2 週間 4 日 3 時間 15 分を表します。

YouTrack における期間値の表示方法は、インスタンスの期間フォーマットとタイムトラッキング設定によって異なります。コンパクト文字列フォーマットは、ワークフローコードで期間値を作成する際に使用するフォーマットです。

期間値を作成する

dateTime.toPeriod() を使用して、周期文字列またはミリ秒数を周期オブジェクトに変換します。

        const dateTime = require('@jetbrains/youtrack-scripting-api/date-time');

        const threeHours = dateTime.toPeriod('3h');
        const fullPeriod = dateTime.toPeriod('2w4d3h15m');
        const fromMilliseconds = dateTime.toPeriod(3 * 60 * 60 * 1000);
    

期間を表すカスタムフィールドに値を書き込む際は、文字列ではなく期間オブジェクトを割り当ててください。

        const entities = require('@jetbrains/youtrack-scripting-api/entities');
        const dateTime = require('@jetbrains/youtrack-scripting-api/date-time');

        exports.rule = entities.Issue.onChange({
            title: 'Set default estimation',
            guard: (ctx) => {
                return ctx.issue.isReported && !ctx.issue.fields.Estimation;
            },
            action: (ctx) => {
                ctx.issue.fields.Estimation = dateTime.toPeriod('1d4h');
            },
            requirements: {
                Estimation: {
                    type: entities.Field.periodType
                }
            }
        });
    

期間フィールドの読み取り

issue.fields から期間フィールドを読み取ります。オプションフィールドは空になる場合があるため、使用する前に値が存在することを確認してください。

        const estimation = ctx.issue.fields.Estimation;

        if (estimation) {
            const weeks = estimation.getWeeks();
            const days = estimation.getDays();
            const hours = estimation.getHours();
            const minutes = estimation.getMinutes();
        }
    

YouTrack が課題に使用するのと同じ形式で値を表示するには、フィールド要件から getValuePresentation() を使用します。

        const presentation = ctx.Estimation.getValuePresentation(ctx.issue);
        ctx.issue.addComment('Current estimation: ' + presentation);
    

期間の変換

周期オブジェクトは数値ではありません。周期の値を比較、加算、減算する必要がある場合は、まず共通の単位に変換してください。

以下のヘルパー関数は、期間値を分に変換します。一般的なデフォルトの勤怠管理設定である、週 5 日作業、1 日 8 時間作業を前提としています。

        const WORKDAYS_PER_WEEK = 5;
        const HOURS_PER_DAY = 8;

        function periodToMinutes(period) {
          if (!period) {
            return 0;
          }

          return period.getMinutes() +
              60 * (period.getHours() +
                  HOURS_PER_DAY * (period.getDays() +
                      WORKDAYS_PER_WEEK * period.getWeeks()));
        }
    

YouTrack インスタンスで異なるタイムトラッキング設定を使用している場合は、定数を調整して、ご自身の作業週と作業日に合わせてください。

分単位で新しい値を計算した後、それを期間フィールドに割り当てる前に、期間単位に変換し直してください。

        const dateTime = require('@jetbrains/youtrack-scripting-api/date-time');

        const EXTRA_MINUTES = 90;
        const currentMinutes = periodToMinutes(ctx.issue.fields.Estimation);
        ctx.issue.fields.Estimation = dateTime.toPeriod((currentMinutes + EXTRA_MINUTES) * 60 * 1000);
    

期間値を比較する

2 つの期間フィールドを比較するには、両方の値を同じ単位に変換してください。以下のルールにより、ユーザーは経過時間を現在の推定値を超えて増加させることができません。

        const entities = require('@jetbrains/youtrack-scripting-api/entities');
        const workflow = require('@jetbrains/youtrack-scripting-api/workflow');

        const WORKDAYS_PER_WEEK = 5;
        const HOURS_PER_DAY = 8;

        function periodToMinutes(period) {
          if (!period) {
            return 0;
          }

          return period.getMinutes() +
              60 * (period.getHours() +
                  HOURS_PER_DAY * (period.getDays() +
                      WORKDAYS_PER_WEEK * period.getWeeks()));
        }

        exports.rule = entities.Issue.onChange({
          title: 'Do not exceed estimation',
          guard: (ctx) => {
            return ctx.issue.fields.isChanged(ctx.SpentTime);
          },
          action: (ctx) => {
            const estimation = periodToMinutes(ctx.issue.fields.Estimation);
            const spentTime = periodToMinutes(ctx.issue.fields.SpentTime);

            workflow.check(!estimation || spentTime <= estimation,
                'Spent time cannot exceed the estimation.');
          },
          requirements: {
            Estimation: {
              type: entities.Field.periodType
            },
            SpentTime: {
              type: entities.Field.periodType,
              name: 'Spent time'
            }
          }
        });
    

日付にはピリオドを使用する

タイムスタンプを前後に移動させる必要がある場合は、dateTime.after() と dateTime.before() を使用してください。

        const dateTime = require('@jetbrains/youtrack-scripting-api/date-time');

        const reminder = dateTime.before(ctx.issue.fields.DueDate, '2d');

        if (ctx.issue.fields.Estimation) {
            const reviewDate = dateTime.after(Date.now(), ctx.issue.fields.Estimation);
        }
    

これらのメソッドは、ミリ秒単位の Unix タイムスタンプを返します。結果を date または date and time フィールドに代入するか、他のタイムスタンプ値と比較してください。

作業項目の所要時間を計算する

作業項目の所要時間は分単位で記録されます。ワークフローが 2 つのタイムスタンプ間の時間を記録する場合、Project.intervalToWorkingMinutes() を使用してプロジェクトの作業時間内に含まれる分数を計算します。

        const duration = ctx.issue.project.intervalToWorkingMinutes(
            ctx.issue.fields.TimerTime,
            Date.now()
        );

        ctx.issue.addWorkItem({
          description: 'The work item automatically added by the timer.',
          date: Date.now(),
          author: ctx.currentUser,
          duration: duration
        });
    

これは、デフォルトの作業タイマーワークフローで使用されるのと同じアプローチです。計算された期間を期間フィールドに保存するには、分数をミリ秒に変換して dateTime.toPeriod() に渡します。

ヒント

期間フィールドに値を割り当てる前に、dateTime.toPeriod() を使用してください。
ワークフローコードでは、3h や 2w4d3h15m のようなコンパクトな周期文字列を使用してください。
期間値を用いて計算する必要がある場合は、getWeeks()、getDays()、getHours()、getMinutes() を使用してください。
期間の値を分に変換してから比較してください。
期間から日付を計算するには、dateTime.after() と dateTime.before() を使用します。
プロジェクトの作業時間を考慮する必要がある場合は、Project.intervalToWorkingMinutes() を使用してください。

2026 年 7 月 06 日

YouTrack および Hub ヘルプの開発者ポータル