Bagikan melalui

Cara menyesuaikan pengaturan cetak (aplikasi perangkat UWP)

Important

Metadata perangkat tidak digunakan lagi dan akan dihapus dalam rilis Windows mendatang. Untuk informasi tentang penggantian fungsionalitas ini, lihat Metadata Kontainer Paket Driver.

Di Windows 8.1, aplikasi perangkat UWP memungkinkan produsen printer menyesuaikan flyout yang menampilkan pengaturan cetak tingkat lanjut. Topik ini memperkenalkan flyout pengaturan cetak tingkat lanjut, dan menunjukkan bagaimana versi C# dari contoh Pengaturan Cetak dan Pemberitahuan Cetak menggantikan flyout bawaan dengan flyout kustom. Untuk mempelajari selengkapnya tentang aplikasi perangkat UWP secara umum, lihat Mengenal aplikasi perangkat UWP.

Versi C# dari sampel Pengaturan cetak dan pemberitahuan cetak menggunakan halaman Preferences.xaml untuk menunjukkan UI flyout kustom untuk pengaturan cetak tingkat lanjut. Kelas pembantu cetak digunakan untuk membuat konteks perangkat (IPrinterExtensionContext) dan melakukan kueri perangkat. The PrinterHelperClass.cs file is in the DeviceAppForPrintersLibrary project and uses APIs defined in the PrinterExtensionLibrary project. Pustaka ekstensi printer menyediakan cara mudah untuk mengakses antarmuka ekstensi printer dari pengandar cetak v4. Untuk informasi selengkapnya, lihat Gambaran umum pustaka ekstensi Printer.

Note

Contoh kode yang ditampilkan dalam topik ini didasarkan pada versi C# dari sampel pengaturan Cetak dan pemberitahuan cetak . Sampel ini juga tersedia di JavaScript dan C++. Perhatikan bahwa karena C++ dapat mengakses COM secara langsung, versi C++ sampel tidak menyertakan proyek pustaka kode. Unduh sampel untuk melihat versi terbaru kode.

Pengaturan cetak tingkat lanjut

Pengalaman pengaturan cetak tingkat lanjut adalah fungsionalitas yang ditawarkan printer ketika pengguna ingin memilih pengaturan cetak yang tidak ditawarkan di jendela Cetak. It is accessible through the More settings link in the Print window. Ini bukan pengalaman layar penuh, tetapi ditampilkan dalam flyout, yang merupakan kontrol untuk menampilkan antarmuka pengguna kontekstual ringan yang ditutup saat pengguna mengklik atau mengetuk di luarnya.

Pengalaman ini dapat digunakan untuk menyoroti fitur yang berbeda untuk printer Anda seperti kemampuan untuk menerapkan marka air ke halaman dokumen, menawarkan opsi pencetakan yang aman, atau opsi peningkatan gambar.

Ketika aplikasi perangkat UWP tidak diinstal untuk printer, Windows menyediakan pengalaman pengaturan cetak default. Jika Windows mendeteksi bahwa aplikasi perangkat UWP diinstal untuk printer Anda, dan bahwa aplikasi telah memilih untuk windows.printTaskSettings ekstensi, aplikasi Anda menggantikan pengalaman default yang disediakan oleh Windows.

Untuk memanggil flyout untuk pengaturan cetak tingkat lanjut:

  1. Buka aplikasi UWP yang mendukung pencetakan

  2. Akses pesona dengan menggesekkan di sisi kanan layar (atau dengan menggunakan Tombol Logo Windows + C)

  3. Tap the Devices charm

  4. Tap Print

  5. Ketuk printer

  6. The Print window opens

  7. Click the More settings link on the Print window

  8. Opsi pengaturan cetak tingkat lanjut muncul

    • The default flyout appears when no UWP device app for the printer is installed

    • A custom flyout appears when a UWP device app for the printer is installed

Contoh jendela pop-up bawaan dan khusus untuk pengaturan lanjutan pencetakan.

Prerequisites

Sebelum Anda memulai:

  1. Pastikan pencetak Anda terinstal menggunakan pengandar cetak v4. Untuk informasi selengkapnya, lihat Mengembangkan driver cetak v4.

  2. Siapkan PC pengembangan Anda. See Getting started for info about downloading the tools and creating a developer account.

  3. Kaitkan aplikasi Anda dengan toko. Lihat Membuat aplikasi perangkat UWP untuk informasi tentang hal tersebut.

  4. Buat metadata perangkat untuk printer Anda yang mengaitkannya dengan aplikasi Anda. Lihat Membuat metadata perangkat untuk informasi selengkapnya tentang hal tersebut.

  5. Buat UI untuk halaman utama aplikasi Anda. Semua aplikasi perangkat UWP dapat diluncurkan dari Mulai, tempat aplikasi tersebut akan ditampilkan layar penuh. Gunakan pengalaman Mulai untuk menyoroti produk atau layanan Anda dengan cara yang cocok dengan merek dan fitur tertentu dari perangkat Anda. Tidak ada batasan khusus pada jenis kontrol UI yang dapat digunakannya. Untuk mulai menggunakan desain pengalaman layar penuh, lihat prinsip desain Microsoft Store.

  6. If you're writing your app with C# or JavaScript, add the PrinterExtensionLibrary and DeviceAppForPrintersLibrary projects to your UWP device app solution. Anda dapat menemukan masing-masing proyek ini di pengaturan Cetak dan sampel pemberitahuan cetak .

