적응형 카드 Designer를 사용하여 위젯 템플릿 만들기

적응형 카드 위젯의 경우 적응형 카드 JSON 템플릿과 필요에 따라 별도의 JSON 데이터 페이로드를 사용하여 UI 및 상호 작용을 정의합니다. 이 문서에서는 데이터 바인딩 및 조건부 레이아웃이 있는 카운팅 위젯 템플릿을 단계별로 설명합니다. Windows 위젯은 URL의 HTML을 표시할 수도 있습니다. 해당 콘텐츠 형식에 대해서는 웹 위젯 공급자를 참조하세요.

계산 위젯

이 문서의 예제는 정수 값을 표시하고 위젯의 UI에서 단추를 클릭하여 값을 증가시키는 간단한 계산 위젯입니다. 이 예제 템플릿은 데이터 바인딩을 사용하여 데이터 컨텍스트에 따라 UI를 자동으로 업데이트합니다.

앱은 위젯 공급자를 구현하여 위젯 템플릿 및/또는 데이터를 생성 및 업데이트하고 위젯 호스트에 전달해야 합니다. win32 앱에서 위젯 공급자 구현 문서에서는 아래 단계에서 생성할 계산 위젯에 대한 위젯 공급자를 구현하기 위한 단계별 지침을 제공합니다.

어댑티브 카드 디자이너

적응형 카드 디자이너는 카드 JSON을 편집하고 레이아웃 및 데이터 바인딩을 미리 보기 위한 온라인 도구입니다. 디자이너를 열어 템플릿에서 작업합니다.

Important

디자이너는 자체 렌더러 및 호스트 옵션을 사용합니다. 해당 항목이 제공하는 기능이 위젯 보드에서 지원된다고, 또는 해당 항목이 Windows 특정 $host 값을 제공한다고 가정하지 마세요. 이 가이드는 호스트 사전 설정 또는 호스트 데이터 편집기를 기반으로 하지 않습니다. 지원되는 각 크기와 테마에 대해 Windows 위젯 제공자에서 최종 템플릿을 테스트합니다.

아래 이미지는 현재 디자이너 인터페이스가 아닌 카드의 레이아웃을 보여 줍니다.

빈 카드로 시작

카드 페이로드 편집기에는 카드의 JSON 정의가 있습니다. 카드의 내용을 다음 빈 카드로 대체합니다.

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": []
}

샘플 데이터 편집기에서는 선택적 JSON 데이터 컨텍스트를 포함합니다. 해당 데이터를 템플릿에 바인딩하는 방법에 대한 자세한 내용은 적응형 카드 템플릿 언어를 참조하세요.

위젯 호스트 속성 Windows

위젯 보드는 런타임에 호스트 속성을 제공합니다. ${$host.widgetSize}와 같은 템플릿 식에서 참조합니다(예: $host). 이러한 속성은 공급자의 데이터 페이로드와 별개입니다. widgetSize 샘플 데이터에 필드를 추가해도 $host.widgetSize이(가) 설정되지는 않습니다.

