README

ValueView 引入了 jQuery.valueview 小部件，可用于显示和编辑数据值（由 DataValues 库定义的 DataValue 对象，并通过 DataValues JavaScript 包支持）。jQuery.valueview 小部件及其资源可以扩展以支持自定义 DataValue 实现。

最近更改可以在 发行说明 中找到。

组件

jQuery.valueview

jQuery.valueview 可用于显示和编辑数据值。虽然小部件的原始构造函数位于 jQuery.valueview.valueview，但应通过其桥接器 jQuery.valueview 实例化。

jQuery.valueview.Expert

jQuery.valueview.Expert 是处理 DataValue 的小部件。一个 Expert 提供编辑特定 DataValue（例如 StringValue）或适用于特定 DataType（例如使用 StringValue 表示的 url DataType；另见 DataTypes 库）的功能。jQuery.valueview.Expert 是此类 Expert 的基本构造函数。

jQuery.valueview.ExpertExtender

jQuery.valueview.ExpertExtender 可用于在交互过程中提供额外信息和/或输入元素。例如，ExpertExtender 可用于提供在保存后解析的值将如何显示的预览（请参阅 jQuery.ExpertExtender.Preview）。可以通过添加到 ExpertExtender 实例的 jQuery.valueview.ExpertExtender.* 输入元素设置与正在编辑的 DataValue 对应的 ValueParser 提供的选项。

jQuery.valueview.ExpertStore

Expert 由 jQuery.valueview.ExpertStore 实例管理，该实例提供其 Expert 给 jQuery.valueview。

ViewState

ViewState 充当一个 外观，连接 Expert 和 jQuery.valueview。 ViewState 允许 Expert 观察 jQuery.valueview 的某些方面，并允许 Expert 更新关联的 jQuery.valueview 实例。

用法

对于用法示例，假设以下包已安装

• DataValues
• DataValues JavaScript
• DataTypes

当使用 jQuery.valueview 处理 DataValue 时，需要一个了解特定于 DataValue 类型 Expert 的 jQuery.valueview.ExpertStore，可以按以下方式设置

var dv = dataValues,
	vv = jQuery.valueview,
	dt = dataTypes,
	experts = new vv.ExpertStore();

var stringValue = new dv.StringValue( 'foo' );

// Consider this a DataType using the StringValue DataValue internally:
var urlDataType = new dt.DataType( 'url', dv.StringValue.TYPE );

experts.registerDataValueExpert( vv.experts.StringValue, dv.StringValue.TYPE );

console.log(
	experts.getExpert( stringValue.getType() )
		=== experts.getExpert( urlDataType.getDataValueType(), urlDataType.getId() )
);
// true because "url" DataType's DataValue type is "string"; The "string" DataValue's Expert will be
// used as fall-back.

现在，可以将 jQuery.valueview.ExpertStore 注入到新的 jQuery.valueview 实例中，使其能够编辑 "string" DataValue。

var $subject = $( '<div/>' ).appendTo( $( 'body' ).empty() );

// In addition to the Expert store, a ValueParser store and two ValueFormatters need to be provided. The parser store
// features the same mechanisms as the Expert store. For this example, we just initialize the parser store with
// the "string" parser as default. The formatters will format a string as it is.
var parsers = new valueParsers.ValueParserStore( valueParsers.StringParser );

$subject.valueview( {
  expertStore: experts,
  parserStore: parsers,
  plaintextFormatter: new valueFormatters.StringFormatter(),
  htmlFormatter: new valueFormatters.StringFormatter(),
  language: 'en', // language code transmitted to Parser
  value: new dv.StringValue( 'text' )
} );

var valueView = $subject.data( 'valueview' );

创建了一个显示 文本 的 jQuery.valueview 后，可以使用小部件的成员函数进行交互，例如

• 清空视图：valueView.value( null );
• 允许用户编辑值：valueView.startEditing();
• 停止用户编辑值：valueView.stopEditing();
• 返回当前值：valueView.value();

将 jQuery.valueview 实例的值设置为一个无法处理的 DataValue，因为无法从 ExpertStore 确定合适的 Expert，将导致显示错误通知。调用 .value() 仍然会返回值，但用户既看不到也无法编辑这个值。

架构

jQuery.valueview 严重依赖于通过 DataValues JavaScript 库定义的 ValueFormatter 和 ValueParser。ValueFormatter 用于将 DataValue 实例转换为 DOM 元素，而 ValueParser 用于将纯文本字符串（可能伴随一些选项）转换为 DataValue 实例。由于 Expert 仅用于编辑值，它们在进入编辑模式时构建，在离开编辑模式后销毁。Expert 有以下生命周期

• _init()：从通过 ViewState 链接的 jQuery.valueview 实例加载解析、格式化和原始（文本）值，并初始化 DOM。
• 编辑循环
  • (用户编辑)
  • Expert 调用 viewNotifier.notify( 'change' ) 并触发解析和格式化。
  • rawValue()：返回当前的原始（文本）值。
  • (可选) preview.showSpinner()：将预览替换为加载旋转器。
  • draw()：(重新)使用从 jQuery.valueview 实例（通过 ViewState）获取的（新）解析和格式化值（重新）绘制 Expert 的不可编辑部分
• destroy()：销毁 DOM。

Expert 需要提供其他方法

• valueCharacteristics()
• focus()
• blur()

Phabricator 上的错误

https://phabricator.wikimedia.org/project/view/918/