Note

Karena C++ dapat mengakses COM secara langsung, aplikasi C++ tidak memerlukan pustaka terpisah untuk bekerja dengan konteks perangkat printer berbasis COM.

Langkah 1: Daftarkan ekstensi

Agar Windows dapat mengenali bahwa aplikasi dapat menyediakan flyout kustom untuk pengaturan cetak tingkat lanjut, aplikasi harus mendaftarkan ekstensi pengaturan tugas cetak. Ekstensi ini dideklarasikan dalam elemen Extension, dengan atribut Category yang diatur ke nilai windows.printTaskSettings. Dalam sampel C# dan C++, Executable atribut diatur ke $targetnametoken$.exe dan EntryPoint atribut diatur ke DeviceAppForPrinters.App.

You can add the print task settings extension on the Declarations tab of the Manifest Designer in Microsoft Visual Studio. Anda juga dapat mengedit XML manifes paket aplikasi secara manual, menggunakan Editor XML (Teks). Right-click the Package.appxmanifest file in Solution Explorer for editing options.

This example shows the print task settings extension in the Extension element, as it appears in the app package manifest file, Package.appxmanifest.

<?xml version="1.0" encoding="utf-8"?>
<Package xmlns="http://schemas.microsoft.com/appx/2010/manifest">
  <Identity Name="Microsoft.SDKSamples.DeviceAppForPrinters.CS" Publisher="CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US" Version="1.0.0.0" />
  <Properties>
    <DisplayName>Device App For Printers C# sample</DisplayName>
    <PublisherDisplayName>Microsoft Corporation</PublisherDisplayName>
    <Logo>Assets\storeLogo-sdk.png</Logo>
  </Properties>
  <Prerequisites>
    <OSMinVersion>6.3.0</OSMinVersion>
    <OSMaxVersionTested>6.3.0</OSMaxVersionTested>
  </Prerequisites>
  <Resources>
    <Resource Language="x-generate" />
  </Resources>
  <Applications>
    <Application Id="DeviceAppForPrinters" Executable="$targetnametoken$.exe" EntryPoint="DeviceAppForPrinters.App">
      <VisualElements DisplayName="Device App For Printers C# sample" Logo="Assets\squareTile-sdk.png" SmallLogo="Assets\smallTile-sdk.png" Description="DeviceAppForPrinters C# sample" ForegroundText="light" BackgroundColor="#00b2f0" ToastCapable="true">
<DefaultTile ShowName="allLogos" ShortName="App4PrinterCS" WideLogo="Assets\tile-sdk.png" />
<SplashScreen Image="Assets\splash-sdk.png" BackgroundColor="#00b2f0" />
      </VisualElements>
      <Extensions>
<Extension Category="windows.backgroundTasks" EntryPoint="BackgroundTask.PrintBackgroundTask">
  <BackgroundTasks>
    <Task Type="systemEvent" />
  </BackgroundTasks>
</Extension>
<Extension Category="windows.printTaskSettings" Executable="$targetnametoken$.exe" EntryPoint="DeviceAppForPrinters.App" />
      </Extensions>
    </Application>
  </Applications>
</Package>

Langkah 2: Bangun UI

Sebelum membangun aplikasi, Anda harus bekerja sama dengan perancang dan tim pemasaran Anda untuk merancang pengalaman pengguna. Pengalaman pengguna harus memproyeksikan aspek branding perusahaan Anda dan membantu Anda membangun koneksi dengan pengguna Anda.

Design guidelines

Penting untuk meninjau panduan flyout aplikasi UWP sebelum merancang flyout kustom Anda. Panduan ini membantu memastikan bahwa flyout Anda memberikan pengalaman intuitif yang konsisten dengan aplikasi UWP lainnya.

Untuk halaman utama aplikasi Anda, perlu diingat bahwa Windows 8.1 dapat menampilkan beberapa aplikasi dalam berbagai ukuran pada satu monitor. Lihat panduan berikut untuk mempelajari selengkapnya tentang bagaimana aplikasi Anda dapat me-reflow dengan anggun antara ukuran layar, ukuran jendela, dan orientasi.

Flyout dimensions

