【译】Caliburn——Action

      最近在学习Caliburn，主要的学习资源还是官网上的文档，蛮详细的，所以翻译一下与园友们共同学习。

      官网中的文档主要是基于其Sample的，有需要的朋友可以去这里下载(我用的VS2010不能打开项目，惨淡。。。)，由于公司用的是1.1 RTW版本的，所以我这里用的也是1.1的。如果您下载的是其他版本的，我不能保证能正确编译运行。 本文源码下载:Caliburn.Action.7z

所需要的程序集

• Caliburn.Core
• Caliburn.PresentationFramework
• Microsoft.Practices.ServiceLocation

最小配置

Note:下面的代码在WPF中应放置于App.xaml.cs中的构造函数中，而在Sliverlight中应放置于App.xaml.cs中的Application_Startup中。

请确保已添加上述程序集，并引入命名空间。

using Caliburn.Core;
using Caliburn.PresentationFramework;

CaliburnFramework
    .ConfigureCore()
    .WithPresentationFramework()
    .Start();

Note: 另一可选的手动配置是继承CaliburnApplication.

使用Actions

    Actions是Caliburn能够支持诸如MVC，MVP和MVVM等UI模式的核心特性。下面让我们了解一下Actions的基本使用。

    在您的项目中，添加一个名为Calculator的类。它将作为您的第一个控制器，放置actions。代码如下:

public class Calculator
{
    public int Divide(int left, int right)
    {
        return left / right;
    }
}

接下来，使用下面的标记填充您的Main Page（Silverlight）或Window（WPF）。Silverlight

<UserControl x:Class="Actions.Page"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:ca="clr-namespace:Caliburn.Actions;assembly=Caliburn.Actions"
             xmlns:local="clr-namespace:Actions"
             xmlns:cm="clr-namespace:Caliburn.RoutedUIMessaging;assembly=Caliburn.RoutedUIMessaging"
             xmlns:ct="clr-namespace:Caliburn.RoutedUIMessaging.Triggers;assembly=Caliburn.RoutedUIMessaging"
             Width="400"
             Height="300">
    <ca:Action.Target>
        <local:Calculator />
    </ca:Action.Target>
 
    <StackPanel x:Name="LayoutRoot">
        <Grid Margin="10">
            <Grid.ColumnDefinitions>
                <ColumnDefinition Width="*" />
                <ColumnDefinition Width="Auto" />
                <ColumnDefinition Width="*" />
                <ColumnDefinition Width="*" />
            </Grid.ColumnDefinitions>
 
            <TextBox x:Name="left"
                     Grid.Column="0" />
            <TextBlock Text="/"
                       Margin="10 0"
                       Grid.Column="1" />
            <TextBox x:Name="right"
                     Grid.Column="2" />
            <Border BorderBrush="Black"
                    BorderThickness="0 0 0 1"
                    Margin="10 0 0 0"
                    Grid.Column="3">
                <TextBlock x:Name="DivideResult" />
            </Border>
        </Grid>
 
        <Button Content="Divide (Trigger Collection w/ Explicit Parameters)">
            <cm:Message.Triggers>
                <ct:RoutedMessageTriggerCollection>
                    <ct:EventMessageTrigger EventName="Click">
                        <ct:EventMessageTrigger.Message>
                            <ca:ActionMessage MethodName="Divide"
                                              OutcomePath="DivideResult.Text">
                                <cm:Parameter ElementName="left"
                                              Path="Text" />
                                <cm:Parameter ElementName="right"
                                              Path="Text" />
                            </ca:ActionMessage>
                        </ct:EventMessageTrigger.Message>
                    </ct:EventMessageTrigger>
                </ct:RoutedMessageTriggerCollection>
            </cm:Message.Triggers>
        </Button>
    </StackPanel>
</UserControl>

WPF

