轻语言网站：静态资源文件的使用

文档概述

网站程序中的所有图片、文本或其它资源文件都必须存放在项目根目录中的 static 文件夹中（即「资源」目录）。在页面代码中使用时，需带上 ./static/ 前缀。本章介绍图片、字体、音频、视频、SVG、图标、JSON/文本等常见资源文件的使用方法。

学习目标

阅读本文档后，你应当能够掌握以下内容：

静态资源目录的位置与 ./static/ 路径前缀
图片资源的赋值方式：图片框.图片 = "./static/logo.jpg"
自定义字体文件的引入：添加字体文件 + 字体名引用
音频播放与浏览器自动播放策略限制
视频播放与尺寸设置
SVG 图片的两种引入方式：置SVG代码 与 加载SVG文件
图标（favicon.ico）的放置位置
读取 JSON 与文本文件内容：读JSON文件/读文本文件
浏览器同源策略与本地服务器环境的必要性

涉及组件

组件	名称	作用	参考文档
图片框	`图片框1`	显示图片	文档`图像类组件_图片框`
标签	`标签1`	显示自定义字体文本	文档`文本类组件_标签`
音频播放器	`音频播放器1`	播放音频	文档`媒体类组件_音频播放器`
视频播放器	`视频播放器1`	播放视频	文档`媒体类组件_视频播放器`
SVG 图像框	`SVG图像框1`/`SVG图像框2`	显示 SVG	文档`图像类组件_SVG图像框`

涉及函数与关键字

关键字： 事件 ... 结束事件、变量

资源引用方式：

相对路径前缀 ./static/ —— 项目内静态资源
网络地址（http:///https://） —— 外部 CDN 或远程资源

字体函数：

添加字体文件(字体名, 路径, 回调) —— 注册自定义字体，加载完成回调

文件读取函数：

读JSON文件(路径, 回调, 是否解析) —— 读取 JSON 文件，回调返回对象或文本
读文本文件(路径, 回调) —— 读取文本文件，回调返回文本内容

音频视频属性：

音频地址 / 视频地址 —— 设置媒体源
视频宽度 / 视频高度 —— 设置视频显示尺寸
自动播放 / 开始播放() —— 音频播放控制（受浏览器策略限制）

SVG 方法：

置SVG代码(SVG代码文本) —— 直接设置 SVG 源码
加载SVG文件(路径) —— 从文件加载 SVG

网站开发常见的资源文件

字体文件：用于引入自定义字体，常见格式有 .ttf、.woff、.woff2 等。
音频文件：用于网页中的音效、背景音乐等，常见格式有 .mp3、.wav、.ogg 等。
视频文件：用于网页中的视频内容，常见格式有 .mp4、.webm、.ogg 等。
图标文件：用于网页中的各种图标，常见格式有 .ico、.svg 等，也可以使用图标字体库如 Font Awesome。
数据文件：用于存储网页需要的数据，常见格式有 .json、.xml、.csv 等。
PDF 文件：用于在网页中嵌入或链接 PDF 文档。
SVG 文件：用于矢量图形，可以直接嵌入 HTML 或作为单独文件引用。

代码使用示例

' 1.图片资源文件的使用
图片框1.图片 = "./static/logo.jpg"

' 2.自定义字体文件的使用
添加字体文件("myfont","./static/fonts/custom.font.ttf",()=>{
    标签1.字体 = "myfont"
})

' 3.播放音频文件
音频播放器1.音频地址 = "../static/music2.mp3"
' 自动播放限制：现代浏览器（Chrome、Firefox、Safari 等）都实现了自动播放策略，但要求用户必须先与页面交互才能播放媒体。
' Promise 拒绝：开始播放函数 返回一个 Promise，当播放被阻止时，这个 Promise 会被拒绝并抛出 NotAllowedError。
' 安全策略：这是浏览器的安全机制，防止网站在用户不知情的情况下播放音频或视频。
' 因此下方两句代码在大部分浏览器中不会生效、必须让用户点击才能播放
'音频播放器1.自动播放 = 真
'音频播放器1.开始播放()

' 4、播放视频文件、由于本地没有找到合适的小素材资源文件作演示，这里使用菜鸟教程里面的一个视频地址
视频播放器1.视频地址 = "https://www.runoob.com/try/demo_source/movie.mp4"
' 视频宽度和元素宽度要手动设置保持一致
视频播放器1.视频宽度 = 320
视频播放器1.视频高度 = 240

' 5.图标文件、图标文件比较简单，只需要在编译输出的项目根目录中
' 放置一个名称为：favicon.ico 的图标文件即可，不需要做其它处理

' 6.置SVG图片
SVG图像框1.置SVG代码("<svg width=\"100\" height=\"100\" viewBox=\"0 0 100 100\"><circle cx=\"50\" cy=\"50\" r=\"40\" fill=\"blue\" /></svg>")
SVG图像框2.加载SVG文件("./static/timer.svg")

读取JSON或文本文件内容

事件 按钮1.被单击(源对象,事件源)
    ' 读取JSON数据文件，并解析
    ' 注意：不能直接在浏览器中打开html页面，需要有服务器环境
    调试输出("读取JSON文件：")
    读JSON文件("./static/jsondata.json",(JSON对象)=>{
        调试输出(JSON对象)
    },真)
结束 事件