Flyout yang menampilkan pengaturan cetak tingkat lanjut memiliki lebar 646 piksel dan tinggi minimal 768 piksel (tinggi aktual tergantung pada resolusi layar pengguna). Tombol Kembali di area judul flyout disediakan oleh Windows. Teks "Judul Aplikasi" adalah judul aplikasi dari manifes aplikasi. Area judul memiliki tinggi 80 piksel, meninggalkan 688 piksel untuk area flyout kustom yang dapat dilihat.

dimensi flyout untuk pengaturan printer tingkat lanjut.

Note

Jika flyout kustom Anda memiliki tinggi lebih dari 688 piksel, pengguna dapat menggeser atau menggulir untuk melihat bagian flyout yang berada di atas atau di bawah area yang dapat dilihat.

Menentukan warna dan ikon judul aplikasi

Judul, warna latar belakang, warna teks, dan logo kecil pada flyout kustom diambil dari VisualElements elemen dalam file manifes paket aplikasi.

This example shows the title and icon, as defined in the VisualElements element, in the app package manifest file (Package.appxmanifest).

      <VisualElements DisplayName="Device App For Printers C# sample" Logo="Assets\squareTile-sdk.png" SmallLogo="Assets\smallTile-sdk.png" Description="DeviceAppForPrinters C# sample" ForegroundText="light" BackgroundColor="#00b2f0" ToastCapable="true">
        <DefaultTile ShowName="allLogos" ShortName="App4PrinterCS" WideLogo="Assets\tile-sdk.png" />
        <SplashScreen Image="Assets\splash-sdk.png" BackgroundColor="#00b2f0" />
      </VisualElements>

Best practices

  • Pertahankan tampilan dan nuansa yang sama. Sesuaikan flyout kustom Anda dengan desain untuk pengalaman Anda di Beranda (halaman Utama aplikasi Anda), termasuk elemen seperti font, warna, dan kontrol. Aplikasi ini harus terasa akrab bagi orang-orang terlepas dari dari mana mereka memanggilnya.

  • Jaga agar interaksi tetap sederhana. Hindari interaksi yang memakan waktu atau kompleks. Dalam kebanyakan kasus, tindakan seperti menyiapkan printer, melihat status, memesan tinta, dan pemecahan masalah paling baik dilakukan di dalam pengalaman Mulai.

  • Usahakan navigasi seminimal mungkin. Hindari membuat pengguna Anda menavigasi bolak-balik di antara beberapa halaman di flyout kustom Anda. Sebagai gantinya, gunakan kontrol pengguliran vertikal atau kontrol di baris yang sama, seperti kontrol pengungkapan progresif, menu tarik-turun, dan pesan kesalahan di baris yang sama.

  • Jangan gunakan flyout pengalih cahaya. Pengalaman cetak sudah menggunakan flyout pengalih cahaya. Menyertakan elemen pengalih cahaya lain dalam flyout kustom Anda dapat membingungkan pengguna Anda.

  • Nonaktifkan tautan yang mengarahkan pengguna menjauh dari pengalaman cetak. Saat pengguna mencetak konten, Anda harus mengambil langkah-langkah untuk memastikan mereka tetap berada dalam konteks cetak. Misalnya, jika aplikasi Anda memiliki tautan yang mengarah ke area lain aplikasi Anda (seperti ke halaman beranda atau ke halaman untuk membeli tinta), Anda harus menonaktifkannya sehingga pengguna tidak meninggalkan pengalaman pengaturan cetak tingkat lanjut secara tidak sengaja.

Langkah 3: Menangani aktivasi

Jika aplikasi Anda telah mendeklarasikan ekstensi pengaturan tugas cetak, aplikasi harus menerapkan OnActivated metode untuk menangani peristiwa Aktivasi aplikasi. Aktivasi aplikasi adalah ketika aplikasi Anda dapat memilih halaman mana yang akan diluncurkan saat aplikasi dimulai. Untuk aplikasi yang telah mendeklarasikan ekstensi pengaturan tugas cetak, Windows meneruskan konteks ekstensi tugas cetak dalam argumen peristiwa yang diaktifkan: Windows.ApplicationModel.Activation.IActivatedEventArgs.

A UWP device app can determine that the activation is intended for advanced print settings (that someone just tapped More options on the print settings dialog) when the event argument's kind property is equal to Windows.ApplicationModel.Activation.ActivationKind.printTaskSettings.

Note

Dalam beberapa kasus, jika pengguna segera menutup aplikasi setelah diluncurkan, pengecualian dapat dilemparkan di dalam handler aktivasi. Untuk menghindari hal ini, pastikan handler aktivasi Anda selesai secara efisien dan tidak melakukan pemrosesan intensif sumber daya.

