一、概述（Overview）
一个 JSValue 实例是一个 JavaScript 值的引用。你可以使用 JSValue 类在 JavaScript 和 Objective-C 或者 Swift 之间进行一些基本数值（比如数字和字符串）转换，这样你就可以在原生代码和 JavaScript 代码之间传递数据了。你也可以利用这个类去创建包装自定义类的 原生对象的JavaScript 对象，或者由原生方法或 block 提供实现的 JavaScript 函数。
每一个 JSValue 实例都来源于代表 JavaScript 执行环境（execution environment）的 JSContext 对象，而那个执行环境（execution environment）就包含了那个 JSValue 值。这个 JSValue 值对它的 context 对象进行了强引用——任何与一个特定 JSContext 实例有关联的值（JSValue）只要被 retain 了，那个 context 就会存活。当你调用了一个 JSValue 对象的实例方法，并且那个方法返回了另一个 JSValue 对象，这个被返回的 JSValue 归属于同一个的 context。
每个 JavaScript value 都跟一个特定的代表执行资源的 JSVirtualMachine 对象有关联。你只能传 JSValue 实例给由相同的虚拟机所管理（host）的 JSValue 和 JSContext 实例方法——如果传了一个值（JSvalue）给一个不同的虚拟机，系统将会抛出一个 Objective-C 异常。
2. JavaScript 和原生之间的数据转换（Converting Between JavaScript and Native Types）
当在使用 Creating JavaScript Values 和 Reading and Converting JavaScript Values 中所列出的方法时，JavaScriptCore 会按照下面的规则，自动将原生的值（value）转成 JavaScript 的值（value）或者将 JavaScript 的值（value）转成原生的值（value）。
NSDictionary 对象或者 Swift 字典和它们所包含的 key 被转成带有对应名字的属性的 JavaScript 对象，反之亦然。字典中的值是被深拷贝和转换的。
NSArray 对象或者 Swift 数组会被转成 JavaScript 数组，反之亦然。字典中的值是被深拷贝和转换的。
Objective-C 的 block（或者带有 @convention(block) 的 Swift 闭包）会被转成 JavaScript 中的
Function对象，参数和返回值也会按照转换规则被转换。对于所有其他的原生的对象类型，JavaScriptCore 会创建一个 JavaScript 包装器对象，这个包装器对象拥有与原生类继承链对应的构造器原型链。默认情况下，包装原生对象的 JavaScript 并不能让原生对象的属性和方法在 JavaScript 也能使用。如果要选择转成 JavaScript 的属性和方法，可以参阅 JSExport Protocol Reference。
当你转换一个对象、方法或者 block 时，JavaScriptCore 将会按照 表 1 中的规则去转换对象属性和方法参数的类型和值。
表 1 Objective-C 或者 Swift 与 JavaScript 之间的类型转换
| Objective-C（和Swift）的数据类型 | JavaScript 的数据类型 | 说明 |
|---|---|---|
nil |
undefined |
|
| NSNull | null |
|
| NSString (Swift String) | String | |
| NSNumber 和 基本数据类型 |
Number, Boolean
|
转换是跟下面的这些方法一致的：① signed integer 类型：valueWithInt32:inContext: / toInt32 ；② unsigned integer 类型： valueWithUInt32:inContext: / toUInt32 ；③ Boolean 类型：valueWithBool:inContext: / toBool；④ 所有其他的数据类型： valueWithDouble:inContext: / toBool |
| NSDictionary (Swift Dictionary) | Object |
递归转换（Recursive conversion） |
| NSArray (Swift Array) | Array |
递归转换（Recursive conversion） |
| NSDate | Date |
|
| Objective-C or Swift object (id orAnyObject)；Objective-C or Swift class (Class orAnyClass) | Object |
使用 valueWithObject:inContext: / toObject 方法转换 |
| Structure types: NSRange, CGRect, CGPoint, CGSize | Object |
不支持其他结构体类型的转换 |
| Objective-C block (Swift closure) | Function |
Convert explicitly with valueWithObject:inContext: / toObject. JavaScript functions do not convert to native blocks/closures unless already backed by a native block/closure. |
二、功能（Tasks）
1.创建 JSValue 对象（Creating JavaScript Values）
+ valueWithNewObjectInContext:
+ valueWithNewRegularExpressionFromPattern:flags:inContext:
+ valueWithNewErrorFromMessage:inContext:
+ valueWithUndefinedInContext:
2.读取、转换 JSValue 对象（Reading and Converting JavaScript Values）
3.判断 JSValue 对象的类型（Determining the Type of a JavaScript Value）
isUndefined* Property*
isNull* Property*
isBoolean* Property*
isNumber* Property*
isString* Property*
isObject* Property*
isArray* Property*
isDate* Property*
4.比较 JSValue 对象（Comparing JavaScript Values）
- isEqualWithTypeCoercionToObject:
5.函数和构造函数（Working with Function and Constructor Values）
6.容器（Working with Container Values）
7.获取一个 JSValue 的上下文（Accessing a Value’s JavaScript Context）
context Property
8.通过下标获取 JSValue（Accessing Values with Subscript Syntax）
- setObject:atIndexedSubscript:
- setObject:forKeyedSubscript:
9. JavaScriptCore 的 C 语言 API（Working with the C JavaScriptCore API）
JSValueRef Property
+ valueWithJSValueRef:inContext:
三、常量（Constants）
Property Descriptor Keys
Keys for the native dictionary representation of a JavaScript property descriptor, used with the defineProperty:descriptor: method.
Declaration
extern NSString * const JSPropertyDescriptorWritableKey;
extern NSString * const JSPropertyDescriptorEnumerableKey;
extern NSString * const JSPropertyDescriptorConfigurableKey;
extern NSString * const JSPropertyDescriptorValueKey;
extern NSString * const JSPropertyDescriptorGetKey;
extern NSString * const JSPropertyDescriptorSetKey;
Constants
-
JSPropertyDescriptorWritableKey
The Boolean value for this key determines whether the property permits assignment with the JavaScript = operator.
Available in iOS 7.0 and later.
-
JSPropertyDescriptorEnumerableKey
The Boolean value for this key determines whether the property appears when enumerating the JavaScript object’s properties.
Available in iOS 7.0 and later.
-
JSPropertyDescriptorConfigurableKey
The Boolean value for this key determines whether the property deleted from its JavaScript object or its descriptor changed.
Available in iOS 7.0 and later.
-
JSPropertyDescriptorValueKey
The value for the property on the JavaScript object.
Available in iOS 7.0 and later.
-
JSPropertyDescriptorGetKey
The JavaScript function to be invoked when reading the property.
Available in iOS 7.0 and later.
-
JSPropertyDescriptorSetKey
The JavaScript function to be invoked when writing to the property.
Available in iOS 7.0 and later.
四、文档修订记录（Document Revision History）
下表所列为文档 JSValue Class Reference 的修订记录。
| 日期 | 说明 |
|---|---|
| 2015-12-08 | 新文档，用来描述一个 JavaScript 的虚拟机中的对象控件的一个值。 |
问题（Question）
- JSValue 可以用来做什么？
- 如何使用 JSValue 来进行原生数据和 JavaScript 数据之间的转换？
- JSValue 和 JSContext 、JSManagedValue 以及 JSVirtualMachine 之间的关系？
