Dodawanie obiektów Silverlight do strony internetowej przy użyciu języka HTML lub JavaScript, cz. II

Artykuł
05/10/2011

Jak to zrobić: określanie i pobieranie niestandardowych parametrów inicjalizacji

Osadzając dodatek plug-in Silverlight na stronie internetowej, w konfiguracji dodatku plug-in można określić niestandardowe parametry inicjalizacji. Parametry te to pary nazw i wartości, które można pobrać w module obsługi zdarzenia Application..::.Startup (j.ang.). Wartości te można również pobrać w dowolnym czasie przy użyciu właściwości SilverlightHost..::.InitParams (j.ang.).

Niestandardowe parametry inicjalizacji pozwalają wpływać na inicjalizację aplikacji za pośrednictwem strony internetowej będącej hostem. Można np. używać niestandardowych parametrów inicjalizacji z formantem zegara opartym na programie Silverlight w celu stosowania wyświetlacza cyfrowego lub analogowego.

Poniższy przykład kodu ukazuje, jak określać niestandardowe parametry inicjalizacji na stronie internetowej będącej hostem. Następnie przykład ukazuje, jak pobierać parametry w module obsługi zdarzeń Startup (j.ang.) przy użyciu właściwości StartupEventArgs..::.InitParams (j.ang.).

Przykład ukazuje również, jak pobierać parametry adresu URL podczas uruchamiania, używając właściwości HtmlDocument..::.QueryString (j.ang.). Należy zwrócić uwagę, że nie można pobierać parametrów adresu URL, jeśli wyłączony jest dostęp do kodu HTML, co jest ustawieniem domyślnym w wypadku hostingu międzydomenowego. Więcej informacji można uzyskać w dokumencie Ustawienia bezpieczeństwa mostka HTML (j.ang.).

Przykład

html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html  >
<!-- zapisane z adresu url=(0014)about:internet -->
<head>
    <title>SilverlightApplication</title>
    <script type="text/javascript" src="Silverlight.js"></script>
</head>
<body>
    <table>
    <tr><td>
        <object id="slPlugin1" width="300" height="50"
            data="data:application/x-silverlight-2," 
            type="application/x-silverlight-2" >
            <param name="source" value="ClientBin/SilverlightApplication.xap"/>
            <param name="initParams" 
                value="id=slPlugin1,embeddingTechnique=objectElement"/>
            <!-- Kod HTML instalacji pominięty. -->
        </object>
    </td></tr>
    <tr><td>
        <div id="silverlightControlHost">
            <script type="text/javascript">
                Silverlight.createObject(
                    "ClientBin/SilverlightApplication.xap",  
                    silverlightControlHost, "slPlugin2",
                    { width: "300", height: "50", background: "white" }, { },
                    "id=slPlugin2,embeddingTechnique=createObject" );
            </script>
        </div>
    </td></tr>
    </table>

</body>
</html>

Visual Basic

Private Sub Application_Startup(ByVal o As Object, _
    ByVal e As StartupEventArgs) Handles Me.Startup

    Dim p As New Page
    Me.RootVisual = p

    ' Zakłada sie, że istnieje element Page.LayoutRoot o wartości StackPanel.
    Dim layoutRoot As StackPanel = p.LayoutRoot

    ' Wyświetla nietandardowe parametry inicjalizacji.
    For Each key As String In e.InitParams.Keys
        layoutRoot.Children.Add(New TextBlock With { _
            .Text = String.Format( _
                "from InitParams: {0} = {1}", _
                key, e.InitParams(key))})
    Next

    ' Wyświetla parametry adresu URL.
    For Each key As String In HtmlPage.Document.QueryString.Keys
        layoutRoot.Children.Add(New TextBlock With { _
            .Text = String.Format( _
                "from QueryString: {0} = {1}", key, _
                HtmlPage.Document.QueryString(key))})
    Next

End Sub

