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

아티클
03/16/2024

참고

일부 정보는 상업용으로 출시되기 전에 상당 부분 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적, 또는 묵시적인 보증을 하지 않습니다.

중요

이 항목에서 설명하는 기능은 빌드 25217부터 Windows의 Dev Channel 미리 보기 빌드에서 사용할 수 있습니다. Windows 프리뷰 빌드에 대한 자세한 내용은 Windows 10 Insider Preview를 참조하세요.

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

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

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

적응형 카드 디자이너

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

프리셋에서 빈 템플릿 만들기

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

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

세 번째 텍스트 편집기는 샘플 호스트 데이터 편집기 라벨이 지정됩니다. 이 편집기는 페이지의 다른 두 편집기 아래로 축소할 수 있습니다. 그렇다면 +를 클릭하여 편집기를 확장합니다. 위젯 보드와 같은 위젯 호스트 앱에는 위젯의 크기와 테마를 나타내는 두 가지 속성이 있습니다. 이러한 속성의 이름은 host.widgetSize 및 host.hostTheme. 지원되는 크기는 'small', 'medium' 및 'large'입니다. 지원되는 테마는 '밝은' 및 '어두운'입니다. 위젯 템플릿은 이러한 속성의 현재 값에 따라 다른 콘텐츠를 동적으로 표시할 수 있습니다. 위젯이 크기와 테마의 변경 내용에 어떻게 반응하는지 확인하려면 편집기에서 이러한 속성의 값을 조정하거나 페이지 맨 위에 있는 호스트 앱 선택 드롭다운 옆에 있는 컨테이너 크기 및 테마 드롭다운에서 이러한 값을 설정할 수도 있습니다.

새 카드 만들기

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

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

TextBlock 요소 추가

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

진행 중인 적응형 카드입니다. 새 TextBlock 텍스트가 포함된 4개의 줄이 있는 위젯을 표시합니다. 네 줄의 텍스트가 위젯의 아래쪽 테두리로 오버플로됩니다.

조건부 레이아웃 구현

추가한 TextBlock 요소를 반영하도록 Card Payload Editor가 업데이트되었습니다. 본문개체의 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이 있는 조건부 레이아웃을 참조하세요.

이제 미리 보기는 다음 이미지와 같습니다.

진행 중인 적응형 카드입니다. 이전 단계에서 표시된 JSON 페이로드에 지정된 텍스트를 포함하는 4개의 줄이 있는 위젯을 표시합니다. 요소를 조건부로 숨기는 대신 모든 요소가 표시되고 이미지의 아래쪽 테두리가 오버플로됩니다.

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

진행 중인 적응형 카드입니다. JSON 페이로드에 지정된 텍스트가 포함된 두 줄이 있는 위젯을 표시합니다. 작은 크기의 TextBlock만 렌더링됩니다.

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

데이터 컨텍스트에 바인딩

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

{"count": "2"}

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

진행 중인 적응형 카드입니다. 이제 첫 번째 텍스트 줄에 데이터 페이로드의 값 2가 포함됩니다.

버튼 추가

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

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

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

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

최종 적응형 카드입니다. 텍스트가 증분된 파란색 단추가 두 텍스트 줄 뒤 표시됩니다.

다음 코드 목록에는 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"
    }
  ]
}

다음을 통해 공유

계산 위젯