Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Artikel ini menentukan protokol untuk mengintegrasikan aplikasi pihak pertama dan ketiga dengan Windows Snipping Tool menggunakan skema ms-screenclip: URI (Pengidentifikasi Sumber Daya Seragam). Protokol ini mendukung pengambilan gambar dan video (dengan audio) melalui Alat Pemotongan, dan pemanggil aplikasi dapat memilih fitur Alat Pemotongan mana yang akan ditampilkan aplikasi mereka.
Important
Protokol ini memerlukan aplikasi Windows yang dikemas (MSIX). Saat aplikasi Anda dipaketkan, sistem operasi secara otomatis menyediakan identitas aplikasi Anda ke Snipping Tool, yang menggunakannya untuk mengarahkan hasil tangkapan kembali ke aplikasi Anda dengan aman. Penelepon yang tidak dikemas (Win32) tidak dapat menerima respons melalui redirect-uri. Jika aplikasi yang tidak dikemas menyediakan redirect-uri, Alat Pemotongan tidak akan memberikan respons dan mungkin keluar tanpa menampilkan UI pengambilan.
Note
Protokol ini menggantikan pengalaman yang didokumenkan dalam Luncurkan cuplikan layar (Tidak digunakan lagi), yang sekarang tidak digunakan lagi.
Fitur yang didukung
Protokol Snipping Tool mendukung fitur-fitur berikut:
- Pengambilan Persegi Panjang
- Pengambilan Bentuk Bebas
- Tangkapan Jendela
- Perekaman Layar
- Menyesuaikan mode pengambilan yang tersedia
- Simpan otomatis (opsional)
Spesifikasi protokol
Format URI:ms-screenclip://{host}/{path}?{query parameters}
| Komponen | Deskripsi | Nilai |
|---|---|---|
| Skema | Skema kustom untuk Snipping Tool | ms-screenclip |
| Host | Operasi yang harus dilakukan pada Alat Pemotong |
capture atau discover |
| Jalur | Jenis media yang akan diambil (hanya berlaku untuk capture host; discover host tidak memiliki jalur) |
/image atau /video |
| Query | Parameter untuk operasi | Lihat tabel di bawah ini |
Note
Jalur dan nama parameter kueri tidak peka huruf besar/kecil. Misalnya, ms-screenclip://capture/Image?Redirect-Uri=my-app://response berulah sama dengan ms-screenclip://capture/image?redirect-uri=my-app://response.
Menangkap host
Gunakan capture host untuk meluncurkan overlay tangkapan layar Snipping Tool.
Jalur
| Jalur | Deskripsi |
|---|---|
/image |
Meluncurkan pengambilan gambar (cuplikan layar). Memerlukan parameter mode. |
/video |
Meluncurkan pengambilan video (perekaman layar). Selalu menggunakan mode persegi panjang. |
Parameter-mode (pengambilan/gambar)
Untuk jalur /image, Anda harus menentukan tepat satu parameter modus. Parameter mode adalah parameter kueri kosong tanpa nilai.
| Parameter | Deskripsi |
|---|---|
rectangle |
Mode pengambilan persegi panjang interaktif. |
freeform |
Mode pengambilan bentuk bebas interaktif. |
window |
Mode pengambilan jendela interaktif. |
Important
Parameter mode harus ditentukan tanpa nilai. Misalnya, gunakan &rectangle, bukan&rectangle=value. Memberikan nilai akan mengakibatkan respons kesalahan.
Untuk /image, Anda harus menentukan tepat satu parameter mode. Menentukan nol atau lebih dari satu mode akan menghasilkan 400 Bad Request respons kesalahan. Untuk /video, parameter mode apa pun diabaikan.
Parameter kueri (pengambilan)
Note
Parameter kueri dapat disediakan dalam urutan apa pun.
| Parameter | Tipe | Required | Deskripsi | Default |
|---|---|---|---|---|
redirect-uri |
URI | Yes | URI Panggilan Balik tempat Alat Pemotongan mengirim respons penangkapan. Aplikasi Anda harus mendaftarkan handler protokol untuk skema URI ini. Jika dihilangkan, Snipping Tool tidak menampilkan UI pengambilan dan tidak mengembalikan respons. | n/a |
user-agent |
string | Tidak (sangat disarankan) | Pengidentifikasi untuk aplikasi panggilan, digunakan untuk pengelogan dan analitik. Diperlukan untuk mendiagnosis masalah melalui saluran dukungan; mengabaikannya dengan risiko Anda sendiri. | n/a |
api-version |
string | Tidak. | Versi protokol yang akan digunakan, misalnya "1.2". Jika dihilangkan, permintaan diproses sebagai versi 1.2. |
1.2 |
x-request-correlation-id |
string | Tidak. | Pengidentifikasi unik untuk permintaan tersebut, memungkinkan referensi ke transaksi atau rantai peristiwa tertentu. | GUID yang dihasilkan secara otomatis |
enabledModes |
string (daftar) | Tidak. | Kontrol mode pengambilan mana yang tersedia di UI. Lihat EnabledModes di bawah ini. | Hanya mode yang disebutkan dalam URI. |
auto-save |
bendera | Tidak. | Saat ada, cuplikan layar atau rekaman yang diambil secara otomatis disimpan ke perangkat pengguna. | Tidak ada (tidak ada penyimpanan otomatis) |
Note
Default api-version1.2 tidak berubah ketika versi protokol yang lebih baru dirilis. Permintaan yang dihilangkan api-version selalu diproses sebagai 1.2. Untuk menggunakan fitur yang ditambahkan dalam versi yang lebih baru, atur api-version ke versi tersebut. Sebaiknya tentukan api-version secara eksplisit di setiap permintaan sehingga aplikasi Anda tetap terikat dengan versi protokol yang diketahui daripada default implisit.
Note
Ketika Anda menyediakan api-version, nilai harus sama persis dengan salah satu nilai dalam /discover array respons supportedVersions (saat ini 1.0, , 1.1dan 1.2). Nilai lain — termasuk nilai perantara seperti 1.15 atau nilai cacat seperti 1.0abc — mengembalikan 400 Bad Request respons. Untuk menemukan set versi yang diterima build Snipping Tool tertentu, panggil temukan host.
Note
Parameter auto-save mengikuti pengaturan Snipping Tool pengguna. Jika pengguna telah menonaktifkan penyimpanan otomatis di Alat Pemotongan, tangkapan tidak disimpan ke perangkat bahkan ketika permintaan Anda menyertakan auto-save.
Menemukan host
discover Gunakan host untuk mengkueri kemampuan, mode, dan versi protokol yang didukung Snipping Tool saat runtime. Ini berguna untuk memeriksa kompatibilitas sebelum membuat permintaan pengambilan.
Parameter kueri (temukan)
| Parameter | Tipe | Required | Deskripsi | Default |
|---|---|---|---|---|
redirect-uri |
URI | Yes | Callback URI tempat Snipping Tool mengirimkan respons kemampuan. Aplikasi Anda harus mendaftarkan handler protokol untuk skema URI ini. Jika dihilangkan, Snipping Tool tidak mengembalikan respons. | n/a |
user-agent |
string | Tidak (sangat disarankan) | Pengidentifikasi untuk aplikasi panggilan, digunakan untuk pengelogan dan analitik. | n/a |
x-request-correlation-id |
string | Tidak. | Pengidentifikasi unik untuk permintaan tersebut. | GUID yang dihasilkan secara otomatis |
Temukan contoh
ms-screenclip://discover?user-agent=MyApp&redirect-uri=my-app://response
Temukan format respons
Responsnya adalah objek JSON yang ditambahkan ke URI pengalihan sebagai discover parameter kueri. Berisi:
-
version: Versi protokol terbaru yang didukung build Snipping Tool ini. -
defaultVersion: Versi protokol diasumsikan ketika permintaanapi-versiontidak menyertakan. Baca ini untuk memahami bagaimana permintaan Anda yang belum di-pin ditafsirkan. -
supportedVersions: Daftar versi protokol yang diterima oleh build Snipping Tool ini. -
capabilities: Larik operasi penangkapan yang didukung, masing-masing dengan:-
path: Titik akhir pengambilan (misalnya,capture/image,capture/video). -
methods: Metode seperti HTTP yang didukung. -
parameters: Parameter yang tersedia untuk titik akhir. -
description: Deskripsi kemampuan.
-
{
"version": 1.2,
"defaultVersion": 1.2,
"supportedVersions": [1.0, 1.1, 1.2],
"capabilities": [
{
"path": "capture/image",
"methods": ["GET"],
"parameters": ["rectangle", "freeform", "window"],
"description": "Captures an image with options for shape."
},
{
"path": "capture/video",
"methods": ["GET"],
"parameters": [],
"description": "Captures a video in a defined area."
}
]
}
ModeDiaktifkan
Parameter ini enabledModes memungkinkan Anda mengontrol mode pengambilan mana yang tersedia di antarmuka pengguna Snipping Tool. Gunakan untuk membatasi atau memperluas pilihan pengguna agar sesuai dengan persyaratan aplikasi Anda.
Mode yang didukung
| Mode | Deskripsi |
|---|---|
RectangleSnip |
Mode Tangkap Persegi Panjang |
WindowSnip |
Mode pengambilan jendela. |
FreeformSnip |
Mode tangkapan bentuk bebas |
FullscreenSnip |
Mode pengambilan layar penuh. |
SnippingAllModes |
Semua mode pengambilan gambar: RectangleSnip, , WindowSnipFreeformSnip, FullscreenSnip. |
RectangleRecord |
Mode perekaman persegi panjang. |
RecordAllModes |
Semua mode perekaman: saat ini RectangleRecord saja. |
All |
Semua mode yang didukung: penyatuan SnippingAllModes dan RecordAllModes. |
Tip
All, SnippingAllModes, dan RecordAllModes adalah nilai agregat. Mode yang disertakan dapat berubah di seluruh rilis Snipping Tool. Aplikasi yang menggunakan salah satu nilai ini secara otomatis mengambil mode yang ditambahkan dalam rilis mendatang. Untuk menjaga set mode yang tersedia tetap di seluruh pembaruan, cantumkan mode tertentu secara eksplisit (misalnya, RectangleSnip,FreeformSnip).
Important
- Untuk
/image, parameter mode (misalnya,rectangle,freeform,window) diperlukan dalam URI, bahkan ketikaenabledModesditentukan. Parameter mode menentukan mode yang awalnya dipilih. - Mode yang ditentukan dalam URI selalu tersedia di UI, bahkan jika tidak tercantum dalam
enabledModes. Misalnya,?freeform&enabledModes=RectangleSnipmenyediakan cuplikan bentuk bebas (dari URI) dan persegi panjang, dengan cuplikan bentuk bebas yang telah dipilih sebelumnya. - Jika
enabledModesdihilangkan, hanya mode yang ditentukan dalam URI yang akan tersedia di UI. - Untuk
/image, jika tidak ada parameter mode yang ditentukan, permintaan tidak valid dan akan mengakibatkan kesalahan, terlepas darienabledModes.
Contoh Mode yang Diaktifkan
Aktifkan hanya cuplikan persegi panjang:
ms-screenclip://capture/image?rectangle&enabledModes=RectangleSnip&user-agent=MyApp&redirect-uri=my-app://response
Aktifkan persegi panjang dan cuplikan jendela:
ms-screenclip://capture/image?rectangle&enabledModes=RectangleSnip,WindowSnip&user-agent=MyApp&redirect-uri=my-app://response
Aktifkan semua mode pemotongan:
ms-screenclip://capture/image?rectangle&enabledModes=SnippingAllModes&user-agent=MyApp&redirect-uri=my-app://response
Aktifkan mode perekaman saja:
ms-screenclip://capture/video?enabledModes=RecordAllModes&user-agent=MyApp&redirect-uri=my-app://response
Aktifkan beberapa mode cuplikan dan perekaman:
ms-screenclip://capture/image?freeform&enabledModes=RectangleSnip,RectangleRecord&user-agent=MyApp&redirect-uri=my-app://response
Karena bentuk bebas ditentukan dalam URI, bentuk bebas akan dipilih sebelumnya. Pengguna dapat beralih antara bentuk bebas, cuplikan persegi panjang, dan rekaman persegi panjang.
Responses
Setelah pengguna menyelesaikan atau membatalkan pengambilan, Snipping Tool mengirimkan respons kembali ke aplikasi Anda melalui redirect-uri. Respons disusun sebagai parameter kueri URI yang ditambahkan ke URI pengalihan Anda.
Jika Anda redirect-uri sudah menyertakan parameter kueri (misalnya, my-app://response?sessionId=abc), parameter tersebut dipertahankan dan parameter respons ditambahkan dengan &. Anda dapat menggunakan ini untuk mengelola status spesifik pemanggil melalui callback — nilai sessionId=abc akan dikembalikan dalam URI respons bersama dengan code, reason, x-request-correlation-id, dan (untuk pengambilan yang berhasil) file-access-token.
Parameter dari respons
| Parameter | Tipe | Hadiah | Deskripsi |
|---|---|---|---|
code |
int | Always | Kode status gaya HTTP menunjukkan hasilnya. |
reason |
string | Always | Deskripsi hasil yang dapat dibaca manusia. |
x-request-correlation-id |
string | Always | ID korelasi dari permintaan asli (atau yang dihasilkan secara otomatis). |
file-access-token |
string | Hanya sukses | Token SharedStorageAccessManager yang mewakili media yang ditangkap. Gunakan ini untuk memperoleh file. |
discover |
string | Temukan saja | JSON yang dienkode URL yang berisi respons kapabilitas. |
Kode status
| Kode | Reason | Deskripsi |
|---|---|---|
| 200 | Keberhasilan | Penangkapan berhasil diselesaikan.
file-access-token disertakan dalam respons. |
| 400 | Permintaan Buruk - Parameter Tidak Valid atau Hilang | Permintaan tidak dapat diproses. Periksa apakah semua parameter yang diperlukan ada dan valid. |
| 408 | Batas Waktu Permintaan - Operasi Membutuhkan Waktu Terlalu Lama | Waktu operasi habis sebelum selesai. |
| 499 | Permintaan Tertutup Klien - Pengguna Membatalkan Cuplikan | Pengguna membatalkan pengambilan dengan menekan Escape atau mengklik. Berlaku untuk /image dan /video hanya. |
| 500 | Kesalahan Server Internal - Pemrosesan Gagal | Terjadi kesalahan tak terduga selama pengambilan. |
Contoh respons
Penangkapan berhasil:
my-app://response?code=200&reason=Success&x-request-correlation-id=aaaa0000-bb11-2222-33cc-444444dddddd&file-access-token=cccc2222-dd33-4444-55ee-666666ffffff
Pengguna dibatalkan:
my-app://response?code=499&reason=Client%20Closed%20Request%20-%20User%20Cancelled%20the%20Snip&x-request-correlation-id=bbbb1111-cc22-3333-44dd-555555eeeeee
Permintaan tidak valid (parameter mode hilang):
my-app://response?code=400&reason=Bad%20Request%20-%20Invalid%20or%20Missing%20Parameters&x-request-correlation-id=bbbb1111-cc22-3333-44dd-555555eeeeee
Contoh URI lengkap
| Kasus Penggunaan | URI | Deskripsi |
|---|---|---|
| Cuplikan layar persegi panjang | ms-screenclip://capture/image?rectangle&user-agent=MyApp&redirect-uri=my-app://response |
Perekaman persegi panjang interaktif. Hasil dikembalikan ke pemanggil. |
| Cuplikan layar bentuk bebas | ms-screenclip://capture/image?freeform&user-agent=MyApp&redirect-uri=my-app://response |
Pengambilan bentuk bebas interaktif. Hasil dikembalikan ke pemanggil. |
| Cuplikan layar jendela | ms-screenclip://capture/image?window&user-agent=MyApp&redirect-uri=my-app://response |
Pengambilan jendela interaktif. Hasil dikembalikan ke pemanggil. |
| Perekaman layar | ms-screenclip://capture/video?user-agent=MyApp&redirect-uri=my-app://response |
Perekaman layar interaktif. Hasil dikembalikan ke pemanggil. |
| Menemukan kemampuan | ms-screenclip://discover?user-agent=MyApp&redirect-uri=my-app://response |
Periksa fitur yang didukung. Kemampuan JSON dikembalikan ke pemanggil. |
| Persegi panjang dengan penyimpanan otomatis | ms-screenclip://capture/image?rectangle&auto-save&user-agent=MyApp&redirect-uri=my-app://response |
Tangkap persegi panjang dengan penyimpanan otomatis diaktifkan. |
| Persegi panjang dengan semua modus | ms-screenclip://capture/image?rectangle&enabledModes=All&user-agent=MyApp&redirect-uri=my-app://response |
Penangkapan persegi panjang telah dipilih sebelumnya, semua mode tersedia di UI. |
Meluncurkan dari aplikasi Anda
Anda harus menggunakan Launcher.LaunchUriAsync untuk meluncurkan Snipping Tool dari aplikasi paket Anda. Metode peluncuran lainnya (seperti Process.Start atau eksekusi shell) tidak akan memberikan identitas aplikasi Anda, dan Snipping Tool tidak akan memberikan respons.
Langkah 1: Mendaftarkan handler protokol
Daftarkan protokol kustom di Anda Package.appxmanifest sehingga aplikasi Anda dapat menerima respons panggilan balik. Nama protokol harus cocok dengan skema yang digunakan dalam redirect-uri.
<Extensions>
<uap:Extension Category="windows.protocol">
<uap:Protocol Name="my-app" DesiredView="default">
<uap:DisplayName>My App Protocol</uap:DisplayName>
</uap:Protocol>
</uap:Extension>
</Extensions>
Lihat Menangani aktivasi URI untuk detail selengkapnya tentang mendaftar dan menangani aktivasi protokol.
Langkah 2: Luncurkan Snipping Tool
// Capture a screenshot in rectangle mode
var uri = new Uri(
"ms-screenclip://capture/image"
+ "?rectangle"
+ "&user-agent=MyApp"
+ "&redirect-uri=my-app://capture-response"
+ "&x-request-correlation-id=" + Guid.NewGuid().ToString()
);
await Launcher.LaunchUriAsync(uri);
// Record a video
var uri = new Uri(
"ms-screenclip://capture/video"
+ "?user-agent=MyApp"
+ "&redirect-uri=my-app://capture-response"
);
await Launcher.LaunchUriAsync(uri);
// Discover capabilities (returns immediately, no capture UI)
var uri = new Uri(
"ms-screenclip://discover"
+ "?user-agent=MyApp"
+ "&redirect-uri=my-app://discover-response"
);
await Launcher.LaunchUriAsync(uri);
Langkah 3: Menangani respons
Saat pengambilan selesai (atau pengguna membatalkan), Snipping Tool mengaktifkan aplikasi Anda melalui redirect-uri Anda dengan parameter hasil yang ditambahkan ke string kueri. Sebagian besar integrasi sudah berjalan ketika respons tiba - pemanggil meluncurkan Alat Pemotongan, lalu menunggu panggilan balik - sehingga aplikasi Anda harus menangani aktivasi cold-start (aplikasi tidak berjalan) dan aktivasi ulang yang hangat (aplikasi sudah berjalan). Berlangganan ke kedua jalur di App.xaml.cs.
Menangani respons pengambilan (gambar atau video):
// In App.xaml.cs: handle protocol activation for both cold-start and warm re-activation
protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
{
// Cold-start path: the app was launched by Snipping Tool's callback.
var activatedArgs = Microsoft.Windows.AppLifecycle.AppInstance.GetCurrent().GetActivatedEventArgs();
if (activatedArgs.Kind == Microsoft.Windows.AppLifecycle.ExtendedActivationKind.Protocol)
{
if (activatedArgs.Data is Windows.ApplicationModel.Activation.IProtocolActivatedEventArgs protocolArgs)
{
_ = HandleProtocolActivationAsync(protocolArgs.Uri);
}
}
// Warm re-activation path: the app is already running when the callback arrives.
Microsoft.Windows.AppLifecycle.AppInstance.GetCurrent().Activated += (sender, e) =>
{
if (e.Kind == Microsoft.Windows.AppLifecycle.ExtendedActivationKind.Protocol &&
e.Data is Windows.ApplicationModel.Activation.IProtocolActivatedEventArgs protocolArgs)
{
_ = HandleProtocolActivationAsync(protocolArgs.Uri);
}
};
}
private async Task HandleProtocolActivationAsync(Uri uri)
{
var query = new WwwFormUrlDecoder(uri.Query);
var code = query.GetFirstValueByName("code");
var reason = query.GetFirstValueByName("reason");
if (code == "200")
{
var token = query.GetFirstValueByName("file-access-token");
var file = await SharedStorageAccessManager.RedeemTokenForFileAsync(token);
// Use the captured file (see "Retrieving captured media" below)
}
else
{
// Handle error (400, 408, 499, 500)
Debug.WriteLine($"Snipping Tool returned {code}: {reason}");
}
}
Menangani respons penemuan:
private void HandleDiscoverResponse(Uri uri)
{
var query = new WwwFormUrlDecoder(uri.Query);
var code = query.GetFirstValueByName("code");
if (code == "200")
{
var discover = query.GetFirstValueByName("discover");
// discover contains a URL-encoded JSON capabilities payload
var capabilities = Uri.UnescapeDataString(discover);
// Parse the JSON to inspect supported capture modes
}
}
Tip
Jika Anda mengirim x-request-correlation-id dengan permintaan, verifikasi bahwa respons menggemakan nilai yang sama sehingga Anda dapat mencocokkan respons dengan permintaan dalam penerbangan yang benar. Jika Anda membiarkan Snipping Tool menghasilkannya secara otomatis, respons membawa nilai yang dihasilkan - perlakukan sebagai cocok dengan permintaan dalam penerbangan terbaru Anda.
Mengambil media yang diambil menggunakan token
Gunakan kelas SharedStorageAccessManager untuk menukarkan file-access-token dan mengakses file yang diambil.
Pembatasan token:
- Token hanya dapat ditukarkan sekali. Setelah penukaran, benda tersebut tidak lagi valid.
- Token kedaluwarsa setelah 14 hari.
- Aplikasi tidak boleh memiliki lebih dari 1000 token aktif. Setelah token ditukarkan, dihapus, atau kedaluwarsa, token tidak lagi dihitung terhadap kuota.
// Redeem the token and display the captured image
var file = await SharedStorageAccessManager.RedeemTokenForFileAsync(token);
using (var stream = await file.OpenReadAsync())
{
var bitmap = new BitmapImage();
await bitmap.SetSourceAsync(stream);
MyImage.Source = bitmap;
}
// Or copy to your app's local storage
var localFolder = ApplicationData.Current.LocalFolder;
await file.CopyAsync(localFolder, file.Name, NameCollisionOption.GenerateUniqueName);
Pertimbangan keamanan
Snipping Tool memvalidasi semua nilai redirect-uri sebelum meluncurkannya. Perlindungan berikut diberlakukan:
- Pemanggil aplikasi terkemas: Saat aplikasi Anda adalah aplikasi Windows terkemas (MSIX), sistem operasi merutekan tanggapan penangkapan kembali ke aplikasi Anda dengan aman, memastikan hanya aplikasi Anda yang dapat menerimanya. Ini adalah jalur integrasi yang direkomendasikan.
- Validasi input: Snipping Tool menolak URI pengalihan yang berisi jalur UNC, spasi kosong awal/akhir, atau karakter kontrol.
-
Tidak ada fragmen: URI Pengalihan yang berisi fragmen URL (misalnya,
my-app://response#section) ditolak. Alat Pemotongan menambahkan parameter respons sebagai string kueri, dan fragmen akan menelannya. - Perlindungan referensi mandiri: URI pengalihan yang akan menyebabkan aktivasi rekursif dari Snipping Tool diblokir.
Important
Untuk aplikasi panggilan:
- Daftarkan handler protokol untuk skema URI pengalihan Anda sehingga aplikasi Anda dapat menerima respons.
- Validasi dan bersihkan semua parameter yang diterima dalam respons sebelum memprosesnya.
- Verifikasi bahwa respons
x-request-correlation-idcocok dengan permintaan dalam penerbangan Anda untuk menghindari penanganan respons kedaluarsa atau mencampur permintaan bersamaan. Correlation-id mencegah kekeliruan; ini tidak menetapkan asal usul token - perutean token yang aman berasal dari kanal callback aplikasi terkemas.
Konten terkait
Windows developer