This example shows the activation event handler in the OnActivated method, as it appears in the Constants.cs file. Argumen peristiwa kemudian dikasting sebagai Windows.ApplicationModel.Activation.PrintTaskSettingsActivatedEventArgs. Although the sample includes this code in the Constants.cs file, it's actually part of the App class that is also defined in the App.xaml.cs file.

partial class App : Application
{
    protected override void OnActivated(IActivatedEventArgs args)
    {
        if (args.Kind == ActivationKind.PrintTaskSettings)
        {
            Frame rootFrame = new Frame();
            if (null == Window.Current.Content)
            {
                rootFrame.Navigate(typeof(MainPage));
                Window.Current.Content = rootFrame;
            }
            Window.Current.Activate();

            MainPage mainPage = (MainPage)rootFrame.Content;

            // Load advanced printer preferences scenario
            mainPage.LoadAdvancedPrintSettingsContext((PrintTaskSettingsActivatedEventArgs)args);
        }
    }
}

Langkah 4: Pengaturan tampilan

Ketika metode dipanggil LoadAdvancedPrintSettingsContext , konteks konfigurasi tugas cetak ditetapkan ke variabel kelas MainPage. Ini akan memungkinkan flyout kustom untuk mengakses pengaturan cetak saat diluncurkan.

Argumen peristiwa yang diteruskan ke LoadAdvancedPrintSettingsContext di dalam metode menyediakan properti untuk mengakses dan mengontrol printer:

  • The args.configuration property provides an object of type Windows.Devices.Printers.Extensions.PrintTaskConfiguration. Objek ini menyediakan akses ke konteks ekstensi tugas cetak, dan juga memungkinkan Anda menambahkan penanganan aktivitas untuk memperbarui tiket cetak.
  • The args.configuration.printerExtensionContext property provides an object of type Windows.Devices.Printers.Extensions.PrinterExtensionContext. Objek ini adalah penunjuk ke antarmuka PrinterExtensionLibrary untuk Skema Cetak, PrintTicket, dan informasi antrean cetak. Nilainya akan menjadi null jika tidak ada antarmuka yang diekspos. Untuk informasi selengkapnya, lihat Gambaran Umum Pustaka Ekstensi Printer.

This example shows the LoadAdvancedPrintSettingsContext method, as it appears in the Constants.cs file.

public PrintTaskConfiguration Config;
public Object Context;

public void LoadAdvancedPrintSettingsContext(PrintTaskSettingsActivatedEventArgs args)
{
    Config = args.Configuration;
    Context = Config.PrinterExtensionContext;
    LoadScenario(typeof(DeviceAppForPrinters.Preferences));
}

On the custom flyout page, Preferences.xaml.cs, a class named rootPage acts as a pointer to the MainPage class so that the print task extension context and the printer device context can be accessed from the flyout.

This example shows the pointer in a portion of Preferences class, from the Preferences.xaml.cs file. Unduh sampel Pengaturan cetak dan pemberitahuan cetak untuk melihat kode lengkap.

public sealed partial class Preferences : SDKTemplate.Common.LayoutAwarePage
{
    // A pointer back to the main page.  
    MainPage rootPage = MainPage.Current;

    // To listen for save requests.
    PrintTaskConfiguration configuration;

    // To create the printer device context.
    Object printerExtensionContext;
    PrintHelperClass printHelper;

    // The features in this sample were chosen because they're available on a wide range of printer drivers.
    private string[] features = { "PageOrientation", "PageOutputColor", "PageMediaSize", "PageMediaType" };
    private string[] selections = { null, null, null, null };

