적응형 카드 디자이너를 사용하여 위젯 템플릿 만들기

Windows 위젯에 대한 UI 및 상호 작용은 적응형 카드를 사용하여 구현됩니다. 각 위젯은 시각적 템플릿과 선택적으로 적응형 카드 스키마를 준수하는 JSON 문서를 사용하여 정의된 데이터 템플릿을 제공합니다. 이 문서에서는 간단한 위젯 템플릿을 만드는 단계를 안내합니다.

계산 위젯

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

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

적응형 카드 디자이너

적응형 카드 디자이너는 적응형 카드용 JSON 템플릿을 쉽게 생성할 수 있는 온라인 대화형 도구입니다. 디자이너를 사용하면 위젯 템플릿을 빌드할 때 렌더링된 시각적 개체와 데이터 바인딩 동작을 실시간으로 볼 수 있습니다. 링크를 따라 디자이너를 엽니다. 이 디자이너는 이 튜토리얼의 모든 단계에 사용됩니다.

사전 설정에서 빈 템플릿 만들기

페이지 위쪽의 호스트 앱 선택 드롭다운에서 위젯 보드를 선택합니다. 그러면 적응형 카드의 컨테이너 크기가 위젯에 지원되는 크기로 설정됩니다. 위젯은 작은 크기, 중간 크기 및 큰 크기를 지원합니다. 기본 템플릿 사전 설정의 크기는 작은 위젯에 대해 올바른 크기입니다. 위젯 내부에 맞게 디자인된 콘텐츠로 대체되므로 콘텐츠가 테두리를 넘칠지 걱정하지 마세요.

페이지 아래쪽에는 세 개의 텍스트 편집기가 있습니다. 레이블이 지정된 카드 페이로드 편집기에는 위젯의 UI에 대한 JSON 정의가 포함되어 있습니다. 레이블이 지정된 샘플 데이터 편집기 편집기 에는 위젯에 대한 선택적 데이터 컨텍스트를 정의하는 JSON이 포함되어 있습니다. 데이터 컨텍스트는 위젯이 렌더링될 때 적응형 카드에 동적으로 바인딩됩니다. 적응형 카드의 데이터 바인딩에 대한 자세한 내용은 적응형 카드 템플릿 언어를 참조하세요.

세 번째 텍스트 편집기는 샘플 호스트 데이터 편집기로 레이블이 붙어 있습니다. 이 편집기가 페이지의 다른 두 편집기 아래로 축소될 수 있음을 유의하세요. 그렇다면 +를 클릭하여 편집기를 확장합니다. 위젯 호스트 앱은 위젯 템플릿에서 사용할 수 있는 호스트 속성을 지정하여 현재 속성 값에 따라 다른 콘텐츠를 동적으로 표시할 수 있습니다. 위젯 보드는 다음 호스트 속성을 지원합니다.

페이지 맨 위에 있는 호스트 앱 선택 드롭다운 옆에 있는 컨테이너 크기 및 테마 드롭다운을 사용하면 편집기에서 샘플 호스트 JSON을 수동으로 편집하지 않고도 이러한 속성을 설정할 수 있습니다.

새 카드 만들기

페이지의 왼쪽 위 모서리에서 새 카드 버튼을 클릭합니다. 만들기 대화 상자에서 빈 카드를 선택합니다. 이제 빈 적응형 카드가 표시됩니다. 또한 샘플 데이터 편집기에서 JSON 문서가 비어 있음을 알 수 있습니다.

만들 계산 위젯은 매우 간단하며, 4개의 TextBlock 요소와 위젯 단추를 정의하는 action.Execute형식의 하나의 작업으로만 구성됩니다.

TextBlock 요소 추가

페이지 왼쪽에 있는 Card 요소 창에서 4개의 TextBlock 요소를 미리보기 창의 빈 적응형 카드로 드래그하여 추가하세요. 이 시점에서 위젯 미리 보기는 다음 이미지와 같이 표시됩니다. 콘텐츠가 위젯 테두리 외부로 다시 오버플로되지만 다음 단계에서 수정됩니다.

조건부 레이아웃 구현

카드 페이로드 편집기가 우리가 추가한 TextBlock 요소를 반영하도록 업데이트되었습니다. 본문 개체의 JSON 문자열을 다음으로 바꿉다.

"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 조건부 레이아웃을 참조하세요.

이제 미리 보기는 다음 이미지와 같이 표시됩니다.

조건문은 미리 보기에 반영되지 않습니다. 디자이너가 위젯 호스트의 동작을 시뮬레이션하지 않기 때문입니다. 페이지 맨 위에 있는 미리 보기 모드 단추를 클릭하여 시뮬레이션을 시작합니다. 이제 위젯 미리 보기는 다음 이미지와 같습니다.

컨테이너 크기 드롭다운에서 "중간"을 선택하면 미리 보기가 중간 크기의 TextBlock만 표시되도록 전환됩니다. 미리 보기의 컨테이너도 크기를 변경하여 미리 보기를 사용하여 지원되는 각 크기에 대한 위젯 컨테이너 내에 UI가 맞는지 확인하는 방법을 보여 줍니다.

데이터 컨텍스트에 바인딩

예제 위젯은 "count"라는 사용자 지정 상태 속성을 사용합니다. 현재 템플릿에서 첫 번째 TextBlock 의 값에 변수 참조 $count가 포함되어 있음을 확인할 수 있습니다. 위젯 보드에서 위젯을 실행하는 경우 위젯 공급자는 데이터 페이로드를 어셈블하고 위젯 호스트에 전달합니다. 디자인 타임에 샘플 데이터 편집기를 사용하여 데이터 페이로드를 프로토타입으로 만들고 다양한 값이 위젯 표시에 미치는 영향을 확인할 수 있습니다. 빈 데이터 페이로드를 다음 JSON으로 바꿉다.

{"count": "2"}

이제 미리 보기에서 개수 속성에 지정된 값을 첫 번째 TextBlock텍스트에 삽입합니다.

버튼 추가

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

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

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

이 JSON 문자열에서 type 속성은 표현되는 동작의 형식을 지정합니다. 위젯은 "Action.Execute" 작업 유형만 지원합니다. 제목은(는) 작업 단추에 표시되는 텍스트를 포함하고 있습니다. 동사 속성은 위젯 호스트가 작업과 연결된 의도를 전달하기 위해 위젯 공급자에게 보내는 앱 정의 문자열입니다. 위젯에는 여러 작업이 있을 수 있으며 위젯 공급자 코드는 요청에서 동사의 값을 확인하여 수행할 작업을 결정합니다.

전체 위젯 템플릿

다음 코드 목록에는 JSON 페이로드의 최종 버전이 표시됩니다.

{
    "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.Submit",
    "title": "Increment",
    "verb": "inc",
    "$when": "${!$host.isSettingsPayload}"
    },
    {
    "type": "Action.Submit",
    "title": "Update Setting",
    "verb": "setting",
    "$when": "${$host.isSettingsPayload}"
    }
],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6"
}