[{"data":1,"prerenderedAt":697},["ShallowReactive",2],{"quirekit-doc:\u002Fclassic\u002Ffonts":3,"quirekit-source:classic\u002Ffonts\u002Fapplication.ts":338,"mdc-dk5k8a-key":339},{"id":4,"title":5,"body":6,"description":326,"extension":327,"keywords":328,"locale":329,"meta":330,"navigation":331,"order":332,"path":333,"section":334,"seo":335,"stem":336,"__hash__":337},"docs\u002Fclassic\u002Ffonts.zh-CN.md","字体加载与替代",{"type":7,"value":8,"toc":320},"minimark",[9,13,18,34,38,91,115,129,133,153,176,199,202,208,288,291,294,301,308,316],[10,11,12],"p",{},"工具栏中有字体名称，不代表浏览器已经有这份字体。字体缺失会改变字宽、换行和分页。应用需要明确选择字体来源，并区分正文保存的字体意图与当前设备能够绘制的字体。",[14,15,17],"h2",{"id":16},"方案一应用已经加载的字体","方案一：应用已经加载的字体",[10,19,20,21,25,26,29,30,33],{},"适合统一品牌字体或离线部署。先在应用样式中声明实际可访问的 ",[22,23,24],"code",{},"@font-face","，再等待加载完成，使用 ",[22,27,28],{},"mountedFamilies"," 告诉 Classic 精确 CSS family。下面的 ",[22,31,32],{},"Application Serif"," 是示例名称，必须换成你实际声明的 family；它不是内置字体。",[35,36],"docs-recipe",{"name":37},"classic\u002Ffonts\u002Fapplication",[39,40,46],"pre",{"className":41,"code":42,"filename":43,"language":44,"meta":45,"style":45},"language-ts shiki shiki-themes github-light github-light github-dark","const webFonts = await prepareApplicationFonts(host.ownerDocument)\nconst instance = createClassicEditor({ element: host, preset, document, webFonts })\n","在创建 Classic 前调用","ts","",[22,47,48,75],{"__ignoreMap":45},[49,50,53,57,61,64,67,71],"span",{"class":51,"line":52},"line",1,[49,54,56],{"class":55},"sDD9d","const",[49,58,60],{"class":59},"sUNQB"," webFonts",[49,62,63],{"class":55}," =",[49,65,66],{"class":55}," await",[49,68,70],{"class":69},"sgQzM"," prepareApplicationFonts",[49,72,74],{"class":73},"sVPnS","(host.ownerDocument)\n",[49,76,78,80,83,85,88],{"class":51,"line":77},2,[49,79,56],{"class":55},[49,81,82],{"class":59}," instance",[49,84,63],{"class":55},[49,86,87],{"class":69}," createClassicEditor",[49,89,90],{"class":73},"({ element: host, preset, document, webFonts })\n",[10,92,93,94,97,98,97,101,104,105,110,111,114],{},"这里的 ",[22,95,96],{},"host","、",[22,99,100],{},"preset",[22,102,103],{},"document"," 沿用",[106,107,109],"a",{"href":108},"\u002Fclassic\u002Fquick-start","快速接入","的宿主、Word 预设和正文。只声明 mountedFamilies 不会替你加载 CSS；",[22,112,113],{},"webFonts: false"," 也不会加载缺失字体或自动消除字体差异。",[10,116,117,120,121,124,125,128],{},[22,118,119],{},"displayName"," 是显示文案，不能代替精确 ",[22,122,123],{},"family","。配置字体来源不等于修改正文的字体选择；改变当前选区字体使用已安装的 ",[22,126,127],{},"setFontFamily(family)"," 命令，整份文档的字体主题则属于规范文档配置。",[14,130,132],{"id":131},"方案二按需安装外部字体","方案二：按需安装外部字体",[10,134,135,138,139,97,142,145,146,149,150,152],{},[22,136,137],{},"webFonts"," 可提供 ",[22,140,141],{},"families",[22,143,144],{},"catalogs"," 与可搜索的 ",[22,147,148],{},"sources","。",[22,151,141],{}," 公开可供安装的元数据；catalog 根据精确 family 返回完整 manifest；source 提供搜索、分页和 manifest 解析。manifest 包含版本、字面、资产和许可告知，不能只给一个显示名称或 CSS URL 冒充完整合同。",[10,154,155,156,159,160,163,164,167,168,171,172,175],{},"挂载后读取 ",[22,157,158],{},"instance.fontLibrary","。先 ",[22,161,162],{},"subscribe(listener)"," 观察加载状态，再根据明确用户操作调用 ",[22,165,166],{},"install(family)","；它返回浏览器注册与布局失效完成的 Promise。",[22,169,170],{},"previewFamily()"," 允许预览而不把记录加入已导入字体，",[22,173,174],{},"importFamily()"," 管理显式导入。页面退出或更换 library 时解除订阅，异步返回后也要复核当前实例。",[10,177,178,179,181,182,184,185,97,188,97,191,194,195,198],{},"默认字体库可以被配置替换；自己提供的 ",[22,180,141],{}," \u002F ",[22,183,144],{}," 是完整配置，不应假定默认来源仍然自动存在。实际预算由 ",[22,186,187],{},"maxAssetBytes",[22,189,190],{},"maxConcurrentAssets",[22,192,193],{},"fetch"," 和 ",[22,196,197],{},"cache"," 控制。",[14,200,201],{"id":201},"读懂字体状态",[10,203,204,207],{},[22,205,206],{},"instance.documentFontStatus"," 描述文档正文字体：",[209,210,211,224],"table",{},[212,213,214],"thead",{},[215,216,217,221],"tr",{},[218,219,220],"th",{},"字段或状态",[218,222,223],{},"含义",[225,226,227,238,248,258,268,278],"tbody",{},[215,228,229,235],{},[230,231,232],"td",{},[22,233,234],{},"requestedFamily",[230,236,237],{},"正文保留的逻辑字体",[215,239,240,245],{},[230,241,242],{},[22,243,244],{},"renderedFamily",[230,246,247],{},"当前选择的具体渲染字体，不代表每个字符都来自它",[215,249,250,255],{},[230,251,252],{},[22,253,254],{},"pending",[230,256,257],{},"正在解析或加载",[215,259,260,265],{},[230,261,262],{},[22,263,264],{},"available",[230,266,267],{},"请求字体可用",[215,269,270,275],{},[230,271,272],{},[22,273,274],{},"substituted",[230,276,277],{},"使用明确替代候选，逻辑字体仍保留",[215,279,280,285],{},[230,281,282],{},[22,283,284],{},"unresolved",[230,286,287],{},"尚无可确认的具体字体",[10,289,290],{},"不要在替代发生时悄悄重写正文的字体名称。不同脚本和单个缺字还可能走 glyph fallback；一个正文字体状态不能证明全文每个字形都相同。",[14,292,293],{"id":293},"布局与导出的验证",[10,295,296,297,300],{},"内置字体安装流程会刷新字体度量与布局；应用自行在挂载后加载 CSS 字体时，需要在就绪后调用当前 ",[22,298,299],{},"instance.editor?.view.refreshFontMetrics()","。保持当前编辑器有效，避免对已经卸载的 Core 刷新。",[10,302,303,304,307],{},"字体缓存、浏览器注册与可导出的字体字节是不同资源。",[22,305,306],{},"fontLibrary.getInstallations()"," 可读取已完成的安装结果；仅本地可用的记录不含可嵌入字节，不能因此声称导出必然携带该字体。导出还需按所用服务确认资源与授权范围。",[10,309,310,311,315],{},"验证首次打开、缓存命中、离线、下载失败和中英混排。等待字体就绪后检查换行、页数与选区位置；不要只确认下拉列表里出现了名称。配置类型在",[106,312,314],{"href":313},"\u002Fclassic\u002Freference","实例参考","查询。",[317,318,319],"style",{},"html pre.shiki code .sDD9d, html code.shiki .sDD9d{--shiki-default:#D73A49;--shiki-light:#D73A49;--shiki-dark:#F97583}html pre.shiki code .sUNQB, html code.shiki .sUNQB{--shiki-default:#005CC5;--shiki-light:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sgQzM, html code.shiki .sgQzM{--shiki-default:#6F42C1;--shiki-light:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sVPnS, html code.shiki .sVPnS{--shiki-default:#24292E;--shiki-light:#24292E;--shiki-dark:#E1E4E8}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":45,"searchDepth":77,"depth":77,"links":321},[322,323,324,325],{"id":16,"depth":77,"text":17},{"id":131,"depth":77,"text":132},{"id":201,"depth":77,"text":201},{"id":293,"depth":77,"text":293},"接入应用字体或外部字体库，区分逻辑字体、实际渲染字体和导出资源。","md",null,"zh-CN",{},true,4,"\u002Fclassic\u002Ffonts","Classic 开发",{"title":5,"description":326},"classic\u002Ffonts.zh-CN","-q7ATDMp308v29BiIon_fDwtmRN6o6jNYDbtLdQ6bB0","import type { ClassicEditorWebFontOptions } from \"@quirekit\u002Fclassic-editor\";\n\n\u002F**\n * Waits for an application-owned @font-face before creating Classic.\n * @param owner - Browser document whose stylesheet already declares the face.\n * @returns Explicit mounted-family configuration without an external catalog.\n *\u002F\nexport async function prepareApplicationFonts(owner: Document): Promise\u003CClassicEditorWebFontOptions> {\n  const faces = await owner.fonts.load('16px \"Application Serif\"');\n  if (faces.length === 0) throw new Error(\"Application Serif has no registered @font-face.\");\n  return { families: [], catalogs: [], mountedFamilies: [{ family: \"Application Serif\", displayName: \"应用正文字体\" }] };\n}\n",{"data":340,"body":341},{},{"type":342,"children":343},"root",[344,692],{"type":345,"tag":39,"props":346,"children":348},"element",{"className":41,"code":347,"language":44,"meta":45,"style":45},"import type { ClassicEditorWebFontOptions } from \"@quirekit\u002Fclassic-editor\";\n\n\u002F**\n * Waits for an application-owned @font-face before creating Classic.\n * @param owner - Browser document whose stylesheet already declares the face.\n * @returns Explicit mounted-family configuration without an external catalog.\n *\u002F\nexport async function prepareApplicationFonts(owner: Document): Promise\u003CClassicEditorWebFontOptions> {\n  const faces = await owner.fonts.load('16px \"Application Serif\"');\n  if (faces.length === 0) throw new Error(\"Application Serif has no registered @font-face.\");\n  return { families: [], catalogs: [], mountedFamilies: [{ family: \"Application Serif\", displayName: \"应用正文字体\" }] };\n}\n\n",[349],{"type":345,"tag":22,"props":350,"children":351},{"__ignoreMap":45},[352,389,397,407,415,439,457,466,540,587,649,683],{"type":345,"tag":49,"props":353,"children":354},{"class":51,"line":52},[355,362,367,373,378,384],{"type":345,"tag":49,"props":356,"children":358},{"style":357},"--shiki-default:#D73A49;--shiki-light:#D73A49;--shiki-dark:#F97583",[359],{"type":360,"value":361},"text","import",{"type":345,"tag":49,"props":363,"children":364},{"style":357},[365],{"type":360,"value":366}," type",{"type":345,"tag":49,"props":368,"children":370},{"style":369},"--shiki-default:#24292E;--shiki-light:#24292E;--shiki-dark:#E1E4E8",[371],{"type":360,"value":372}," { ClassicEditorWebFontOptions } ",{"type":345,"tag":49,"props":374,"children":375},{"style":357},[376],{"type":360,"value":377},"from",{"type":345,"tag":49,"props":379,"children":381},{"style":380},"--shiki-default:#032F62;--shiki-light:#032F62;--shiki-dark:#9ECBFF",[382],{"type":360,"value":383}," \"@quirekit\u002Fclassic-editor\"",{"type":345,"tag":49,"props":385,"children":386},{"style":369},[387],{"type":360,"value":388},";\n",{"type":345,"tag":49,"props":390,"children":391},{"class":51,"line":77},[392],{"type":345,"tag":49,"props":393,"children":394},{"emptyLinePlaceholder":331},[395],{"type":360,"value":396},"\n",{"type":345,"tag":49,"props":398,"children":400},{"class":51,"line":399},3,[401],{"type":345,"tag":49,"props":402,"children":404},{"style":403},"--shiki-default:#6A737D;--shiki-light:#6A737D;--shiki-dark:#6A737D",[405],{"type":360,"value":406},"\u002F**\n",{"type":345,"tag":49,"props":408,"children":409},{"class":51,"line":332},[410],{"type":345,"tag":49,"props":411,"children":412},{"style":403},[413],{"type":360,"value":414}," * Waits for an application-owned @font-face before creating Classic.\n",{"type":345,"tag":49,"props":416,"children":418},{"class":51,"line":417},5,[419,424,429,434],{"type":345,"tag":49,"props":420,"children":421},{"style":403},[422],{"type":360,"value":423}," * ",{"type":345,"tag":49,"props":425,"children":426},{"style":357},[427],{"type":360,"value":428},"@param",{"type":345,"tag":49,"props":430,"children":431},{"style":369},[432],{"type":360,"value":433}," owner",{"type":345,"tag":49,"props":435,"children":436},{"style":403},[437],{"type":360,"value":438}," - Browser document whose stylesheet already declares the face.\n",{"type":345,"tag":49,"props":440,"children":442},{"class":51,"line":441},6,[443,447,452],{"type":345,"tag":49,"props":444,"children":445},{"style":403},[446],{"type":360,"value":423},{"type":345,"tag":49,"props":448,"children":449},{"style":357},[450],{"type":360,"value":451},"@returns",{"type":345,"tag":49,"props":453,"children":454},{"style":403},[455],{"type":360,"value":456}," Explicit mounted-family configuration without an external catalog.\n",{"type":345,"tag":49,"props":458,"children":460},{"class":51,"line":459},7,[461],{"type":345,"tag":49,"props":462,"children":463},{"style":403},[464],{"type":360,"value":465}," *\u002F\n",{"type":345,"tag":49,"props":467,"children":469},{"class":51,"line":468},8,[470,475,480,485,490,495,501,506,511,516,520,525,530,535],{"type":345,"tag":49,"props":471,"children":472},{"style":357},[473],{"type":360,"value":474},"export",{"type":345,"tag":49,"props":476,"children":477},{"style":357},[478],{"type":360,"value":479}," async",{"type":345,"tag":49,"props":481,"children":482},{"style":357},[483],{"type":360,"value":484}," function",{"type":345,"tag":49,"props":486,"children":488},{"style":487},"--shiki-default:#6F42C1;--shiki-light:#6F42C1;--shiki-dark:#B392F0",[489],{"type":360,"value":70},{"type":345,"tag":49,"props":491,"children":492},{"style":369},[493],{"type":360,"value":494},"(",{"type":345,"tag":49,"props":496,"children":498},{"style":497},"--shiki-default:#E36209;--shiki-light:#E36209;--shiki-dark:#FFAB70",[499],{"type":360,"value":500},"owner",{"type":345,"tag":49,"props":502,"children":503},{"style":357},[504],{"type":360,"value":505},":",{"type":345,"tag":49,"props":507,"children":508},{"style":487},[509],{"type":360,"value":510}," Document",{"type":345,"tag":49,"props":512,"children":513},{"style":369},[514],{"type":360,"value":515},")",{"type":345,"tag":49,"props":517,"children":518},{"style":357},[519],{"type":360,"value":505},{"type":345,"tag":49,"props":521,"children":522},{"style":487},[523],{"type":360,"value":524}," Promise",{"type":345,"tag":49,"props":526,"children":527},{"style":369},[528],{"type":360,"value":529},"\u003C",{"type":345,"tag":49,"props":531,"children":532},{"style":487},[533],{"type":360,"value":534},"ClassicEditorWebFontOptions",{"type":345,"tag":49,"props":536,"children":537},{"style":369},[538],{"type":360,"value":539},"> {\n",{"type":345,"tag":49,"props":541,"children":543},{"class":51,"line":542},9,[544,549,555,559,563,568,573,577,582],{"type":345,"tag":49,"props":545,"children":546},{"style":357},[547],{"type":360,"value":548},"  const",{"type":345,"tag":49,"props":550,"children":552},{"style":551},"--shiki-default:#005CC5;--shiki-light:#005CC5;--shiki-dark:#79B8FF",[553],{"type":360,"value":554}," faces",{"type":345,"tag":49,"props":556,"children":557},{"style":357},[558],{"type":360,"value":63},{"type":345,"tag":49,"props":560,"children":561},{"style":357},[562],{"type":360,"value":66},{"type":345,"tag":49,"props":564,"children":565},{"style":369},[566],{"type":360,"value":567}," owner.fonts.",{"type":345,"tag":49,"props":569,"children":570},{"style":487},[571],{"type":360,"value":572},"load",{"type":345,"tag":49,"props":574,"children":575},{"style":369},[576],{"type":360,"value":494},{"type":345,"tag":49,"props":578,"children":579},{"style":380},[580],{"type":360,"value":581},"'16px \"Application Serif\"'",{"type":345,"tag":49,"props":583,"children":584},{"style":369},[585],{"type":360,"value":586},");\n",{"type":345,"tag":49,"props":588,"children":590},{"class":51,"line":589},10,[591,596,601,606,611,616,621,626,631,636,640,645],{"type":345,"tag":49,"props":592,"children":593},{"style":357},[594],{"type":360,"value":595},"  if",{"type":345,"tag":49,"props":597,"children":598},{"style":369},[599],{"type":360,"value":600}," (faces.",{"type":345,"tag":49,"props":602,"children":603},{"style":551},[604],{"type":360,"value":605},"length",{"type":345,"tag":49,"props":607,"children":608},{"style":357},[609],{"type":360,"value":610}," ===",{"type":345,"tag":49,"props":612,"children":613},{"style":551},[614],{"type":360,"value":615}," 0",{"type":345,"tag":49,"props":617,"children":618},{"style":369},[619],{"type":360,"value":620},") ",{"type":345,"tag":49,"props":622,"children":623},{"style":357},[624],{"type":360,"value":625},"throw",{"type":345,"tag":49,"props":627,"children":628},{"style":357},[629],{"type":360,"value":630}," new",{"type":345,"tag":49,"props":632,"children":633},{"style":487},[634],{"type":360,"value":635}," Error",{"type":345,"tag":49,"props":637,"children":638},{"style":369},[639],{"type":360,"value":494},{"type":345,"tag":49,"props":641,"children":642},{"style":380},[643],{"type":360,"value":644},"\"Application Serif has no registered @font-face.\"",{"type":345,"tag":49,"props":646,"children":647},{"style":369},[648],{"type":360,"value":586},{"type":345,"tag":49,"props":650,"children":652},{"class":51,"line":651},11,[653,658,663,668,673,678],{"type":345,"tag":49,"props":654,"children":655},{"style":357},[656],{"type":360,"value":657},"  return",{"type":345,"tag":49,"props":659,"children":660},{"style":369},[661],{"type":360,"value":662}," { families: [], catalogs: [], mountedFamilies: [{ family: ",{"type":345,"tag":49,"props":664,"children":665},{"style":380},[666],{"type":360,"value":667},"\"Application Serif\"",{"type":345,"tag":49,"props":669,"children":670},{"style":369},[671],{"type":360,"value":672},", displayName: ",{"type":345,"tag":49,"props":674,"children":675},{"style":380},[676],{"type":360,"value":677},"\"应用正文字体\"",{"type":345,"tag":49,"props":679,"children":680},{"style":369},[681],{"type":360,"value":682}," }] };\n",{"type":345,"tag":49,"props":684,"children":686},{"class":51,"line":685},12,[687],{"type":345,"tag":49,"props":688,"children":689},{"style":369},[690],{"type":360,"value":691},"}\n",{"type":345,"tag":317,"props":693,"children":694},{},[695],{"type":360,"value":696},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",1793045224594]