    // . . .
    // . . .
    // . . .

When the page constructor for Preferences.xaml.cs is called, objects are created for the print task extension context (a PrintTaskConfiguration object named configuration) and the printer device context (a PrintHelperClass object named printHelper).

Setelah objek-objek tersebut dibuat, konteks perangkat printer digunakan pada metode DisplaySettings untuk memuat TextBlocks dan ComboBoxes. Perhatikan bahwa tidak seperti JavaScript, perubahan pemilihan tidak diaktifkan pada thread yang sama dengan aplikasi lainnya. Anda harus mempertahankan cache lokal pilihan pengguna untuk digunakan nanti.

This example shows the custom flyout page constructor, DisplaySettings, and other helper methods in the Preferences.xaml.cs file.

public Preferences()
{
    this.InitializeComponent();

    configuration = rootPage.Config;
    printerExtensionContext = rootPage.Context;
    printHelper = new PrintHelperClass(printerExtensionContext);

    // Disable scenario navigation by hiding the scenario list UI elements
    ((UIElement)rootPage.FindName("Scenarios")).Visibility = Windows.UI.Xaml.Visibility.Collapsed;
    ((UIElement)rootPage.FindName("ScenarioListLabel")).Visibility = Windows.UI.Xaml.Visibility.Collapsed;
    ((UIElement)rootPage.FindName("DescriptionText")).Visibility = Windows.UI.Xaml.Visibility.Collapsed;

    DisplaySettings();
}


private void DisplaySettings(bool constraints=false)
{
    PrintOptions.Visibility = Windows.UI.Xaml.Visibility.Visible;
    WaitPanel.Visibility = Windows.UI.Xaml.Visibility.Collapsed;

    // Fill in the drop-down select controls for some common printing features.
    TextBlock[] featureLabels = { PageOrientationLabel, PageOutputColorLabel, PageMediaSizeLabel, PageMediaTypeLabel };
    ComboBox[] featureBoxes = { PageOrientationBox, PageOutputColorBox, PageMediaSizeBox, PageMediaTypeBox };

    for (int i = 0; i < features.Length; i++)
    {
        // Only display a feature if it exists
        featureLabels[i].Visibility = Windows.UI.Xaml.Visibility.Collapsed;
        featureBoxes[i].Visibility = Windows.UI.Xaml.Visibility.Collapsed;

        string feature = features[i];

        // Check whether the currently selected printer's capabilities include this feature.
        if (!printHelper.FeatureExists(feature))
        {
            continue;
        }

        // Fill in the labels so that they display the display name of each feature.
        featureLabels[i].Text = printHelper.GetFeatureDisplayName(feature);
        string[] index = printHelper.GetOptionInfo(feature, "Index");
        string[] displayName = printHelper.GetOptionInfo(feature, "DisplayName");
        string selectedOption = printHelper.GetSelectedOptionIndex(feature);

        // Unless specified, do not get constraints
        bool[] constrainedList = constraints ? printHelper.GetOptionConstraints(feature) : new bool[index.Length];

        // Populate the combo box with the options for the current feature.
        PopulateBox(featureBoxes[i], index, displayName, selectedOption, constrainedList);
        selections[i] = selectedOption;

        // Every time the selection for a feature changes, we update our local cached set of selections.
        featureBoxes[i].SelectionChanged += OnFeatureOptionsChanged;

        // Show existing features
        featureLabels[i].Visibility = Windows.UI.Xaml.Visibility.Visible;
        featureBoxes[i].Visibility = Windows.UI.Xaml.Visibility.Visible;
    }
}

void PopulateBox(ComboBox box, string[] index, string[] displayName, string selectedOption, bool[] constrainedList)
{
    // Clear the combobox of any options from previous UI refresh before repopulating it.
    box.SelectionChanged -= OnFeatureOptionsChanged;
    box.Items.Clear();
    // There should be only one displayName for each possible option.
    if (index.Length == displayName.Length)
    {
        for (int i = 0; i < index.Length; i++)
        {
            // Create a new DisplayItem so the user will see the friendly displayName instead of the index.
            ComboBoxItem newItem = new ComboBoxItem();
            newItem.Content = displayName[i];
            newItem.DataContext = index[i];
            newItem.Foreground = constrainedList[i] ? new SolidColorBrush(Colors.Red) : new SolidColorBrush(Colors.Black);
            box.Items.Add(newItem);

            // Display current selected option as selected in the combo box.
            if (selectedOption == index[i])
            {
                box.SelectedIndex = i;
                box.Foreground = newItem.Foreground;
            }
        }
    }
}

private void OnFeatureOptionsChanged(object sender, SelectionChangedEventArgs args)
{
    ComboBox comboBox = sender as ComboBox;

    for (int i = 0; i < features.Length; i++)
    {
        if (features[i] + "Box" == comboBox.Name)
        {
            selections[i] = (comboBox.SelectedItem as ComboBoxItem).DataContext as string;
        }
    }
}

Langkah 5: Simpan pengaturan

When the user has finished setting advanced print settings, the Microsoft Store device app needs to save the changes before the user goes back to the Print window. To do that, the app needs to listen for when the user taps the Back button (from the custom flyout page). Ketika itu terjadi, acara SaveRequested dalam konteks ekstensi tugas cetak (configuration objek) dipicu.

This example shows the event listener for SaveRequested, being added in the OnNavigatedTo event handler of the custom flyout, in the Preferences.xaml.cs file. When the SaveRequested event is triggered, the OnSaveRequested method will be invoked (that method is also in the Preferences.xaml.cs file).

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    if (null == configuration)
    {
        rootPage.NotifyUser("Configuration arguments cannot be null", NotifyType.ErrorMessage);
        return;
    }

    // Add an event listener for saverequested (the back button of the flyout is pressed).
    configuration.SaveRequested += OnSaveRequested;
}

Dalam metode OnSaveRequested, aplikasi pertama-tama menggunakan objek printHelper untuk mengatur opsi yang saat ini dipilih untuk setiap fitur pada konteks ekstensi printer. Kemudian memanggil metode Save pada objek request yang diteruskan sebagai argumen ke metode OnSaveRequested. Metode ini Save , dari kelas Windows.Devices.Printers.Extensions.PrintTaskConfigurationSaveRequest, menggunakan konteks ekstensi printer untuk memvalidasi tiket cetak dan menyimpan konfigurasi tugas cetak.