<Window x:Class="Actions.Window1"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:local="clr-namespace:Actions"
        xmlns:cal="http://www.caliburnproject.org"
        Title="Window1"
        SizeToContent="WidthAndHeight">
    <cal:Action.Target>
        <local:Calculator />    
    </cal:Action.Target>
     
    <StackPanel>
        <Grid Margin="10">
            <Grid.ColumnDefinitions>
                <ColumnDefinition Width="*" />
                <ColumnDefinition Width="Auto" />
                <ColumnDefinition Width="*" />
                <ColumnDefinition Width="*" />
            </Grid.ColumnDefinitions>
            
            <TextBox x:Name="left" 
                     Grid.Column="0"/>
            <TextBlock Text="/"
                       Margin="10 0"
                       Grid.Column="1"/>
            <TextBox x:Name="right" 
                     Grid.Column="2"/>
            <Border BorderBrush="Black"
                    BorderThickness="0 0 0 1"
                    Margin="10 0 0 0"
                    Grid.Column="3">
                <TextBlock x:Name="DivideResult" />
            </Border>
            
        </Grid>
         
        <Button Content="Divide (Trigger Collection w/ Explicit Parameters)">
            <cal:Message.Triggers>
                <cal:RoutedMessageTriggerCollection>
                    <cal:EventMessageTrigger EventName="Click">
                        <cal:EventMessageTrigger.Message>
                            <cal:ActionMessage MethodName="Divide"
                                           OutcomePath="DivideResult.Text">
                                <cal:Parameter Value="{Binding ElementName=left, Path=Text}"/>
                                <cal:Parameter Value="{Binding ElementName=right, Path=Text}"/>
                            </cal:ActionMessage>
                        </cal:EventMessageTrigger.Message>
                    </cal:EventMessageTrigger>
                </cal:RoutedMessageTriggerCollection>
            </cal:Message.Triggers>
        </Button>
    </StackPanel>
</Window>

Note:值得一提的是，在WPF与Sliverlight两个版本中有些许微妙的差别。首先，WPF版本中只使用一个命名空间就包含了所有Caliburn的特性。WPF可以通过XmlnsDefinition特性支持，而在SL中却是不起作用的。其次，声明变量的语法也有些差别。SL V2中不支持ElementName绑定和Freezables，在V3中也只是部分支持，因此不能像WPF那样直接绑定参数值。然而可以使用ElementName和Path去实现达到相同的效果。你可以从这里获得更多关于parameters的细节。(我没学过SL，所以上面的区别对我来说不是区别,不过还是请懂SL的朋友注意一下)

Note:该示例中内联了Calculator的实例化。不过本人不太喜欢View Control（视图控件？没看懂啥意思，也不会翻译，还请园友们指教）。这里仅作掩饰用。

    那么，这些标记又是干什么用的呢？（不要担心标记的数量，我待会将向您演示如何大量精简）。先看看<Button/>元素。注意Message.Triggers附加属性的使用。有了这个属性，我们可以添加传递消息的触发器到任意元素。这里，我们可以使用一个EventMessageTrigger（详情请看Message Triggers）。EventMessageTriggers允许我们使用触发的事件传递信息给控制器。因此，当Button的Click事件被触发时，我们将发送附加的信息到控制器。而我们正在发送的信息是一个ActionMessage，指明将要调用的方法是"Divide”。并且ActionMessage也指明了”left”和”right”元素的Text属性应将作为参数传递给”Divide”方法。最终，“Divide”方法的返回值绑定到了“DivideResult”元素的Text属性。

    现在我们已经有了可以发送具体消息的触发器了，但是问题来了——谁将处理这个消息呢？仔细观察后发现：根元素UserControl/Window拥有一个具有值得附加属性。通过使用Action.Target属性我们可以指明一个具体的实例去处理ActionMessages。对于这个简单的例子，我们声明了一个内联实例，然而在大多数应用程序中更有可能会通过数据绑定或Resolve Extension实现。

