1# 属性字符串 (系统接口) 2 3方便灵活应用文本样式的对象，可通过TextController中的[setStyledString](./ts-basic-components-text.md#setstyledstring12)方法与Text组件绑定，可通过RichEditorStyledStringController中的[setStyledString](ts-basic-components-richeditor.md#setstyledstring12)方法与RichEditor组件绑定。 4 5> **说明：** 6> 7> 该组件从API Version 13开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> 当前页面仅包含本模块的系统接口，其他公开接口参见[属性字符串](ts-universal-styled-string.md)。 10 11## StyledString 12 13### marshalling 14 15static marshalling(styledString: StyledString): ArrayBuffer 16 17序列化属性字符串。 18 19**系统接口：** 此接口为系统接口。 20 21**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 22 23**系统能力：** SystemCapability.ArkUI.ArkUI.Full 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| ----- | ----- | ---- | ---- | 29| styledString | [StyledString](ts-universal-styled-string.md) | 是 | 属性字符串参数。 | 30 31**返回值：** 32 33| 类型 |说明 | 34| ------- | --------------------------------- | 35| ArrayBuffer | 序列化后的buffer信息。<br/>**说明：** <br/>目前支持文本和图片。 | 36 37### marshalling<sup>18+</sup> 38 39static marshalling(styledString: StyledString, callback: StyledStringMarshallCallback): ArrayBuffer 40 41序列化属性字符串，通过定义回调来序列化属性字符串的[StyledStringMarshallingValue](#styledstringmarshallingvalue18)。 42 43**系统接口：** 此接口为系统接口。 44 45**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 46 47**系统能力：** SystemCapability.ArkUI.ArkUI.Full 48 49**参数：** 50 51| 参数名 | 类型 | 必填 | 说明 | 52| ----- | ----- | ---- | ---- | 53| styledString | [StyledString](ts-universal-styled-string.md) | 是 | 属性字符串参数。 | 54| callback | [StyledStringMarshallCallback](#styledstringmarshallcallback18) | 是 | 如何序列化[StyledStringMarshallingValue](#styledstringmarshallingvalue18)的回调。 | 55 56**返回值：** 57 58| 类型 |说明 | 59| ------- | --------------------------------- | 60| ArrayBuffer | 序列化后的buffer信息。<br/>**说明：** <br/>目前支持文本和图片。 | 61 62### unmarshalling 63 64static unmarshalling(buffer: ArrayBuffer): Promise\<StyledString> 65 66反序列化后得到属性字符串。 67 68**系统接口：** 此接口为系统接口。 69 70**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 71 72**系统能力：** SystemCapability.ArkUI.ArkUI.Full 73 74**参数：** 75 76| 参数名 | 类型 | 必填 | 说明 | 77| ----- | ----- | ---- | ---- | 78| buffer | ArrayBuffer | 是 | 属性字符串序列化后的数据。 | 79 80**返回值：** 81 82| 类型 | 说明 | 83| -------------------------------- | --------------------- | 84| Promise\<[StyledString](ts-universal-styled-string.md)> |Promise对象，返回属性字符串。 | 85 86 87### unmarshalling<sup>18+</sup> 88 89static unmarshalling(buffer: ArrayBuffer, callback: StyledStringUnmarshallCallback): Promise\<StyledString> 90 91反序列化后得到属性字符串，通过定义回调来反序列化[StyledStringMarshallingValue](#styledstringmarshallingvalue18)。 92 93**系统接口：** 此接口为系统接口。 94 95**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 96 97**系统能力：** SystemCapability.ArkUI.ArkUI.Full 98 99**参数：** 100 101| 参数名 | 类型 | 必填 | 说明 | 102| ----- | ----- | ---- | ---- | 103| buffer | ArrayBuffer | 是 | 属性字符串序列化后的数据。 | 104| callback | [StyledStringUnmarshallCallback](#styledstringunmarshallcallback18) | 是 | 如何反序列化ArrayBuffer的回调。 | 105 106**返回值：** 107 108| 类型 | 说明 | 109| -------------------------------- | --------------------- | 110| Promise\<[StyledString](ts-universal-styled-string.md)> |Promise对象，返回属性字符串。 | 111 112**错误码**： 113 114以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)。 115 116| 错误码ID | 错误信息 | 117| ------- | -------- | 118| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 119 120## StyledStringMarshallingValue<sup>18+</sup> 121 122type StyledStringMarshallingValue = UserDataSpan 123 124属性字符串自定义序列化对象类型，需要开发者定义序列化和反序列化的方式。 125 126**系统接口：** 此接口为系统接口。 127 128**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 129 130**系统能力：** SystemCapability.ArkUI.ArkUI.Full 131 132| 类型 | 说明 | 133| ------ | ---------- | 134| [UserDataSpan](ts-universal-styled-string.md#userdataspan) | UserDataSpan样式。 | 135 136## StyledStringMarshallCallback<sup>18+</sup> 137 138type StyledStringMarshallCallback = (marshallableVal: StyledStringMarshallingValue) => ArrayBuffer 139 140属性字符串[StyledStringMarshallingValue](#styledstringmarshallingvalue18)序列化回调类型。 141 142**系统接口：** 此接口为系统接口。 143 144**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 145 146**系统能力：** SystemCapability.ArkUI.ArkUI.Full 147 148**参数：** 149 150| 参数名 | 类型 | 必填 | 说明 | 151| ------- | ------ | ---- | --------------------------- | 152| marshallableVal | [StyledStringMarshallingValue](#styledstringmarshallingvalue18)| 是 | 属性字符串序列化对象。 | 153 154**返回值：** 155 156| 类型 | 说明 | 157| -------------------------------- | --------------------- | 158| ArrayBuffer | [StyledStringMarshallingValue](#styledstringmarshallingvalue18)序列化后的数据。| 159 160## StyledStringUnmarshallCallback<sup>18+</sup> 161 162type StyledStringUnmarshallCallback = (buf: ArrayBuffer) => StyledStringMarshallingValue 163 164属性字符串反序列化ArrayBuffer得到[StyledStringMarshallingValue](#styledstringmarshallingvalue18)回调类型。 165 166**系统接口：** 此接口为系统接口。 167 168**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 169 170**系统能力：** SystemCapability.ArkUI.ArkUI.Full 171 172**参数：** 173 174| 参数名 | 类型 | 必填 | 说明 | 175| ------- | ------ | ---- | --------------------------- | 176| buf | ArrayBuffer | 是 | [StyledStringMarshallingValue](#styledstringmarshallingvalue18)序列化后的数据。 | 177 178**返回值：** 179 180| 类型 | 说明 | 181| -------------------------------- | --------------------- | 182| [StyledStringMarshallingValue](#styledstringmarshallingvalue18) | 反序列化得到的[StyledStringMarshallingValue](#styledstringmarshallingvalue18) 。| 183 184## 示例 185 186### 示例1 (属性字符串序列化和反序列化) 187 188该示例通过marshalling、unmarshalling属性实现了属性字符串序列化和反序列化的功能。 189 190```ts 191// xxx.ets 192import { LengthMetrics } from '@kit.ArkUI' 193 194@Entry 195@Component 196struct Index { 197 @State textTitle: string = "序列化和反序列化接口" 198 @State textResult: string = "Hello world" 199 @State serializeStr: string = "序列化" 200 @State flag: boolean = false 201 private textAreaController: TextAreaController = new TextAreaController() 202 private buff: Uint8Array = new Uint8Array() 203 204 fontStyle: TextStyle = new TextStyle({ 205 fontWeight: FontWeight.Lighter, 206 fontFamily: 'HarmonyOS Sans', 207 fontColor: Color.Green, 208 fontSize: LengthMetrics.vp(30), 209 fontStyle: FontStyle.Normal 210 }) 211 // 创建属性字符串对象 212 styledString: StyledString = new StyledString("Hello world", 213 [{ start: 0, length: 11, styledKey: StyledStringKey.FONT, styledValue: this.fontStyle }]); 214 215 @Builder 216 controllableBuild() { 217 Column(){ 218 TextArea({ 219 text: this.textResult, 220 controller: this.textAreaController 221 }).width('95%').height('40%').enableKeyboardOnFocus(false) 222 223 Button(this.serializeStr) 224 .margin(5) 225 .onClick(async ()=>{ 226 this.flag = !this.flag 227 if (!this.flag) { 228 console.info("Debug: 反序列化") 229 let styles: StyledString = await StyledString.unmarshalling(this.buff.buffer) 230 this.textTitle = "调取decodeTlv接口后，反序列化的结果显示：" 231 if (styles == undefined) { 232 console.error("Debug: styledString 获取失败！！！") 233 return 234 } 235 this.textResult = styles.getString() 236 console.info("Debug: this.textResult = " + this.textResult) 237 let stylesArr = styles.getStyles(0, this.textResult.length, StyledStringKey.FONT) 238 console.info("Debug: stylesArr.length = " + stylesArr.length) 239 for (let i = 0; i < stylesArr.length; ++i) { 240 console.info("Debug: style.start = " + stylesArr[i].start) 241 console.info("Debug: style.length = " + stylesArr[i].length) 242 console.info("Debug: style.styledKey = " + stylesArr[i].styledKey) 243 let font = stylesArr[i].styledValue as TextStyle 244 console.info("Debug: style.fontColor = " + font.fontColor) 245 console.info("Debug: style.fontSize = " + font.fontSize) 246 console.info("Debug: style.fontFamily = " + font.fontFamily) 247 console.info("Debug: style.fontStyle = " + font.fontStyle) 248 } 249 let subStr = styles.subStyledString(0, 2) 250 console.info("Debug: subStr = " + subStr.getString()) 251 this.serializeStr = "序列化" 252 } else { 253 console.info("Debug: 序列化") 254 let resultBuffer = StyledString.marshalling(this.styledString) 255 this.buff = new Uint8Array(resultBuffer) 256 this.textTitle = "调取encodeTlv接口后，序列化的结果显示：" 257 this.textResult = this.buff.toString() 258 console.info("Debug: buff = " + this.buff.toString()) 259 this.serializeStr = "反序列化" 260 } 261 }) 262 }.margin(10) 263 } 264 265 build() { 266 Column() { 267 Blank().margin(30) 268 Text(this.textTitle) 269 this.controllableBuild() 270 } 271 } 272} 273``` 274 275### 示例2 (带UserDataSpan的属性字符串序列化和反序列化) 276 277该示例通过marshalling、unmarshalling函数实现了属性字符串及其UserDataSpan序列化和反序列化的功能。 278 279```ts 280enum MyUserDataType { 281 TYPE1 = 0, 282 TYPE2 283} 284 285class MyUserData extends UserDataSpan { 286 constructor(){ 287 super() 288 } 289 marshalling() { 290 console.log("MyUserData marshalling...") 291 const text = "MyUserData1"; 292 const buffer = new ArrayBuffer(text.length + 1); 293 const uint8View = new Uint8Array(buffer); 294 // 写入类型 295 uint8View[0] = MyUserDataType.TYPE1; 296 for (let i = 1; i < text.length; i++) { 297 uint8View[i] = text.charCodeAt(i); 298 } 299 return uint8View.buffer; 300 } 301 unmarshalling() 302 { 303 console.log("MyUserData unmarshalling...") 304 return new MyUserData() 305 } 306} 307 308class MyUserData2 extends UserDataSpan { 309 marshalling() { 310 console.log("MyUserData2 marshalling...") 311 const text = "MyUserData2"; 312 const buffer = new ArrayBuffer(text.length + 1); 313 const uint8View = new Uint8Array(buffer); 314 uint8View[0] = MyUserDataType.TYPE2; 315 for (let i = 1; i < text.length; i++) { 316 uint8View[i] = text.charCodeAt(i); 317 } 318 return uint8View.buffer; 319 } 320 unmarshalling() 321 { 322 console.log("MyUserData2 unmarshalling...") 323 return new MyUserData2() 324 } 325} 326 327@Entry 328@Component 329struct MarshallExample1 { 330 331 controller : TextController = new TextController() 332 333 build() { 334 Column() { 335 Text(undefined, {controller: this.controller}) 336 Button("Marshall&UnMarshall") 337 .onClick(async () => { 338 let myData = new MyUserData(); 339 let myData2 = new MyUserData2(); 340 let myStyledString = new MutableStyledString("12345", [{ 341 start: 0, 342 length: 3, 343 styledKey: StyledStringKey.USER_DATA, 344 styledValue: myData 345 }, { 346 start: 3, 347 length: 1, 348 styledKey: StyledStringKey.USER_DATA, 349 styledValue: myData2 350 }]) 351 352 let buffer = StyledString.marshalling(myStyledString, (marshallingValue: StyledStringMarshallingValue)=> { 353 // 根据类型选择对应的序列化接口 354 if (marshallingValue instanceof MyUserData) { 355 console.log("StyledString.marshalling MyUserData") 356 let value = marshallingValue as MyUserData; 357 return value.marshalling() 358 } else if (marshallingValue instanceof MyUserData2) { 359 console.log("StyledString.marshalling MyUserData2") 360 let value = marshallingValue as MyUserData2; 361 return value.marshalling() 362 } 363 console.log("StyledString.marshalling default") 364 return new ArrayBuffer(10) 365 }) 366 367 let newStyledString = await StyledString.unmarshalling(buffer, (value: ArrayBuffer) => { 368 // 1. 读取 type 类型， 369 // 2. 根据类型，选择对应的接口解析这个 buffer 370 const uint8View = new Uint8Array(value); 371 let type = uint8View[0]; 372 console.log("unmarshalling length:" + uint8View.length) 373 if (type == MyUserDataType.TYPE1) { 374 console.log("unmarshalling type1:" + type) 375 let myUserData = new MyUserData() 376 return myUserData.unmarshalling() 377 } else if (type == MyUserDataType.TYPE2) { 378 console.log("unmarshalling type2:" + type) 379 let myUserData = new MyUserData2() 380 return myUserData.unmarshalling() 381 } 382 return new ArrayBuffer(0) 383 }) 384 385 this.controller.setStyledString(newStyledString) 386 }) 387 .fontSize(20) 388 .margin(10) 389 } 390 .justifyContent(FlexAlign.Center) 391 .width('100%') 392 .height('100%') 393 } 394} 395```