private void Application_Startup(object sender, StartupEventArgs e)
{
    Page p = new Page();
    this.RootVisual = p;

    // Zakłada się, że istnieje element Page.LayoutRoot o wartości StackPanel.
    StackPanel layoutRoot = p.LayoutRoot; 

    // Wyświetla nietandardowe parametry inicjalizacji.
    foreach (String key in e.InitParams.Keys)
    {
        layoutRoot.Children.Add(new TextBlock() {
            Text = String.Format(
                "from InitParams: {0} = {1}", key, 
                e.InitParams[key])
        });
    }

    // Wyświetla parametry adresu URL.
    foreach (String key in HtmlPage.Document.QueryString.Keys)
    {
        layoutRoot.Children.Add(new TextBlock()
        {
            Text = String.Format(
                "from QueryString: {0} = {1}", key, 
                HtmlPage.Document.QueryString[key])
        });
    }            
}

Usługi rozszerzeń aplikacji mogą uzyskać dostęp do niestandardowych parametrów inicjalizacji w implementacjach metody IApplicationService..::.StartService (j.ang.). Więcej informacji można uzyskać w dokumencie Usługi rozszerzeń aplikacji (j.ang.).

Wersje dodatku plug-in Silverlight

Aby uruchomić aplikację opartą na programie Silverlight na stronie internetowej, użytkownicy muszą mieć zainstalowaną odpowiednią wersję dodatku plug-in Silverlight. Istnieją dwa sposoby określenia wymaganej wersji dodatku plug-in, które można zastosować zależnie od sposobu jego osadzenia:

· Przy użyciu elementu object języka HTML.

· Przy użyciu funkcji pliku pomocniczego Silverlight.js.

Niezależnie od wybranej opcji można ustawić wyświetlanie użytkownikom monitów o zainstalowanie poprawnej wersji, jeśli jeszcze nie jest ona zainstalowana. Więcej informacji o udostępnianiu interfejsu instalacji i uaktualnienia można uzyskać, pobierając oficjalny dokument i przykładowy kod: Interfejs instalacji programu Microsoft Silverlight (j.ang.).

Można też określić wymaganą wersję środowiska wykonawczego w manifeście zestawu aplikacji. Więcej informacji można uzyskać w dokumencie Deployment..::.RuntimeVersion (j.ang.). Jest to przydatne, jeśli działanie aplikacji zależy od funkcjonalności dostępnej w określonej wersji programu Silverlight, która uległa jednak zmianie w kolejnej wersji. Więcej informacji można uzyskać w dokumencie Zapewnianie działania aplikacji programu Silverlight 2 w programie Silverlight 3 (j.ang.).

Zazwyczaj nie ma potrzeby uwzględniania specjalnej obsługi różnych wersji aplikacji. Model hostingu internetowego pozwala w dowolnym momencie zastąpić aplikację wersją zaktualizowaną. Użytkownikom odwiedzającym zawsze będzie wyświetlana najnowsza wersja. Należy jednak wziąć pod uwagę kilka dodatkowych kwestii, jeśli aplikacja wykorzystuje funkcjonalność działania poza przeglądarką lub buforowania w bibliotece. Więcej informacji można uzyskać w dokumentach Obsługa działania poza przeglądarką (j.ang.) i Jak to zrobić: używanie buforowania w bibliotece (j.ang.).

Obsługa wersji przy użyciu elementu Object języka HTML

W przypadku korzystania z elementu object w celu określenia wymaganej wersji programu Silverlight należy użyć atrybutu type o wartości odpowiadającej typowi MIME programu Silverlight. Każda główna wersja ma osobny typ MIME, podany na końcu niniejszego dokumentu.

Jeśli nie jest zainstalowana wersja dodatku plug-in Silverlight o określonym typie MIME, wyświetlana jest zawartość elementu object języka HTML. W ten sposób można udostępnić łącze służące do instalacji.