재산	가치	설명
host.widgetSize (위젯의 크기를 나타내는 코드 변수)	"소형", "중형" 또는 "대형"	고정된 위젯의 크기입니다.
host.hostTheme	"밝은" 또는 "어두운"	위젯 보드가 표시되는 디바이스의 현재 테마입니다.
host.isSettingsPayload	참 또는 거짓	이 값이 true이면 사용자가 위젯 상황에 맞는 메뉴에서 위젯 사용자 지정 단추를 클릭했습니다. 이 속성 값을 사용하여 사용자 지정 설정 UI 요소를 표시할 수 있습니다. 이는 IWidgetProvider2.OnCustomizationRequested 를 사용하여 위젯 공급자 앱에서 JSON 페이로드를 변경하는 대체 방법입니다. 자세한 내용은 위젯 사용자 지정 구현을 참조하세요.
host.isHeaderSupported	참 또는 거짓	이 값이 true이면 헤더 사용자 지정이 지원됩니다. 자세한 내용은 isHeaderSupported를 참조하세요.
host.isHeader	참 또는 거짓	이 값이 true이면 호스트는 위젯 헤더 렌더링을 위해 페이로드를 요청합니다.
host.isWebSupported	참 또는 거짓	이 값이 false이면 호스트는 현재 위젯의 웹 콘텐츠 로드를 지원하지 않습니다. 이 경우 웹 위젯은 위젯 공급자가 제공하는 대체 JSON 페이로드를 표시하지만 이 값을 사용하여 콘텐츠를 추가로 사용자 지정할 수 있습니다. 자세한 내용은 웹 위젯 공급자를 참조하세요.
host.isUserContextAuthenticated	참 또는 거짓	이 값이 false이면 Action.OpenUrl만 지원됩니다. isUserContextAuthenticated의 값은 대화형 작업 제한에 따라 위젯 콘텐츠를 적절하게 조정하는 데 사용할 수 있습니다.

계산 위젯은 4개의 TextBlock 요소와 버튼에 사용할 하나의 Action.Execute 동작을 사용합니다.

TextBlock 요소 추가

디자이너의 요소 팔레트에서 4개의 TextBlock 요소를 추가하거나 카드 JSON에 직접 추가합니다. 조건부 레이아웃을 적용하기 전에 카드에는 아래 그림과 같이 4줄의 텍스트가 있습니다.

조건부 레이아웃 구현

카드 페이로드 편집기에서 본문 배열을 다음 조각으로 바꾸세요.

"body": [
    {
        "type": "TextBlock",
        "text": "You have clicked the button ${count} times"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if medium",
        "$when": "${$host.widgetSize==\"medium\"}"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if small",
        "$when": "${$host.widgetSize==\"small\"}"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if large",
        "$when": "${$host.widgetSize==\"large\"}"
    }
]

적응형 카드 템플릿 언어에서 $when 속성은 연결된 값이 true로 평가될 때 포함 요소가 표시되도록 지정합니다. 값이 false로 평가되면 포함하는 요소가 표시되지 않습니다. 예제의 본문 요소에서 세 개의 TextBlock 요소 중 하나가 표시되고 다른 두 요소는 속성 값 $host.widgetSize 에 따라 숨겨집니다. 적응형 카드 지원되는 조건부에 대한 자세한 내용은 $when 조건부 레이아웃을 참조하세요.

템플릿 식을 평가하지 않으면 카드에 네 개의 텍스트 블록이 모두 표시됩니다.

위젯 보드가 템플릿을 "small"로 설정하여 $host.widgetSize로 평가하면 작은 크기의 텍스트 블록만 개수와 함께 표시됩니다.

템플릿을 공급자와 통합한 후 위젯 보드에서 고정된 위젯의 크기를 조정하고 일치하는 텍스트 블록이 표시되는지 확인합니다. 위젯 공급자 매니페스트에 테스트할 각 크기를 선언합니다. Windows 호스트 데이터가 없는 일반 디자이너 미리 보기는 이러한 조건을 확인할 수 없습니다.

데이터 컨텍스트에 바인딩

이 예제에서는 첫 번째 ${count}에서 count로 참조되는 라는 이름의 데이터 속성을 사용합니다. 런타임에 공급자는 위젯 호스트에 데이터 페이로드를 보냅니다. 디자인 타임에 샘플 데이터 편집기에서 다음 JSON을 입력하고 디자이너의 미리 보기를 사용하여 개수 바인딩을 확인합니다. 이 샘플 데이터는 별도의 Windows 호스트 속성을 제공하지 않습니다.

{"count": "2"}

{"count": "2"}를 샘플 데이터로 사용하면 템플릿 확장은 첫 번째 2에서 을(를) ${count}로 대체합니다. 미리 보기를 사용하도록 설정한 후 디자이너에서 이 바인딩을 확인합니다. 위젯 보드에서 위에서 설명한 대로 별도의 $host.widgetSize 조건을 확인합니다.

