コントロールに対してタスクレコーダーが生成するテキストの制御

[アーティクル]
03/21/2023

この記事では、タスクレコーダーがコントロールに対して生成する命令ラベルを決定する方法について説明します。また、これらのラベルがユーザーにとって意味があることを確認できる方法について説明します。

タスクガイド、Microsoft Word 文書、およびヘルプコンテンツは、可読性のためにコンテンツ作成標準に適合するように、すべてのコントロールには有用で意味のある指示ラベルが必要です。最初に、次の 2 つの項目を定義する必要があります。

コントロールラベル - コントロールのラベルプロパティから取得される値です。
命令ラベル – コントロールがそのコントロールの使用方法について記述する際にタスクレコーダーに指示するラベル (「OK をクリック」、「ファーストネームフィールドに「John」と入力します」など)。

コントロールがタスクレコーダーにイベントを記録するとき、次の 3 つの方法を使用して、ユーザーに表示される命令ラベルを決定できます。

タスクレコーダーイベントのログの一部として、コントロールは使用する正確な命令ラベル ID を指定することがあります。ベストプラクティスとして、ラベル ID に名前を付ける方法は以下のとおりです: [クライアントコントロールタイプ名]_[プロパティまたはコマンド名] 指示ラベル ID の手動仕様については、この記事の後半のコード例を参照してください (OptionalInstructionLabelIDOverride)。
コントロールが命令ラベル ID を明示的に指定していない場合、タスクレコーダーは SysTaskRecorderLabel ファイルを参照して、次の命名構文に適合する既存の命令ラベル ID を検索しようとします: [クライアントコントロールタイプ名]_[ロパティまたはコマンド名] このタイプの命令ラベル ID が見つかった場合、タスクレコーダーはそれを使用します。
ラベルが、上記の方法を使用して特定できない場合、タスクレコーダは、より汎用的な指示ラベルに転用されます。一般的な指示ラベルは、SysTaskRecorder ラベルファイルにあります。コマンド用の汎用命令ラベルが 1つとプロパティ用の汎用命令ラベルがもう 1 つあります。
- コマンドの一般的な指示ラベルを次に示します:
  - ラベル ID: CommandUserAction
  - ラベル文字列: %2 %1
- プロパティの一般的な指示ラベルを次に示します:
  - ラベル ID: PropertySetValue
  - ラベル文字列: %1 フィールドに %2 と入力する

タスクレコーダーは、(前の 3 つの方法のいずれかで) 使用する命令ラベルを決定すると、次の引数を使用してそのラベルの文字列の書式設定を行います。

%1 – この引数は、コントロールラベルです。タスクレコーダーは、対話可能なラベルを調べることによってコントロールラベルを取得します。ただし、コントロールはこのラベルを上書きし、個々のラベルを提供します。この記事の後半のサンプルコードを参照してください (OptionalControlLabelOverride)。
%2 – この引数は、値 (プロパティの場合) またはコマンド名 (コマンドの場合) のいずれかです。この値は、イベントのロギングの一部として、コントロールがタスクレコーダーに送信した値になります。ただし、生データの値は、エンドユーザーにとって醜いまたは意味がないものです。したがって、コントロールでは、未処理のデータ値の代わりにタスクレコーダーが表示できる値のユーザーフレンドリなバージョンを提供することもできます。この記事の後半のサンプルコードを参照してください (OptionalValueLabelOverride)。
%3–%5 – これらはコマンド引数であり、めったに使用されません。ただし、たとえば、グリッドはそれらを使用して行番号を記録します。

事例研究

改善の事例研究のようにチェックボックスコントロールを使用しましょう。現在、方法 1 または方法 2 (この記事の前のセクションを参照) のいずれかを介するチェックボックスに対して命令ラベルが指定されていません。したがって、代わりに汎用プロパティ命令ラベルが使用されます。他のユーザーが、失敗した場合に情報ログを表示するという名前のフィールドのチェックボックスをオンにし記録する場合、現在の出荷タスクレコーダーは次のようになります。

失敗時に情報ログ表示フィールドで、True と入力します。

ただし、通常エンドユーザーは、チェックボックスを True に設定することの意味を理解していない場合があります。したがって、次のようなラベルを生成するためのチェックボックスの改善が推奨されます。

失敗時に情報ログ表示をチェックしてください。

こうした改善を行うには、新しいラベル ID を追加する必要があります。その後、イベントがメソッド 1 を使用してタスクレコーダーにログオンしているときに、そのユーザーはラベル ID を使用する必要があります。

ラベル ID: Checkbox_Value
ラベル文字列: 「%2 %1」

この変更により、次のような出力が生成されます。

失敗時に infolog を表示します。

これは見たいものではありません。したがって、チェックボックスがプロパティ変更イベントをタスクレコーダーに記録すると、「チェック」または「チェック解除」のいずれかを示す特定の<値ラベルを渡す必要があります。コントロールが明示的に値ラベルを指定した場合、タスクレコーダーは記録された生データ値 (この場合は True または False) の代わりにその値ラベルを使用します。この記事の後半のサンプルコードを参照してください (OptionalValueLabelOverride)。ユーザーが新しいラベルを作成し、イベントがタスクレコーダーに記録されたときの値ラベルを指定すると、コントロールは適切なテキスト出力を行います。

失敗時に情報ログ表示をチェックしてください。

最後に、チェックボックスには、チェックボックスの「例の値」を使用するため、2 番目の命令ラベルが必要です。「値の例」は、タスクレコーダーがユーザーに対して指示ラベルを表示する特別な方法を示します。タスク記録の作成者は、タスクガイドが、ガイドが記録されたときに入力されたものと同じ値を入力することをユーザーに指示するかどうか、またはビジネス要件に固有の独自の値を入力することをユーザーに指示するかどうかを指定できます。値指示ラベルの例では、以下のラベル ID 構文が表示されます: [クライアントコントロールタイプ名]_[プロパティ名]_チェックボックス例に対する例、値ラベルは次のようになります:

ラベル ID: Checkbox_Value_Example
ラベル文字列: 「%1 フィールドをオンまたはオフにします」。

次のコード例は、X++ コントロールによってプロパティ変更イベントがタスクレコーダーに記録される様子を示しています。 C++ カーネルコントロールには、同様のアプリケーションプログラミングインターフェイス (API) が存在します。コマンドイベントに、同種の API があります。

[FormPropertyAttribute(FormPropertyKind::Value, #MyPropertyName)]
    public str value(str_value = valueProperty.parmValue())
    {
        if(!prmIsDefault(_value))
        {
            using (var scope = SysTaskRecorder::addPropertyUserAction(#MyPropertyName, this, _value, [OptionalInstructionLabelIDOverride], [OptionalValueLabelOverride], [OptionalControlLabelOverride]))
            {
                // Property set logic goes here
                valueProperty.setValueOrBinding(_value);
            }
        }
    }

コントロールに対してタスク レコーダーが生成するテキストの制御

事例研究

その他のリソース

コントロールに対してタスクレコーダーが生成するテキストの制御