Opcjonalnie można określić wartość MinRuntimeVersion (j.ang.) w formie majorVersion.minorVersion.buildNumber.revisionNumber. Wszystkie wartości poza majorVersion są w nim opcjonalne. W takim wypadku, jeśli użytkownik ma zainstalowaną wcześniejszą wersję dodatku plug-in, dodatek nie wczyta pakietu aplikacji. Zamiast tego dodatek plug-in spowoduje wyświetlenie komunikatu „Click to install the required version” (kliknij, aby zainstalować wymaganą wersję). Zapobiega to wykorzystaniu przez złośliwe aplikacje błędów we wcześniejszych wersjach programu Silverlight, które zostały naprawione w nowszych wersjach. Jeśli dodatek plug-in jest za mały, aby wyświetlić domyślny kompunikat, można wyświetlić monit o uaktualnienie zgodnie z informacjami podanymi poniżej.

Po określeniu wartości MinRuntimeVersion (j.ang.) opcjonalnie można określić wartość AutoUpgrade (j.ang.). Jeśli wymagane jest uaktualnienie, a wartość AutoUpgrade (j.ang.) zostanie ustawiona na true, dodatek plug-in spowoduje wyświetlenie monitu o uaktualnienie, a następnie ponowne uruchomienie przeglądarki internetowej. Wyświetlenie monitu o uaktualnienie nie wpływa na wyświetlanie domyślnego komunikatu w dodatku plug-in.

Jeśli wymagane jest uaktualnienie, niezależnie od ustawienia AutoUpgrade (j.ang.) występują dwa błędy:

· 8001 — Wymagane uaktualnienie.

· 8002 — Wymagane ponowne uruchomienie przeglądarki.

Można reagować na te błędy przy użyciu modułu OnError (j.ang.) w celu wyświetlania własnego monitu o uaktualnienie i ponowne uruchomienie przeglądarki. W takim wypadku jednak zazwyczaj nie ustawia się wartości AutoUpgrade (j.ang.) na true.

Więcej informacji na temat obsługi błędów przy użyciu modułu OnError (j.ang.) można znaleźć w dokumentach Obsługa błędów (j.ang.) i Komunikaty o błędach (j.ang.).

Obsługa wersji przy użyciu funkcji pliku pomocniczego Silverlight.js

W razie korzystania z funkcji pliku pomocniczego Silverlight.js, należy określić numer wersji programu Silverlight w formie majorVersion.minorVersion.buildNumber.revisionNumber. Wszystkie wartości poza majorVersion są opcjonalne. Numery wersji są używane przez następujące funkcje:

· Funkcja isInstalled. Ta funkcja przyjmuje parametr version i wskazuje, czy dana wersja programu Silverlight jest zainstalowana.

· Funkcja createObject i createObjectEx. Te funkcje przyjmują wartość version w tablicy parametrów properties. Jeśli określona wersja programu Silverlight jest zainstalowana, dodatek plug-in zostaje osadzony na stronie internetowej. W przeciwnym wypadku te funkcje spowodują wyświetlenie alternatywnego kodu HTML.

· Funkcja getSilverlight. Ta funkcja przyjmuje parametr version i podejmuje próbę pobrania odpowiedniego instalatora programu Silverlight.

Można użyć tych i innych funkcji pliku Silverlight.js do osadzenia dodatku plug-in Silverlight i dostosowania interfejsu instalacji i uaktualnienia. Więcej informacji można uzyskać w dokumencie Informacje referencyjne pliku Silverlight.js (j.ang.).

Informacje o wersji

W poniższej tabeli podano typy MIME i numery wersji odpowiadające poszczególnym głównym wydaniom dodatku plug-in Silverlight. Każda wersja jest kompatybilna wstecznie z poprzednimi wersjami. Jeśli aplikacja do uruchomienia wymaga programu Silverlight 1.0, będzie ona mogła działać również w programie Silverlight 3, jednak jedynie z wykorzystaniem interfejsu API języka JavaScript. Więcej informacji można uzyskać w dokumencie Modele aplikacji i programowania (j.ang.).

