使用 ms-tonepicker URI 配置選擇並儲存音調

2025-06-10

本主題描述如何使用 ms-tonepicker： URI 配置。此 URI 設定可用來：

判斷裝置上是否提供音調選擇器。
顯示音調選擇器以列出可用的鈴聲、系統音效、文字音調和警示音效：並取得音調標記，代表用戶選取的聲音。
顯示音調儲存器，它會接受聲音檔案令牌作為輸入，並將它儲存到裝置。之前儲存的音調可透過音調選擇器獲取。使用者也可以給語氣一個友好的名稱。
將音調標記轉換為其友好的名稱。

ms-tonepicker：URI 模式參考

此 URI 配置不會透過 URI 配置字串傳遞自變數，而是透過 ValueSet傳遞自變數。所有字串都會區分大小寫。

下列各節指出應該傳遞哪些參數以完成指定任務。

工作：判斷裝置上是否有音調選擇器

var status = await Launcher.QueryUriSupportAsync(new Uri("ms-tonepicker:"),     
                                     LaunchQuerySupportType.UriForResults,
                                     "Microsoft.Tonepicker_8wekyb3d8bbwe");

if (status != LaunchQuerySupportStatus.Available)
{
    // the tone picker is not available
}

工作：顯示音調選擇器

您可以傳遞來顯示音調選擇器的自變數如下所示：

參數	類型	為必填項目	可能的值	說明
行動	字符串	是的	“PickRingtone”	開啟音調選擇器。
當前音調文件路徑	字符串	否	現有的音調標記。	要顯示為色調選擇器中當前色調的音調。如果未設定此值，預設會選取清單上的第一個音調。嚴格來說，這不是檔案路徑。您可以從音調選擇器傳回的 `CurrenttoneFilePath` 值，取得適合 `ToneToken` 的值。
類型過濾器	字符串	否	“鈴聲”、“通知”、“鬧鐘”、“無”	選取要新增至選擇器中的音調。如果未指定任何篩選，則會顯示所有音調。

在 LaunchUriResults.Result中傳回的值：

傳回值	類型	可能的值	說明
結果	Int32	0（成功）。 1 取消。 7 個無效的參數。 8 - 沒有音調符合篩選準則。 255 - 未實作指定的動作。	選擇器作業的結果。
ToneToken	字符串	選取的音調標記。如果使用者在選擇器中選取預設，則字串是空的。	此令牌可用於通知彈跳訊息的負載，也可以設為聯絡人的鈴聲或簡訊音效。在 Result 和 result 皆為 0 時，才會在 ValueSet 中傳回參數。
顯示名稱	字符串	指定的音調的友善名稱。	可以向用戶顯示的字串，表示選取的音調。在 Result 和 result 皆為 0 時，才會在 ValueSet 中傳回參數。

範例：開啟音調選擇器，讓使用者可以選取音調

LauncherOptions options = new LauncherOptions();
options.TargetApplicationPackageFamilyName = "Microsoft.Tonepicker_8wekyb3d8bbwe";

ValueSet inputData = new ValueSet() {
    { "Action", "PickRingtone" },
    { "TypeFilter", "Ringtones" } // Show only ringtones
};

LaunchUriResult result = await Launcher.LaunchUriForResultsAsync(new Uri("ms-tonepicker:"), options, inputData);

if (result.Status == LaunchUriStatus.Success)
{
     Int32 resultCode =  (Int32)result.Result["Result"];
     if (resultCode == 0)
     {
         string token = result.Result["ToneToken"] as string;
         string name = result.Result["DisplayName"] as string;
     }
     else
     {
           // handle failure
     }
}

工作：顯示音調保存功能

您可以傳遞來顯示音調儲存器的自變數如下所示：

參數	類型	為必填項目	可能的值	說明
行動	字符串	是的	“SaveRingtone”	開啟選擇器以儲存鈴聲。
ToneFileSharingToken	字符串	是的	SharedStorageAccessManager 用於儲存鈴聲文件的檔案共用權杖。	將特定聲音檔案儲存為鈴聲。檔案支援的內容類型為 mpeg 音訊和 x-ms-wma 音訊。
顯示名稱	字符串	否	指定的音調的友善名稱。	設定儲存指定之鈴聲時要使用的顯示名稱。