단추 추가

다음 단계는 위젯에 단추를 추가하는 것입니다. 위젯 호스트에서 사용자가 단추를 클릭하면 호스트가 위젯 공급자에게 요청을 합니다. 이 예제에서는 위젯 공급자가 개수 값을 증가시키고 업데이트된 데이터 페이로드를 반환합니다. 이 작업에는 위젯 공급자가 필요하므로 적응형 카드 Designer에서 이 동작을 볼 수는 없지만 디자이너를 사용하여 UI 내에서 단추의 레이아웃을 조정할 수 있습니다.

적응형 카드 대화형 요소는 action 요소로 정의됩니다. 카드 페이로드 편집기의 본문 요소 바로 다음에 다음 JSON 블록을 추가합니다. 본문 요소의 닫는 대괄호(]) 후에 쉼표를 추가해야 합니다. 그렇지 않으면 디자이너가 서식 오류를 보고합니다.

,
"actions": [                                                      
    {                                                               
        "type": "Action.Execute",                               
        "title": "Increment",                                   
        "verb": "inc"                                           
    }                                                               
]

type 속성은 Action.Execute를 선택하며, 위젯 호스트는 이를 공급자의 OnActionInvoked 콜백으로 전달합니다. URL 탐색에는 대신 Action.OpenUrl을 사용하세요. 해당 공급자 콜백을 호출하지 않습니다. 제목은 단추 텍스트를 제공하고 verb는 공급자가 처리하는 앱 정의 작업입니다. $host.isUserContextAuthenticated가 false이면 Action.Execute 상호 작용을 제공하지 마세요. Action.OpenUrl만 지원됩니다.

전체 위젯 템플릿

다음 코드 목록에는 카운팅 위젯 상호 작용에 대한 최종 템플릿이 표시됩니다. Action.Execute 단추에는 인증된 사용자 컨텍스트가 필요합니다. 공급자와 함께 위젯 보드에서 이를 검증하세요. 디자이너는 공급자의 증분 처리기를 실행하지 않습니다.

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": [
    {
      "type": "TextBlock",
      "text": "You have clicked the button ${count} times"
    },
    {
      "type": "TextBlock",
       "text": "Rendering Only if Small",
      "$when": "${$host.widgetSize==\"small\"}"
    },
    {
      "type": "TextBlock",
      "text": "Rendering Only if Medium",
      "$when": "${$host.widgetSize==\"medium\"}"
    },
    {
      "type": "TextBlock",
      "text": "Rendering Only if Large",
      "$when": "${$host.widgetSize==\"large\"}"
    }
    ],
   "actions": [
    {
      "type": "Action.Execute",
      "title": "Increment",
      "verb": "inc"
    }
  ]
}

설정 페이로드 예제

다음 코드 목록에서는 사용자가 위젯 사용자 지정 단추를 클릭할 때 host.isSettingsPayload 속성을 사용하여 다른 콘텐츠를 표시하는 JSON 페이로드의 간단한 예제를 보여 줍니다.

{
    "type": "AdaptiveCard",
    "body": [
    {
        "type": "Container",
        "items":[
            {
                "type": "TextBlock",
                "text": "Content payload",
                "$when": "${!$host.isSettingsPayload}"
            }
        ]
    },
    {
        "type": "Container",
        "items":[
            {
                "type": "TextBlock",
                "text": "Settings payload",
                "$when": "${$host.isSettingsPayload}"
            }
        ]
    }
],
"actions": [
    {
        "type": "Action.Execute",
        "title": "Increment",
        "verb": "inc",
        "$when": "${!$host.isSettingsPayload}"
    },
    {
        "type": "Action.Execute",
        "title": "Update Setting",
        "verb": "setting",
        "$when": "${$host.isSettingsPayload}"
    }
],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6"
}