Wersja	Typ MIME	Numer wersji	Adres URL instalatora
Silverlight 1.0	application/x-silverlight	1.0	https://go.microsoft.com/fwlink/?LinkId=110408
Silverlight 2.0	application/x-silverlight-2	2.0.31005	https://go.microsoft.com/fwlink/?LinkID=124807
Silverlight 3.0	application/x-silverlight-2	3,0.0.40624	https://go.microsoft.com/fwlink/?LinkID=149156
Uwaga:
Typ MIME „application/x-silverlight-2” jest używany w programie Silverlight 2 i we wszystkich kolejnych wersjach. Wydania beta poszczególnych wersji programu Silverlight mają takie same główne i poboczne numery (np. 3.0), jak wydania ostateczne. Dlatego też należy zawsze podać numer kompilacji (np. 40624), aby wskazać wydanie ostateczne. Adresy URL instalatorów przekierowują do odpowiedniego instalatora lub komunikatu o błędzie, zależnie od platformy i przeglądarki użytkownika. Adres URL instalatora dla programu Silverlight 1.0 przekierowuje np. do instalatora programu Silverlight 3, z wyjątkiem platform, które nie obsługują programu Silverlight lub obsługują jedynie program Silverlight 1.0.

Zmiany wielkości dodatku plug-in Silverlight

Osadzając dodatek plug-in Silverlight na stronie internetowej, można określić jego wielkość stałą lub zmienną (zależną od wielkości elementu nadrzędnego). Do ustawiania odpowiednio szerokości i wysokości dodatku plug-in służą parametry width i height o wartościach w pikselach lub procentowych.

W razie określenia wartości stałych, wielkość dodatku plug-in pozostanie niezmienna niezależnie od wielkości kontenera nadrzędnego. Jeśli kontener nadrzędny jest za mały, aby wyświetlić dodatek plug-in, dodatek zostanie przysłonięty.

W razie określenia wartości procentowych wielkość dodatku plug-in będzie ulegać zmianom wraz ze zmianą wielkości elementu nadrzędnego. Jeśli jednak w interfejsie użytkownika aplikacji zostaną określone wartości stałe, interfejs może zostać przysłonięty po zmianie wielkości dodatku plug-in. Więcej informacji można uzyskać w sekcji poświęconej zmianie wielkości okien w dokumencie System układu graficznego programu Silverlight (j.ang.).

Poniższa ilustracja ukazuje skutki zmiany wielkości okna przeglądarki przy wartościach width i height określonych w procentach.

Wartości szerokości i wysokości dodatku plug-in Silverlight ustawione na 75%

Zmiana wielkości okna przeglądarki ma minimalny wpływ na wydajność wystąpień dodatku plug-in Silverlight. W większości wypadków np. odtwarzanie zawartości audio lub wideo nie zostaje w ogóle zakłócone wskutek zmiany wielkości okna przeglądarki.

Sprawdzanie rzeczywistej wielkości dodatku plug-in Silverlight

Jeśli wielkość dodatku plug-in została określona jako procentowa wartość nadrzędnego elementu HTML, w celu poznania rzeczywistej wielkości trzeba znać wielkość elementu nadrzędnego. Rzeczywistą wielkość można sprawdzić w wartościach Content..::.ActualWidth (j.ang.) i Content..::.ActualHeight (j.ang.), ale dopiero po wystąpieniu zdarzenia Content..::.Resized (j.ang.). Kiedy wystąpi np. zdarzenie Application..::.Startup (j.ang.) właściwości te nie mają znaczących wartości.

Wielkość dodatku plug-in Silverlight ulega również zmianie po przejściu w tryb pełnoekranowy. W tym jednak wypadku nie występuje zdarzenie Content..::.Resized (j.ang.). Zamiast niego zachodzi zdarzenie Content..::.FullScreenChanged (j.ang.). Można też wyświetlić cały dodatek plug-in w trybie pełnoekranowym w reakcji na działanie użytkownika, ustawiając właściwość Content..::.IsFullScreen (j.ang.). W trybie pełnoekranowym wielkość dodatku plug-in jest dostosowana do rozdzielczości monitora. Więcej informacji można uzyskać w dokumencie Obsługa trybu pełnoekranowego (j.ang.).