Note:ResolveExtension仅在WPF中可用，因为在SL中目前不支持自定义标价扩展。为避免这个问题，可以通过为Action.Target指明一个字符串值。在这种情况下，该字符串被用来在实现了IContainer的实例中检索资源。如果你使用SimpleContainer（Caliburn的默认Container），且所有的服务都通过其Type注册过，那么也可以实现上面的方法——只要将其Type作为Key就好了。

    现在我们已经有了必须的代码和标记，我们也理解了基本使用，好了，是时候运行了。在两个textbox中输入一些值然后单击按钮。（如果输入正确）你会看到正确的除法运算的结果。在”Divide”方法中设置一个断点并重新运行。接下来，在右边的textbox中输入“0”，单击按钮后，抛出异常。糟糕！这可不行！我们必须修正它。

改变Calculator类定义，如下：

using Caliburn.PresentationFramework.Filters;

[Rescue("GeneralRescue")]
public class Calculator
{
    public int Divide(int left, int right)
    {
        return left / right;
    }
 
    public void GeneralRescue(Exception ex)
    {
        MessageBox.Show(ex.Message);
    }
}

Note: 在非视图类中调用MessageBox.Show并不是一个好的实践，考虑实现MessageBoxService。

    再次运行，在右侧的textbox中输入0。这次，会弹出一个消息框，程序也没有崩溃。一个resuce就是一个具体类型的filter，可以捕获异常。filter所需的参数只有一个，就是可以将异常信息传递过去的方法的名称。如果resuce放置一个类上，那么在该类中所有有Caliburn调用action而产生的异常都会被指定的方法所处理。此外，resuces可以被放置在具体的方法上。在这种情况下，类级别的resuce会被方法级别的重写。resuce虽然阻止了程序的崩溃，但是并未提供给我们想要的用户体验。理想情况下，我们希望如果文本框输入值不合法，按钮就应该被禁用。接下来，看另一个类型的filter可以帮助我们。

再次更新Calculator，如下：

[Rescue("GeneralRescue")]
public class Calculator
{
    [Preview("CanDivide", AffectsTriggers = true)]
    public int Divide(int left, int right)
    {
        return left / right;
    }
 
    public bool CanDivide(int left, int right)
    {
        return right != 0;
    }
  
    public void GeneralRescue(Exception ex)
    {
        MessageBox.Show(ex.Message);
    }
}

    现在我们增加了Preview过滤器。该方法会在其装饰的方法执行前而执行。如果返回false，其装饰的方法不会允许执行。注意该方法和其所要装饰的方法的参数是一样的。并且，如果AffectsTriggers设置为true，Preview过滤器会影响UI的状态。这是默认值，不需要具体指明除非你想关闭这个行为。再次运行，输入值。你会发现如果输入不合法的值，按钮会自动被禁用。

Note: 按照惯例，如果有一个名为Can{ActionName}的方法，Caliburn会自动为相应的Action加上Preview，而你不需要自己加上该特性。

Note: 你也可以将Can{ActionName}作为属性，它也会被自动触发（因此，你仅仅需要为非惯例名称手动加上Preview特性）。当你这样做时，也可以引发属性改变通知强制相关联的触发器重新评估。

    现在你已经理解了一些主要概念，接下来我们将研究一些可选的标记语法去帮助我们使Caliburn更加方便。在接下来的例子中，我们会使用与前面相同的xaml，除了<Button/>。所有其他的标记对于WPF和SL都是一样。

使用下面的标记替换<Button/>：

<Button Content="Divide (Trigger Collection w/ Inferred Parameters)">
    <cm:Message.Triggers>
        <ct:RoutedMessageTriggerCollection>
            <ct:EventMessageTrigger EventName="Click">
                <ct:EventMessageTrigger.Message>
                    <ca:ActionMessage MethodName="Divide" />
                </ct:EventMessageTrigger.Message>
            </ct:EventMessageTrigger>
        </ct:RoutedMessageTriggerCollection>
    </cm:Message.Triggers>
