|
1 | | - Before submitting, delete all "<!-- TEMPLATE" marked comments in this file, |
2 | | - and the following quote banner: |
3 | | ---> |
4 | | -> See comments in Markdown for how to use this spec template |
5 | | -
|
6 | | -<!-- TEMPLATE |
7 | | - The purpose of this spec is to describe new APIs, in a way |
8 | | - that will transfer to learn.microsoft.com (https://learn.microsoft.com/microsoft-edge/webview2/). |
9 | | -
|
10 | | - There are two audiences for the spec. The first are people that want to evaluate and |
11 | | - give feedback on the API, as part of the submission process. |
12 | | - So the second audience is everyone that reads there to learn how and why to use this API. |
13 | | - Some of this text also shows up in Visual Studio Intellisense. |
14 | | - When the PR is complete, the content within the 'Conceptual Pages' section of the review spec will be incorporated into the public documentation at |
15 | | - http://learn.microsoft.com (LMC). |
16 | | -
|
17 | | - For example, much of the examples and descriptions in the `RadialGradientBrush` API spec |
18 | | - (https://github.com/microsoft/microsoft-ui-xaml-specs/blob/master/active/RadialGradientBrush/RadialGradientBrush.md) |
19 | | - were carried over to the public API page on LMC |
20 | | - (https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.media.radialgradientbrush?view=winui-2.5) |
21 | | -
|
22 | | - Once the API is on LMC, that becomes the official copy, and this spec becomes an archive. |
23 | | - For example if the description is updated, that only needs to happen on LMC and needn't |
24 | | - be duplicated here. |
25 | | -
|
26 | | - Examples: |
27 | | - * New set of classes and APIs (Custom Downloads): |
28 | | - https://github.com/MicrosoftEdge/WebView2Feedback/blob/master/specs/CustomDownload.md |
29 | | - * New member on an existing class (BackgroundColor): |
30 | | - https://github.com/MicrosoftEdge/WebView2Feedback/blob/master/specs/BackgroundColor.md |
31 | | -
|
32 | | - Style guide: |
33 | | - * Use second person; speak to the developer who will be learning/using this API. |
34 | | - (For example "you use this to..." rather than "the developer uses this to...") |
35 | | - * Use hard returns to keep the page width within ~100 columns. |
36 | | - (Otherwise it's more difficult to leave comments in a GitHub PR.) |
37 | | - * Talk about an API's behavior, not its implementation. |
38 | | - (Speak to the developer using this API, not to the team implementing it.) |
39 | | - * A picture is worth a thousand words. |
40 | | - * An example is worth a million words. |
41 | | - * Keep examples realistic but simple; don't add unrelated complications. |
42 | | - (An example that passes a stream needn't show the process of launching the File-Open dialog.) |
43 | | - * Use GitHub flavored Markdown: https://guides.github.com/features/mastering-markdown/ |
44 | | -
|
45 | | ---> |
46 | | - |
47 | 1 | Sensitivity label support for Webview2 |
48 | 2 | === |
49 | 3 |
|
50 | 4 | # Background |
51 | | -<!-- TEMPLATE |
52 | | - Use this section to provide background context for the new API(s) |
53 | | - in this spec. Try to briefly provide enough information to be able to read |
54 | | - the rest of the document. |
55 | | -
|
56 | | - This section and the appendix are the only sections that likely |
57 | | - do not get copied into any official documentation, they're just an aid |
58 | | - to reading this spec. If you find useful information in the background |
59 | | - or appendix consider moving it to documentation. |
60 | | -
|
61 | | - If you're modifying an existing API, included a link here to the |
62 | | - existing page(s) or spec documentation. |
63 | | -
|
64 | | - For example, this section is a place to explain why you're adding this |
65 | | - API rather than modifying an existing API. |
66 | | -
|
67 | | - For example, this is a place to provide a brief explanation of some dependent |
68 | | - area, just explanation enough to understand this new API, rather than telling |
69 | | - the reader "go read 100 pages of background information posted at ...". |
70 | | ---> |
71 | 5 | Web pages may contain content with sensitive information. Such information can be identified using data loss protection methods. The purpose of this API is to provide sensitivity label information, communicated by web pages through the Page Interaction Restriction Manager (see details here), to the host application. This enables the host application to be informed of the presence of sensitive content. |
72 | 6 |
|
73 | 7 | # Description |
74 | 8 |
|
75 | | -_(This is conceptual documentation that will go to learn.microsoft.com "how to" page)_ |
76 | | - |
77 | | -<!-- TEMPLATE |
78 | | - (Optional) |
79 | | -
|
80 | | - All APIs have reference docs, but some APIs or groups of APIs have an additional high level, |
81 | | - conceptual page (called a "how-to" page). This section can be used for that content. |
82 | | -
|
83 | | - For example, there are several navigation events each with their own reference doc, but then |
84 | | - there's also a concept doc on navigation |
85 | | - (https://learn.microsoft.com/microsoft-edge/webview2/concepts/navigation-events). |
86 | | -
|
87 | | - Sometimes it's difficult to decide if text belongs on a how-to page or an API page. |
88 | | - Because our API reference documentation is automatically turned into reference docs you can |
89 | | - lean towards including text in the API documentation below instead of in this conceptual |
90 | | - section. |
91 | | ---> |
92 | 9 | We propose introducing a SensitivityLabelChanged event to the CoreWebView2 object, enabling applications to monitor changes in sensitivity labels within hosted content. This functionality is restricted to URLs explicitly included in an allow list configured by the application. The allow list can be set at the profile level, thereby enabling the Page Interaction Restriction Manager for content within specified URLs. By default, the allow list is empty, preventing hosted content from transmitting sensitivity label information. |
93 | 10 | The core features of this proposal are as follows: |
94 | 11 | • Configure the allowlist filter for Page Interaction Restriction Manager at the profile level. |
@@ -196,77 +113,6 @@ void GetCurrentAllowlist() |
196 | 113 | } |
197 | 114 | ``` |
198 | 115 |
|
199 | | -<!-- TEMPLATE |
200 | | - Use this section to explain the features of the API, showing |
201 | | - example code with each description in both C# (for our WinRT API or .NET API) and |
202 | | - in C++ for our COM API. Use snippets of the sample code you wrote for the sample apps. |
203 | | - The sample code for C++ and C# should demonstrate the same thing. |
204 | | - If you are introducing a JavaScript API or otherwise the sample relies on HTML or JS |
205 | | - include that and consider including it in its own HTML or JS sample code. |
206 | | -
|
207 | | - As an example of this section, see the Examples section for the Custom Downloads |
208 | | - APIs (https://github.com/MicrosoftEdge/WebView2Feedback/blob/master/specs/CustomDownload.md). |
209 | | -
|
210 | | - The general format is: |
211 | | -
|
212 | | - ## FirstFeatureName |
213 | | -
|
214 | | - Feature explanation text goes here, including why an app would use it, how it |
215 | | - replaces or supplements existing functionality. |
216 | | -
|
217 | | - ```c# |
218 | | - void SampleMethod() |
219 | | - { |
220 | | - var show = new AnExampleOf(); |
221 | | - show.SomeMembers = AndWhyItMight(be, interesting) |
222 | | - } |
223 | | - ``` |
224 | | -
|
225 | | - ```cpp |
226 | | - void SampleClass::SampleMethod() |
227 | | - { |
228 | | - winrt::com_ptr<ICoreWebView2> webview2 = ... |
229 | | - } |
230 | | - ``` |
231 | | -
|
232 | | - If the sample code requires JS or HTML include that as well |
233 | | -
|
234 | | - ```html |
235 | | - <script> |
236 | | - chrome.webview.postMessage(...); |
237 | | - </script> |
238 | | - ``` |
239 | | -
|
240 | | - ## SecondFeatureName |
241 | | -
|
242 | | - Feature explanation text goes here, including why an app would use it, how it |
243 | | - replaces or supplements existing functionality. |
244 | | -
|
245 | | - ```c# |
246 | | - void SampleMethod() |
247 | | - { |
248 | | - var show = new AnExampleOf(); |
249 | | - show.SomeMembers = AndWhyItMight(be, interesting) |
250 | | - } |
251 | | - ``` |
252 | | -
|
253 | | - ```cpp |
254 | | - void SampleClass::SampleMethod() |
255 | | - { |
256 | | - winrt::com_ptr<ICoreWebView2> webview2 = ... |
257 | | - } |
258 | | - ``` |
259 | | -
|
260 | | -
|
261 | | - If the sample code requires JS or HTML include that as well |
262 | | -
|
263 | | - ```html |
264 | | - <script> |
265 | | - chrome.webview.postMessage(...); |
266 | | - </script> |
267 | | - ``` |
268 | | -
|
269 | | ---> |
270 | 116 | # API Details |
271 | 117 |
|
272 | 118 | ``` |
@@ -307,91 +153,3 @@ namespace Microsoft.Web.WebView2.Core |
307 | 153 | } |
308 | 154 | } |
309 | 155 | ``` |
310 | | -<!-- TEMPLATE |
311 | | - The exact API, in IDL format for our COM API and |
312 | | - in MIDL3 format (https://learn.microsoft.com/uwp/midl-3/) |
313 | | - when possible. |
314 | | -
|
315 | | - Include every new or modified type but use // ... to remove any methods, |
316 | | - properties, or events that are unchanged. |
317 | | -
|
318 | | - For the MIDL3 parts, after running build-apiwriter, open the generated |
319 | | - `Microsoft.Web.WebView2.Core.idl` and find the new or modified portions |
320 | | - generated from your modifications to the COM IDL. |
321 | | -
|
322 | | - (GitHub's markdown syntax formatter does not (yet) know about MIDL3, so |
323 | | - use ```c# instead even when writing MIDL3.) |
324 | | -
|
325 | | - Example: |
326 | | -
|
327 | | -``` |
328 | | -[uuid(B625A89E-368F-43F5-BCBA-39AA6234CCF8), object, pointer_default(unique)] |
329 | | -interface ICoreWebView2Settings4 : ICoreWebView2Settings3 { |
330 | | - /// The IsPinchZoomEnabled property enables or disables the ability of |
331 | | - /// the end user to use a pinching motion on touch input enabled devices |
332 | | - /// to scale the web content in the WebView2. It defaults to TRUE. |
333 | | - /// When set to FALSE, the end user cannot pinch zoom. |
334 | | - /// This API only affects the Page Scale zoom and has no effect on the |
335 | | - /// existing browser zoom properties (IsZoomControlEnabled and ZoomFactor) |
336 | | - /// or other end user mechanisms for zooming. |
337 | | - /// |
338 | | - /// \snippet SettingsComponent.cpp TogglePinchZooomEnabled |
339 | | - [propget] HRESULT IsPinchZoomEnabled([out, retval] BOOL* enabled); |
340 | | - /// Set the IsPinchZoomEnabled property |
341 | | - [propput] HRESULT IsPinchZoomEnabled([in] BOOL enabled); |
342 | | -} |
343 | | -``` |
344 | | -
|
345 | | -```c# (but really MIDL3) |
346 | | -namespace Microsoft.Web.WebView2.Core |
347 | | -{ |
348 | | - runtimeclass CoreWebView2Settings |
349 | | - { |
350 | | - // ... |
351 | | -
|
352 | | - [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Settings5")] |
353 | | - { |
354 | | - Boolean IsPinchZoomEnabled { get; set; }; |
355 | | - } |
356 | | - } |
357 | | -} |
358 | | -``` |
359 | | -
|
360 | | -If you are introducing a WebView2 JavaScript API include the TypeScript |
361 | | -definition of that API and reference documentation for it as well. |
362 | | -You can use https://www.typescriptlang.org/play to verify your TypeScript |
363 | | -
|
364 | | -```ts |
365 | | -interface WebView extends EventTarget { |
366 | | - postMessage(message: any) : void; |
367 | | - hostObjects: HostObjectsAsyncRoot; |
368 | | - // ... |
369 | | -} |
370 | | -
|
371 | | -interface HostObjectsAsyncRoot { |
372 | | - cleanupSome() : void; |
373 | | - options: HostObjectsOptions; |
374 | | -} |
375 | | -
|
376 | | -interface HostObjectsOptions { |
377 | | - forceLocalProperties: string[]; |
378 | | - log: (...data: any[]) => void; |
379 | | - shouldSerializeDates: boolean; |
380 | | - defaultSyncProxy: boolean; |
381 | | - forceAsyncMethodMatches: RegExp[]; |
382 | | - ignoreMemberNotFoundError: boolean; |
383 | | -} |
384 | | -``` |
385 | | -
|
386 | | ---> |
387 | | - |
388 | | - |
389 | | -# Appendix |
390 | | -<!-- TEMPLATE |
391 | | - Anything else that you want to write down about implementation notes and for posterity, |
392 | | - but that isn't necessary to understand the purpose and usage of the API. |
393 | | -
|
394 | | - This or the Background section are a good place to describe alternative designs |
395 | | - and why they were rejected, any relevant implementation details, or links to other |
396 | | - resources. |
397 | | ---> |
0 commit comments