Important

Jika tiket cetak tidak valid dalam bentuk apa pun, metode Save memunculkan pengecualian yang harus ditangani oleh aplikasi. Jika aplikasi tidak menangani pengecualian, alur dihentikan, memaksa pengguna untuk menyalakan flyout dan memulai ulang alur cetak.

This example shows the OnSaveRequested method in the Preferences.xaml.cs file. Karena peristiwa SaveRequested tidak dinaikkan pada utas UI, peristiwa tersebut perlu menggunakan Windows.UI.Core.CoreDispatcher untuk mengirim pesan ke utas UI agar dapat menampilkan pesan yang sesuai saat memvalidasi dan menyimpan tiket.

async private void OnSaveRequested(object sender, PrintTaskConfigurationSaveRequestedEventArgs args)
{
    if (null == printHelper || null == printerExtensionContext || null == args)
    {
        await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () =>
        {
            rootPage.NotifyUser("onSaveRequested: args, printHelper, and context cannot be null", NotifyType.ErrorMessage);
        });
        return;
    }

    // Get the request object, which has the save method that allows saving updated print settings.
    PrintTaskConfigurationSaveRequest request = args.Request;

    if (null == request)
    {
        await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () =>
        {
            rootPage.NotifyUser("onSaveRequested: request cannot be null", NotifyType.ErrorMessage);
        });
        return;
    }

    PrintTaskConfigurationSaveRequestedDeferral deferral = request.GetDeferral();

    // Two separate messages are dispatched to:
    // 1) put up a popup panel,
    // 2) set the each options to the print ticket and attempt to save it,
    // 3) tear down the popup panel if the print ticket could not be saved.
    await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () =>
    {
        PrintOptions.Visibility = Windows.UI.Xaml.Visibility.Collapsed;
        WaitPanel.Visibility = Windows.UI.Xaml.Visibility.Visible;
    });

    // Go through all the feature select elements, look up the selected
    // option name, and update the context
    // for each feature
    for (var i = 0; i < features.Length; i++)
    {
        // Set the feature's selected option in the context's print ticket.
        // The printerExtensionContext object is updated with each iteration of this loop
        printHelper.SetFeatureOption(features[i], selections[i]);
    }

    bool ticketSaved;
    try
    {
        // This save request will throw an exception if ticket validation fails.
        // When the exception is thrown, the app flyout will remain.
        // If you want the flyout to remain regardless of outcome, you can call
        // request.Cancel(). This should be used sparingly, however, as it could
        // disrupt the entire the print flow and will force the user to
        // light dismiss to restart the entire experience.
        request.Save(printerExtensionContext);

        if (configuration != null)
        {
            configuration.SaveRequested -= OnSaveRequested;
        }
        ticketSaved = true;
    }
    catch (Exception exp)
    {
        // Check if the HResult from the exception is from an invalid ticket, otherwise rethrow the exception
        if (exp.HResult.Equals(unchecked((int)0x8007000D))) // E_INVALID_DATA
        {
            ticketSaved = false;
        }
        else
        {
            throw;
        }
    }

    // If ticket isn't saved, refresh UI and notify user
    if (!ticketSaved)
    {
        await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () =>
        {
            rootPage.NotifyUser("Failed to save the print ticket", NotifyType.ErrorMessage);
            DisplaySettings(true);
        });
    }
    deferral.Complete();
}

Menyimpan opsi yang memerlukan input pengguna