W przypadku niektórych przeglądarek dostępna jest funkcja powiększania, pozwalająca zmienić wielkość wyświetlanej zawartości. Kiedy użytkownik zmienia ustawienie powiększenia w przeglądarce, zmienia się wielkość dodatku plug-in i zachodzi zdarzenie Resized (j.ang.). Domyślnie zawartość dodatku plug-in także zmienia wielkość. Można jednak wyłączyć zmiany wielkości, ustawiając wartość właściwości Settings..::.EnableAutoZoom (j.ang.) na false lub zastępując ją obsługą zdarzenia Content..::.Zoomed (j.ang.). Chcąc uzupełnić działanie funkcji powiększania zamiast ją zastępować, można ustawić obsługę zdarzenia Zoomed (j.ang.), a wartość właściwości EnableAutoZoom (j.ang.) ustawić na true. Można uzyskać dostęp do bieżącego ustawienia powiększenia w oknie przeglądarki, używając właściwości Content..::.ZoomFactor (j.ang.).

Poniższy przykład kodu ilustruje pobieranie rzeczywistej wielkości dodatku plug-in w reakcji na zdarzenia Resized (j.ang.) i FullScreenChanged (j.ang.).

Visual Basic

Private WithEvents rootPage As Page = New Page()
Private WithEvents htmlContent As Content
Private Sub Application_Startup(ByVal o As Object, ByVal e As StartupEventArgs) Handles Me.Startup
    Me.RootVisual = rootPage
    htmlContent = Me.Host.Content
End Sub

Private Sub ToggleFullScreen(ByVal sender As Object, _
    ByVal e As MouseButtonEventArgs) Handles rootPage.MouseLeftButtonDown
    Me.Host.Content.IsFullScreen = Not Me.Host.Content.IsFullScreen
End Sub

Private Sub DisplaySizeInformation( _
    ByVal sender As Object, ByVal e As EventArgs) _
    Handles htmlContent.FullScreenChanged, htmlContent.Resized

    Dim message As String = String.Format( _
        "ActualWidth={0}, ActualHeight={1}", _
        Me.Host.Content.ActualWidth, _
        Me.Host.Content.ActualHeight)

    rootPage.LayoutRoot.Children.Clear()
    Dim t As New TextBlock()
    t.Text = message
    rootPage.LayoutRoot.Children.Add(t)

End Sub

Page rootPage = new Page();
private void Application_Startup(object sender, StartupEventArgs e)
{
    this.RootVisual = rootPage;

    rootPage.LayoutRoot.MouseLeftButtonDown +=
        delegate(Object s, MouseButtonEventArgs args) {
            this.Host.Content.IsFullScreen =
                !this.Host.Content.IsFullScreen;
        };

    this.Host.Content.FullScreenChanged += 
        new EventHandler(DisplaySizeInformation);

    this.Host.Content.Resized += 
        new EventHandler(DisplaySizeInformation);
}

private void DisplaySizeInformation(Object sender, EventArgs e)
{
    String message = String.Format(
        "ActualWidth={0}, ActualHeight={1}",
        this.Host.Content.ActualWidth,
        this.Host.Content.ActualHeight);

    rootPage.LayoutRoot.Children.Clear();
    rootPage.LayoutRoot.Children.Add(
        new TextBlock { Text = message });
}

Dodawanie obiektów Silverlight do strony internetowej przy użyciu języka HTML lub JavaScript, cz. II

Jak to zrobić: określanie i pobieranie niestandardowych parametrów inicjalizacji

Wersje dodatku plug-in Silverlight

Zmiany wielkości dodatku plug-in Silverlight

Dodatkowe zasoby