npm - @colin4k1024/tsp - Versions diffs - 2.4.0 - Mend

@colin4k1024/tsp 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1867) hide show

package/skills/goframe-v2/references//346/240/270/345/277/203/347/273/204/344/273/266//346/250/241/346/235/277/345/274/225/346/223/216//346/250/241/346/235/277/345/274/225/346/223/216-/346/250/241/346/235/277/345/270/203/345/261/200.md ADDED Viewed

@@ -0,0 +1,148 @@
+`gview`模板引擎支持两种`layout`模板布局方式：
+1. `define` + `template`方式
+2. `include`模板嵌入方式
+这两种方式均支持对模板变量的传入。
+### `define` + `template`
+由于`gview`底层采用了`ParseFiles`方式批量解析模板文件，因此可以使用`define`标签定义模板内容块，通过`template`标签在其他任意的模板文件中引入指定的模板内容块。`template`标签支持跨模板引用，也就是说`define`标签定义的模板内容块可能是在其他模板文件中，`template`也可以随意引入。
+:::warning
+注意：
+- 为嵌套的子模板传递模板变量时，应当使用： `{{template "xxx" .}}` 的语法。
+- 模板文件的后缀名，要跟 `define template` 文件的后缀名保持一致。
+:::
+使用示例：
+1. `layout.html`
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>GoFrame Layout</title>
+    {{template "header" .}}
+</head>
+<body>
+    <div class="container">
+    {{template "container" .}}
+    </div>
+    <div class="footer">
+    {{template "footer" .}}
+    </div>
+</body>
+</html>
+```
+2. `header.html`
+```html
+{{define "header"}}
+    <h1>{{.header}}</h1>
+{{end}}
+```
+1. `container.html`
+```html
+{{define "container"}}
+<h1>{{.container}}</h1>
+{{end}}
+```
+1. `footer.html`
+```html
+{{define "footer"}}
+<h1>{{.footer}}</h1>
+{{end}}
+```
+1. `main.go`
+```go
+package main
+import (
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/net/ghttp"
+)
+func main() {
+    s := g.Server()
+    s.BindHandler("/", func(r *ghttp.Request) {
+        r.Response.WriteTpl("layout.html", g.Map{
+            "header":    "This is header",
+            "container": "This is container",
+            "footer":    "This is footer",
+        })
+    })
+    s.SetPort(8199)
+    s.Run()
+}
+```
+执行后，访问 [http://127.0.0.1:8199](http://127.0.0.1:8199/) 结果如下：
+### `include`模板嵌入
+当然我们也可以使用`include`标签来实现页面布局。
+:::warning
+注意，为嵌套的子模板传递模板变量时，应当使用： `{{include "xxx" .}}` 的语法。
+:::
+使用示例：
+1. `layout.html`
+```html
+{{include "header.html" .}}
+{{include .mainTpl .}}
+{{include "footer.html" .}}
+```
+2. `header.html`
+```html
+<h1>HEADER</h1>
+```
+3. `footer.html`
+```html
+<h1>FOOTER</h1>
+```
+4. `main1.html`
+```html
+<h1>MAIN1</h1>
+```
+1. `main2.html`
+```html
+<h1>MAIN2</h1>
+```
+1. `main.go`
+```go
+package main
+import (
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/net/ghttp"
+)
+func main() {
+    s := g.Server()
+    s.BindHandler("/main1", func(r *ghttp.Request) {
+        r.Response.WriteTpl("layout.html", g.Map{
+            "mainTpl": "main/main1.html",
+        })
+    })
+    s.BindHandler("/main2", func(r *ghttp.Request) {
+        r.Response.WriteTpl("layout.html", g.Map{
+            "mainTpl": "main/main2.html",
+        })
+    })
+    s.SetPort(8199)
+    s.Run()
+}
+```
+执行后，访问不同的路由地址，将会看到不同的结果：
+1. [http://127.0.0.1:8199/main1](http://127.0.0.1:8199/main1)
+2. [http://127.0.0.1:8199/main2](http://127.0.0.1:8199/main2)

@@ -0,0 +1,193 @@
+模板引擎默认使用了`{{`和`}}`作为左右闭合标签，开发者可通过`gview.SetDelimiters`方法设置自定义的模板闭合标签。
+使用`.`来访问当前对象的值（模板局部变量）。
+使用`$`来引用当前模板根级的上下文（模板全局变量）。
+使用`$var`来访问特定的模板变量。
+**模板中支持的`go`语言符号**
+```
+{{"string"}}     // 一般 string
+{{`raw string`}} // 原始 string
+{{'c'}}          // byte
+{{print nil}}    // nil 也被支持
+```
+**模板中的 `pipeline`**
+可以是上下文的变量输出，也可以是函数通过管道传递的返回值
+```
+{{. | FuncA | FuncB | FuncC}}
+```
+当 `pipeline` 的值等于:
+- `false` 或 `0`
+- `nil的指针` 或 `interface`
+- 长度为 `0` 的 `array`, `slice`, `map`, `string`
+那么这个 `pipeline` 被认为是空。
+:::warning
+需要注意：在 `gf` 模板引擎中，当模板中展示的指定变量不存在时，将会显示为空（标准库模板引擎会展示 `<no value>`）。
+:::
+## `if … else … end`
+```
+{{if pipeline}}...{{end}}
+```
+`if` 判断时， `pipeline` 为空时，相当于判断为 `false`。
+支持嵌套的循环
+```
+{{if .condition}}
+    ...
+{{else}}
+    {{if .condition2}}
+        ...
+    {{end}}
+{{end}}
+```
+也可以使用 `else if` 进行
+```
+{{if .condition}}
+    ...
+{{else if .condition2}}
+    ...
+{{else}}
+    ...
+{{end}}
+```
+## `range … end`
+```
+{{range pipeline}} {{.}} {{end}}
+```
+`pipeline` 支持的类型为 `slice`, `map`, `channel`。
+注意：在 `range` 循环内部， `.` 符号会被覆盖为以上类型的子元素（局部变量）。如果想在循环中访问外部变量（全局变量），请加上 `$` 符号，如： `{{$.Session.Name}}`
+此外，对应的值长度为 `0` 时， `range` 不会执行， `.` 不会改变。
+例如，遍历 `map`:
+```
+{{range $key, $value := .MapContent}}
+    {{$key}}:{{$value}}
+{{end}}
+```
+例如，遍历 `slice`:
+```
+{{range $index, $elem := .SliceContent}}
+    {{range $key, $value := $elem}}
+        {{$key}}:{{$value}}
+    {{end}}
+{{end}}
+```
+## `with … end`
+```
+{{with pipeline}}...{{end}}
+```
+`with` 用于重定向 `pipeline`
+```
+{{with .Field.NestField.SubField}}
+    {{.Var}}
+{{end}}
+```
+## `define`
+`define` 可以用来 **自定义模板内容块**(给一段模板内容定义一个模板名称)，可用于模块定义和模板嵌套(使用在 `template` 标签中)。
+```
+{{define "loop"}}
+    <li>{{.Name}}</li>
+{{end}}
+```
+其中 `loop` 为该模板内容块的名称，随后可使用 `template` 标签调用模板：
+```
+<ul>
+    {{range .Items}}
+        {{template "loop" .}}
+    {{end}}
+</ul>
+```
+:::warning
+`define` 标签需要结合 `template` 标签一起使用，并且支持跨模板使用（在同一模板目录/子目录下有效，原理是使用的 `ParseFiles` 方法解析模板文件）。
+:::
+## `template`
+```
+{{template "模板名称" pipeline}}
+```
+将对应的上下文 `pipeline` 传给模板，才可以在模板中调用。
+注意： `template` 标签参数为 `模板名称`，而不是模板文件路径， `template` 标签不支持模板文件路径。
+:::warning
+`template` 标签需要结合 `define` 标签一起使用，并且支持跨模板使用（在同一模板目录/子目录下有效，原理是使用的 `ParseFiles` 方法解析模板文件）。
+:::
+## `include`
+**该标签为 `gf` 框架模板引擎新增标签**
+```
+{{include "模板文件名(需要带完整文件名后缀)" pipeline}}
+```
+在模板中可以使用 `include` 标签载入其他模板（任意路径），模板文件名支持 **相对路径** 以及文件的系统 **绝对路径**。如果想要把当前模板的模板变量传递给子模板(嵌套模板)，可以这样：
+```
+{{include "模板文件名(需要带完整文件名后缀)" .}}
+```
+与 `template` 标签的区别是： `include` 仅支持 **文件路径**，不支持 **模板名称**；而 `tempalte` 标签仅支持 **模板名称**，不支持 **文件路径**。
+## 注释
+允许多行文本注释，不允许嵌套。
+```
+{{/*
+comment content
+support new line
+*/}}
+```
+## 删除空白符号
+删除移除空格换行符
+```
+# 使用{{-语法去除模板内容左侧的所有空白符号， 使用-}}去除模板内容右侧的所有空白符号。
+# 注意：-要紧挨{{和}}，同时与模板值之间需要使用空格分隔。
+{{- .Name -}}
+{{- range $key, $value := .list}}
+  "{{$value}}"
+{{- end}}
+```
+## 更多使用说明
+[template package - html/template - Go Packages](https://pkg.go.dev/html/template)
+[template package - text/template - Go Packages](https://pkg.go.dev/text/template)

@@ -0,0 +1,122 @@
+视图组件是`GoFrame`框架核心的组件之一，当然也支持非常方便的配置管理功能。
+## 配置对象
+配置对象定义： [https://pkg.go.dev/github.com/gogf/gf/v2/os/gview#Config](https://pkg.go.dev/github.com/gogf/gf/v2/os/gview#Config)
+## 配置文件
+视图组件支持配置文件，当使用`g.View(单例名称)`获取`View`单例对象时，将会自动通过默认的配置管理对象获取对应的`View`配置。默认情况下会读取`viewer.单例名称`配置项，当该配置项不存在时，将会读取`viewer`配置项。
+完整配置文件配置项及说明如下，其中配置项名称不区分大小写：
+```
+[viewer]
+    Paths       = ["/var/www/template"] # 模板文件搜索目录路径，建议使用绝对路径。默认为当前程序工作路径
+    DefaultFile = "index.html"          # 默认解析的模板引擎文件。默认为"index.html"
+    Delimiters  =  ["${", "}"]          # 模板引擎变量分隔符号。默认为 ["{{", "}}"]
+    AutoEncode  = false                 # 是否默认对变量内容进行XSS编码。默认为false
+    [viewer.Data]                       # 自定义的全局Key-Value键值对，将在模板解析中可被直接使用到
+        Key1 = "Value1"
+        Key2 = "Value2"
+```
+### 示例1，默认配置项
+```
+[viewer]
+    paths       = ["template", "/var/www/template"]
+    defaultFile = "index.html"
+    delimiters  =  ["${", "}"]
+    [viewer.data]
+        name    = "gf"
+        version = "1.10.0"
+```
+随后可以使用 `g.View()` 获取默认的单例对象时自动获取并设置该配置。
+### 示例2，多个配置项
+多个 `View` 对象的配置示例：
+```
+[viewer]
+    paths       = ["template", "/var/www/template"]
+    defaultFile = "index.html"
+    delimiters  =  ["${", "}"]
+    [viewer.data]
+        name    = "gf"
+        version = "1.10.0"
+    [viewer.view1]
+        defaultFile = "layout.html"
+        delimiters  = ["${", "}"]
+    [viewer.view2]
+        defaultFile = "main.html"
+        delimiters  = ["#{", "}"]
+```
+我们可以通过单例对象名称获取对应配置的 `View` 单例对象：
+```go
+// 对应 viewer.view1 配置项
+v1 := g.View("view1")
+// 对应 viewer.view2 配置项
+v2 := g.View("view2")
+// 对应默认配置项 viewer
+v3 := g.View("none")
+// 对应默认配置项 viewer
+v4 := g.View()
+```
+### 配置方法
+方法列表： [https://pkg.go.dev/github.com/gogf/gf/v2/os/gview](https://pkg.go.dev/github.com/gogf/gf/v2/os/gview)
+简要说明：
+1. 可以通过 `SetConfig` 及 `SetConfigWithMap` 来设置。
+2. 也可以使用 `View` 对象的 `Set*` 方法进行特定配置的设置。
+3. 主要注意的是，配置项在 `View` 对象执行视图解析之前设置，避免并发安全问题。
+### `SetConfigWithMap` 方法
+我们可以使用 `SetConfigWithMap` 方法通过 `Key-Value` 键值对来设置/修改 `View` 的特定配置，其余的配置使用默认配置即可。其中 `Key` 的名称即是 `Config` 这个 `struct` 中的属性名称，并且不区分大小写，单词间也支持使用 `-`/ `_`/ `空格` 符号连接，具体可参考 [类型转换-Struct转换](../类型转换/类型转换-Struct转换.md) 章节转换规则。
+简单示例：
+```go
+package main
+import (
+    "context"
+    "fmt"
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/os/gview"
+)
+func main() {
+    view := gview.New()
+    view.SetConfigWithMap(g.Map{
+        "Paths":       []string{"template"},
+        "DefaultFile": "index.html",
+        "Delimiters":  []string{"${", "}"},
+        "Data": g.Map{
+            "name":    "gf",
+            "version": "1.10.0",
+        },
+    })
+    result, err := view.ParseContent(context.TODO(), "hello ${.name}, version: ${.version}")
+    if err != nil {
+        panic(err)
+    }
+    fmt.Println(result)
+}
+```
+其中 `DefaultFile` 表示默认解析的模板文件，键名也可以使用 `defaultFile`, `default-File`, `default_file`, `default file`，其他配置属性以此类推。
+## 注意事项
+经常有小伙伴问，为神马我的模板解析没有生效？为神马页面上直接将我写的标签原木原样显示出来了？
+这个时候请检查你的配置文件中是否有设置模板标签，常见的是 `delimiters` 设置为了 `["${", "}"]`，但是模板中使用的是 `["{{", "}}"]`。

package/skills/goframe-v2/references//346/240/270/345/277/203/347/273/204/344/273/266//346/250/241/346/235/277/345/274/225/346/223/216//346/250/241/346/235/277/345/274/225/346/223/216.md ADDED Viewed

@@ -0,0 +1,184 @@
+## 模板引擎特点
+1. 简单、易用、强大；
+2. 支持多模板目录搜索；
+3. 支持 `layout` 模板设计；
+4. 支持模板视图对象单例模式；
+5. 与配置管理模块原生集成，使用方便；
+6. 底层采用了二级缓存设计，性能高效；
+7. 新增模板标签及大量的内置模板变量、模板函数；
+8. 支持模板文件修改后自动更新缓存机制，对开发过程更友好；
+9. `define`/ `template` 标签支持跨模板调用（同一模板路径包括子目录下的模板文件）；
+10. `include` 标签支持任意路径的模板文件引入；
+## 通用视图管理
+通用视图管理即使用原生的模板引擎 `gview` 模块来实现模板管理，包括模板读取展示，模板变量渲染等等。可以使用通过方法 `gview.Instance` 来获取视图单例对象，并可以按照单例对象名称进行获取。同时也可以通过对象管理器 `g.View()` 来获取默认的单例 `gview` 对象。
+**接口文档**：
+[https://pkg.go.dev/github.com/gogf/gf/v2/os/gview](https://pkg.go.dev/github.com/gogf/gf/v2/os/gview)
+简要说明：
+1. `gview.Get` 用于根据给定的一个模板目录路径，获得对应的单例模板引擎对象；
+2. `gview.New` 同样可以根据给定的模板目录路径创建模板引擎对象，但没有单例管理；
+3. `SetPath/AddPath` 用于设置/添加当前模板引擎对象的模板目录路径，其中 `SetPath` 会覆盖所有的模板目录设置，推荐使用 `AddPath`；
+4. `Assign/Assigns` 用于设置模板变量，通过该模板引擎解析的所有模板均可以使用这些模板变量；
+5. `BindFunc` 用于绑定模板函数，具体使用方法参考后续示例程序；
+6. `Parse/ParseContent` 用于解析模板文件/内容，可以在解析时给定临时的模板变量及模板函数；
+7. `SetDelimiters` 用于设置该模板引擎对象的模板解析分隔符号，默认为 `{{ }}`（与 `vuejs` 前端框架有冲突）；
+:::warning
+需要注意，从 `goframe v1.16` 版本开始，所有模板的解析方法都额外增加了第一个输入参数为 `Context` 上下文变量的传递。
+:::
+### 示例1，解析模板文件
+`index.tpl`
+```
+id:{{.id}}, name:{{.name}}
+```
+`main.go`
+```go
+package main
+import (
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/net/ghttp"
+)
+func main() {
+    s := g.Server()
+    s.BindHandler("/template", func(r *ghttp.Request) {
+        r.Response.WriteTpl("index.tpl", g.Map{
+            "id":   123,
+            "name": "john",
+        })
+    })
+    s.SetPort(8199)
+    s.Run()
+}
+```
+执行后，访问 [http://127.0.0.1:8199/template](http://127.0.0.1:8199/template) 可以看到解析后的内容为： `id:123, name:john`
+### 示例2，解析模板内容
+```go
+package main
+import (
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/net/ghttp"
+)
+func main() {
+    s := g.Server()
+    s.BindHandler("/template", func(r *ghttp.Request){
+        tplContent := `id:{{.id}}, name:{{.name}}`
+        r.Response.WriteTplContent(tplContent, g.Map{
+            "id"   : 123,
+            "name" : "john",
+        })
+    })
+    s.SetPort(8199)
+    s.Run()
+}
+```
+执行后，访问 [http://127.0.0.1:8199/template](http://127.0.0.1:8199/template) 可以看到解析后的内容为： `id:123, name:john`
+### 示例3，自定义模板分隔符
+在项目中我们经常会遇到 `Golang` 默认模板变量分隔符号与 `Vue` 的变量分隔符号冲突的情况（都使用的是 `{{ }}`），我们可以使用 `SetDelimiters` 方法来自定义全局的 `Golang` 模板变量分隔符号：
+```go
+// main.go
+package main
+import (
+    "context"
+    "fmt"
+    "github.com/gogf/gf/v2/frame/g"
+)
+func main() {
+    v := g.View()
+    v.SetDelimiters("${", "}")
+    b, err := v.Parse(
+        context.TODO(),
+        "gview_delimiters.tpl",
+        map[string]interface{}{
+            "k": "v",
+        })
+    fmt.Println(err)
+    fmt.Println(b)
+}
+```
+```html
+<!-- gview_delimiters.tpl -->
+test.tpl content, vars: ${.}
+```
+执行后，输出结果为：
+```html
+<nil>
+test.tpl content, vars: map[k:v]
+```
+## 目录配置方法
+`GoFrame` 框架的模板引擎支持非常灵活的多目录自动搜索功能，通过 `SetPath` 可以修改模板目录为唯一的一个目录地址，同时，我们可以通过 `AddPath` 方法添加多个搜索目录，模板引擎底层将会按照添加目录的顺序作为优先级进行自动检索。直到检索到一个匹配的文件路径为止，如果在所有搜索目录下查找不到模板文件，那么会返回失败。
+**默认目录配置**：
+`gview` 视图对象初始化时，默认会自动添加以下模板文件搜索目录：
+1. **当前工作目录及其下的 `template` 目录**：例如当前的工作目录为 `/home/www` 时，将会添加 `/home/www` 及 `/home/www/template`；
+2. **当前可执行文件所在目录及其下的 `template` 目录**：例如二进制文件所在目录为 `/tmp` 时，将会添加 `/tmp` 及 `/tmp/template`；
+3. **当前 `main` 源代码包所在目录及其下的 `template` 目录**（仅对源码开发环境有效）：例如 `main` 包所在目录为 `/home/john/workspace/gf-app` 时，将会添加 `/home/john/workspace/gf-app` 及 `/home/john/workspace/gf-app/template`；
+## 修改模板目录
+我们可以通过以下方式修改视图对象的模板文件搜索目录，视图对象将会只在该指定目录执行配置文件检索：
+1. （推荐）单例模式获取全局View对象，通过 `SetPath` 方法手动修改；
+2. 修改命令行启动参数 - `gf.gview.path`；
+3. 修改指定的环境变量 - `GF_GVIEW_PATH`；
+例如，我们的执行程序文件为 `main`，那么可以通过以下方式修改模板引擎的模板目录(Linux下)：
+1. （推荐）通过单例模式
+```go
+g.View().SetPath("/opt/template")
+```
+2. 通过命令行参数
+```shell
+./main --gf.gview.path=/opt/template/
+```
+3. 通过环境变量
+   - 启动时修改环境变量：
+     ```shell
+     GF_GVIEW_PATH=/opt/config/; ./main
+     ```
+   - 使用 `genv` 模块来修改环境变量：
+     ```go
+     genv.Set("GF_GVIEW_PATH", "/opt/template")
+     ```
+## 自动检测更新
+模板引擎使用了精心设计的 **缓存机制**，当模板文件第一次被读取后会被缓存到内存，下一次读取时将会直接从缓存中获取，以提高执行效率。并且，模板引擎提供了对模板文件的 **自动检测更新机制**，当模板文件在外部被修改后，模板引擎能够即时地监控到并刷新模板文件的缓存内容。
+## 相关文档