Sampel Pengaturan cetak dan pemberitahuan cetak menunjukkan cara mengatur fitur yang ditentukan, yang mencakup sebagian besar opsi cetak. Namun, beberapa opsi memerlukan UI kustom untuk mendapatkan nilai yang ditentukan pengguna. Misalnya, jika aplikasi menggunakan pengaturan cetak tingkat lanjut untuk menentukan ukuran halaman kustom, aplikasi akan mengambil langkah-langkah ini untuk menyimpan nilai yang ditentukan pengguna:

  1. Ambil tiket cetak selama aktivasi aplikasi. Aktivasi aplikasi untuk pengaturan cetak dijelaskan sebelumnya di Langkah 3: Menangani aktivasi.

  2. Periksa apakah opsi ukuran halaman ditentukan. Di aplikasi C# atau JS, kelas pembantu cetak dapat memeriksa opsi ini. Dalam aplikasi C++, panggil QueryInterface di IPrintSchemaOption untuk mengambil IPrintSchemaPageMediaSizeOption.

    Contoh ini memperlihatkan metode di kelas pembantu cetak yang memeriksa apakah opsi ukuran halaman ditentukan.

    public bool ShouldShowCustomUI(string index)
{
    if (null != index)
    {
        string feature = "PageMediaSize";
        int i = int.Parse(index);
        IPrintSchemaOption selectedOption = GetCachedFeatureOptions(feature)[i];
        if (selectedOption.Name.Equals("CustomMediaSize", StringComparison.CurrentCulture)
            || selectedOption.Name.Equals("PSCustomMediaSize", StringComparison.CurrentCulture))
        {
            return true;
        }
    }
    return false;
}

  3. Dalam flyout kustom, tampilkan UI kustom yang meminta tinggi dan lebar halaman kepada pengguna, dan mengambil tinggi dan lebar yang ditentukan pengguna dari IPrintSchemaPageMediaSizeOption.

    Contoh ini menunjukkan metode untuk flyout kustom yang meminta tinggi dan lebar halaman kepada pengguna.

    private void ShowCustomPageMediaSizeUI(string index, bool keepValue)
{
    //Hide custom media size UI unless needed
    if (IsCustomSizeSelected(index))
    {
       if (keepValue && (!customWidth.Equals("")) && (!customHeight.Equals("")))
       {
                    CustomWidthBox.Text = customWidth;
                    CustomHeightBox.Text = customHeight;
       }
       else
       {
          // Use a helper function from the WinRT helper component
          CustomWidthBox.Text = printHelper.GetCustomWidth(index);
          CustomHeightBox.Text = printHelper.GetCustomHeight(index);
       }
       CustomUIPanel.Visibility = Windows.UI.Xaml.Visibility.Visible;
       CustomWidthBox.KeyDown += OnCustomValueEntered;
       CustomHeightBox.KeyDown += OnCustomValueEntered;
    }
    else
    {
       CustomUIPanel.Visibility = Windows.UI.Xaml.Visibility.Collapsed;
       CustomWidthBox.KeyDown -= OnCustomValueEntered;
       CustomHeightBox.KeyDown -= OnCustomValueEntered;
    }
}

  4. IPrintSchemaPageMediaSizeOption Perbarui objek dengan nilai yang ditentukan pengguna dan validasi bahwa tinggi dan lebar cocok dengan nilai yang ditentukan pengguna.

    Contoh ini adalah metode pembantu untuk memperbarui IPrintSchemaPageMediaSizeOption objek di kelas pembantu printer. Handler OnSaveRequested dalam flyout kustom akan memanggil fungsi ini jika menentukan bahwa opsi ukuran halaman kustom diminta.

    public void SetCustomMediaSizeDimensions(string width, string height)
{
  if ((null == width) && (null == height) && (null == Capabilities))
  {
                return;
  }
  try
  {
                CheckSizeValidity(width, height);
  }
  catch (FormatException e)
  {
                throw new ArgumentException(e.Message);
  }
  catch (OverflowException e)
  {
                throw new ArgumentException(e.Message);
  }

  // The context is retrieved during app activation.
  IPrintSchemaTicket ticket = context.Ticket;

  //
  // Input XML as Stream
  //
  XElement ticketRootXElement = null;
  using (Stream ticketReadStream = ticket.GetReadStream())
  {
     ticketRootXElement = XElement.Load(ticketReadStream);
  }

  XNamespace psfNs = PrintSchemaConstants.FrameworkNamespaceUri;
  XNamespace pskNs = PrintSchemaConstants.KeywordsNamespaceUri;
  string pskPrefix = ticketRootXElement.GetPrefixOfNamespace(pskNs);

  // Modify the MediaSizeHeight and MediaSizeWidth
  IEnumerable<XElement> parameterInitCollection =
    from c in ticketRootXElement.Elements(psfNs + "ParameterInit")

  select c;

  foreach (XElement parameterInit in parameterInitCollection)
  {
    if (0 == String.Compare((string)parameterInit.Attribute("name"), pskPrefix + ":PageMediaSizePSWidth"))
    {
      IEnumerable<XElement> valueCollection = from c in parameterInit.Elements(psfNs + "Value")
      select c;
      valueCollection.ElementAt(0).Value = width;
    }

     else if (0 == String.Compare((string)parameterInit.Attribute("name"), pskPrefix + ":PageMediaSizePSHeight"))
    {
      IEnumerable<XElement> valueCollection = from c in parameterInit.Elements(psfNs + "Value")
      select c;
      valueCollection.ElementAt(0).Value = height;
     }
  }

  //
  // Write XLinq changes back to DOM
  //
   using (Stream ticketWriteStream = ticket.GetWriteStream())
   {
     ticketRootXElement.Save(ticketWriteStream);
   }
}

Testing

