Dodawanie obiektów Silverlight do strony internetowej przy użyciu języka HTML lub JavaScript, cz. II .png "Udostępnij na: Facebook")
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
C#
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 | http://go.microsoft.com/fwlink/?LinkId=110408 |
| Silverlight 2.0 | application/x-silverlight-2 | 2.0.31005 | http://go.microsoft.com/fwlink/?LinkID=124807 |
| Silverlight 3.0 | application/x-silverlight-2 | 3,0.0.40624 | http://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
C#
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 });
}