</Button>

    这个标记和上面最初的trigger/message声明非常相似。惟一的区别是没有参数。如果没有指定参数，Caliburn将尝试通过基于（方法）参数的名称检索UI元素和资源而决定其值。如果Action有返回值，方法的名称+“Result”会被用作key去检索UI而实现绑定。运行，你会发现几乎依旧正常工作。然而如果你在右侧的文本框内输入0，按钮仍然可以使用，但是action却不会触发（你可以设置断点调试确认）。这是因为Caliburn在消息被发送之前都不知道该消息包含哪些UI元素，此外它也不能提前更新UI，但仍能过滤action。（请注意）仅当不需要通过输入值去改变UI的情况下才使用推断参数。

现在，再次替换<Button/>，如下：

<Button Content="Divide (Attachment w/ Explicit Parameters)"
        cm:Message.Attach="[Event Click] = [Action Divide(left.Text, right.Text) : DivideResult.Text]" />

这是应优先使用的声明triggers/messages的方式。我们使用了另一个附加属性：Message.Attach。通过这个属性，我们可以提供一个字符串，然后它将被解析传入trigger。你看到的声明在运行时其实是和原来的例子是一模一样的。再次运行，确认一下行为。在等号左侧，我们指出了trigger的类型和参数。在这里，我们为Click事件声明了一个ventMessageTrigger。你可以在这里获得更多缩减trigger语法的详细信息。在等号的右侧，我们声明了消息的类型和内容。这样，我们有了一个ActionMessage，其参数从left和right文本框中获得，返回值绑定回了”Divideresult”的text属性。其中，方括号”[“是可选的，但是它显得更清晰更可读。

Note for WPF: 如果需要，你也可以为某些参数指明具体的绑定模式。如下：

<Button Content="Divide (Attachment w/ Explicit Parameters and Modes)"
        cm:Message.Attach="[Event Click] = [Action Divide(left.Text:TwoWay, right.Text:OneWay) : DivideResult.Text]" />

接下来，再次替换<Button/>,如下：

<Button Content="Divide (Attachment w/ Inferred Parameters)"
        cm:Message.Attach="[Event Click] = [Action Divide]" />

     这个在功能上和第二个比较长的标记示例是一样的。在这种情况下，参数被Caliburn自动推断出。

再次替换<Button/>，如下：

<Button Content="Divide (Attachment w/ Default Trigger/Message and Explicit Parameters)"
        cm:Message.Attach="Divide(left.Text, right.Text) : DivideResult.Text" />

    这个示例很有趣。在这里，Caliburn会基于被绑定元素的类型选择一个默认的触发器。Caliburn也会用默认的消息解析器解析（消息）。这里，Click事件的默认的触发器是EventMessageTrigger，默认的消息类型是ActionMessage，所以该标记产生了与先前的第一个例子一样的运行时行为。即使这是非常简洁的。但我个人仍更喜欢显示声明trigger和message类型，这取决于你的愿望。

再次替换<Button/>，如下：

<Button Content="Divide (Attachment w/ Defaults)"
        cm:Message.Attach="Divide" />

    在上面的标记中，所有东西都会被Caliburn通过推断得出：触发器类型，消息类型，参数类型和返回值。它仍然可以工作，但请谨慎使用。

    经过上面的例子，你可能会困惑——哪有人会使用那么长的语法？的确，在绝大多数情况下，你不需要这么做，但是它提供了最大程度的灵活性。最后一点，如果你希望为一个元素附加多个消息，你可以用分号隔开。就像下面这样：

<Button Content="Divide or Multiply"
        cm:Message.Attach="[Event Click] = [Action Divide(left.Text:TwoWay, right.Text:OneWay) : DivideResult.Text];
                           [Event MouseRightButtonUp] = [Action Multiply(left.Text:TwoWay, right.Text:OneWay) : MultiplyResult.Text]" />