Sebelum dapat menguji aplikasi perangkat UWP, aplikasi tersebut harus ditautkan ke printer Anda menggunakan metadata perangkat.

  • Anda memerlukan salinan paket metadata perangkat untuk printer Anda, untuk menambahkan info aplikasi perangkat ke dalamnya. Jika Anda tidak memiliki metadata perangkat, Anda dapat membuatnya menggunakan Wizard Penulisan Metadata Perangkat seperti yang dijelaskan dalam topik Membuat metadata perangkat untuk aplikasi perangkat UWP Anda.

    Note

    Untuk menggunakan Wizard Penulisan Metadata Perangkat, Anda harus menginstal Microsoft Visual Studio Professional, Microsoft Visual Studio Ultimate, atau SDK mandiri untuk Windows 8.1, sebelum menyelesaikan langkah-langkah dalam topik ini. Menginstal Microsoft Visual Studio Express untuk Windows menginstal versi SDK yang tidak menyertakan wizard.

Langkah-langkah berikut membuat aplikasi Anda dan menginstal metadata perangkat.

  1. Aktifkan tanda tangan uji.

    1. Mulai Wizard Penulisan Metadata Perangkat dari %ProgramFiles(x86)%\Windows Kits\8.1\bin\x86 dengan klik dua kali pada DeviceMetadataWizard.exe.

    2. From the Tools menu, select Enable Test Signing.

  2. Mulai ulang komputer

  3. Bangun solusi dengan membuka file solusi (.sln). Tekan F7 atau buka > dari menu atas setelah contoh selesai dimuat.

  4. Putuskan sambungan dan copot pemasangan printer. Langkah ini diperlukan agar Windows akan membaca metadata perangkat yang diperbarui saat perangkat terdeteksi berikutnya.

  5. Edit dan simpan metadata perangkat. Untuk menautkan aplikasi perangkat ke perangkat, Anda harus mengaitkan aplikasi perangkat dengan perangkat Anda

    Note

    Jika Anda belum membuat metadata perangkat, lihat Membuat metadata perangkat untuk aplikasi perangkat UWP Anda.

    1. Jika Wizard Penulisan Metadata Perangkat belum dibuka, mulai dari %ProgramFiles(x86)%\Windows Kits\8.1\bin\x86, dengan mengklik dua kali DeviceMetadataWizard.exe.

    2. Klik Edit Perangkat Metadata. Ini akan memungkinkan Anda mengedit paket metadata perangkat yang ada.

    3. In the Open dialog box, locate the device metadata package associated with your UWP device app. (It has a devicemetadata-ms file extension.)

    4. Pada halaman Tentukan informasi aplikasi perangkat UWP , masukkan info aplikasi Microsoft Store di kotak aplikasi perangkat UWP . Klik Impor file manifes aplikasi UWP untuk secara otomatis memasukkan nama Paket , nama penerbit , dan ID aplikasi UWP .

    5. If your app is registering for printer notifications, fill out the Notification handlers box. In Event ID, enter the name of the print event handler. In Event Asset, enter the name of the file where that code resides.

    6. When you're done, click Next until you get to the Finish page.

    7. Pada halaman Tinjau paket metadata perangkat , pastikan semua pengaturan sudah benar dan pilih kotak centang Salin paket metadata perangkat ke penyimpanan metadata di komputer lokal . Then click Save.

  6. Sambungkan kembali pencetak Anda agar Windows membaca metadata perangkat yang diperbarui ketika perangkat tersambung.

Troubleshooting

Masalah: Pengaturan cetak lanjutan menunjukkan jendela pop up default alih-alih jendela pop up kustom

Jika flyout pengaturan cetak lanjutan menampilkan flyout bawaan alih-alih flyout kustom yang diimplementasikan oleh aplikasi Anda...

  • Possible cause: Test signing is not turned on. Lihat bagian Debugging dalam topik ini untuk informasi tentang mengaktifkannya.

  • Possible cause: The app is not querying for the right Package Family Name. Periksa Nama Famili Paket dalam kode Anda. Open up package.appxmanifest in Visual Studio and make sure that the package family name you are querying for matches the one in the Packaging tab, in the Package Family Name field.

  • Possible cause: The device metadata is not associated with the Package Family Name. Gunakan Wizard Penulisan Metadata Perangkat untuk membuka metadata perangkat dan periksa nama keluarga paket. Start the wizard from %ProgramFiles(x86)%\Windows Kits\8.1\bin\x86, by double-clicking DeviceMetadataWizard.exe.

Masalah: Aplikasi diluncurkan dalam flyout kemudian segera diberhentikan

Jika flyout kustom Anda untuk pengaturan cetak tingkat lanjut menghilang segera setelah diluncurkan...

  • Possible cause: In Windows 8, there is a known issue that within a flyout, UWP apps will be dismissed under the debugger. Nonaktifkan penelusuran kesalahan setelah Anda tahu bahwa aktivasi berfungsi. Jika Anda perlu memecahkan masalah saat menyimpan tiket cetak, lampirkan debugger setelah aktivasi.
  • Last updated on