在 LaunchUriResults.Result中傳回的值：

傳回值	類型	可能的值	說明
結果	Int32	0（成功）。使用者取消了項目 1。 2-無效的檔案。 3-無效的檔案內容類型。檔案超過 Windows 10 的鈴聲大小上限（1MB）。 5 檔案超過 40 秒長度限制。 6-File 受到數位版權管理的保護。 7 個無效的參數。	選擇器作業的結果。

範例：將本機音樂檔案儲存為鈴聲

LauncherOptions options = new LauncherOptions();
options.TargetApplicationPackageFamilyName = "Microsoft.Tonepicker_8wekyb3d8bbwe";

ValueSet inputData = new ValueSet() {
    { "Action", "SaveRingtone" },
    { "ToneFileSharingToken", SharedStorageAccessManager.AddFile(myLocalFile) }
};

LaunchUriResult result = await Launcher.LaunchUriForResultsAsync(new Uri("ms-tonepicker:"), options, inputData);

if (result.Status == LaunchUriStatus.Success)
{
     Int32 resultCode = (Int32)result.Result["Result"];

     if (resultCode == 0)
     {
         // no issues
     }
     else
     {
          switch (resultCode)
          {
             case 2:
              // The specified file was invalid
              break;
              case 3:
              // The specified file's content type is invalid
              break;
              case 4:
              // The specified file was too big
              break;
              case 5:
              // The specified file was too long
              break;
              case 6:
              // The file was protected by DRM
              break;
              case 7:
              // The specified parameter was incorrect
              break;
          }
      }
 }

工作：將音調令牌轉換成其易於理解的名稱

您可以傳遞以取得語氣易記名稱的自變數如下所示：

參數	類型	為必填項目	可能的值	說明
行動	字符串	是的	“GetToneName”	表示您想要取得語調的易記名稱。
ToneToken	字符串	是的	音調標記	要從中取得顯示名稱的音調標記。

在 LaunchUriResults.Result中傳回的值：

返回值	類型	可能的值	說明
結果	Int32	0-選擇器作業成功。 7-不正確的參數（例如，未提供 ToneToken）。 9-讀取指定令牌的名稱時發生錯誤。 10-找不到指定的音調標記。	選擇器作業的結果。
顯示名稱	字符串	音調的友好名稱。	傳回選取音調的顯示名稱。只有當 Result 為 0 時，才會在 ValueSet 中傳回此參數。

範例：從 Contact.RingToneToken 擷取鈴聲令牌，並在聯繫人卡片中顯示其友好名稱。

using (var connection = new AppServiceConnection())
{
    connection.AppServiceName = "ms-tonepicker-nameprovider";
    connection.PackageFamilyName = "Microsoft.Tonepicker_8wekyb3d8bbwe";
    AppServiceConnectionStatus connectionStatus = await connection.OpenAsync();
    if (connectionStatus == AppServiceConnectionStatus.Success)
    {
        var message = new ValueSet() {
            { "Action", "GetToneName" },
            { "ToneToken", token)
        };
        AppServiceResponse response = await connection.SendMessageAsync(message);
        if (response.Status == AppServiceResponseStatus.Success)
        {
            Int32 resultCode = (Int32)response.Message["Result"];
            if (resultCode == 0)
            {
                string name = response.Message["DisplayName"] as string;
            }
            else
            {
                // handle failure
            }
        }
        else
        {
            // handle failure
        }
    }
}

共用方式為

使用 ms-tonepicker URI 配置選擇並儲存音調

ms-tonepicker：URI 模式參考

工作：判斷裝置上是否有音調選擇器

工作：顯示音調選擇器

工作：顯示音調保存功能

工作：將音調令牌轉換成其易於理解的名稱

意見反應

其他資源