事件 按钮2.被单击(源对象,事件源)
    读文本文件("./static/data.txt",(文本内容)=>{
        调试输出(文本内容)
    })
结束 事件

注意：

除了图片、音视频资源与脚本文件之外，使用其它任何资源文件时，都必须在本地服务器环境中打开页面才有效，直接在浏览器中打开 .html 文件将无效。

关键代码解读

1. 图片资源引用

图片框1.图片 = "./static/logo.jpg"

必须带 ./static/ 前缀（项目内资源）
也可使用网络地址：图片框1.图片 = "https://..."
.spldg XML 中设置图片属性写法：图片="./static/avatar.jpg"

2. 自定义字体加载

添加字体文件("myfont","./static/fonts/custom.font.ttf",()=>{
    标签1.字体 = "myfont"
})

添加字体文件 异步加载字体文件
参数：字体名（自定义）、路径、加载完成回调
字体加载是异步的，必须在回调中才能使用该字体
支持格式：.ttf、.woff、.woff2 等

3. 音频播放与浏览器自动播放限制

音频播放器1.音频地址 = "../static/music2.mp3"
'音频播放器1.自动播放 = 真       ' 大部分浏览器不生效
'音频播放器1.开始播放()           ' 大部分浏览器不生效

现代浏览器（Chrome、Firefox、Safari）都实施了自动播放策略
**必须用户先与页面交互（点击等）**才能播放媒体
开始播放() 返回 Promise，被阻止时会抛 NotAllowedError
这是浏览器的安全机制，防止网站在用户不知情的情况下播放音视频
解决方案：在按钮点击事件中调用 开始播放()

4. 视频播放

视频播放器1.视频地址 = "https://www.runoob.com/try/demo_source/movie.mp4"
视频播放器1.视频宽度 = 320
视频播放器1.视频高度 = 240

视频地址可为本地 ./static/ 路径或网络地址
视频宽高需手动设置，与组件尺寸保持一致
跨域视频需服务端配置 CORS

5. 网站图标 favicon

项目根目录（编译输出目录）放置：favicon.ico

网站图标无需代码处理
只需在编译输出目录根中放置一个名为 favicon.ico 的文件
浏览器会自动请求该文件作为标签页图标

6. SVG 图片两种引入方式

' 方式一：直接写 SVG 源码
SVG图像框1.置SVG代码("<svg width=\"100\" height=\"100\" viewBox=\"0 0 100 100\"><circle cx=\"50\" cy=\"50\" r=\"40\" fill=\"blue\" /></svg>")

' 方式二：从文件加载
SVG图像框2.加载SVG文件("./static/timer.svg")

置SVG代码 直接传入 SVG 源码字符串，适合动态生成或小段 SVG
加载SVG文件 从 ./static/ 加载 .svg 文件，适合复杂图形
两种方式任选其一

7. 读取 JSON 与文本文件

读JSON文件("./static/jsondata.json",(JSON对象)=>{
    调试输出(JSON对象)
},真)

读文本文件("./static/data.txt",(文本内容)=>{
    调试输出(文本内容)
})

均为异步读取，通过回调接收内容
读JSON文件 第三个参数 真 表示自动解析为对象；假 表示返回原始文本
必须在服务器环境中打开页面：浏览器同源策略限制下，file:// 协议无法 AJAX 读取本地文件

注意事项

资源目录固定为 static：所有静态资源必须放在 static 目录下，引用时带 ./static/ 前缀。
网络地址不需要前缀：引用 CDN 或远程资源时直接使用完整 URL（http:///https://）。
音频自动播放受限：现代浏览器禁止无用户交互的自动播放，应在用户点击事件中调用 开始播放()。
JSON/文本文件需服务器环境：直接双击打开 .html 文件（file://）无法 AJAX 读取文件，必须部署到本地 WEB 环境或服务器。
字体加载是异步的：添加字体文件 在回调中才能使用该字体，回调前使用会回退到默认字体。
视频尺寸需手动设：视频宽度/视频高度 应与视频播放器组件尺寸保持一致，否则可能拉伸变形。
favicon 无需代码：仅需在编译输出目录根放一个 favicon.ico，浏览器自动请求。
SVG 字符串转义：置SVG代码 中 SVG 源码字符串内的双引号需用 \" 转义。
跨域资源需 CORS：引用外部域名资源时，目标服务器需配置 Access-Control-Allow-Origin。

学习要点总结

知识点	关键代码	适用场景
资源路径前缀	`./static/`	项目内资源引用
网络资源	`https://...`	CDN/远程资源
图片赋值	`图片框.图片 = "..."`	显示图片
自定义字体	`添加字体文件(名,路径,回调)`	引入字体
字体引用	`标签.字体 = "字体名"`	应用字体
音频地址	`音频播放器.音频地址 = "..."`	音频源
视频地址	`视频播放器.视频地址 = "..."`	视频源
视频尺寸	`视频宽度`/`视频高度`	视频显示尺寸
SVG 源码	`置SVG代码("...")`	动态 SVG
SVG 文件	`加载SVG文件("...")`	静态 SVG
读取 JSON	`读JSON文件(路径,回调,真)`	加载 JSON 数据
读取文本	`读文本文件(路径,回调)`	加载文本内容
网站图标	`favicon.ico` 放根目录	标签页图标

轻语言网站开发SDK文档