위젯 공급자 패키지 매니페스트 XML 형식
위젯 호스트에 표시되려면 Windows 위젯을 지원하는 앱이 시스템에 위젯 제공업체를 등록해야 합니다. Win32 앱의 경우 패키지된 앱만 현재 지원되며 위젯 공급자는 앱 패키지 매니페스트 파일에 등록 정보를 지정합니다. 이 문서에서는 위젯 등록을 위한 XML 형식을 문서화합니다. Win32 위젯 공급자에 대한 예제 패키지 매니페스트의 코드 목록은 예제 섹션을 참조하세요.
앱 확장
앱 패키지 매니페스트 파일은 Windows 앱에 대한 다양한 확장 및 기능을 지원합니다. 앱 패키지 매니페스트 형식은 패키지 매니페스트 스키마 참조에 설명된 스키마 집합에 의해 정의됩니다. 위젯 공급자는 uap3:AppExtension 내에서 등록 정보를 선언합니다. 확장의 이름 특성은 "com.microsoft.windows.widgets"로 설정해야 합니다.
위젯 공급자는 uap3:AppExtension의 자식으로 uap3:Properties를 포함해야 합니다. 패키지 매니페스트 스키마는 올바른 형식의 XML을 요구하는 것 외에는 uap3:Properties 요소의 구조를 적용하지 않습니다. 이 문서의 나머지 부분에는 위젯 호스트가 위젯 공급자를 성공적으로 등록하기 위해 기대하는 XML 형식에 대해 설명합니다.
<uap3:Extension Category="windows.appExtension">
<uap3:AppExtension Name="com.microsoft.windows.widgets" DisplayName="WidgetTestApp" Id="ContosoWidgetApp" PublicFolder="Public">
<uap3:Properties>
<!-- Widget provider registration content goes here -->
</uap3:Properties>
</uap3:AppExtension>
</uap3:Extension>
요소 계층 구조
WidgetProvider
ProviderIcons
Icon
활성화
CreateInstance
ActivateApplication
정의
정의
기능
기능
크기
ThemeResources
아이콘
Icon
스크린샷
스크린샷
DarkMode
아이콘
Icon
스크린샷
스크린샷
LightMode
아이콘
Icon
스크린샷
스크린샷
WidgetProvider
위젯 공급자 등록 정보의 루트 요소입니다.
WidgetProviderIcons
위젯 공급자 앱을 나타내는 아이콘을 지정합니다.
활성화
위젯 공급자에 대한 활성화 정보를 지정합니다. 매니페스트에 CreateInstance 및 ActivateApplication을 모두 지정하면 CreateInstance가 우선합니다.
CreateInstance
IWidgetProvider 인터페이스를 구현하는 Win32 기반 위젯 공급자에 대해 CreateInstance를 지정해야 합니다. 시스템은 CoCreateInstance를 호출하여 인터페이스를 활성화합니다. ClassId 특성은 IWidgetProvider 인터페이스를 구현하는 CreateInstance 서버에 대한 CLSID를 지정합니다.
| attribute | Type | 필수 | 설명 | 기본값 |
|---|---|---|---|---|
| ClassId | GUID | 예 | 위젯 공급자를 구현하는 CreateInstance 서버의 CLSID입니다. | 해당 없음 |
ActivateApplication
ActivateApplication을 지정하면 위젯 공급자가 명령줄을 통해 활성화되고 인수는 base64url로 인코딩된 JSON 문자열로 제공됩니다. 위젯 공급자는 CreateInstance 활성화 유형을 사용하는 것이 좋습니다. ActivateApplication 명령줄 형식에 대한 자세한 내용은 위젯 공급자 ActivateApplication 프로토콜을 참조하세요.
정의
하나 이상의 위젯 등록에 대한 컨테이너 요소입니다.
정의
단일 위젯에 대한 등록을 나타냅니다.
| attribute | Type | 필수 | 설명 | 기본값 |
|---|---|---|---|---|
| ID | string | 예 | 위젯을 식별하는 ID입니다. 이 값은 위젯 선택기의 탐색 모음에도 표시됩니다. 위젯 공급자 구현은 이 문자열을 사용하여 각 작업에 대해 참조되는 앱의 위젯을 결정하거나 지정합니다. 이 문자열은 앱 매니페스트 파일 내에 정의된 모든 위젯에 대해 고유해야 합니다. | 해당 없음 |
| DisplayName | string | 예 | 위젯 호스트에 표시되는 위젯의 이름입니다. | 해당 없음 |
| 설명 | string | 예 | 위젯에 대한 간단한 설명입니다. | 해당 없음 |
| AllowMultiple | 부울 값 | 아니요 | 이 위젯의 인스턴스가 하나만 지원되는 경우 false로 설정합니다. 이 속성은 선택 사항이며 기본값은 true입니다. | true |
| IsCustomizable | 부울 값 | 아니요 | Windows 앱 SDK 1.4에 도입되었습니다. 앱이 위젯 사용자 지정을 지원하는 경우 true로 설정합니다. 이렇게 하면 위젯의 줄임표 메뉴에 위젯 사용자 지정 단추가 표시됩니다. | false |
| AdditionalInfoUri | string | 아니요 | 위젯 프레임의 제목 표시줄을 클릭하거나 상황에 맞는 메뉴의 Powered by 요소를 클릭할 때 사용할 위젯과 연결할 수 있는 URI입니다. | 해당 없음 |
| ExcludedRegions | string | 아니요 | 위젯을 사용할 수 없는 지역 목록입니다. 위젯은 ExcludedRegions 또는 ExclusiveRegions를 지정할 수 있지만 단일 위젯 정의에서 둘 다 지정해서는 안됩니다. 특성 값은 두 문자 영역 코드의 쉼표로 구분된 목록입니다. | 해당 없음 |
| ExclusiveRegions | string | 아니요 | 위젯을 사용할 수 있어야 하는 유일한 지역 목록입니다. 위젯은 ExcludedRegions 또는 ExclusiveRegions를 지정할 수 있지만 단일 위젯 정의에서 둘 다 지정해서는 안됩니다. 특성 값은 두 문자 영역 코드의 쉼표로 구분된 목록입니다. | 해당 없음 |
기능
선택 사항. 단일 위젯에 대한 기능을 지정합니다. 기능을 선언하지 않으면 기본적으로 '큰' 크기를 지정하는 하나의 기능이 추가됩니다.
기능
위젯에 대한 기능을 지정합니다.
크기
연결된 위젯에 대해 지원되는 크기를 지정합니다.
| attribute | Type | 필수 | 설명 | 기본값 |
|---|---|---|---|---|
| 이름 | string | 예 | 위젯에 대해 지원되는 크기를 지정합니다. 값은 "small", "medium", "large" 중 하나여야 합니다. | 해당 없음 |
ThemeResources
위젯의 테마 리소스를 지정합니다.
아이콘
하나 이상의 Icon 요소에 대한 컨테이너 요소입니다.
Icon
필수입니다. 위젯의 특성 영역에 표시되는 아이콘을 지정합니다.
| attribute | Type | 필수 | 설명 | 기본값 |
|---|---|---|---|---|
| Path | string | 예 | 아이콘 이미지 파일의 패키지 상대 경로입니다. | 해당 없음 |
스크린샷
필수입니다. 위젯의 스크린샷을 하나 이상 지정합니다.
스크린샷
필수입니다. 위젯의 스크린샷을 지정합니다. 이 스크린샷은 위젯 호스트에 추가할 위젯을 선택할 때 위젯 대화 상자 추가의 위젯 호스트에 표시됩니다. 아래에 나열된 선택적 DarkMode 또는 LightMode 요소에 대한 스크린샷을 제공하는 경우 위젯 호스트는 현재 디바이스 테마와 일치하는 스크린샷을 사용합니다. 현재 디바이스 테마에 대한 스크린샷을 제공하지 않으면 이 스크린샷 요소에 제공된 이미지가 사용됩니다. 스크린샷 이미지의 디자인 요구 사항 및 지역화된 스크린샷의 명명 규칙에 대한 자세한 내용은 위젯 선택기와 통합을 참조하세요.
참고 항목
현재 미리 보기 릴리스에서는 위젯 스크린샷이 위젯 보드의 위젯 추가 대화 상자에 표시되지 않습니다.
| attribute | Type | 필수 | 설명 | 기본값 |
|---|---|---|---|---|
| Path | string | 예 | 스크린샷 이미지 파일의 패키지 상대 경로입니다. | 해당 없음 |
| DisplayAltText | string | 아니요 | 접근성을 위한 이미지의 대체 텍스트입니다. | 해당 없음 |
DarkMode
선택 사항. 디바이스에서 어둡게 모드가 활성화된 경우의 테마 리소스를 지정합니다. 선택적 DarkMode 요소에서 하나 이상의 스크린샷 이미지를 지정하는 경우 디바이스가 어둡게 모드인 경우 위젯 호스트가 이러한 스크린샷을 선택합니다. 다크 모드 이미지를 제공하지 않으면 위젯 호스트는 위에서 설명한 필수 최상위 스크린샷 요소를 사용합니다. 스크린샷 이미지의 디자인 요구 사항 및 지역화된 스크린샷의 명명 규칙에 대한 자세한 내용은 위젯 선택기와 통합을 참조하세요.
LightMode
선택 사항. 디바이스에서 라이트 모드가 활성화된 경우의 테마 리소스를 지정합니다. 선택적 LightMode 요소에 하나 이상의 스크린샷 이미지를 제공하는 경우 위젯 호스트는 디바이스가 라이트 모드에 있을 때 이러한 스크린샷을 선택합니다. 라이트 모드 이미지를 제공하지 않으면 위젯 호스트는 위에서 설명한 필수 최상위 스크린샷 요소를 사용합니다. 스크린샷 이미지의 디자인 요구 사항 및 지역화된 스크린샷의 명명 규칙에 대한 자세한 내용은 위젯 선택기와 통합을 참조하세요.
예시
다음 코드 예제에서는 위젯 패키지 매니페스트 XML 형식의 사용을 보여줍니다.
<uap3:Extension Category="windows.appExtension">
<uap3:AppExtension Name="com.microsoft.windows.widgets" DisplayName="Widget Test App" Id="ContosoWidgetApp" PublicFolder="Public">
<uap3:Properties>
<WidgetProvider>
<ProviderIcons>
<Icon Path="Images\StoreIcon.png" />
</ProviderIcons>
<Activation>
<!-- App exports COM interface which implements IWidgetProvider -->
<CreateInstance ClassId="XXXXXXXX-XXXX-XXXX-XXXX-D3397A3FF15C" />
</Activation>
<Definitions>
<Definition
Id="Weather_Widget"
DisplayName="Microsoft Weather Widget"
Description="Weather Widget Description"
AdditionalInfoUri="https://contoso.com/widgets/Weather"
ExclusiveRegions="US,UK"
AllowMultiple="true">
<Capabilities>
<Capability>
<Size Name="small" />
</Capability>
<Capability>
<Size Name="medium" />
</Capability>
<Capability>
<Size Name="large" />
</Capability>
</Capabilities>
<ThemeResources>
<Icons>
<Icon Path="Assets\icon.png" />
<Icon Path="Assets\icon.gif" />
</Icons>
<Screenshots>
<Screenshot Path="Assets\background.png" DisplayAltText ="For accessibility"/>
</Screenshots>
<!-- DarkMode and LightMode are optional -->
<DarkMode>
<Icons>
<Icon Path="Assets\dark.png" />
</Icons>
<Screenshots>
<Screenshot Path="Assets\darkBackground.png" DisplayAltText ="For accessibility"/>
</Screenshots>
</DarkMode>
<LightMode>
<Icons>
<Icon Path="Assets\light.png" />
</Icons>
<Screenshots>
<Screenshot Path="Assets\lightBackground.png"/>
</Screenshots>
</LightMode>
</ThemeResources>
</Definition>
</Definitions>
</WidgetProvider>
</uap3:Properties>
</uap3:AppExtension>
</uap3:Extension>
Windows developer